Bots API

Usar a IA da Sendeasy a partir da sua própria aplicação — um assistente dentro do seu produto, uma rotina no seu backend, uma tela que resume documentos — sem passar pelo WhatsApp.

O bot é quem carrega as instruções: você o cria e edita no painel, e aqui informa o botId. Trocar o comportamento da IA é editar o bot, não mudar o seu código.

Pré-requisitos

1. API Token do projeto — em Integrações → WABA → seção de API Tokens, onde você cria um token com nome e pode revogá-lo. É o mesmo token da WABA API e da E-mail API: um por projeto, não um por produto.
2. Um bot criado no painel, com as instruções e as fontes de conhecimento — veja /bot. Guarde o botId.
3. Créditos de bot disponíveis no plano do projeto.

Use GET /api/v1/ai/health para conferir a integração sem gastar crédito.

Autenticação

Header obrigatório:

Authorization: Bearer <api_token>

O token identifica o projeto, e é ele que autoriza o botId: um bot de outro projeto é recusado, mesmo que você saiba o id.

Endpoints

Limite: 60 requisições por minuto por API Token (429 ERR_PUBLIC_AI_RATE_LIMIT). A contagem é por token, não por IP — vários servidores usando o mesmo token dividem a cota, e o mesmo servidor com tokens diferentes tem cotas separadas.

Geração de texto

POST /api/v1/ai/completion

Payload

Informe botId ou instructions. Sem nenhum dos dois a rota responde 400, em vez de gastar crédito para devolver texto fora de contexto.

Exemplo

curl --location 'https://backend.sendeasy.app/api/v1/ai/completion' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "botId": "seu-bot-id",
    "prompt": "Resuma em dois parágrafos a política de trocas."
  }'

Resposta de sucesso:

{
  "success": true,
  "result": "A política de trocas permite devolução em até 30 dias..."
}

Com "responseFormat": "json", a resposta vem parseada em dados no lugar de result — útil quando o prompt pede uma estrutura e você não quer tratar o texto:

{
  "success": true,
  "dados": { "prazo_dias": 30, "exige_nota": true }
}

Extração de PDF

POST /api/v1/ai/extract

Envio multipart/form-data com o arquivo no campo file. Apenas PDF, até 25 MB.

curl --location 'https://backend.sendeasy.app/api/v1/ai/extract' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --form 'file=@"/caminho/contrato.pdf"' \
  --form 'mode="text"'

{
  "success": true,
  "result": "CONTRATO DE PRESTAÇÃO DE SERVIÇOS..."
}

A leitura usa OCR quando o PDF é digitalizado, então arquivos grandes demoram. Se a IA não reconhecer o conteúdo, a resposta é 502 com a explicação do porquê — repetir o envio do mesmo arquivo não resolve.

Busca na base de conhecimento

POST /api/v1/ai/search

Recupera trechos das fontes do bot, sem gerar texto. Serve para fundamentar uma resposta sua, ou para mostrar a origem da informação ao usuário.

filters aceita dois campos, ambos listas de padrões de nome de arquivo (% casa qualquer trecho):

{
  "botId": "seu-bot-id",
  "query": "prazo de garantia",
  "filters": {
    "incluirArquivos": ["manual-%", "politica-trocas.pdf"],
    "excluirArquivos": ["rascunho-%"]
  }
}

Vale quando a base é grande e você já sabe onde a resposta está: sem filtro, um documento extenso pode ocupar as vagas do resultado e abafar o que interessa.

curl --location 'https://backend.sendeasy.app/api/v1/ai/search' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "botId": "seu-bot-id",
    "query": "prazo de garantia",
    "topK": 3
  }'

{
  "success": true,
  "trechos": [
    {
      "texto": "A garantia legal é de 90 dias para produtos duráveis...",
      "procedencia": "manual-do-cliente.pdf",
      "score": 0.82
    }
  ]
}

Não consome crédito: é recuperação de conteúdo, não geração. Se a busca falhar, a resposta vem com trechos: [] em vez de erro — sem contexto a sua resposta perde fundamentação, não deixa de existir.

Diagnóstico da integração

GET /api/v1/ai/health

Não consome crédito e não aciona o modelo. Responde as duas perguntas que explicam quase toda falha de integração: o serviço de IA está no ar e ainda há saldo?

curl --location 'https://backend.sendeasy.app/api/v1/ai/health' \
  --header 'Authorization: Bearer SEU_API_TOKEN'

{
  "success": true,
  "companyId": 42,
  "botrag": { "ok": true, "latenciaMs": 210 },
  "creditos": { "disponivel": 4820, "mes": "9/2026" },
  "checkedAt": "2026-09-01T12:30:00.000Z"
}

• botrag.ok: false — o serviço de IA está indisponível; um campo detalhe acompanha a causa. Nada a fazer do seu lado além de repetir depois.
• creditos.disponivel: 0 — o projeto ficou sem créditos e as rotas de geração vão responder 402. Renove o plano ou aguarde a franquia do mês seguinte.

Qual bot o token alcança

O botId é resolvido dentro do projeto do seu API Token. Um token de um projeto não consegue usar o bot de outro, mesmo sabendo o id: a rota responde 403 sem gerar nada nem tocar no seu saldo. Bot que não existe responde 404.

Vale para completion e search — as duas rotas que resolvem um bot. extract não usa botId.

Créditos e estorno

• Cada geração (completion, extract) desconta 1 crédito de bot do projeto.
• Sem crédito, a rota responde 402 ERR_NO_BOT_CREDITS antes de qualquer débito.
• Se a geração falhar depois do débito, o crédito é estornado automaticamente e a rota responde 502.
• search e health não consomem nada.

Códigos de erro

Bots API × bot no WhatsApp

O mesmo bot, dois caminhos — a diferença é quem conduz a conversa: