API Key

A caixa API Key faz uma requisição HTTP para um serviço externo autenticado por cabeçalho X-API-KEY. Ela é o caminho mais direto para conversar com uma API sua (ou de terceiros) que usa esse padrão de autenticação: você informa a URL, a chave, o método e, quando o método pede, o corpo da requisição.

Casos de uso típicos:

• consultar informações em um sistema próprio (status de pedido, saldo, protocolo) antes de responder ao cliente;
• notificar um sistema externo de que algo aconteceu na conversa (pagamento confirmado, cadastro concluído);
• registrar o atendimento em uma plataforma de terceiros;
• encadear o resultado da resposta em variáveis de sessão para as próximas caixas.

Em execução, a caixa dispara o comando dialog.rest(...) do runtime com o cabeçalho X-API-KEY já montado, e o resultado chega de volta de forma assíncrona para o tratamento de sucesso/falha.

Onde encontrar

1. Abra Configuração → Fluxos.
2. Crie ou abra uma versão do fluxo no editor.
3. Na barra de caixas à esquerda do editor, procure o ícone de chave — “API Key” (ao passar o mouse: “Configure uma requisição com X-API-Key”).
4. Adicione a caixa ao diagrama e selecione-a para abrir o painel de configuração.
5. Preencha os campos e clique em Aplicar. Depois, salve a versão do fluxo.

Como funciona

O comportamento geral é:

Caixa API Key
      │
      ├── dispara dialog.rest(...) com o cabeçalho X-API-KEY
      │
      ▼ (resposta chega de forma assíncrona)
Tratamento do retorno
      ├── status 2xx ──► caixa configurada em “Em caso de sucesso...”
      └── outro status ──► caixa configurada em “Caso haja alguma falha...”

Quando a caixa é executada, o script gerado por ela:

1. monta o cabeçalho X-API-KEY com o valor informado (ou lido de uma variável);
2. acrescenta os cabeçalhos extras configurados na tabela Cabeçalho da requisição;
3. dispara dialog.rest(cabecalhos, url, metodo, corpo);
4. quando a resposta chega, monta restResponse com statusCode e body e aplica o tratamento escolhido:
   • Executar script — roda o script informado em “Script a executar após a requisição” (a variável restResponse está disponível nele) e desvia para sucesso/falha conforme o status;
   • Armazenar resposta — grava o objeto restResponse inteiro na variável informada e desvia para sucesso/falha.

Para uma caixa configurada com URL https://api.exemplo.com/pedidos/123, método GET e chave abc123, o script gerado é equivalente a:

dialog.rest({"X-API-KEY": "abc123"}, "https://api.exemplo.com/pedidos/123", "get", null);

E o retorno é tratado no onExternal da própria caixa, equivalente a:

let restResponse = {statusCode: input.statusCode, body: input.body};
// em modo “Executar script”, aqui entra o script que você escreveu, por exemplo:
let dados = JSON.parse(restResponse.body);
dialog.set('statusPedido', dados.status);

if (restResponse.statusCode >= 200 && restResponse.statusCode < 300)
  dialog.go("Informar status");

Importante: o corpo da resposta (restResponse.body) chega como texto. Se a API devolve JSON, use JSON.parse(restResponse.body) antes de acessar os campos.

Campos da caixa

Nome

Identifica a caixa no diagrama. Exemplos: Consultar status do pedido, Notificar sistema externo.

URL de destino

Endereço completo da requisição, incluindo https://. Aceita interpolação de variáveis (veja a seção abaixo), o que permite montar URLs dinâmicas como https://api.exemplo.com/pedidos/{{pedidoId}}.

Método da requisição

Um entre POST, GET, DELETE e PUT. O campo Corpo da requisição só aparece para métodos diferentes de GET.

X-API-KEY

Valor do cabeçalho X-API-KEY enviado na requisição. É o único campo obrigatório — o salvamento recusa a caixa sem ele (“O campo X-API-KEY deve ser preenchido”). Aceita interpolação: informe a chave literal (abc123) ou leia de uma variável de sessão ({{chaveApi}}), o que evita deixar a chave fixa no fluxo.

Cabeçalho da requisição

Tabela de pares Chave/Valor com cabeçalhos HTTP extras (Content-Type, Authorization, etc.). Os valores também aceitam interpolação de variáveis.

Corpo da requisição

Texto enviado como corpo da requisição (aparece para POST, PUT e DELETE). Aceita interpolação — por exemplo:

{"protocolo": "{{protocolo}}", "evento": "pagamento-confirmado"}

Executar script / Armazenar resposta

Escolhe o que fazer com a resposta:

Em ambos os modos, os desvios de sucesso/falha continuam valendo.

Em caso de sucesso da requisição, vai para:

Caixa de destino quando o status da resposta está entre 200 e 299.

Caso haja alguma falha na requisição, vai para:

Caixa de destino quando o status fica fora dessa faixa (ou quando o script falha, no modo Executar script). Recomendado sempre configurar — rede e API falham.

Interpolação de variáveis

Os campos URL de destino, X-API-KEY, valores da tabela de cabeçalhos e Corpo da requisição aceitam os mesmos marcadores das demais caixas de requisição:

https://api.exemplo.com/pedidos/{{pedidoId}}   →  "https://api.exemplo.com/pedidos/" + dialog.get('pedidoId')
{{chaveApi}}                                    →  dialog.get('chaveApi')

Exemplos

Exemplo 1 — Consultar o status de um pedido (GET)

Objetivo: antes de responder ao cliente, consultar o status do pedido em uma API própria.

No script da resposta:

let dados = JSON.parse(restResponse.body);
dialog.set('statusPedido', dados.status);

Perguntar pedido (Coletar dados, variável "pedidoId")
      │
      ▼
Consultar status do pedido (API Key, GET)
      ├── sucesso ──► Informar status
      └── falha ────► Avisar indisponibilidade

Exemplo 2 — Notificar um sistema externo (POST) e guardar a resposta

Objetivo: avisar o sistema de retaguarda que o pagamento foi confirmado e guardar o retorno para uso posterior.

Depois desta caixa, dialog.get('respostaApi') devolve o objeto com .statusCode e .body para as caixas seguintes.

Exemplo 3 — Fluxo de demanda externa (padrão do assistente)

Objetivo: entender onde a caixa aparece em um fluxo real. O assistente de criação de fluxo “Fluxo externo” gera um atendimento que recebe um pedido de um sistema externo, cria o ticket e usa caixas API Key para chamar o endpoint do parceiro com X-API-KEY nas transições do pedido (processar, finalizar, recusar, corrigir), sempre desviando para a próxima etapa em caso de sucesso.

O formato gerado é o mesmo dos exemplos acima: dialog.rest({"X-API-KEY": ...}, url, "post", ...) com a navegação de sucesso configurada.

Validações e mensagens comuns

Ao aplicar a caixa, o builder verifica:

Os demais campos não são validados pelo builder — uma URL vazia ou malformada só falha na execução. Confira a URL antes de publicar.

Diferença entre “API Key”, “Requisição REST” e “WebHook”

• API Key: requisição HTTP com o cabeçalho X-API-KEY fixo, informado em um campo próprio. É a forma mais direta de chamar uma API com esse padrão de autenticação.
• Requisição REST: requisição HTTP com controle total dos cabeçalhos — use quando a autenticação não for X-API-KEY (Bearer, Basic, assinaturas).
• WebHook: cria um endpoint recebido (o sistema externo chama o fluxo), e não uma chamada de saída.

Todas as caixas de requisição usam o mesmo comando de runtime (dialog.rest) e o mesmo formato de resposta (statusCode/body).

Boas práticas

• Prefira ler a chave de uma variável de sessão ({{chaveApi}}) em vez de deixá-la fixa no fluxo — assim a chave pode ser trocada sem editar o diagrama.
• Configure sempre a caixa de falha: API pode estar fora, demorar ou recusar a chave. Sem falha configurada, a conversa fica sem caminho quando a requisição não retorna 2xx.
• Use GET para consultas e POST/PUT para operações que alteram dados; lembre de que o corpo só aparece fora do GET.
• Faça JSON.parse do corpo antes de usar os campos, e proteja o parse — corpo vazio ou inválido derruba o script (no modo Executar script, o erro desvia para a falha).
• Dê nomes funcionais às caixas (Consultar status do pedido em vez de API Key 1).
• Teste os dois caminhos (sucesso e falha) antes de publicar a versão do fluxo.