---
title: Integration API
description: Endpoints para integração com a plataforma Atende Direito via Flow Token.
---

# Integration API

A **Integration API** expõe endpoints RESTful para acessar e manipular dados do Atende Direito de forma programática. Todas as rotas requerem autenticação via token do workspace e estão disponíveis sob o prefixo `/api/flow/`.

<Dica>

Os endpoints da Integration API são projetados para serem chamados a partir de fluxos no Flow Builder (via nó **Requisição HTTP**), webhooks externos ou automações — não via MCP. Use-os quando você precisar de uma integração direta com a plataforma sem passar por um servidor intermediário.

</Dica>

## Autenticação

Toda requisição à Integration API deve incluir o header de autenticação:

```
X-Flow-Token: {workspace_token}
```

Onde `{workspace_token}` é o token do workspace gerado na plataforma. Sem esse header, a requisição retorna status `401 Unauthorized`.

---

## Endpoints disponíveis

A Integration API oferece operações em vários recursos: **conversas**, **mensagens**, **contatos**, **tags**, **pipelines**, **produtos**, **automações** e mais. Abaixo estão documentados em detalhe o endpoint de geração de PDF de transcript de conversa e os endpoints de consulta de mensagens por contato.

**Telefone de contatos**: nos endpoints que recebem telefone (ex.: criação de contato em `POST /api/flow/contacts`), envie números estrangeiros com `+` e DDI (ex.: `+44 7911 123456`). Sem `+`, números de 10 ou 11 dígitos (DDD + número) são interpretados como brasileiros. O valor é gravado em formato E.164 só com dígitos (`447911123456`). Número inválido retorna **422** com erro no campo `phone`.

### Gerar PDF do Transcript de Conversa

Renderiza o histórico completo de mensagens de uma conversa em PDF via Gotenberg (chromium headless) e retorna a URL pública do arquivo salvo.

**Requisição:**

```
POST /api/flow/conversations/{id}/transcript-pdf
```

| Parâmetro | Localização | Descrição |
|-----------|-------------|-----------|
| `id` | Path | ID da conversa (ULID ou UUID) |
| `X-Flow-Token` | Header | Token de autenticação do workspace |

**Resposta de sucesso (200):**

```json
{
  "data": {
    "url": "https://cdn.exemplo.com/transcripts/{workspace_id}/{conversation_id}/{ulid}.pdf",
    "file_key": "transcripts/{workspace_id}/{conversation_id}/{ulid}.pdf"
  }
}
```

| Campo | Descrição |
|-------|-----------|
| `url` | URL pública do PDF, acessível para download ou exibição no navegador |
| `file_key` | Chave do arquivo no storage do workspace (usado internamente para referência) |

**Respostas de erro:**

- **404 Not Found**: conversa não encontrada no workspace
  ```json
  {}
  ```

- **502 Bad Gateway**: falha ao gerar o PDF (serviço de geração de PDF indisponível ou erro na renderização)
  ```json
  {
    "error": "Falha ao gerar PDF",
    "message": "Não foi possível gerar o PDF da conversa: [motivo técnico]"
  }
  ```

### Conteúdo do PDF

O PDF gerado inclui:
- **Cabeçalho**: nome do contato, número de telefone, data/hora de início da conversa
- **Corpo**: histórico completo de mensagens com:
  - Remetente (Contato, Atendente, Assistente virtual ou Sistema)
  - Data/hora de envio
  - Conteúdo da mensagem (texto) ou placeholder para mídia (p. ex., `[imagem]`, `[áudio]`, `[vídeo]`, `[documento: nome.pdf]`)
- **Rodapé**: data/hora de geração do PDF

<Aviso>

O PDF contém o transcript completo da conversa, incluindo informações pessoais (PII). Armazene-o de forma segura e garanta que apenas usuários autorizados do workspace tenham acesso ao link.

</Aviso>

### Última Mensagem do Contato

Retorna a última mensagem enviada ou recebida do contato **no canal informado**, com informações da conversa relacionada.

<Aviso>

O histórico de mensagens é **isolado por canal**: `channel_id` é obrigatório e o retorno contém apenas mensagens daquele canal específico. Se o contato conversou pelo WhatsApp e pelo Instagram, por exemplo, são duas consultas separadas (uma por `channel_id`) — não existe mais um endpoint que retorne "o histórico completo do contato" somando todos os canais.

</Aviso>

**Requisição:**

```
GET /api/flow/contacts/{id}/last-message
```

| Parâmetro | Localização | Descrição |
|-----------|-------------|-----------|
| `id` | Path | ID do contato (ULID) |
| `channel_id` | Query | **Obrigatório.** ID do canal (ULID) ao qual restringir a busca |
| `X-Flow-Token` | Header | Token de autenticação do workspace |

**Resposta de sucesso (200):**

```json
{
  "data": {
    "id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
    "conversation_id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
    "content": "Última mensagem",
    "message_type": "text",
    "sender_type": "contact",
    "sent_at": "2026-01-28T10:00:00-03:00",
    "conversation": {
      "id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
      "status": "open"
    }
  }
}
```

**Respostas de erro:**

- **422 Unprocessable Entity**: `channel_id` não informado na query
  ```json
  {
    "error": "Canal não informado",
    "message": "O parâmetro channel_id é obrigatório: o histórico de mensagens é isolado por canal."
  }
  ```

- **404 Not Found**: contato não encontrado no workspace
  ```json
  {
    "error": "Contato não encontrado",
    "message": "Nenhum contato encontrado com o ID informado."
  }
  ```

- **404 Not Found**: `channel_id` não corresponde a um canal do workspace
  ```json
  {
    "error": "Canal não encontrado",
    "message": "Nenhum canal encontrado com o channel_id informado neste workspace."
  }
  ```

- **404 Not Found**: contato ainda não possui mensagens no canal informado
  ```json
  {
    "error": "Mensagem não encontrada",
    "message": "Este contato ainda não possui mensagens"
  }
  ```

### Histórico de Mensagens do Contato

Retorna, de forma paginada, as mensagens das conversas do contato **no canal informado**.

<Aviso>

Assim como no endpoint de última mensagem, `channel_id` é obrigatório e o histórico é isolado por canal — nenhuma mensagem de outro canal é retornada, mesmo pertencendo ao mesmo contato.

</Aviso>

**Requisição:**

```
GET /api/flow/contacts/{id}/messages
```

| Parâmetro | Localização | Descrição |
|-----------|-------------|-----------|
| `id` | Path | ID do contato (ULID) |
| `channel_id` | Query | **Obrigatório.** ID do canal (ULID) ao qual restringir a busca |
| `page` | Query | Página atual (inicia em 1) |
| `per_page` | Query | Quantidade de mensagens por página (máximo 100, padrão 20) |
| `message_type` | Query | Filtro opcional por tipo de mensagem (ex.: `text`, `image`, `video`, `audio`, `document`) |
| `X-Flow-Token` | Header | Token de autenticação do workspace |

**Resposta de sucesso (200):**

```json
{
  "data": [
    {
      "id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
      "conversation_id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
      "content": "Olá",
      "message_type": "text",
      "media_url": null,
      "media_type": null,
      "sender_type": "contact",
      "sent_at": "2026-01-28T10:00:00-03:00",
      "read_at": null,
      "remote_message_id": null,
      "conversation": {
        "id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
        "channel_id": "01HQ8V9X7Y6DWRZ3KP5MC4JTNH",
        "channel_name": "WhatsApp Principal",
        "status": "open"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 50,
    "last_page": 3
  }
}
```

As mensagens são ordenadas por `sent_at` decrescente (mais recente primeiro). Cada item pode incluir opcionalmente `quoted_message` (`id`, `content`, `message_type`) quando a mensagem for uma resposta a outra mensagem.

**Respostas de erro:**

- **422 Unprocessable Entity**: `channel_id` não informado na query — mesmo formato do endpoint de última mensagem acima
- **404 Not Found**: contato não encontrado no workspace — mesmo formato do endpoint de última mensagem acima
- **404 Not Found**: `channel_id` não corresponde a um canal do workspace — mesmo formato do endpoint de última mensagem acima

---

## Exemplo: Usar no Flow Builder

**Caminho recomendado — Ferramenta MCP (sem credencial no fluxo):**

O jeito mais limpo é usar o nó **Ferramenta MCP** com o servidor interno Atende Direito:

<Passos>
  <Passo>Arraste um nó **Ferramenta MCP** para o canvas.</Passo>
  <Passo>Configure:
    - **Servidor MCP**: selecione **Atende Direito** (aparece como "Interno" no catálogo).
    - **Ferramenta**: escolha `generateConversationTranscriptPdf`.
    - **Parâmetros**: 
      - `conversation_id`: <code v-pre>{{event.conversation_id}}</code> (preenchido automaticamente com a conversa atual quando omitido em contexto de agent).
  </Passo>
  <Passo>Salve e conecte a saída. A URL do PDF estará em <code v-pre>{{node_{id_do_no}.output.data.url}}</code>.</Passo>
  <Passo>Para capturar a URL, use: <code v-pre>{{node_{id_do_no}.output.data.url}}</code> em qualquer nó posterior (p. ex., Enviar Mensagem, Atribuir Variável, Ação na Plataforma).</Passo>
</Passos>

**Exemplo completo: Trigger conversa fechada → Gerar PDF via MCP → Guardar URL em campo customizado**

```flow
[Trigger: Conversa Fechada] 
  → [Ferramenta MCP: generateConversationTranscriptPdf com {{event.conversation_id}}]
  → [Ação na Plataforma: add_custom_field com {{node_mcp.output.data.url}}]
```

---

**Alternativa — Requisição HTTP (para integrações externas como n8n):**

Se você precisa integrar com um serviço externo (n8n, Zapier, etc.), use o nó **Requisição HTTP**:

<Passos>
  <Passo>Arraste um nó **Requisição HTTP** para o canvas.</Passo>
  <Passo>Configure:
    - **Método**: `POST`
    - **URL**: <code v-pre>https://seu-dominio.com/api/flow/conversations/{{event.conversation_id}}/transcript-pdf</code>
    - **Autenticação**: selecione `API Key` com header customizado `X-Flow-Token` e use uma **credencial** do workspace (o token nunca fica exposto no grafo do fluxo).
    - **Body**: (deixe vazio para POST sem corpo)
  </Passo>
  <Passo>Salve e conecte a saída. A resposta estará em <code v-pre>{{http.body.data}}</code>.</Passo>
  <Passo>Para capturar a URL, use: <code v-pre>{{http.body.data.url}}</code> em qualquer nó posterior.</Passo>
</Passos>

---

## Saiba mais

- [Ferramenta MCP](/guia/flow-builder/acoes/ferramenta-mcp) — nó determinístico sem LLM
- [Requisição HTTP](/guia/flow-builder/dados/http) — como configurar chamadas HTTP no canvas
- [Referência MCP](/dev/referencia) — autenticação e limites da Integration API