Referência da API /v1

Esta é a lista completa das rotas /v1. O contrato exato de cada request/response é a combinação desta referência com os exemplos testados nas páginas de guia (Enviar mensagens, Webhooks, Transmissões e limites). Cada exemplo roda contra o handler real antes de ser publicado, então request e resposta mostrados nunca divergem do comportamento em produção.

Convenções

Base URL de todas as rotas:

https://botozap.com.br/api/v1

Toda requisição leva a sua chave de API no header, como Authorization: Bearer ou como X-API-Key. A conta é derivada da chave, então você nunca passa um id de conta (o isolamento multi-tenant é garantido no servidor). Detalhes de autenticação e escopos em Autenticação.

Authorization: Bearer $BOTOZAP_KEY
# ou
X-API-Key: $BOTOZAP_KEY

As respostas seguem um envelope fixo:

• Sucesso singular: { "data": <objeto> }.
• Lista: { "data": [...], "paging" | "meta": {...} }.
• Exceção: POST /api/v1/messages retorna direto { id, wamid, to, status }, sem envelope.

Erros vêm num envelope estruturado com código e mensagem:

{
  "error": {
    "code": "forbidden_scope",
    "message": "Esta chave de API não tem o escopo 'messages:send'."
  }
}

Escopos

Cada rota exige um escopo específico (coluna Escopo nas tabelas abaixo). Uma chave criada com a lista de escopos vazia tem acesso total a todas as rotas: é o comportamento legado para chaves criadas antes de o sistema de escopos existir. Veja a explicação completa em Autenticação.

Ambiente sandbox

Uma chave bz_sandbox_ só pode acessar uma allow-list fail-closed de rotas. Hoje, apenas POST /api/v1/messages, GET /api/v1/messages, GET /api/v1/messages/{id}, GET /api/v1/media/{id} e GET /api/v1/media/{id}/download(marcadas "sandbox" nas tabelas abaixo; nas rotas de mídia, uma chave sandbox só consulta a mídia sintética sandbox-media-0001). Qualquer outra rota responde 403 sandbox_forbidden para uma chave sandbox. Veja Sandbox vs. produção.

Paginação

Dois modelos coexistem, dependendo do recurso, nunca os dois na mesma rota:

Por cursor

Para coleções grandes e de append (mensagens, contatos, conversas, webhooks, entregas de webhook, logs de API, destinatários de transmissão). Query params: limit (padrão 20, máximo 100), after e before. A resposta traz:

{
  "data": [...],
  "paging": {
    "cursors": { "before": "...", "after": "..." },
    "next": "...",
    "previous": "..."
  }
}

Rotas por cursor: /api/v1/messages, /api/v1/contacts, /api/v1/conversations, /api/v1/webhooks, /api/v1/webhook_deliveries, /api/v1/api_logs, /api/v1/broadcasts/{id}/recipients.

Por página (offset)

Para coleções pequenas e estáveis (clientes, números, templates, usuários, transmissões, flows, links de onboarding, atribuições de conversa). Query params: page e per_page (padrão 20, máximo 100). A resposta traz:

{
  "data": [...],
  "meta": { "page": 1, "per_page": 20, "total_pages": 3, "total_count": 42 }
}

Os mesmos números também vêm nos headers X-Page, X-Per-Page, X-Total-Pages e X-Total. Rotas por página: /api/v1/customers, /api/v1/phone_numbers, /api/v1/templates, /api/v1/users, /api/v1/broadcasts, /api/v1/flows, /api/v1/flows/{id}/versions, /api/v1/customers/{id}/setup_links, /api/v1/conversations/{id}/assignments.

Mensagens

Clientes

Templates

Hoje não existe PATCH nem DELETE de template pela API. Para editar ou remover, use o painel.

Transmissões

Limites de destinatários por transmissão, quota mensal, rate limit e o messaging limit da Meta (quatro coisas diferentes) estão detalhados em Transmissões e limites.

Contatos

Conversas

Webhooks

Números

Mídia

Flows

Usuários

Logs de API

Entregas de webhook

Shapes exatos

Esta referência lista os endpoints, o escopo e o que cada um faz. O contrato exato de campos (o que realmente entra e sai de cada chamada) é a própria API REST, documentada nos exemplos testados das páginas de guia: cada exemplo mostrado neste site roda de verdade contra o handler correspondente antes de ser publicado, então nunca há divergência entre o que você lê aqui e o que a API faz.