---
title: Entrada por API (outro sistema inicia)
slug: helper/entrada-por-api-outro-sistema-inicia
createdAt: 2026-11-19T14:26:40.595Z
---

## Rotas de API — outro sistema iniciando o atendimento

Serve para um **sistema externo** (uma URA, um portal do cidadão, um app, um outro bot) **iniciar e dirigir um atendimento** no seu fluxo — começando **no ponto exato** que você quiser, já com os dados em mãos.

Exemplo: o cidadão ligou na central de atendimento, escolheu "2ª via" no menu de voz e pediu para continuar no WhatsApp. A central chama a nossa API dizendo "abre o atendimento de 2ª via para este telefone, com este CPF e este protocolo". Quando o cidadão manda a primeira mensagem no WhatsApp, o bot **já começa na 2ª via**, sem repetir menu.

### Como funciona (visão geral)

1. No fluxo, você adiciona o bloco **Início por API** no ponto onde a conversa deve começar e dá um **endereço (slug)** a ele.
2. Ao **publicar**, esse bloco vira uma **rota** — uma URL que o sistema externo chama.
3. Em **Administração › Integrações › Entrada por API** você **gera uma chave** e **copia o contrato** para entregar a quem vai integrar.
4. O sistema externo chama a rota (`start`). O atendimento fica **armado**.
5. O cidadão manda a primeira mensagem no canal → o bot **abre no bloco da rota**, com as variáveis já preenchidas.

### Uma slug por tema

Sim. **Cada bloco "Início por API" tem sua própria slug** — então você abre **quantas rotas quiser**, uma para cada assunto, apontando para partes diferentes do fluxo:

| Endereço                              | Começa em           | Recebe         |
| ------------------------------------- | ------------------- | -------------- |
| `POST /api/flow/segunda-via/sessions` | ramo da 2ª via      | cpf            |
| `POST /api/flow/agendamento/sessions` | ramo de agendamento | cpf, data      |
| `POST /api/flow/divida/sessions`      | ramo de negociação  | cpf, protocolo |

É assim que "acionar o fluxo em qualquer lugar" acontece: o **ponto de entrada é o bloco** onde você colocou o Início por API. Arraste-o para onde quiser, ligue no ramo certo, dê a slug — pronto.

### Campos que você recebe

No bloco você define as **variáveis obrigatórias** (ex.: `cpf`, `protocolo`). A chamada **precisa** enviá-las; sem elas a API **recusa** (não abre atendimento sem os dados). Elas ficam disponíveis no fluxo como `{{cpf}}`, `{{protocolo}}`, etc. `telefone` e `protocolo` da chamada entram automaticamente no contexto.

### Autenticação

Toda chamada leva:

- **`X-Api-Key`** — a chave gerada em Rotas de API (identifica o seu workspace).
- **`X-Signature`** — `HMAC-SHA256` do corpo (bytes) usando o **segredo** da chave, em hexadecimal. Obrigatório em `POST`, `PATCH` e `DELETE`.

### Os endereços (verbos)

### Iniciar — `POST /api/flow/{slug}/sessions`

Corpo:

```javascript
{
  "telefone": "+5561999990000",
  "protocolo": "PROTO-123",
  "modo": "armar",
  "variaveis": { "cpf": "12345678909" }
}
```

- `telefone` — obrigatório, formato internacional (E.164).
- `protocolo` — opcional; serve de **idempotência** (repetir a mesma chamada não abre duas conversas, devolve a existente).
- `modo` — `armar` (padrão: o cidadão fala primeiro) ou `proativo` (o bot fala primeiro — requer template aprovado, *em breve*).
- `variaveis` — as obrigatórias da rota + quaisquer outras livres.

Resposta **202**:

```javascript
{ "session_id": "…", "estado": "armada", "protocolo": "PROTO-123", "telefone": "+5561999990000" }
```

### Consultar — `GET /api/flow/sessions/{session_id}`

Devolve o estado (`armada` → `ativa` → `encerrada`), o `conversa_id` quando o atendimento abre, e as variáveis. Precisa só de `X-Api-Key`.

### Atualizar — `PATCH /api/flow/sessions/{session_id}`

Injeta/atualiza variáveis do atendimento (mescla com as existentes).

```javascript
{ "variaveis": { "status_pagamento": "confirmado" } }
```

### Encerrar — `DELETE /api/flow/sessions/{session_id}`

Marca a sessão como encerrada.

### Exemplo de ponta a ponta (curl)

```javascript
# 1) o sistema externo inicia o atendimento de "2ª via" para o telefone
curl -X POST 'https://SEU-DOMINIO/api/flow/segunda-via/sessions' \
  -H 'X-Api-Key: ak_xxx' \
  -H 'X-Signature: <HMAC_SHA256_do_corpo_com_o_segredo>' \
  -H 'Content-Type: application/json' \
  -d '{"telefone":"+5561999990000","protocolo":"P-777","variaveis":{"cpf":"12345678909"}}'
# -> 202 { "session_id": "abc", "estado": "armada" }

# 2) (opcional) consulta depois
curl 'https://SEU-DOMINIO/api/flow/sessions/abc' -H 'X-Api-Key: ak_xxx'
```

O cidadão manda a primeira mensagem no WhatsApp e o bot abre na 2ª via, com `{{cpf}}` e `{{protocolo}}` prontos.

### Onde isto fica

**Administração › Integrações**, na seção **Entrada por API** — no fim da página, depois das conexões. Os dois assuntos moram juntos de propósito: em cima, a plataforma chamando um sistema de fora; embaixo, um sistema de fora chamando a plataforma. É a mesma pergunta ("o que está conectado?") pelos dois lados.

:inlineImage[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/AKcgQBK2MJv5KHn5hblFA_bed294d9aaad8460e81d0d6831589b2c.jpg" alt="Chaves de entrada e rotas publicadas, com o contrato de cada uma" caption size="160" width="1600" height="911"} *Chaves de entrada e rotas publicadas, com o contrato de cada uma*

### Chaves de entrada

Cada chave identifica quem está chamando. No chaveiro você pode:

| Ação                      | O que acontece                                            |
| ------------------------- | --------------------------------------------------------- |
| **Gerar chave**           | cria o par chave + segredo                                |
| **Copiar o segredo**      | o segredo aparece **uma única vez**, na hora da criação   |
| **Revogar**               | a chave para de ser aceita na hora                        |
| **Reativar**              | volta a valer, sem precisar gerar outra                   |
| **Esconder as revogadas** | tira do caminho o que já não vale, sem apagar o histórico |

### Rotas publicadas — e o contrato

Cada bloco "Início por API" de um fluxo publicado abre uma rota. Cada rota tem o documento pronto — método, endereço, cabeçalhos, corpo esperado e um `curl` de exemplo — para você copiar e entregar ao integrador, sem escrever nada à mão. **Ver o contrato completo** abre tudo; os botões de copiar pegam o endereço, o caminho ou o exemplo inteiro.

### Relatório de disparos de uma campanha

Outro sistema consulta o que cada disparo de uma campanha deu, com a mesma chave de entrada. São os mesmos campos do **Exportar** da aba Disparos.

`GET /api/disparos/public/campaigns/{campanha_id}/dispatches`

| Parâmetro | O que faz                                                          |
| --------- | ------------------------------------------------------------------ |
| `page`    | página, a partir de 1                                              |
| `limit`   | linhas por página, de 1 a 5000 (padrão 500)                        |
| `status`  | só os disparos nessa situação: sent, delivered, read, failed…      |
| `day`     | só os disparos criados nesse dia (AAAA-MM-DD, horário de Brasília) |

```javascript
curl -s "https://SEU-ENDERECO/api/disparos/public/campaigns/ID-DA-CAMPANHA/dispatches?limit=5000&page=1" \
  -H "X-Api-Key: SUA-CHAVE"
```

```javascript
{"items": [{"Campanha": "Aviso de corte", "Canal": "WhatsApp", "DataDisparo": "12/11/2026", "HoraDisparo": "17:42:18",
  "NomeCliente": "ACME LTDA", "Telefone": "5561999990001", "Situacao": "Erro", "SituacaoEnvio": "Destinatário sem WhatsApp",
  "CodigoErro": "131026", "DescricaoErro": "Message undeliverable, (#131026) Message Undeliverable. (Gupshup 131026)",
  "CPC": "N/A", "RespostaUsuario": "Não", "DataResposta": "", "HoraResposta": "", "UltimaResposta": ""}],
 "total": 29357, "page": 1, "limit": 5000}
```

A chave vai em `X-Api-Key` ou `Authorization: Bearer`. A chave criada junto com uma campanha **Via API** lê só a campanha dela; as demais leem qualquer campanha do workspace.

| Campo             | Valores                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `Situacao`        | Concluido (saiu da plataforma), Erro, Em processamento (ainda na fila) |
| `SituacaoEnvio`   | Envio confirmado, Aguardando envio ou o motivo da falha em uma frase   |
| `CodigoErro`      | o código do fornecedor ou da plataforma; N/A quando não houve erro     |
| `CPC`             | Sim, Não ou N/A (a campanha não confirma a pessoa certa)               |
| `RespostaUsuario` | Sim ou Não; data, hora e texto são da última resposta                  |
| `UltimaResposta`  | o texto da última resposta em uma linha, até 30 caracteres             |

Respostas de erro: 401 sem chave ou chave inválida, 403 chave de outra campanha, 404 campanha inexistente, 422 limit fora de 1 a 5000, 429 acima do teto de consultas por minuto da mesma chave (60, por padrão).

### Indicadores de atendimento

Outro sistema consulta os números dos painéis de fila e de agentes de um dia ou de um período, com a mesma chave de entrada.

`GET /api/atendimento/public/indicators`

| Parâmetro       | O que faz                                       |
| --------------- | ----------------------------------------------- |
| `day`           | um dia só (AAAA-MM-DD, horário de Brasília)     |
| `start` e `end` | um período, os dois juntos; no máximo 366 dias  |
| `assistant`     | só os atendimentos desse assistente (o id dele) |

Use `day` **ou** `start` e `end`. A chave vai em `X-Api-Key` ou `Authorization: Bearer`.

```javascript
curl -s "https://SEU-ENDERECO/api/atendimento/public/indicators?day=2026-11-12" \
  -H "X-Api-Key: SUA-CHAVE"
```

```javascript
{"periodo": {"inicio": "2026-11-12", "fim": "2026-11-12"}, "assistente": null,
 "totais": {"atendimentos_total": 7, "somente_bot": 1, "resolvidos_pela_ia": 0, "somente_humano": 1,
   "taxa_derivacao_humano": 0.5714, "atendimentos_encerrados": 7, "bot_para_atendente": 3, "desistencias": 2,
   "taxa_desistencia": 0.2857, "escalados_pela_ia": 1, "espera_media_seg": 120.0, "espera_ate_desistir_seg": 900.0,
   "tempo_medio_atendimento_seg": 480.0, "csat_media": null, "csat_respostas": 0, "atendentes_ativos": 1,
   "tempo_disponivel_seg": 10800.0, "tempo_em_pausa_seg": 3600.0, "pausas": 1, "pausas_acima_do_previsto": 0},
 "por_dia": [{"dia": "2026-11-12", "atendimentos_encerrados": 7, "bot_para_atendente": 3}],
 "por_canal": [{"canal": "widget", "atendimentos_encerrados": 6, "bot_para_atendente": 3}],
 "por_fila": [{"fila": "suporte", "atendimentos_encerrados": 6, "bot_para_atendente": 3}],
 "por_hora": [{"hora": "14h", "atendimentos_encerrados": 7, "bot_para_atendente": 3}],
 "por_atendente": [{"atendente": "ana@orgao.gov.br", "atendimentos_encerrados": 3, "pausas": 1}],
 "por_motivo": [{"motivo": "agente", "quantidade": 4}],
 "pausas_por_tipo": [{"pausa": "Almoço", "pausas": 1, "tempo_seg": 3600.0}]}
```

Cada item de `por_dia` e `por_canal` traz os mesmos campos de totais; o exemplo mostra só alguns. `por_fila` não traz os campos de quem atendeu: conversa que ficou no bot não tem fila. Dia, canal ou fila sem movimento no período não aparece.

| Campo                                        | O que é                                                                                                                |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `atendimentos_total`                         | todos os atendimentos encerrados no período: só bot, IA e com atendente                                                |
| `somente_bot`                                | terminaram no bot, sem ir para fila                                                                                    |
| `resolvidos_pela_ia`                         | a IA resolveu sem passar para um atendente                                                                             |
| `somente_humano`                             | chegaram ao atendente sem passar por bot (e-mail)                                                                      |
| `taxa_derivacao_humano`                      | % Derivação para Humano: do total, a fatia que um atendente atendeu (bot\_para\_atendente + somente\_humano), de 0 a 1 |
| `atendimentos_encerrados`                    | atendimentos humanos encerrados no período, com as desistências                                                        |
| `bot_para_atendente`                         | saíram da IA ou do menu para uma fila e um atendente assumiu                                                           |
| `desistencias`, `taxa_desistencia`           | entraram na fila e saíram antes de alguém assumir; a taxa vai de 0 a 1                                                 |
| `escalados_pela_ia`                          | atendimentos que a IA passou para um atendente                                                                         |
| `espera_media_seg`                           | média de espera na fila de quem foi atendido, em segundos                                                              |
| `espera_ate_desistir_seg`                    | média de espera de quem desistiu, em segundos                                                                          |
| `tempo_medio_atendimento_seg`                | duração média do atendimento humano, em segundos                                                                       |
| `csat_media`, `csat_respostas`               | nota média e quantidade de avaliações                                                                                  |
| `atendentes_ativos`                          | pessoas que ficaram disponíveis em algum momento                                                                       |
| `tempo_disponivel_seg`, `tempo_em_pausa_seg` | soma do tempo disponível e do tempo em pausa                                                                           |
| `pausas`, `pausas_acima_do_previsto`         | pausas iniciadas e as que passaram do tempo cadastrado                                                                 |

Média sem dado no período vem `null`; contagem vem 0. Com `assistant`, os campos de jornada do atendente (`atendentes_ativos`, tempos e pausas) e `pausas_por_tipo` não vêm: a pausa é da pessoa, não do assistente.

Respostas de erro: 401 sem chave ou chave inválida, 404 assistente inexistente, 422 período ausente, invertido, acima de 366 dias ou `day` junto com `start`/`end`, 429 acima do teto de consultas por minuto da mesma chave (30, por padrão).

### Detalhe dos atendimentos

Atendimento a atendimento do período, com os marcos de cada um, para o outro sistema montar os próprios índices. Entram os que ficaram só no bot, os que a IA resolveu e os que foram para um atendente.

`GET /api/atendimento/public/conversations`

| Parâmetro       | O que faz                                       |
| --------------- | ----------------------------------------------- |
| `day`           | um dia só (AAAA-MM-DD, horário de Brasília)     |
| `start` e `end` | um período, os dois juntos; no máximo 366 dias  |
| `assistant`     | só os atendimentos desse assistente (o id dele) |
| `page`          | página, a partir de 1                           |
| `limit`         | linhas por página, de 1 a 5000 (padrão 500)     |

O dia é o do encerramento. A lista sai do atendimento mais antigo para o mais novo.

```javascript
curl -s "https://SEU-ENDERECO/api/atendimento/public/conversations?day=2026-11-12&limit=5000&page=1" \
  -H "X-Api-Key: SUA-CHAVE"
```

```javascript
{"items": [{"Id_Conversa": "0b9f6c1e-3d2a-4a57-9c0e-5f1f6f1f7a10", "Protocolo": "2026-000777",
   "Inicio_Bot": "2026-11-12T09:22:28-03:00", "Final_Bot": "2026-11-12T09:24:28-03:00",
   "Entrada_Fila": "2026-11-12T09:24:28-03:00", "Inicio_Hmn": "2026-11-12T09:25:28-03:00",
   "Final_Hmn": "2026-11-12T09:32:28-03:00", "Canal_Atend": "gupshup", "Servico": "Central 156",
   "Nome_Cliente": "Maria da Silva", "Fone_Cliente": "5561999990001", "Situacao": "Concluído",
   "Tmp_Atend_Bot": 120, "Tmp_Fila_Hmn": 60, "Tmp_Atend_Hmn": 420, "Finalizacao": "Agente",
   "Motivo": "agente", "Tempo_Total": 600, "Operador": "ana@orgao.gov.br", "Grupo_Resp": "suporte"}],
 "total": 5231, "page": 1, "limit": 5000}
```

| Campo                                                           | O que é                                                                                       |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `Id_Conversa`, `Protocolo`                                      | identificador do atendimento e o protocolo, quando houve                                      |
| `Inicio_Bot`, `Final_Bot`                                       | primeira mensagem do atendimento e o momento em que saiu do bot (foi para a fila ou terminou) |
| `Entrada_Fila`, `Inicio_Hmn`, `Final_Hmn`                       | entrou na fila, o atendente assumiu, o atendimento terminou; vazios quando não houve          |
| `Canal_Atend`, `Servico`                                        | canal e nome do assistente                                                                    |
| `Nome_Cliente`, `Fone_Cliente`                                  | nome do contato e o identificador dele no canal (o telefone, no WhatsApp)                     |
| `Tmp_Atend_Bot`, `Tmp_Fila_Hmn`, `Tmp_Atend_Hmn`, `Tempo_Total` | tempo no bot, na fila, com o atendente e do início ao fim, em segundos                        |
| `Finalizacao`                                                   | Bot, IA, Agente ou Sem atendente (entrou na fila e saiu antes de alguém assumir)              |
| `Motivo`                                                        | como terminou: agente, inatividade, fim\_fluxo, a tabulação escolhida pelo atendente…         |
| `Operador`, `Grupo_Resp`                                        | login do atendente (AutoAtendimento no bot e na IA) e a fila                                  |

Datas em ISO 8601, no horário de Brasília. `Situacao` é sempre Concluído: a lista traz só atendimento encerrado.

Respostas de erro: 401 sem chave ou chave inválida, 404 assistente inexistente, 422 período ausente, invertido, acima de 366 dias, `day` junto com `start`/`end` ou `limit` fora de 1 a 5000, 429 acima do teto de consultas por minuto da mesma chave (60, por padrão).
