Configurar o card Requisição HTTP
Caminho: Configurações → Fluxo de comunicação → (fluxo) → Abrir fluxo → + → Ferramentas do sistema → Requisição HTTP
Visão geral
O card Requisição HTTP faz o agente virtual chamar a API de um sistema externo durante o atendimento, para consultar um pedido, enviar uma fatura ou cadastrar um contato, por exemplo. A resposta da API pode ser guardada em variáveis, usadas pelos cards seguintes, ou virar um menu de opções para o contato escolher.
Esta página explica todos os campos do card. Para um exemplo completo, com pergunta, consulta e decisão, veja Criar um fluxo de comunicação low code com requisição HTTP.
Pré-requisitos
- Uma integração HTTP instalada em Opa! Store → Http, com o endereço do sistema e a autenticação. Veja Configurar a integração HTTP.
- Os dados da API: caminho (endpoint), método, cabeçalhos, corpo e formato da resposta.
- Permissão para editar fluxos de comunicação.
Passo a passo
- Abra o fluxo de comunicação.
- Clique no + abaixo do card depois do qual a requisição deve ser feita.
- Na janela Novo estágio, marque Ferramentas do sistema no campo Tipo e escolha Requisição HTTP em Ferramenta.
- Preencha a seção Configuração (veja a tabela abaixo).
- Na seção Resposta, preencha o Mapeamento de propriedades da resposta para variáveis (JSON).
- Clique em Testar requisição para conferir o resultado.
- Clique em Salvar.
Campos da configuração
| Campo | O que faz |
|---|---|
| Integração | A integração HTTP que será usada. É obrigatória. |
| Endpoint | O caminho a chamar, somado ao endereço da integração. Aceita variáveis entre chaves duplas, como /pedidos/. |
| Método | GET, POST, PUT, PATCH ou DELETE. É obrigatório. |
| Headers (JSON) | Cabeçalhos da requisição, em formato JSON. |
| Body (JSON) | Corpo da requisição, em formato JSON. |
| Query Params (JSON) | Parâmetros de busca da requisição, em formato JSON. |
| Utilizar Pre-request Script | Liga um script em JavaScript executado antes da chamada. |
| Utilizar Pos-request Script | Liga um script em JavaScript executado depois da chamada. |
Os campos Headers, Body e Query Params precisam estar em JSON válido. Você pode usar variáveis do fluxo entre chaves duplas. O botão Biblioteca de variáveis lista as variáveis disponíveis para esse card: escolha uma e clique no nome dela para copiá-lo. Se a integração usa autenticação por token, você também pode usar para colocar o token em outro ponto da requisição.
Scripts antes e depois da chamada
Os scripts servem para preparar dados antes da chamada ou tratar a resposta depois. Dentro deles, você acessa as variáveis assim:
FLOW.nome_da_variavel: variáveis criadas nos cards do fluxo.SYSTEM.nome_da_variavel: variáveis do sistema, como o protocolo.RESPONSE.data,RESPONSE.erroreRESPONSE.statusCode: o resultado da chamada (só no Pos-request Script).
Use SETVARS({ ... }) para criar variáveis. O valor passado precisa ser um objeto. As variáveis criadas no Pre-request Script podem ser usadas no endpoint, nos headers, no body e nos query params. As criadas no Pos-request Script ficam disponíveis para os cards seguintes.
Mapeamento da resposta
O campo Mapeamento de propriedades da resposta para variáveis (JSON) indica de onde tirar cada dado da resposta. A resposta tem três partes: data (o conteúdo retornado), error (o erro, se houver) e statusCode (o código de resposta). Exemplo:
{ "status_pedido": "data.status", "codigo_http": "statusCode" }Os nomes das variáveis devem estar em lowercase, camelCase ou snake_case e não podem se repetir em outro card do fluxo.
Gerar pergunta de escolha com a resposta
Marque Gerar pergunta de escolha com a resposta quando a API retornar uma lista e o contato precisar escolher um item. Preencha:
- Propriedade da resposta que contém o array de dados (opcional): onde está a lista na resposta, como
data.pedidos. Se ficar em branco, o card usa a resposta inteira. - Mensagem da pergunta: o texto enviado antes da lista.
- Descrição da opção de escolha: como cada item aparece, com os atributos entre chaves. Exemplo:
Pedido {id} - {status}. - Mapeamento de propriedades da escolha para variáveis (JSON): quais dados do item escolhido viram variáveis. Exemplo:
{ "id_pedido": "id" }. - Mensagem de erro na escolha, Quantidade de tentativas, Mensagem após máximo de tentativas e Fluxo a ser executado após máximo de tentativas: tratam as respostas inválidas. Se a Quantidade de tentativas ficar em branco, o limite é 3.
O contato recebe os itens numerados e responde com o número. Se a lista vier vazia, o agente virtual não faz a pergunta e segue para o próximo card.
Regras e comportamentos
- Teste da requisição: o botão Testar requisição abre a janela Resultado do teste com a resposta da API. O teste executa o Pre-request Script, mas não o Pos-request Script nem o mapeamento da resposta.
- Integração indisponível: se a integração escolhida foi removida ou não está disponível no momento do atendimento, o agente virtual encerra o atendimento.
- Erro da API: o card não interrompe o fluxo quando a API responde com erro. Para tratar o erro, mapeie
statusCodeouerrorpara uma variável e use um card Condicional. - Dados sensíveis: respostas marcadas como Campo com informações sensíveis em um card Enviar pergunta podem ser usadas neste card. Veja Configurar o card Enviar pergunta.
Problemas comuns
| Sintoma | O que verificar |
|---|---|
| O sistema não salva e aponta o campo Headers, Body ou Query Params | O conteúdo precisa ser JSON válido. Confira aspas, vírgulas e chaves. |
| O nome da variável é recusado | Use lowercase, camelCase ou snake_case, sem espaços nem acentos, e sem repetir o nome de uma variável de outro card. |
| A variável do mapeamento fica vazia | Use Testar requisição e confira o caminho no mapeamento, como data.status. |
| O atendimento é encerrado na requisição | Confira se a integração HTTP ainda está instalada em Opa! Store → Http e se o método escolhido está preenchido. |
Boas práticas
- Teste a requisição antes de salvar o fluxo.
- Trate o caminho de erro com um Condicional, para o contato não ficar sem resposta quando a API falhar.
- Dê nomes às variáveis que digam o que guardam, como
status_pedido.