# Combot API

> O Combot é a CONEXÃO da empresa com o WhatsApp: ele entrega e recebe as mensagens.
> Fluxo: seu sistema chama a API -> o Combot entrega no WhatsApp do cliente; o cliente
> responde -> o Combot repassa para o seu sistema por webhook.
>
> Dois cenários de uso:
> 1. VOCÊ JÁ TEM UM SISTEMA (ERP / provedor de internet / CRM): o Combot é só o
>    transporte. Ele encaminha as mensagens recebidas para o seu webhook e o seu sistema
>    responde via POST /api/v1/messages. Quem decide o que responder é o SEU sistema
>    (a IA do Combot fica desligada).
> 2. VOCÊ NÃO TEM SISTEMA: use a IA treinável do Combot, que responde sozinha — ou
>    consulte a resposta por POST /api/v1/ai/reply e use como quiser.

Base URL: https://combot.com.br/api/v1
Autenticação: header `Authorization: Bearer <API_KEY>` (gere em /app/integracoes; requer plano Profissional)
Formato: JSON (application/json)
Especificação OpenAPI: https://combot.com.br/openapi.json
Documentação humana: https://combot.com.br/docs

## Endpoints

### POST /api/v1/messages
Envia uma mensagem de WhatsApp pela conta da empresa.
Body: { "to": "5511999998888", "text": "..." }  OU  { "conversationId": "...", "text": "..." }
Resposta: { "ok": true, "messageId": "...", "conversationId": "..." }

Opcional — BOTÕES DE COPIAR (PIX, boleto), até 3:
Body: {
  "to": "5511999998888",
  "text": "*PIX copia-e-cola* — R$ 119,90",
  "footer": "Fast Telekom",
  "buttons": [
    { "displayText": "📋 Copiar código Pix", "copyCode": "00020126..." },
    { "displayText": "📋 Copiar código do boleto", "copyCode": "34191.79001..." }
  ]
}
- displayText: texto do botão (máx. 25 caracteres). copyCode: o que vai para a área de transferência.
- O Combot também envia o código numa mensagem própria, dentro de bloco de código (```),
  porque um código solto (o PIX contém "br.gov.bcb.pix") vira LINK no WhatsApp e o
  cliente acaba copiando só um pedaço. Assim ele copia o código inteiro.

Opcional — ARQUIVO (PDF do boleto) ou IMAGEM (QR Code do PIX), por URL pública:
Body: { "to": "5511999998888", "type": "document", "url": "https://.../boleto.pdf", "filename": "Fatura.pdf", "caption": "Total: R$ 119,90" }
Body: { "to": "5511999998888", "type": "image", "url": "https://.../qrcode-pix.png", "caption": "Aponte a câmera do banco" }
- type: "document" (vira um cartão com o nome do arquivo e botão de baixar) ou "image".
- Com `type` + `url`, o campo `text` não é obrigatório (a legenda vai em `caption`).
- A URL precisa ser pública (o Combot baixa o arquivo para enviar).

### POST /api/v1/ai/reply
Gera uma resposta usando a IA e a base de conhecimento treinada da empresa (não envia nada ao cliente).
Body: { "message": "..." }
Resposta: { "reply": "...", "handoff": false, "tokensIn": 0, "tokensOut": 0 }

## Webhook (receber atendimentos)
Configure a URL do seu webhook em /app/integracoes e ligue "Redirecionar atendimentos".
Cada mensagem recebida é enviada por POST à sua URL, assinada em `X-Combot-Signature`
(HMAC-SHA256 do corpo, com o segredo exibido em Integrações).
Payload: {
  "event": "message.received",
  "conversationId": "...",
  "contact": { "id": "...", "name": "...", "phone": "..." },
  "message": { "id": "<id estável p/ dedup>", "externalId": "<wamid do WhatsApp ou null>", "text": "...", "direction": "inbound" },
  "isNewContact": false
}
Deduplicação: use `message.id` (ou `message.externalId`) como chave idempotente — a Meta pode reentregar o mesmo evento.

## Erros
401 missing_token | invalid_token — chave ausente/inválida
403 plan_without_api_access — plano sem acesso à API
400 missing_text | missing_recipient | missing_message — corpo incompleto
404 conversation_not_found — conversa inexistente
409 no_whatsapp_channel — nenhum WhatsApp conectado

## Notas para agentes de IA
- Sempre autentique no backend; nunca exponha a API key ao usuário final.
- Para responder um atendimento recebido via webhook, use o `conversationId` em POST /api/v1/messages.
- Respeite os limites do plano; trate 403/409 pedindo ao usuário para conectar o WhatsApp/fazer upgrade.