Atende Direito · Docs

Tema

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.

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âmetroLocalizaçãoDescrição
idPathID da conversa (ULID ou UUID)
X-Flow-TokenHeaderToken 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"
  }
}
CampoDescrição
urlURL pública do PDF, acessível para download ou exibição no navegador
file_keyChave 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

Última Mensagem do Contato ​

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

Requisição:

GET /api/flow/contacts/{id}/last-message
ParâmetroLocalizaçãoDescrição
idPathID do contato (ULID)
channel_idQueryObrigatório. ID do canal (ULID) ao qual restringir a busca
X-Flow-TokenHeaderToken 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.

Requisição:

GET /api/flow/contacts/{id}/messages
ParâmetroLocalizaçãoDescrição
idPathID do contato (ULID)
channel_idQueryObrigatório. ID do canal (ULID) ao qual restringir a busca
pageQueryPágina atual (inicia em 1)
per_pageQueryQuantidade de mensagens por página (máximo 100, padrão 20)
message_typeQueryFiltro opcional por tipo de mensagem (ex.: text, image, video, audio, document)
X-Flow-TokenHeaderToken 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:

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

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:

  1. Arraste um nó **Requisição HTTP** para o canvas.
  2. Configure: - **Método**: `POST` - **URL**: https://seu-dominio.com/api/flow/conversations/{{event.conversation_id}}/transcript-pdf - **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)
  3. Salve e conecte a saída. A resposta estará em {{http.body.data}}.
  4. Para capturar a URL, use: {{http.body.data.url}} em qualquer nó posterior.

Saiba mais ​