🌐 Bloco HTTP Request

O bloco HTTP Request permite conectar um fluxo de atendimento do ZapChatPro a sistemas externos por meio de uma API.

Com esse recurso, o Flowbuilder pode consultar ou enviar informações para sistemas financeiros, ERPs, plataformas de cobrança e outras aplicações integradas.

Neste tutorial, utilizaremos como exemplo a consulta de uma segunda via de boleto em um sistema externo.

aviso

Para realizar a integração, é necessário ter acesso à documentação da API que será utilizada.

Solicite ao responsável pelo sistema externo as seguintes informações:

URL dos endpoints;
Método da requisição;
Headers obrigatórios;
Credenciais ou API Key;
Estrutura do corpo da requisição;
Estrutura da resposta da API.

🌐 O que é o bloco HTTP Request

O bloco HTTP Request permite realizar uma chamada para uma API externa durante o atendimento.

Por meio dele, o fluxo pode:

Consultar dados de clientes;
Buscar boletos e cobranças;
Gerar tokens de autenticação;
Enviar informações para um sistema externo;
Armazenar dados da resposta em variáveis;
Verificar se a requisição foi concluída com sucesso.

A configuração exata depende da documentação da API utilizada.

⚙️ Campos do bloco HTTP Request

Os campos disponíveis podem variar conforme a versão do sistema. Os principais são:

URL: informe o endereço completo do endpoint que será consultado.
Método: selecione o método exigido pela API, como GET, POST, PUT, PATCH ou DELETE.
Timeout: defina o tempo máximo que o sistema deverá aguardar pela resposta da API.
Headers: informe os cabeçalhos exigidos pela integração, como Content-Type, Authorization ou x-api-key.
Parâmetros de consulta: adicione os parâmetros que deverão ser enviados na URL.
Corpo da requisição: informe os dados que serão enviados para a API, normalmente em formato JSON.
Variáveis de resposta: defina quais informações retornadas pela API deverão ser armazenadas em variáveis.
Variável de status: armazena o código de status retornado pela requisição, quando utilizado.
Variável de sucesso: armazena o resultado da execução da chamada, permitindo verificar se a requisição foi concluída corretamente.

Exemplo de Headers

{
  "Content-Type": "application/json",
  "x-api-key": "SUA_API_KEY"
}

aviso

Nunca compartilhe uma API Key, token ou senha em prints, mensagens públicas ou documentações abertas.

Essas informações devem ser tratadas como credenciais de acesso.

📦 Como salvar e utilizar variáveis

As variáveis permitem armazenar informações para utilizá-las em outros blocos do fluxo.

Por exemplo, o CPF informado pelo cliente pode ser armazenado em uma variável chamada:

cpfCliente

Uma resposta da API também pode ser armazenada em variáveis, como:

unidadeId
unidadeNome
jwtToken
linhaDigitavel
urlBoleto

Para salvar uma informação retornada pela API, informe:

Caminho da resposta: posição em que o valor está localizado no retorno da API.
Nome da variável: nome que será utilizado para acessar essa informação nos próximos blocos.

Exemplo

Considere a seguinte resposta:

{
  "data": [
    {
      "id": 10,
      "nome": "Unidade Centro"
    }
  ]
}

Para salvar o identificador e o nome da unidade, utilize:

Caminho da resposta	Variável
`data[0].id`	`unidadeId`
`data[0].nome`	`unidadeNome`

dica

Utilize nomes de variáveis claros e sem espaços. Exemplos: cpfCliente, jwtToken, linhaDigitavel e urlBoleto.

🧩 Como utilizar variáveis nas requisições

Para inserir uma variável em uma mensagem, URL, Header ou corpo da requisição, utilize a seguinte estrutura:

${nomeDaVariavel}

Exemplo em uma mensagem

Olá, ${unidadeNome}! Localizamos o seu cadastro.

Exemplo no corpo da requisição

{
  "cpf": "${cpfCliente}"
}

Exemplo em um Header

{
  "Authorization": "Bearer ${jwtToken}"
}

Durante a execução do fluxo, o sistema substitui a variável pelo valor armazenado.

aviso

O nome utilizado entre ${ e } deve ser exatamente igual ao nome da variável criada anteriormente.

🧾 Exemplo de fluxo para segunda via de boleto

Neste exemplo, o fluxo solicitará o CPF do cliente, consultará o cadastro em uma API externa, gerará um token e buscará a segunda via do boleto.

informação

As URLs, credenciais e estruturas apresentadas são apenas exemplos.

Substitua os dados conforme a documentação da API utilizada em sua operação.

Visão geral do fluxo

Início
  → Pergunta: solicitar CPF
  → HTTP Request: localizar cliente
  → Condição: cliente encontrado?
      ├── Não → Mensagem de cadastro não localizado
      └── Sim → HTTP Request: gerar token
                   → HTTP Request: buscar boleto
                       → Mensagem final

1️⃣ Adicionar o bloco Pergunta

Adicione um bloco Pergunta para solicitar o CPF do cliente.

Exemplo de mensagem:

Por favor, informe seu CPF para localizarmos o seu cadastro.

Salve a resposta na variável:

cpfCliente

2️⃣ Adicionar o primeiro HTTP Request

Adicione um bloco HTTP Request para consultar o cliente na API externa.

Configure os campos conforme o exemplo:

Método: POST
URL:

https://api.suaempresa.com.br/v3/chatbot/cliente/buscar

Headers:

{
  "Content-Type": "application/json",
  "x-api-key": "SUA_API_KEY"
}

Corpo da requisição:

{
  "cpf": "${cpfCliente}"
}

Variáveis de resposta:

Caminho da resposta	Variável
`data[0].id`	`unidadeId`
`data[0].nome`	`unidadeNome`

Variável de sucesso:

buscaClienteOk

Conecte a saída do bloco Pergunta à entrada desse bloco.

3️⃣ Adicionar o bloco Condição

Na categoria Lógica, adicione um bloco Condição.

Configure a condição para verificar se:

buscaClienteOk

é igual a:

true

Esse bloco deverá separar o fluxo em dois caminhos:

Sim: o cliente foi localizado;
Não: o cliente não foi localizado.

Conecte a saída do primeiro bloco HTTP Request à entrada do bloco Condição.

4️⃣ Configurar o caminho “Não”

Na saída Não, adicione um bloco Mensagem.

Exemplo:

Não foi possível localizar seu cadastro com o CPF informado.

Confira os dados e tente novamente ou solicite atendimento com nossa equipe.

Caso necessário, conecte esse caminho a um bloco responsável por direcionar o atendimento para uma fila ou setor.

5️⃣ Configurar o caminho “Sim”

Na saída Sim, adicione outro bloco HTTP Request para gerar o token de autenticação.

Configure os campos conforme o exemplo:

Método: POST
URL:

https://api.suaempresa.com.br/v3/chatbot/auth/token

Corpo da requisição:

{
  "unidadeId": "${unidadeId}"
}

Variável de resposta:

Caminho da resposta	Variável
`data.token`	`jwtToken`

Conecte a saída Sim do bloco Condição à entrada desse bloco.

6️⃣ Adicionar a consulta do boleto

Adicione outro bloco HTTP Request para buscar a segunda via do boleto.

Configure os campos conforme o exemplo:

Método: GET
URL:

https://api.suaempresa.com.br/v3/chatbot/financeiro/segunda-via

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer ${jwtToken}"
}

Variáveis de resposta:

Caminho da resposta	Variável
`data[0].url`	`urlBoleto`
`data[0].linhaDigitavel`	`linhaDigitavel`

Conecte a saída do bloco responsável por gerar o token à entrada desse bloco.

7️⃣ Adicionar a mensagem final

Adicione um bloco Mensagem após a consulta do boleto.

Exemplo:

Aqui está a segunda via do seu boleto! 😊

📋 Linha digitável:
${linhaDigitavel}

🔗 Link do boleto:
${urlBoleto}

Conecte a saída do último bloco HTTP Request à entrada dessa mensagem.

🧱 Exemplo de JSON

A estrutura abaixo representa um exemplo técnico de configuração de um bloco HTTP Request:

{
  "type": "httpRequest",
  "data": {
    "url": "https://api.suaempresa.com.br/v3/chatbot/cliente/buscar",
    "method": "POST",
    "timeout": 10000,
    "headers": {
      "Content-Type": "application/json",
      "x-api-key": "SUA_API_KEY"
    },
    "requestBody": "{\"cpf\": \"${cpfCliente}\"}",
    "queryParams": [],
    "responseVariables": [
      {
        "path": "data[0].id",
        "variableName": "unidadeId"
      },
      {
        "path": "data[0].nome",
        "variableName": "unidadeNome"
      }
    ],
    "statusVariable": "",
    "successVariable": "buscaClienteOk"
  }
}

informação

Esse JSON serve apenas como referência técnica. A configuração normal deve ser realizada diretamente pelos campos do bloco no Flowbuilder.

🧪 Como testar o bloco

Antes de ativar o fluxo para os clientes, teste cada etapa da integração.

Testar somente o bloco HTTP Request

Dentro da configuração do bloco, utilize o botão Testar API.

Esse teste permite verificar:

Se a URL está correta;
Se os Headers foram configurados corretamente;
Se a autenticação foi aceita;
Se o corpo da requisição está no formato esperado;
Se os caminhos das variáveis correspondem à resposta da API.

💳 Bloco pronto de segunda via de boleto

Caso a cobrança seja realizada por Asaas, SGP ou Atlaz, verifique a disponibilidade do bloco 2ª Via de Boleto.

Esse bloco simplifica a configuração e evita a criação manual das requisições.

Os principais campos são:

Provedor: selecione o sistema responsável pela cobrança.
Tipo de identificador: escolha o dado utilizado para localizar o cliente, como CPF/CNPJ, telefone, e-mail ou código externo.
Valor do identificador: informe um valor fixo ou uma variável, como ${cpfCliente}.
Prefixo das variáveis geradas: defina o prefixo utilizado nas variáveis criadas pelo bloco.
Enviar PDF automaticamente: ative essa opção quando desejar enviar o arquivo do boleto diretamente pelo WhatsApp.
Mensagens por status: configure os caminhos de sucesso, cliente não encontrado, cobrança não localizada, documento inválido ou erro de integração.

dica

Utilize o bloco HTTP Request quando o sistema de cobrança possuir uma API própria ou quando não houver uma integração pronta disponível no Flowbuilder.

aviso

Uma API externa lenta ou indisponível pode atrasar a resposta do fluxo. Configure mensagens adequadas para orientar o cliente quando a consulta não puder ser concluída.

❓ Dúvidas frequentes

Onde consigo a URL da API?

A URL deve ser fornecida pela empresa responsável pelo sistema externo ou pela equipe técnica responsável pela integração.

O que é uma API Key?

É uma chave utilizada para autenticar o acesso à API. Ela deve ser mantida em segurança e não deve ser compartilhada publicamente.

Posso utilizar uma variável no corpo da requisição?

Sim. Utilize a variável no formato:

${nomeDaVariavel}

Exemplo:

{
  "cpf": "${cpfCliente}"
}

Como descubro o caminho de uma informação na resposta?

Execute a chamada pelo botão Testar API e analise o JSON retornado.

Por exemplo, para acessar o campo id abaixo:

{
  "data": [
    {
      "id": 10
    }
  ]
}

Utilize o caminho:

data[0].id

O que acontece quando a API retorna um erro?

O fluxo deve possuir uma condição ou um caminho específico para tratar a falha e apresentar uma mensagem adequada ao cliente.

Posso utilizar o bloco para outras integrações?

Sim. A mesma estrutura pode ser utilizada para diferentes sistemas externos. Será necessário adaptar a URL, os Headers, o corpo da requisição e os caminhos da resposta conforme a documentação de cada API.

✅ Finalização

Pronto! Agora você já sabe como utilizar o bloco HTTP Request no Flowbuilder para consultar uma API externa, armazenar informações em variáveis e utilizar os dados retornados durante o atendimento.

Antes de ativar o fluxo, teste todas as requisições e confirme se os caminhos de sucesso e erro estão funcionando corretamente.

🌐 O que é o bloco HTTP Request​

⚙️ Campos do bloco HTTP Request​

Exemplo de Headers​

📦 Como salvar e utilizar variáveis​

Exemplo​

🧩 Como utilizar variáveis nas requisições​

Exemplo em uma mensagem​

Exemplo no corpo da requisição​

Exemplo em um Header​

🧾 Exemplo de fluxo para segunda via de boleto​

Visão geral do fluxo​

1️⃣ Adicionar o bloco Pergunta​

2️⃣ Adicionar o primeiro HTTP Request​

3️⃣ Adicionar o bloco Condição​

4️⃣ Configurar o caminho “Não”​

5️⃣ Configurar o caminho “Sim”​

6️⃣ Adicionar a consulta do boleto​

7️⃣ Adicionar a mensagem final​

🧱 Exemplo de JSON​

🧪 Como testar o bloco​

Testar somente o bloco HTTP Request​

💳 Bloco pronto de segunda via de boleto​

❓ Dúvidas frequentes​

Onde consigo a URL da API?​

O que é uma API Key?​

Posso utilizar uma variável no corpo da requisição?​

Como descubro o caminho de uma informação na resposta?​

O que acontece quando a API retorna um erro?​

Posso utilizar o bloco para outras integrações?​

✅ Finalização​

🌐 O que é o bloco HTTP Request

⚙️ Campos do bloco HTTP Request

Exemplo de Headers

📦 Como salvar e utilizar variáveis

Exemplo

🧩 Como utilizar variáveis nas requisições

Exemplo em uma mensagem

Exemplo no corpo da requisição

Exemplo em um Header

🧾 Exemplo de fluxo para segunda via de boleto

Visão geral do fluxo

1️⃣ Adicionar o bloco Pergunta

2️⃣ Adicionar o primeiro HTTP Request

3️⃣ Adicionar o bloco Condição

4️⃣ Configurar o caminho “Não”

5️⃣ Configurar o caminho “Sim”

6️⃣ Adicionar a consulta do boleto

7️⃣ Adicionar a mensagem final

🧱 Exemplo de JSON

🧪 Como testar o bloco

Testar somente o bloco HTTP Request

💳 Bloco pronto de segunda via de boleto

❓ Dúvidas frequentes

Onde consigo a URL da API?

O que é uma API Key?

Posso utilizar uma variável no corpo da requisição?

Como descubro o caminho de uma informação na resposta?

O que acontece quando a API retorna um erro?

Posso utilizar o bloco para outras integrações?

✅ Finalização