---
title: "API Key"
slug: "api-key"
updated: 2026-09-14T17:03:16Z
published: 2026-09-14T17:03:16Z
canonical: "docs.omnisiga.ai/api-key"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Opção | Comportamento |
| --- | --- |
| **Executar script** | Mostra o editor **“Script a executar após a requisição”**. O script roda com `restResponse` (`statusCode` e `body`) disponível. Se houver caixa de falha configurada, o script é protegido: erro de execução desvia para a falha. |
| **Armazenar resposta** | Grava o objeto `restResponse` inteiro na variável informada em **Nome da variável de armazenamento da resposta**. Nas próximas caixas, leia com `dialog.get('variavel')` e acesse `.statusCode` e `.body`. |

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:

| Marcador | Efeito no script gerado |
| --- | --- |
| `{{variavel}}` | vira `dialog.get('variavel')` — lê a variável de sessão na execução |
| `{{!codigo}}` | insere a expressão JavaScript informada |
| texto puro | vira string literal |

```
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.

| Campo | Valor |
| --- | --- |
| Nome | `Consultar status do pedido` |
| URL de destino | `https://api.exemplo.com/pedidos/{{pedidoId}}` |
| Método da requisição | `GET` |
| X-API-KEY | `{{chaveApi}}` |
| Tratamento | `Executar script` |
| Em caso de sucesso... vai para | `Informar status` |
| Caso haja alguma falha... vai para | `Avisar indisponibilidade` |

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.

| Campo | Valor |
| --- | --- |
| Nome | `Notificar pagamento` |
| URL de destino | `https://api.exemplo.com/eventos` |
| Método da requisição | `POST` |
| X-API-KEY | `abc123` |
| Cabeçalho da requisição | `Content-Type` = `application/json` |
| Corpo da requisição | `{"protocolo": "{{protocolo}}", "evento": "pagamento-confirmado"}` |
| Tratamento | `Armazenar resposta` |
| Nome da variável de armazenamento da resposta | `respostaApi` |
| Em caso de sucesso... vai para | `Confirmar ao cliente` |
| Caso haja alguma falha... vai para | `Registrar falha` |

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:

| Situação | Mensagem |
| --- | --- |
| Campo X-API-KEY vazio | “O campo X-API-KEY deve ser preenchido” |

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.