Autenticação

Sua chave de API

Gere e gerencie suas chaves no painel, em Configurações › Desenvolvedores › Chaves de API. Só Administrador cria e revoga chaves. Cada chave pertence à sua conta e concede acesso apenas aos recursos dela.

Na criação você escolhe o nome, o ambiente, os escopos (pelo menos um) e, se quiser, uma expiração: 30, 90 ou 365 dias, ou uma data até 10 anos à frente (vale até o fim do dia, no horário de Brasília). Sem expiração, a chave vale até ser revogada. Depois de expirada ou revogada, toda chamada com ela responde 401 unauthorized. Escopos e ambiente não mudam depois: para outra combinação, gere uma chave nova e revogue a antiga.

O valor completo aparece uma única vez, na criação; guardamos só um hash. Trate a chave como um segredo: guarde em variável de ambiente, nunca no controle de versão nem no código do cliente. Se uma chave vazar, revogue-a no painel e gere outra. Toda chamada usa HTTPS.

Como autenticar

Envie a chave em um dos dois headers aceitos: X-API-Key ou Authorization no formato Bearer. Escolha um só; se os dois vierem, vale o X-API-Key. A conta é resolvida a partir da chave, então você nunca passa um id de conta no corpo da requisição.

# X-API-Key
curl https://botozap.com.br/api/v1/messages \
  -H "X-API-Key: $BOTOZAP_KEY"

# ou Authorization: Bearer
curl https://botozap.com.br/api/v1/messages \
  -H "Authorization: Bearer $BOTOZAP_KEY"

Sandbox vs. produção

Existem dois ambientes, escolhidos ao gerar a chave: Produção (prefixo bz_live_) e Sandbox (prefixo bz_sandbox_). O ambiente autoritativo é o registrado no servidor para aquela chave; o prefixo é só para você reconhecê-la em logs e no painel.

Uma chave sandbox nunca chama a Meta e nunca consome quota. O envio aceita qualquer destino e simula o ciclo de vida da mensagem, e os números mágicos escolhem o cenário. Templates criados com ela nascem APPROVED num catálogo sintético. Nas rotas liberadas, ela só lê e escreve dados do ambiente sandbox: nunca vê números, contatos, conversas ou Eventos de produção.

Por segurança, a chave sandbox só acessa uma allow-list de 44 rotas: POST /api/v1/messages, GET /api/v1/messages, GET /api/v1/messages/{id}, GET /api/v1/events, GET /api/v1/templates, POST /api/v1/templates, GET /api/v1/templates/{id}, GET /api/v1/contacts, GET /api/v1/conversations, GET /api/v1/conversations/{id}, PATCH /api/v1/conversations/{id}, GET /api/v1/conversations/{id}/assignments, POST /api/v1/conversations/{id}/assignments, GET /api/v1/conversations/{id}/assignments/{assignmentId}, PATCH /api/v1/conversations/{id}/assignments/{assignmentId}, GET /api/v1/conversations/{id}/tools, PATCH /api/v1/conversations/{id}/tools, GET /api/v1/opportunities, POST /api/v1/opportunities, GET /api/v1/opportunities/{id}, PATCH /api/v1/opportunities/{id}, GET /api/v1/opportunities/{id}/activities, GET /api/v1/opportunities/{id}/conversations, POST /api/v1/opportunities/{id}/conversations, DELETE /api/v1/opportunities/{id}/conversations, GET /api/v1/demands, POST /api/v1/demands, GET /api/v1/demands/{id}, PATCH /api/v1/demands/{id}, GET /api/v1/demands/{id}/activities, GET /api/v1/demands/{id}/conversations, POST /api/v1/demands/{id}/conversations, DELETE /api/v1/demands/{id}/conversations, GET /api/v1/radar, GET /api/v1/radar/stage-rules, GET /api/v1/channel_accounts, GET /api/v1/channel_accounts/{id}, GET /api/v1/phone_numbers, GET /api/v1/channel_accounts/{id}/comment-rules, POST /api/v1/channel_accounts/{id}/comment-rules, GET /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, PATCH /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, GET /api/v1/media/{id} e GET /api/v1/media/{id}/download. Qualquer outra rota responde 403 com code: "sandbox_forbidden". Isso é deliberado: uma chave sandbox é tratada como descartável e nunca deve ter o poder de uma chave de produção em transmissões, clientes, webhooks etc. Veja o guia completo em Primeiros passos e os cenários simulados em Enviar mensagens.

Escopos

Cada chave é restrita a um conjunto de escopos (ex.: messages:send, broadcasts:write, webhooks:read), um por recurso e ação. Toda rota da referência da API declara o escopo que exige, e o catálogo completo está em Erros e escopos.

Toda chave precisa de pelo menos um escopo. Sem o escopo exigido pela rota, a API responde 403 com code: "forbidden_scope". Uma lista vazia não libera nada, e :write não inclui :read.

Erros de autenticação e autorização

Erros seguem o envelope { error: { code, message } }. Chave ausente, inválida, revogada ou expirada responde 401 com code: "unauthorized"; chave válida sem o escopo exigido responde 403 com code: "forbidden_scope". Os demais códigos que qualquer rota pode devolver estão em Erros e escopos.

{
  "error": {
    "code": "unauthorized",
    "message": "Chave de API ausente ou inválida."
  }
}

Rate limit

Toda rota /v1 soma para o mesmo limite por conta: 120 requisições a cada 10 segundos. Ao excedê-lo, a API responde 429 com code: "rate_limited" e os headers X-RateLimit-*/Retry-After. Detalhes completos (e os outros limites independentes da API) em Transmissões e limites.

Veja o panorama da API ou vá direto para Primeiros passos.