Chaves de API

Uma chave de API é uma senha que você entrega a outro sistema para ele usar o BotoZap em seu nome. Com ela, o site da sua loja, o seu sistema de gestão, uma automação (como o n8n) ou um programa feito pelo seu desenvolvedor consegue, por exemplo, mandar mensagens, consultar contatos ou criar oportunidades no funil, sem ninguém abrir o painel.

Você só precisa de uma chave se alguém for integrar outro sistema ao BotoZap. Para usar o painel no dia a dia, não precisa.

As chaves ficam em Configurações › Chaves de API.

Antes de começar

• Criar e revogar chaves é só para Administrador. Se você trabalha sozinho, você já é o Administrador da conta. Quem é Operador vê a lista, mas não vê o botão Nova chave nem a opção de revogar.
• A chave vale para a conta inteira: uma mesma chave alcança todos os seus clientes, e quem integra escolhe o cliente em cada pedido. O seletor de cliente do topo não muda nada nesta tela.
• Combine com quem vai integrar o que o sistema precisa fazer. Isso define as permissões.

Produção ou Sandbox

Ao criar uma chave, você escolhe o Ambiente:

• Produção: a chave trabalha com os seus números reais. Mensagens enviadas com ela chegam aos contatos de verdade. O código da chave começa com bz_live_.
• Sandbox: um ambiente de testes. Nada é enviado ao WhatsApp de verdade: o BotoZap simula os envios e as respostas, sem custo. O código começa com bz_sandbox_. É o ideal para o desenvolvedor montar e testar a integração antes de ligar na produção.

Na lista, as chaves de testes aparecem com a etiqueta Sandbox ao lado do nome.

Permissões em linguagem simples

Cada chave só faz o que você marcar em Permissões. É preciso marcar pelo menos uma. Em geral, cada assunto tem duas opções:

• Ler (ou Consultar): o sistema só consulta. Exemplos: Ler mensagens, Ler contatos, Ler templates, Ler transmissões.
• Gerenciar: o sistema também cria, altera ou apaga. Exemplos: Gerenciar contatos, Gerenciar templates, Gerenciar transmissões, Gerenciar agendamentos.

Algumas permissões merecem atenção especial:

• Enviar mensagens: o sistema manda mensagens pelo seu número para os seus contatos.
• Gerenciar agentes: o sistema configura os agentes de IA e controla o atendimento.
• Gerenciar webhooks: o sistema escolhe para onde o BotoZap manda os avisos automáticos. Veja Webhooks.
• Gerenciar clientes e Gerenciar números: o sistema mexe no cadastro dos seus clientes e dos números conectados.
• Enviar arquivos de mídia: o sistema guarda no BotoZap imagens, vídeos, áudios e documentos a partir de um link, para usar depois nas mensagens.
• Ler respostas rápidas e Gerenciar respostas rápidas: o sistema consulta ou altera as respostas rápidas que você usa no atendimento.

Cada opção da tela traz uma descrição curta do que libera. Na dúvida, marque só o que a integração precisa: uma chave com menos permissões causa menos estrago se vazar.

Passo a passo: criar uma chave

1. Abra Configurações › Chaves de API e clique em Nova chave.
2. Em Nome da chave, escreva onde ela vai ser usada, por exemplo "Site da loja" ou "Integração n8n". O nome ajuda a saber qual chave revogar depois.
3. Em Ambiente, escolha Produção ou Sandbox.
4. Em Permissões, marque o que a integração precisa.
5. Em Expiração, escolha Nunca expira, Em 30 dias, Em 90 dias, Em 1 ano ou Data específica…. Com data específica, a chave vale até o fim do dia escolhido, no horário de Brasília.
6. Clique em Gerar chave.
7. Na janela Sua nova chave de API, clique no botão de copiar e guarde a chave em um lugar seguro, ou entregue direto para quem vai integrar.
8. Clique em Já guardei a chave.

A janela só fecha pelo botão Já guardei a chave, para você não perder a chave com um clique fora dela.

Acompanhar as chaves

A lista mostra, para cada chave:

• Nome e, se for de testes, a etiqueta Sandbox;
• Prefixo: o começo do código, para você reconhecer a chave sem expor o resto;
• Permissões marcadas;
• Status: Ativa, Expirada ou Revogada;
• Expira em: a data de expiração ou Nunca;
• Último uso: a última data em que um sistema usou a chave, ou Nunca.

Use os filtros Ativas, Expiradas, Revogadas e Todas no alto da lista. A tela abre em Ativas.

Passo a passo: revogar uma chave

Revogar é desligar a chave para sempre. Faça isso quando uma integração for desativada, quando alguém que tinha a chave sair da equipe ou se você suspeitar que ela vazou.

1. Na linha da chave, clique no botão de três pontos (Ações da chave).
2. Clique em Revogar.
3. Confirme em Revogar chave.

A mensagem Chave revogada confirma. A partir desse momento, qualquer sistema que use essa chave para de funcionar, e não há como desfazer. Se a integração ainda for necessária, crie uma chave nova e entregue a quem cuida dela.

Problemas comuns

O botão Nova chave não aparece. Seu papel na conta é Operador. Peça a um Administrador.

Aparece "Chaves de API indisponíveis agora." O BotoZap não conseguiu carregar a lista neste momento. Suas chaves continuam valendo e as integrações seguem funcionando; atualize a página em instantes.

O botão Gerar chave fica apagado. Marque pelo menos uma permissão.

Aparece "A data de expiração precisa ser no futuro." ou "A data de expiração é muito distante (máx. 10 anos)." Escolha uma data a partir de amanhã e dentro de dez anos.

A integração parou de funcionar. Confira o Status da chave. Se estiver Expirada ou Revogada, crie uma nova e entregue a quem cuida da integração. Se estiver Ativa, peça a quem integrou para conferir os registros em Registros de API, Meta e webhooks.

Perdi a chave logo depois de criar. Não há como ver de novo. Revogue a chave perdida e crie outra.