Navegar na CentralChaves de API

Chaves de API

Entenda para que serve uma chave de API, crie uma com as permissões certas para quem vai integrar e revogue quando não precisar mais.

Atualizado em

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 canais reais, os números de WhatsApp e a conta do Instagram. 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 nem ao Instagram 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. Com uma chave Sandbox ativa, a tela Canais mostra também um número e uma conta do Instagram de teste, com o selo Sandbox.

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 pelos seus canais para os seus contatos, no WhatsApp e no Instagram.
  • 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 regras de comentário e Gerenciar regras de comentário: o sistema consulta ou altera as regras de Comentários → DM do Instagram.
  • Ler plano e cobrança e Gerenciar slots adicionais: o sistema consulta o plano e os slots adicionais (com vencimento e link da fatura) ou compra e cancela slots de R$ 47 por mês. Comprar um slot gera cobrança. Veja Plano e cobrança.
  • 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, a chave já vem com Em 1 ano. Você pode trocar por Nunca expira, Em 30 dias, Em 90 dias ou Data específica…. Com data específica, a chave vale até o fim do dia escolhido, no horário de Brasília.
  6. Se quiser, em IPs autorizados, informe de quais endereços a chave pode ser usada (veja Limitar a chave a certos IPs). Em branco, a chave funciona de qualquer lugar.
  7. Clique em Gerar chave.
  8. 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.
  9. Clique em Já guardei a chave.

Importante: a chave completa aparece uma única vez. Depois que você fecha a janela, o BotoZap não consegue mostrá-la de novo. Se ela se perder, revogue e crie outra.

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

Limitar a chave a certos IPs

Por padrão, uma chave funciona de qualquer lugar da internet. Se a sua integração sempre chama o BotoZap do mesmo servidor, você pode restringir a chave aos IPs desse servidor. Assim, mesmo que a chave vaze, ela não serve para quem chamar de outro lugar.

No campo IPs autorizados, escreva um endereço por linha (ou separados por vírgula). Cada item pode ser:

  • um IP simples, como 203.0.113.10;
  • uma faixa, como 198.51.100.0/24;
  • um IP ou faixa IPv6, como 2001:db8::/32.

Cabem até 20 itens por chave. Deixar em branco libera qualquer IP, como antes. Chamadas de um IP fora da lista recebem o erro ip_not_allowed e ficam registradas nos registros de API.

Como descobrir o IP do servidor. É o IP de onde a chamada sai, não o do seu computador. Peça à pessoa que cuida da hospedagem ou da automação (n8n, Make, servidor da loja) o "IP de saída" ou "IP fixo de saída". Se ela não souber, faça o próprio servidor consultar um serviço como https://api.ipify.org e anote o resultado. Atenção: hospedagens que trocam de IP a cada execução (algumas funções serverless e planos gratuitos) não combinam com esta lista, a menos que tenham IP fixo.

Cuidado para não travar a sua integração. Se o IP estiver errado ou mudar, a integração para de funcionar até você corrigir a lista. Para ajustar, abra a linha da chave, clique em Editar IPs autorizados e salve: vale na próxima chamada. Na dúvida, apague a lista para liberar qualquer IP e refaça com calma.

Só Administrador edita a lista. Ela vale para chaves ativas; as chaves já revogadas não podem ser editadas.

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;
  • IPs autorizados: a lista da chave, ou Qualquer IP;
  • 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.

O sino avisa 30 dias e de novo 7 dias antes de uma chave vencer, e os Administradores recebem um e-mail em cada aviso. A chave criada com até 30 dias de prazo só recebe o aviso dos 7 dias, e a de até 7 dias não recebe aviso. Depois de trocar na integração, revogue a chave antiga: o aviso some quando ela vence ou é revogada. O sino também avisa quando uma chave passa 90 dias sem uso; ela continua funcionando até alguém revogar.

Dica: uma chave ativa com Último uso muito antigo pode ser de uma integração desligada. Confirme com quem integrou e revogue se não for mais usada.

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.

A integração recebe ip_not_allowed. O IP de onde ela chama não está na lista da chave. A mensagem do erro mostra o IP que o BotoZap viu: confira se é o do servidor certo e adicione-o em Editar IPs autorizados.

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