{ "openapi": "3.1.0", "info": { "title": "API Bocca", "version": "1.0.0", "description": "Sistemas externos criam **leads, contatos, empresas e mensagens** numa conta Bocca pela API de entrada, e recebem os eventos da conta pelos **webhooks de sa\u00edda**. Toda a API fala JSON (`Content-Type: application\/json`).\n\nComece pelo `GET \/pipelines`: \u00e9 dele que saem os ids de funil e etapa que os outros endpoints aceitam.\n\n## Autentica\u00e7\u00e3o\n\nToda chamada leva a chave de API da conta em um destes headers:\n\n```http\nAuthorization: Bearer SUA_API_KEY\nX-Api-Key: SUA_API_KEY\n```\n\nA chave \u00e9 criada dentro do app, em **Configura\u00e7\u00f5es > Webhooks e API**, e \u00e9 mostrada **uma \u00fanica vez** (guardamos s\u00f3 o hash). Quem n\u00e3o copiou na hora gera outra. Chave revogada responde `401` como se n\u00e3o existisse.\n\nA chave identifica a conta: n\u00e3o h\u00e1 id de conta na URL nem em header separado.\n\n## Permiss\u00f5es da chave (escopos)\n\nCada endpoint exige uma permiss\u00e3o da chave, indicada na se\u00e7\u00e3o de cada rota. Crie **uma chave por integra\u00e7\u00e3o**, marcando s\u00f3 o que ela precisa: assim a chave do formul\u00e1rio do seu site n\u00e3o consegue disparar WhatsApp se vazar. Sem a permiss\u00e3o, a resposta \u00e9 `403` com `error: insufficient_scope` dizendo qual faltou.\n\n| Escopo | O que permite |\n|---|---|\n| `pipeline.read` | Ler funis e etapas. |\n| `lead.write` | Criar e atualizar leads. |\n| `contact.write` | Criar e atualizar contatos. |\n| `company.write` | Criar e atualizar empresas. |\n| `message.send` | Enviar mensagem de WhatsApp. Permiss\u00e3o sens\u00edvel: a UI pede confirma\u00e7\u00e3o ao marcar. |\n\n## Limites de requisi\u00e7\u00e3o\n\nAt\u00e9 **300 requisi\u00e7\u00f5es por minuto por conta** (somando todas as chaves). Acima disso a resposta \u00e9 `429`; espere o pr\u00f3ximo minuto e reenvie. Sem chave v\u00e1lida o limite \u00e9 30 por minuto por IP.\n\n## Como sincronizamos (merge n\u00e3o-destrutivo)\n\nOs endpoints de escrita fazem *upsert*: localizamos o registro pelo **email** (sen\u00e3o pelo telefone; empresas por CNPJ, sen\u00e3o dom\u00ednio, sen\u00e3o nome). Se j\u00e1 existe, preenchemos **s\u00f3 os campos vazios** e juntamos as tags; nunca sobrescrevemos o que j\u00e1 tinha. Pra mover um lead de etapa de forma expl\u00edcita, use `POST \/leads\/stage`.\n\nTelefones s\u00e3o normalizados: 10 ou 11 d\u00edgitos viram `+55DDDNUMERO`; n\u00fameros com c\u00f3digo do pa\u00eds mant\u00eam o pr\u00f3prio c\u00f3digo. Toda chamada fica registrada no hist\u00f3rico da tela de Webhooks.\n\n## Campos UTM\n\n`POST \/leads` aceita os cinco campos UTM padr\u00e3o (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`). Eles seguem o merge n\u00e3o-destrutivo: o primeiro toque registrado no lead n\u00e3o \u00e9 sobrescrito por chamadas seguintes. Aparecem no perfil do lead e nos relat\u00f3rios de origem.\n\n## Webhooks de sa\u00edda\n\nCadastre uma ou mais URLs em **Configura\u00e7\u00f5es > Webhooks e API** e escolha os eventos de cada uma. A cada evento fazemos um `POST` JSON pra sua URL com os headers:\n\n| Header | Conte\u00fado |\n|---|---|\n| `X-Bocca-Event` | Nome do evento (ex.: `lead.created`). |\n| `X-Bocca-Signature-256` | `sha256=` + HMAC-SHA256 do corpo cru, com o secret do webhook. |\n\n### Eventos\n\n| Evento | Nome na UI | Quando dispara |\n|---|---|---|\n| `lead.created` | Lead adicionado | Um lead novo entrou, de qualquer origem (WhatsApp, API de entrada, Kommo, manual). |\n| `lead.updated` | Lead editado | Dados do lead foram editados (nome, contato, valor, respons\u00e1vel...). |\n| `lead.stage_changed` | Lead mudou de etapa | O lead foi movido de etapa no funil (traz a etapa antiga e a nova em `changes`). |\n| `message.received` | Mensagem recebida | Chegou uma mensagem do lead num canal conectado. |\n| `message.sent` | Mensagem enviada | Uma resposta foi enviada ao lead (por um atendente ou por uma automa\u00e7\u00e3o). Envios feitos pelo SEU app via API de entrada tamb\u00e9m disparam; ignore o pr\u00f3prio eco filtrando `message.via = \"inbound_api\"`. Notas internas n\u00e3o disparam. |\n\n### Payload dos eventos de lead (`lead.*`)\n\n```json\n{\n \"event\": \"lead.stage_changed\",\n \"tenant_id\": \"9d2e...\",\n \"lead\": {\n \"id\": \"9d2e...\", \"name\": \"Jo\u00e3o\", \"phone\": \"+5585999998888\",\n \"email\": null, \"source\": \"whatsapp_evolution\", \"status\": \"qualifying\",\n \"pipeline_id\": \"9d2e...\", \"stage_id\": \"9d2e...\", \"owner_id\": \"9d2e...\",\n \"value_cents\": 150000, \"tags\": [\"site\"],\n \"created_at\": \"2026-07-17T14:00:00-03:00\"\n },\n \"changes\": { \"stage_id\": { \"old\": \"9d2e...\", \"new\": \"9d2e...\" } }\n}\n```\n\n`changes` aparece em `lead.updated` e `lead.stage_changed` com o valor antigo e o novo de cada campo alterado.\n\n### Payload dos eventos de mensagem (`message.*`)\n\n```json\n{\n \"event\": \"message.received\",\n \"tenant_id\": \"9d2e...\",\n \"lead\": {\n \"id\": \"9d2e...\", \"name\": \"Jo\u00e3o\", \"phone\": \"+5585999998888\",\n \"email\": null, \"source\": \"whatsapp_evolution\", \"status\": \"new\"\n },\n \"message\": {\n \"id\": \"9d2e...\", \"direction\": \"inbound\", \"sender\": \"lead\",\n \"type\": \"text\", \"content\": \"Oi, quero saber mais\",\n \"media_url\": null, \"external_id\": \"wamid...\", \"channel_id\": \"9d2e...\",\n \"channel_phone\": \"+5585988887777\", \"channel_name\": \"Comercial\",\n \"via\": null, \"created_at\": \"2026-07-17T14:00:00-03:00\"\n }\n}\n```\n\n### Validando a assinatura\n\nCalcule o HMAC-SHA256 do corpo **cru** da requisi\u00e7\u00e3o com o secret do webhook (mostrado uma \u00fanica vez ao criar ou rotacionar) e compare com o header. Exemplo em PHP:\n\n```php\n$body = file_get_contents('php:\/\/input');\n$expected = 'sha256=' . hash_hmac('sha256', $body, $secret); \/\/ secret do webhook\n$received = $_SERVER['HTTP_X_BOCCA_SIGNATURE_256'] ?? '';\nif (! hash_equals($expected, $received)) {\n http_response_code(401);\n exit;\n}\n```\n\n### Entregas e retentativas\n\nResponda `2xx` r\u00e1pido (ideal: enfileire e processe depois). Erro `5xx` do seu servidor gera novas tentativas (at\u00e9 3 no total, com intervalo de 15s); `4xx` \u00e9 tratado como configura\u00e7\u00e3o errada e n\u00e3o h\u00e1 nova tentativa. Redirecionamentos n\u00e3o s\u00e3o seguidos. Importa\u00e7\u00f5es em massa (ex.: conectar o Kommo) podem gerar muitos eventos de lead de uma vez." }, "servers": [ { "url": "https:\/\/api.bocca.ia.br\/api\/v1\/inbound" } ], "security": [ { "http": [] } ], "paths": { "\/contacts": { "post": { "operationId": "inboundWebhook.contact", "description": "Upsert de contato na agenda: localizamos pelo `email` (sen\u00e3o pelo `phone`).\nSe j\u00e1 existe, preenchemos s\u00f3 os campos vazios e juntamos as tags; nunca\nsobrescrevemos o que j\u00e1 tinha. Responde `201` quando criou e `200` quando\natualizou. Requer o escopo `contact.write`.", "summary": "Criar ou atualizar contato", "tags": [ "Contatos" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do contato.", "maxLength": 200 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "E-mail. \u00c9 a chave prim\u00e1ria de sincroniza\u00e7\u00e3o.", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "description": "Telefone. Chave de sincroniza\u00e7\u00e3o quando n\u00e3o h\u00e1 e-mail.", "maxLength": 30 }, "whatsapp_phone": { "type": [ "string", "null" ], "description": "WhatsApp, quando for diferente do telefone principal.", "maxLength": 30 }, "title": { "type": [ "string", "null" ], "description": "Cargo do contato.", "maxLength": 150 }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id da empresa do contato (da resposta de POST \/companies)." }, "lead_source": { "type": [ "string", "null" ], "description": "Origem do contato, texto livre (ex.: \"site\", \"indica\u00e7\u00e3o\").", "maxLength": 100 }, "tags": { "type": [ "array", "null" ], "description": "Tags do contato. Uni\u00e3o com as existentes, sem duplicar.", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/companies": { "post": { "operationId": "inboundWebhook.company", "description": "Upsert de empresa: localizamos pelo identificador mais forte informado\n(`cnpj`, sen\u00e3o `domain`, sen\u00e3o `name`). Se j\u00e1 existe, preenchemos s\u00f3 os\ncampos vazios; nunca sobrescrevemos o que j\u00e1 tinha. Responde `201` quando\ncriou e `200` quando atualizou. Requer o escopo `company.write`.", "summary": "Criar ou atualizar empresa", "tags": [ "Empresas" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Raz\u00e3o social ou nome fantasia.", "maxLength": 200 }, "domain": { "type": [ "string", "null" ], "description": "Dom\u00ednio do site (aceita URL completa; guardamos s\u00f3 o host).", "maxLength": 255 }, "cnpj": { "type": [ "string", "null" ], "description": "CNPJ (s\u00f3 os d\u00edgitos s\u00e3o considerados). Identificador mais forte de deduplica\u00e7\u00e3o.", "maxLength": 20 }, "phone": { "type": [ "string", "null" ], "description": "Telefone da empresa.", "maxLength": 30 }, "industry": { "type": [ "string", "null" ], "description": "Setor de atua\u00e7\u00e3o, texto livre.", "maxLength": 100 }, "size": { "type": [ "string", "null" ], "description": "Porte, texto livre (ex.: \"11-50\").", "maxLength": 50 }, "address": { "type": [ "array", "null" ], "description": "Endere\u00e7o como objeto livre (ex.: {\"cidade\": \"Fortaleza\", \"uf\": \"CE\"}).", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/pipelines": { "get": { "operationId": "inboundWebhook.pipelines", "description": "Devolve os funis ativos da conta com suas etapas, na ordem em que aparecem\nno CRM. Integre pelos **ids** (est\u00e1veis mesmo se o nome da etapa mudar):\ns\u00e3o eles que `POST \/leads` e `POST \/leads\/stage` aceitam. \u00c9 por aqui que\ntoda integra\u00e7\u00e3o come\u00e7a. Requer o escopo `pipeline.read`.", "summary": "Listar funis e etapas", "tags": [ "Funis e etapas" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "funnel_step": { "type": "string" } }, "required": [ "id", "name", "funnel_step" ] } } }, "required": [ "id", "name", "stages" ] } } }, "required": [ "data" ] } } } } } } }, "\/leads": { "post": { "operationId": "inboundWebhook.lead", "description": "Upsert de lead: localizamos pelo `email` (sen\u00e3o pelo `phone`). Se j\u00e1 existe,\npreenchemos s\u00f3 os campos hoje vazios e juntamos as tags (merge n\u00e3o-destrutivo);\nse n\u00e3o, criamos com origem `inbound_api`. Informe pelo menos `email` ou `phone`.\n\nOs campos `utm_*` registram a campanha que trouxe o lead e seguem o mesmo\nmerge: o primeiro toque n\u00e3o \u00e9 sobrescrito. Responde `201` quando criou e\n`200` quando atualizou. Requer o escopo `lead.write`.", "summary": "Criar ou atualizar lead", "tags": [ "Leads" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Nome do lead.", "maxLength": 150 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "E-mail. \u00c9 a chave prim\u00e1ria de sincroniza\u00e7\u00e3o.", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "description": "Telefone. Chave de sincroniza\u00e7\u00e3o quando n\u00e3o h\u00e1 e-mail; 10\/11 d\u00edgitos ganham +55.", "maxLength": 30 }, "pipeline_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id do funil (obtido em GET \/pipelines)." }, "stage_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id da etapa (obtido em GET \/pipelines). N\u00e3o move lead que j\u00e1 tem etapa; pra mover use POST \/leads\/stage." }, "tags": { "type": [ "array", "null" ], "description": "Tags do lead. Uni\u00e3o com as existentes, sem duplicar.", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "utm_source": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_medium": { "type": [ "string", "null" ], "maxLength": 100 }, "utm_campaign": { "type": [ "string", "null" ], "maxLength": 200 }, "utm_term": { "type": [ "string", "null" ], "maxLength": 200 }, "utm_content": { "type": [ "string", "null" ], "maxLength": 200 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/leads\/stage": { "post": { "operationId": "inboundWebhook.leadStage", "description": "Movimento expl\u00edcito de etapa (o upsert de `POST \/leads` nunca move um lead\nque j\u00e1 tem etapa). Localize o lead por `lead_id` ou por `phone`. O funil \u00e9\ndeduzido da etapa; automa\u00e7\u00f5es de mudan\u00e7a de etapa (cad\u00eancias, webhooks de\nsa\u00edda) disparam normalmente. Requer o escopo `lead.write`.", "summary": "Mover lead de etapa", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "lead_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id do lead (da resposta de POST \/leads ou dos webhooks de sa\u00edda)." }, "phone": { "type": [ "string", "null" ], "description": "Telefone do lead, alternativa ao lead_id.", "maxLength": 30 }, "stage_id": { "type": "string", "format": "uuid", "description": "Id da etapa de destino (obtido em GET \/pipelines)." } }, "required": [ "stage_id" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "lead_id": { "type": "string" }, "stage_id": { "type": "string" }, "pipeline_id": { "type": "string" } }, "required": [ "ok", "lead_id", "stage_id", "pipeline_id" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "lead_not_found" }, "message": { "type": "string", "const": "Lead n\u00e3o encontrado." } }, "required": [ "error", "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/messages": { "post": { "operationId": "inboundWebhook.message", "description": "Envia um WhatsApp pro lead pelo canal conectado da conta e registra a\nmensagem na conversa do CRM (em tempo real). \u00c9 como um app externo (ex.:\numa IA pr\u00f3pria) responde o lead em nome da conta. Identifique o alvo por\n`lead_id`, `phone` (cria o lead se n\u00e3o existir) ou `external_id`.\n\nA resposta \u00e9 `201` mesmo quando o provider falhou (`status: \"failed\"`):\na mensagem fica registrada com a falha vis\u00edvel na conversa; n\u00e3o reenvie.\nRequer o escopo `message.send`, o \u00fanico que dispara WhatsApp de verdade.", "summary": "Enviar mensagem ao lead", "tags": [ "Mensagens" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Texto da mensagem.", "maxLength": 4096 }, "message": { "type": "string", "description": "Sin\u00f4nimo de body (compatibilidade); envie um dos dois.", "maxLength": 4096 }, "lead_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id do lead alvo." }, "phone": { "type": [ "string", "null" ], "description": "Telefone do lead alvo. Se n\u00e3o existir lead com esse n\u00famero, criamos um.", "maxLength": 30 }, "external_id": { "type": [ "string", "null" ], "description": "Identificador do lead no SEU sistema, alternativa ao lead_id.", "maxLength": 191 }, "name": { "type": [ "string", "null" ], "description": "Nome pro lead criado via phone (ignorado se o lead j\u00e1 existe).", "maxLength": 150 }, "channel_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Canal WhatsApp de sa\u00edda; sem ele, usamos o canal da conversa do lead." } } } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "const": "message" }, "id": { "type": "string" }, "lead_id": { "type": "string" }, "external_id": { "type": "null" }, "status": { "type": "string", "enum": [ "failed", "sent" ] } }, "required": [ "entity", "id", "lead_id", "external_id", "status" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "Chave de API da conta (criada em Configura\u00e7\u00f5es > Webhooks e API). Envie em `Authorization: Bearer SUA_API_KEY` ou no header `X-Api-Key`.", "scheme": "bearer" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }