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 a expiração. A chave vem com 1 ano; dá para trocar por 30 ou 90 dias, por uma data até 10 anos à frente (vale até o fim do dia, no horário de Brasília) ou por “Nunca expira”, e aí ela vale até ser revogada. 30 dias antes de vencer, e de novo aos 7, o sino do painel avisa e os Administradores da conta recebem um e-mail; a chave com até 30 dias de prazo só recebe o aviso dos 7. 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.
Opcionalmente, a chave também leva uma lista de IPs autorizados, que você pode editar a qualquer momento.
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.
A verificação em duas etapas do painel (aplicativo autenticador) vale para as pessoas que entram no painel e não muda nada na API: a chave de API não passa por ela e segue sendo a credencial das chamadas automáticas. Quem conecta um assistente por OAuth (ChatGPT, Claude) digita o código do aplicativo na tela de autorização, se o tiver ativado.
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 54 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}, PATCH /api/v1/templates/{id}, GET /api/v1/contacts, GET /api/v1/conversations, GET /api/v1/conversations/{id}, PATCH /api/v1/conversations/{id}, POST /api/v1/conversations/{id}/read, 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}/message-rules, POST /api/v1/channel_accounts/{id}/message-rules, GET /api/v1/channel_accounts/{id}/message-rules/{ruleId}, PATCH /api/v1/channel_accounts/{id}/message-rules/{ruleId}, DELETE /api/v1/channel_accounts/{id}/message-rules/{ruleId}, GET /api/v1/channel_accounts/{id}/message-rules/{ruleId}/qr, 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}, GET /api/v1/channel_accounts/{id}/comment-rules/{ruleId}/metrics, PATCH /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, DELETE /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. O ambiente é conferido antes dos escopos: numa rota fora da lista, dar mais escopos à chave sandbox não muda a resposta. Para receber os eventos do sandbox, cadastre o webhook pelo painel, em Webhooks (veja Registrar um webhook). 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.
IPs autorizados por chave
Cada chave pode ter uma lista de até 20 endereços IP ou faixas CIDR, IPv4 ou IPv6 (por exemplo 203.0.113.10, 198.51.100.0/24 ou 2001:db8::/32). Com a lista preenchida, só chamadas vindas desses endereços passam; as demais recebem 403 com code: "ip_not_allowed", e a recusa fica no log da API. Lista vazia aceita qualquer IP, que é o padrão. A checagem vem logo depois de validar a chave e antes dos escopos. Uma chamada cujo IP não pode ser identificado também é recusada quando a lista está preenchida. A lista vale só para chaves de API: o acesso por OAuth do MCP não usa chave fixa e não passa por ela.
Cadastre o IP de saída do servidor que chama o BotoZap, não o do seu computador. Para descobri-lo, rode no próprio servidor, por exemplo, curl https://api.ipify.org (ou curl https://api64.ipify.org se ele sair por IPv6). Cuidado com ambientes cujo IP de saída muda (funções serverless, alguns planos gratuitos): com o IP errado, a integração para de funcionar até a lista ser corrigida. Edite a lista no painel, em Chaves de API › Editar IPs autorizados; vale na próxima chamada.
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"; chamada de um IP fora da lista da chave responde 403 com code: "ip_not_allowed". 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. Os envios (POST /v1/messages e o pedido de consentimento) têm ainda um teto próprio: 60 envios a cada 10 segundos por conta. Ao exceder um dos dois, 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.
