Automação - ação Chamar API e gravar a resposta no negócio
Como fazer a automação consultar ou avisar outro sistema no meio do fluxo e gravar no negócio o que esse sistema respondeu - montar a chamada, guardar a chave de acesso como segredo, ligar a resposta aos campos, testar sem gravar e acompanhar nos logs. Com os limites e as regras de segurança.
Quando usar
Use quando a automação precisa consultar ou avisar outro sistema no meio do fluxo e gravar no negócio o que ele respondeu.
Antes de começar
- Ser quem gerencia o CRM (só quem gerencia cria, altera e testa esta ação)
- O endereço público da API do outro sistema, o método e a chave de acesso
- Um exemplo da resposta dessa API, para saber onde está cada informação
- Os campos do negócio que vão receber os dados (os campos adicionais são criados antes, em Campos extras)
Para que serve e quando usar
No meio da automação, o CRM consulta ou avisa outro sistema e grava no negócio o que esse sistema respondeu. As ações que vêm depois já enxergam os campos gravados.
É diferente da ação "Chamar webhook", que só avisa o outro sistema e não usa a resposta.
O CRM não tem "bloco de código". Rodar um programa escrito pelo usuário dentro do sistema daria a esse programa acesso ao que não é dele. O que um bloco de código faria foi dividido em duas ações seguras: Chamar API, para buscar ou enviar dados, e Calcular campo, para fazer conta, montar texto e escolher valor com condição.
Antes de começar
| O que | Detalhe |
|---|---|
| Quem faz | Quem gerencia o CRM. Os outros usuários não criam, não alteram e não testam esta ação |
| Endereço da API | Público, começando com https:// ou http://. Endereço da rede interna da empresa não é chamado |
| Método | GET, POST, PUT, PATCH ou DELETE, conforme o outro sistema pede |
| Chave de acesso | A chave ou o token que o outro sistema exige, e o nome do cabeçalho em que ela vai |
| Exemplo da resposta | Para saber o caminho de cada informação. O teste da própria tela mostra a resposta |
| Campos do negócio | Os que vão receber os dados. Campo adicional é criado antes, em CRM > Painel de controle > grupo Configuração e integrações > cartão Campos extras |
Exemplo - consultar o provisionamento e gravar o plano no negócio
Quando o negócio entra na etapa Viabilidade, o CRM pergunta ao sistema de provisionamento qual plano o cliente tem e grava no negócio.
- 1
Abra CRM > Painel de controle > grupo Automação > cartão Automações e clique em Nova automação.
- 2
No cartão Quando, escolha "Card entrou em etapa", o funil e a etapa.
- 3
Clique em Adicionar ação. No cartão Então, em "Tipo de ação", escolha "Chamar API e gravar a resposta".
- 4
Em Chamada, escolha o "Método" GET e preencha o "Endereço (URL)". Exemplo: https://api.seusistema.com.br/clientes/{{cliente.documento}}.
- 5
Para pôr um dado do negócio no endereço, abra "Variáveis do negócio para usar no endereço e no corpo" e clique na variável. Ela é copiada: cole no lugar certo.
- 6
Em Cabeçalhos, clique em Adicionar cabeçalho. No nome, escreva Authorization. No valor, digite a chave de acesso do outro sistema. O campo já vem marcado como Segredo.
- 7
Em "O que gravar da resposta", clique em Adicionar campo para cada informação. Preencha o caminho na resposta e escolha o campo do negócio. Exemplo: o caminho dados.cliente.plano no campo Plano, e o caminho dados.cliente.mensalidade no campo Valor do negócio.
- 8
Em "Se a chamada falhar", confira o "Tempo limite (s)" e escolha, em "Depois da falha", entre "Continuar com as próximas ações" e "Parar o fluxo nesta ação".
- 9
Clique em Testar chamada. Busque um negócio, escolha em "Negócio do teste" e clique em Testar agora.
- 10
Confira o resultado e clique em Publicar automação.
Como montar a chamada
| Variável | O que entra no lugar |
|---|---|
| {{cliente.nome}} | Nome do cliente |
| {{cliente.documento}} | CPF ou CNPJ |
| {{cliente.email}} | |
| {{cliente.whatsapp}} | |
| {{cliente.contato}} | Nome do contato |
| {{card.numero}} | Número do negócio |
| {{card.titulo}} | Título |
| {{etapa.nome}} | Etapa |
| {{funil.nome}} | Funil |
| {{responsavel.nome}} | Responsável |
| {{registro.valor_numero}} | Valor do negócio como número, por exemplo 1500.5 |
| {{campo.chave}} | Campo adicional do negócio. Troque "chave" pela chave do campo |
O começo do endereço, até a primeira barra, não aceita variável. Variável só entra no caminho e nos parâmetros.
Nos métodos POST, PUT, PATCH e DELETE aparece o quadro "Corpo (JSON)". Ele é opcional. Texto vai entre aspas; variável fora de aspas só serve para número. Em GET não há corpo.
| A informação está em | Caminho |
|---|---|
| Um campo dentro de outro | dados.cliente.plano |
| O primeiro item de uma lista | itens[0].nome |
O que não vier na resposta deixa o campo do negócio como está.
O teste da chamada
O teste faz a chamada uma vez, com os dados do negócio escolhido, e mostra a resposta. Nenhum campo do negócio é gravado no teste.
| Parte | O que olhar |
|---|---|
| Selo | O código da resposta e o tempo, por exemplo "HTTP 200 em 120 ms". Sem resposta, aparece "Sem resposta" |
| Resposta | O que o outro sistema devolveu. Chaves e senhas aparecem mascaradas |
| Caminho, Campo do negócio e O que seria gravado | Linha a linha, o valor que cada campo receberia, ou o motivo de ele não ser aceito |
Segurança - o que a ação faz para proteger a sua chave e os seus dados
- A chave de acesso fica em um cabeçalho marcado como Segredo. Ao salvar, o valor é guardado com segurança e nunca mais aparece na tela: o campo mostra "Definido - digite para trocar".
- Cabeçalho com nome de credencial é sempre segredo, e a tela não deixa desmarcar. Vale para Authorization, Cookie e para nomes com api-key, token, secret, senha ou password.
- A chave só é enviada ao servidor para o qual foi digitada. Se o endereço mudar para outro servidor, é preciso digitar a chave de novo.
- Chave colocada no endereço (nos parâmetros) ou no corpo fica visível para quem edita a automação. Use sempre o cabeçalho com Segredo.
- A ação só chama endereço público. Endereço da rede interna ou do próprio servidor não é chamado.
- O começo do endereço não aceita variável. Um dado do negócio nunca muda para qual servidor a chamada vai.
- O valor das variáveis entra sempre codificado: ele não muda o servidor do endereço nem a forma do corpo.
- O endereço não aceita usuário e senha.
- Em POST, PUT, PATCH e DELETE, o redirecionamento não é seguido.
- Só quem gerencia o CRM cria, altera e testa a ação. Nos logs, o conteúdo da resposta aparece só para quem gerencia o CRM.
O que a ação pode gravar
| Campo | Observação |
|---|---|
| Próxima ação | Texto |
| Data da próxima ação | Data |
| Valor do negócio | Número. Valor de negócio já ganho não é alterado |
| Produto / serviço | Texto |
| Canal de origem do cliente | Texto |
| Observações gerais | Texto |
| Campos adicionais do funil | Aparecem na lista com o nome do funil. Para um que não está na lista, escolha "Outro campo adicional (pela chave)" e digite a chave |
Responsável, etapa e cliente não são gravados por esta ação: cada um tem a sua ação própria na automação.
O valor é conferido antes de gravar. Texto em campo numérico, data inválida ou campo obrigatório vazio recusam a gravação inteira: nada é gravado pela metade.
Limites
| Assunto | Limite |
|---|---|
| Métodos | GET, POST, PUT, PATCH e DELETE |
| Corpo | Em JSON. Em GET não há corpo |
| Tempo limite | De 2 a 30 segundos. O padrão é 15 |
| Tamanho da resposta | Até 256 KB. Acima disso nada é gravado |
| Cabeçalhos | Até 20 |
| Linhas em "O que gravar da resposta" | Até 30 |
Quando a chamada é repetida
| Situação | O que o CRM faz |
|---|---|
| Falha de rede ou erro do servidor de destino (500 a 599) | Tenta de novo sozinho, com a mesma identificação da chamada, para o destino descartar a cópia |
| Recusa do destino (400 a 499) | Não repete |
| Chamada que já deu certo | Nunca é repetida na mesma execução |
| POST e PATCH sem resposta | Ficam como "Incerto" e só saem de novo pelo Reprocessar, nos logs |
| GET, PUT e DELETE sem resposta | São tentados de novo sozinhos |
A identificação da chamada vai no cabeçalho X-Hap-Event-Id. Quem cuida do outro sistema pode usá-la para reconhecer a mesma chamada repetida.
Onde acompanhar
- 1
Abra CRM > Painel de controle > grupo Configuração e integrações > cartão Logs e histórico.
- 2
Clique na linha da execução.
- 3
Veja o bloco "Chamadas de API": o método, o endereço, a situação, o código da resposta e o tempo de cada chamada.
O conteúdo da resposta aparece só para quem gerencia o CRM. O botão Reprocessar refaz a execução que falhou.
Usar a resposta nas ações seguintes
As ações que vêm depois, na mesma automação, já enxergam o que a chamada gravou. Exemplo: a API grava a mensalidade em um campo adicional e a ação seguinte, Calcular campo, multiplica por 12 e grava o valor do negócio. Veja o artigo "Automação - ação Calcular campo (fórmula)", nos links.
Problemas comuns
- Aparece "Esse endereço não é público (rede interna ou o próprio servidor): a chamada não é feita." - o endereço aponta para a rede interna da empresa ou para o próprio servidor. A ação só chama endereço público.
- Aparece "Use o endereço completo, começando com https:// ou http://" - falta o começo do endereço.
- Aparece "O começo do endereço (até a primeira barra) não aceita variável." - a variável foi posta no nome do servidor. Ela só entra no caminho e nos parâmetros, depois da primeira barra.
- Aparece "O endereço não pode ter usuário e senha. Use um cabeçalho marcado como segredo." - tire o usuário e a senha do endereço e mande a chave em um cabeçalho com Segredo marcado.
- Aparece que o valor do cabeçalho foi definido para outro servidor - o endereço mudou de servidor depois que a chave foi guardada. Digite a chave de novo e salve.
- Aparece "Digite o valor do cabeçalho" - o cabeçalho está marcado como Segredo e ainda não tem valor guardado.
- Aparece que o cabeçalho é definido pelo sistema e não pode ser informado - o nome escolhido é reservado. Remova esse cabeçalho.
- Aparece "O corpo não é um JSON válido." - no corpo, texto vai entre aspas e variável fora de aspas só serve para número.
- O resultado diz que a resposta não é um JSON e o mapa não foi aplicado - o outro sistema devolveu uma página ou um texto. Confira o endereço e a chave de acesso.
- O teste mostra "Não veio na resposta - o campo não seria alterado" - o caminho do mapa não existe naquela resposta. Abra a resposta no teste e acerte o caminho.
- O resultado diz que o campo é numérico e o valor não é um número - o caminho aponta para um texto. Aponte para o valor numérico ou grave em um campo de texto.
- O resultado diz que o endereço redirecionou - em POST, PUT, PATCH e DELETE o redirecionamento não é seguido. Informe o endereço final.
- O botão Testar agora está apagado - escolha o negócio do teste. Em POST, PUT, PATCH e DELETE, marque também a confirmação de que o teste faz a chamada de verdade. Se o endereço estiver com erro, corrija antes.
- A chamada aparece como "Incerto" nos logs - foi um POST ou um PATCH que ficou sem resposta. Ele pode ter chegado ao outro sistema, então não sai de novo sozinho. Confira no outro sistema e, se precisar, use Reprocessar.
- Não consigo salvar nem testar a ação - criar, alterar e testar a ação Chamar API é só de quem gerencia o CRM.
- O tipo de ação não aparece na lista - a sua base ainda não recebeu a atualização. Ela chega na próxima atualização do sistema; se precisar antes, fale com o suporte da Hap.