JSON é o formato no qual os sistemas externos trocam dados: assim respondem as APIs de transportadoras, serviços de pagamento e sistemas de gestão. O processo de negócios do Bitrix24 enxerga o JSON como uma string comum: não há ações nativas para extrair dela um valor ou montar uma estrutura para envio. Vamos analisar a combinação de três robôs: o primeiro envia uma requisição HTTP e recebe a resposta, o segundo extrai do JSON o valor desejado pelo caminho, o terceiro monta um JSON a partir dos campos do negócio para enviar para fora.

Onde o processo de negócios se depara com JSON?

Três pontos típicos. O primeiro — respostas de APIs externas: o processo consulta o status da entrega, o saldo em estoque ou a taxa de câmbio e recebe um JSON. O segundo — webhooks: um sistema externo envia dados, e eles caem em um campo ou variável como uma única string do tipo {"order":{"id":518,"status":"paid"}} — e é preciso fazer algo com ela. O terceiro — envio de dados para fora: o sistema externo espera um JSON de estrutura definida, e é preciso montá-lo a partir dos campos do negócio. Nos três casos, o designer nativo de processos de negócios oferece trabalhar com a string inteira, e normalmente é nesse ponto que se chama o programador. Os três robôs abaixo fecham o ciclo sem código.

Como enviar uma requisição a um sistema externo?

O robô «Requisição HTTP GET/POST» se conecta a qualquer API externa. Entrada: URL, método — GET, POST, PUT, PATCH, DELETE ou HEAD, por padrão GET —, corpo da requisição para POST e PUT, cabeçalhos como objeto JSON do tipo {"Authorization":"Bearer …"} e tempo limite em segundos, por padrão 10. Saída: o corpo da resposta, o código de status HTTP e o indicador «Sucesso» (Y/N — código 2xx). O corpo da resposta é gravado em uma variável e passado para o próximo robô interpretar. Assim o processo descobre por conta própria o status do pedido no sistema de gestão conforme o cronograma das etapas, sem esperar que o gerente verifique manualmente. O robô está disponível nos planos pagos do Bitrix24.

Como extrair um valor da resposta JSON?

O robô «Extrair valor de JSON pelo caminho» interpreta a string JSON e retorna o valor pelo caminho separado por pontos: chaves de objetos e índices numéricos de arrays. Para a resposta {"data":{"user":{"email":"a@b.ru"}}}, o caminho data.user.email retorna a@b.ru; o primeiro elemento de uma lista é obtido por um caminho do tipo items.0.name. Saída: o valor como string e o indicador «Caminho encontrado» (Y/N); se no caminho houver um objeto ou array, ele é retornado como um valor à parte na forma de JSON — e é interpretado pelo mesmo robô mais uma vez, agora pelo caminho interno. Um JSON inválido ou um caminho inexistente resulta no indicador N, e não na parada do processo. O valor encontrado é gravado pela ação seguinte em um campo do negócio ou contato.

Como montar um JSON a partir dos campos do negócio?

Tarefa inversa: o sistema externo espera um JSON, mas os dados estão em campos e variáveis. O robô «Montar JSON a partir de campos» recebe duas listas múltiplas — chaves e valores; a ordem deve coincidir: a primeira chave recebe o primeiro valor. Nos valores são inseridos campos do negócio e variáveis do processo. Números e os valores true/false são reconhecidos automaticamente e vão para o JSON sem aspas, o resto — como strings; há a opção de formatar com recuos para legibilidade. A saída é um objeto JSON pronto: ele é inserido no corpo da requisição POST do robô «Requisição HTTP GET/POST» ou passado ao sistema externo por qualquer outro meio.

Como tratar erros de integração?

Os sistemas externos respondem com erros, e o processo precisa sobreviver a isso. Ambos os robôs retornam indicadores em vez de parar. «Sucesso = N» na requisição HTTP significa uma resposta fora dos códigos 2xx: o código de status indica a causa — 401 sobre um problema de autorização, 404 sobre um endereço errado, 5xx sobre uma falha do outro lado. «Caminho encontrado = N» na interpretação do JSON — a resposta veio com estrutura diferente ou o JSON é inválido. Com base nesses indicadores, no designer de processos de negócios constrói-se um ramo separado: uma tarefa para o responsável com o corpo da resposta dentro, e o negócio permanece na etapa atual até ser esclarecido. Sem esse ramo, o processo grava silenciosamente um valor vazio, e o erro aparece depois — já no cliente.

Conclusão

A combinação «requisição → interpretação → montagem» fecha a integração típica sem código: «Requisição HTTP GET/POST» troca dados com o sistema externo, «Extrair valor de JSON pelo caminho» interpreta a resposta, «Montar JSON a partir de campos» prepara os dados para envio. Os três estão no catálogo da Roboteka e são instalados a partir do Bitrix24.Marketplace. Não há robô para a sua integração — descreva a tarefa, fazemos de graça e adicionamos à biblioteca comum.