Documentação da API

Como enviar dados pra Bocca e como receber os eventos dela no seu sistema. Você precisa de uma conta Bocca pra gerar a chave; esta página é o contrato, e pode ser lida sem entrar.

Referência completa da API

Todas as rotas com parâmetros, respostas, erros e exemplos de código, incluindo os campos utm_* do lead. Dá pra testar as chamadas direto do navegador, com a sua chave.

Abrir a referência Spec OpenAPI (JSON)

API de entrada

Sistemas externos criam leads, contatos, empresas e mensagens numa conta Bocca. Toda chamada leva o header Authorization: Bearer SUA_API_KEY, e as de escrita mandam JSON. A chave é criada dentro do app, em Configurações → Webhooks, e é mostrada uma única vez. Comece pelo GET de funis: é dele que saem os ids de funil e etapa que os outros endpoints aceitam.

Cada endpoint exige uma permissão da chave. Crie uma chave por integração, marcando só o que ela precisa: assim a chave do formulário do seu site não consegue disparar WhatsApp se vazar. Sem a permissão, a resposta é 403 e diz qual faltou.

Endpoints

FunisGEThttps://api.bocca.ia.br/api/v1/inbound/pipelinespipeline.read

LeadsPOSThttps://api.bocca.ia.br/api/v1/inbound/leadslead.write

ContatosPOSThttps://api.bocca.ia.br/api/v1/inbound/contactscontact.write

EmpresasPOSThttps://api.bocca.ia.br/api/v1/inbound/companiescompany.write

MensagensPOSThttps://api.bocca.ia.br/api/v1/inbound/messagesmessage.send

Exemplo (criar um lead)

curl -X POST https://api.bocca.ia.br/api/v1/inbound/leads \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"João","email":"joao@empresa.com","phone":"+5585999998888","tags":["site"]}'

Sincronizamos pelo email (senão telefone): se o registro já existe, preenchemos só os campos vazios e juntamos as tags. Nunca sobrescrevemos o que já tinha. Toda chamada fica registrada no histórico da tela de Webhooks.

Webhooks de saída

Cadastre uma ou mais URLs na tela de Webhooks e escolha os eventos de cada uma. A cada evento, fazemos um POST com JSON pra sua URL com os headers X-Bocca-Event (nome do evento) e X-Bocca-Signature-256 (assinatura). Se seu servidor responder erro 5xx, tentamos de novo (até 3 tentativas no total). Importações em massa (ex.: conectar o Kommo) podem gerar muitos eventos de lead de uma vez.

Eventos

Evento	Quando dispara
Lead adicionado `lead.created`	Um lead novo entrou, de qualquer origem (WhatsApp, API de entrada, Kommo, manual).
Lead editado `lead.updated`	Dados do lead foram editados (nome, contato, valor, responsável…).
Lead mudou de etapa `lead.stage_changed`	O lead foi movido de etapa no funil (traz a etapa antiga e a nova em changes).
Mensagem recebida `message.received`	Chegou uma mensagem do lead num canal conectado.
Mensagem enviada `message.sent`	Uma resposta foi enviada ao lead (por um atendente ou por uma automação). Envios feitos pelo SEU app via API de entrada também disparam. Ignore o próprio eco filtrando message.via = "inbound_api". Notas internas não disparam.

Payload: eventos de mensagem

{
  "event": "message.received",
  "tenant_id": "…",
  "lead": { "id": "…", "name": "João", "phone": "+5585999998888",
            "email": null, "source": "whatsapp_evolution", "status": "new" },
  "message": { "id": "…", "direction": "inbound", "sender": "lead",
               "type": "text", "content": "Oi, quero saber mais",
               "media_url": null, "external_id": "…", "channel_id": "…",
               "via": null, "created_at": "2026-07-17T14:00:00-03:00" }
}

Payload: eventos de lead

{
  "event": "lead.stage_changed",
  "tenant_id": "…",
  "lead": { "id": "…", "name": "João", "phone": "+5585999998888",
            "email": null, "source": "whatsapp_evolution", "status": "qualifying",
            "pipeline_id": "…", "stage_id": "…", "owner_id": "…",
            "value_cents": 150000, "tags": ["site"],
            "created_at": "2026-07-17T14:00:00-03:00" },
  "changes": { "stage_id": { "old": "…", "new": "…" } }
}

changes aparece em lead.updated e lead.stage_changed com o valor antigo e o novo de cada campo alterado.

Validando a assinatura

Calcule o HMAC-SHA256 do corpo cru da requisição com o secret do webhook (mostrado uma única vez ao criar ou rotacionar) e compare com o header. Exemplo em PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret); // secret do webhook
$received = $_SERVER['HTTP_X_BOCCA_SIGNATURE_256'] ?? '';
if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Dúvida na integração? suporte@bocca.ia.br