De quem ela é, o que vem dentro e por que o botão às vezes recusa

A credencial é sua. Quem gerou foi a Meta, no nome do seu número, no momento em que você conectou. A Zera guarda uma cópia cifrada para operar e devolve ela na tela quando você pede. Esta página diz o que vem em cada campo, quem consegue exibir, as doze recusas possíveis e o que fazer quando o token para de funcionar.

De quem é esta credencial

Isto vale a pena ficar claro antes de qualquer comando, porque muda o que você faz quando alguma coisa dá errado.

Como só a Meta revoga, também não existe botão de gerar outra credencial no painel. E como não dá para gerar outra, também não dá para mostrar uma vez só e nunca mais: quem perdesse ficaria preso. A regra virou a oposta, de propósito: você exibe quantas vezes precisar, e toda exibição faz barulho. As duas metades desse barulho estão descritas mais abaixo.

Onde ela fica no painel

No painel, abra Canais, clique no seu número e fique na aba Detalhes. No cartão Credencial da Cloud API, o botão Mostrar a credencial revela o token. Logo abaixo dele, com o rótulo O código de verificação do webhook deste número e botão de copiar próprio, vem o webhook_verify_token, quando a resposta o traz. Se ela traz null, a tela diz que não veio código e que ele nasce na primeira tentativa de apontar o endereço. No plano com caixa de entrada, esse null não é desenhado, porque ali o painel não aponta endereço.

O painel conta o que vai acontecer antes do clique, e não depois. Cinco comportamentos que são de desenho:

• A exibição exige um acesso recente: uma sessão com menos de dez minutos de vida. Estar logado há dias não serve.
• O dono da conta recebe um e-mail no mesmo minuto, toda vez. Esse aviso não pode ser desligado, e se o e-mail não for aceito a credencial não sai.
• A exibição vira linha na aba Atividade do número, que você mesmo vê.
• A credencial some da tela assim que você troca de aba ou recarrega a página. Ela não fica guardada no navegador, e o valor nunca vira atributo do HTML.
• Existe um limite de três exibições a cada 24 horas na conta, e a resposta traz esse número em vez de a tela chutar. A janela corre a partir de cada exibição, e não vira à meia-noite.

Não existe chave de API que busque a credencial. A rota que a tela usa só responde POST, cobra o cookie de sessão do painel com menos de dez minutos de vida, e responde origem quando o pedido se identifica como vindo de outro site: é o navegador que declara isso, em todo POST de outra origem, e é assim que um pedido forjado de fora é barrado. Um programa que não manda esses cabeçalhos passa por essa conferência, e o que segura ele é o cookie de sessão, que só existe dentro do navegador de quem entrou no painel. A resposta é no-store. Se o seu sistema precisa do token, copie uma vez e guarde no cofre que você já usa para as suas outras chaves.

Campo por campo

Quando a exibição é liberada, isto é o que a tela recebe. Seis campos na credencial, e três de contexto em volta.

{
  "ok": true,
  "revelada_em": 1755990000,
  "credencial": {
    "token": "EAAG...",
    "phone_number_id": "123456789012345",
    "waba_id": "987654321098765",
    "webhook": null,
    "webhook_verify_token": null,
    "expira_em": null
  },
  "aviso": { "enviado_para": "[email protected]" },
  "teto_por_dia": 3
}

Para trocar o endereço guardado, use o painel: em Canais, abra o número, vá na aba Detalhes e procure o cartão Ajustes de API. O endereço fica lá, com um botão para editar. Salvar em branco apaga o que estava guardado. A troca é de painel, e não um caminho de API para o seu sistema chamar.

Esse salvamento aponta na Meta. Ele avisa o dono da conta por e-mail antes de tocar em qualquer coisa, exige uma sessão com menos de dez minutos de vida, escreve a sobreposição no seu número e relê para gravar o estado verdadeiro. E é ele que devolve o código de verificação, quando o mesmo salvamento que gera o código fecha o apontamento. Se o código foi gerado antes, numa tentativa que a Meta recusou ou numa reaplicação feita pela rotina de operação da Zera, ele só sai por esta exibição. Com a conexão do número ainda por concluir, o salvamento só guarda o endereço. O passo a passo, com as travas e os estados possíveis, está em Receber mensagens.

Quem consegue exibir

[Decisão de 06/09/2026] Todo plano, inclusive o que tem caixa de entrada. Até 06/09/2026 esta seção dizia que só o plano sem caixa de entrada exibia: quem contratou o plano com a caixa da Zera tinha o atendimento rodando com essa mesma credencial, e a tela explicava e não mostrava nada, porque girar ou vazar ela derrubaria o próprio atendimento.

O ZeraSync passou a incluir a API do WhatsApp: a credencial serve para o seu sistema enviar, e o recebimento continua sendo da caixa de entrada da Zera (veja a faixa acima, e webhook.js desta mesma rota, que segue recusando plano com caixa). As duas coisas dividem a mesma credencial de propósito. O risco de girar ou vazar continua real, e quem segura ele hoje é a ausência de um botão de girar/regerar token nesta rota (veja "Por que não existe um botão de gerar outra", mais abaixo): enquanto não existir essa ação, só ver o valor não derruba nada.

Todo plano, sim. Toda pessoa da conta, não: desde 06 de setembro de 2026 só o dono da conta exibe a credencial. Quem entrou por convite recebe so_o_dono, HTTP 403, mesmo com uma sessão recém-feita. Isso é o que mais pega desenvolvedor, porque o normal é o cliente convidar quem vai integrar. O motivo está escrito na rota: o ZeraSync passou a incluir a API do WhatsApp justamente no plano vendido com a equipe inteira atendendo, ou seja, no plano em que a conta tem vários membros de baixo privilégio, e com essa credencial dá para mandar mensagem em nome da empresa e queimar a qualidade do número na Meta. A mesma conta já esconde o telefone completo desse membro; a credencial não podia ficar mais aberta que o telefone. Quem integra pede os valores ao dono da conta.

A conferência do plano é do lado do servidor, lendo o banco, e nunca um campo que veio do navegador. Dois casos que ainda caem numa recusa:

• Número de outra conta, ou identificador que não existe: os dois respondem nao_encontrado, HTTP 404, com o corpo idêntico. Um 403 confirmaria que aquele identificador existe, e confirmar a existência já é vazar.
• Número que nunca conectou (sem_waba) ou credencial sem cofre (sem_token): nenhum dos dois é sobre plano, são sobre o estado da conexão com a Meta: ver a tabela abaixo.

plano_com_inbox continua no vocabulário fechado da rota (a tabela abaixo lista os doze), mas nenhuma linha de decideRevelacao() emite esse código hoje: ele fica reservado para o dia em que nascer uma ação de girar/regerar token, que aí sim precisa recusar plano com caixa.

As doze recusas, e o que fazer em cada uma

O vocabulário é fechado: são estes doze códigos e nenhum outro. A ordem da tabela é a ordem em que a decisão pergunta, da trava que não custa nada para a que custa trabalho. Toda recusa decidida por esta rota devolve também o teto_por_dia. As recusas do portão comum do painel acontecem antes de a rota decidir qualquer coisa, e saem sem esse campo: sessao, conta_cancelada, origem, so_o_dono (quem entrou por convite é barrado ali, antes de a idade da sessão ser conferida), o nao_encontrado de identificador malformado e o indisponivel de banco fora do ar. Se você programa contra a resposta, trate teto_por_dia como opcional.

Duas observações honestas sobre essa lista. A primeira: indisponivel é também a resposta para um pedido que não seja POST, com HTTP 405. Hoje isso não acontece na sua tela, porque a rota só existe em POST: é um cinto para o dia em que alguém acrescentar outro caminho.

A segunda: existe ainda uma recusa que vem antes desta lista, e é do portão comum do painel. Se o pedido se identificar como vindo de outro site, a resposta é origem, HTTP 403, e o painel mostra esse código cru dizendo que não sabe traduzir ele. Não é defeito de conta nenhuma: é a guarda de origem barrando uma requisição forjada de fora, que é o caso em que o navegador declara a origem por conta própria.

Por que os dez minutos

O seu acesso ao painel vale por 30 dias. A credencial vale mais do que isso, porque sobrevive à sessão e só a Meta revoga. Se um cookie for roubado de um notebook esquecido, meses depois, ele ainda abre o painel; a trava dos dez minutos é o que impede que ele abra também a credencial de produção. É o mesmo padrão do banco que pede a senha de novo para mostrar o número do cartão.

Duas consequências práticas: entrar de novo, pelo link do e-mail ou pela senha, libera a exibição por dez minutos, e não é preciso fazer nada além disso. E se a leitura da idade da sessão falhar por qualquer motivo, a resposta é recusa, nunca liberação: não saber a idade é o caso em que mais interessa recusar.

Três a cada 24 horas, e o aviso que não desliga

O limite é de três exibições por conta, e não por número. Se você tem três números na mesma conta, os três dividem as mesmas três exibições.

• A janela é de 24 horas corridas, contada a partir de cada exibição, e não da meia-noite. A quarta tentativa dentro dessa janela recebe 429.
• A linha é gravada antes de o pedido dar certo, e não depois. É isso que impede dez cliques ao mesmo tempo de lerem a mesma contagem zero e passarem todos juntos. O que fica descontado das três são as exibições que aconteceram, mais as raras em que nem a devolução da cota conseguiu gravar.
• Falha nossa devolve a cota. Quando o problema é do nosso lado, o cofre que não abriu ou o e-mail que não saiu, aquela tentativa é marcada como ignorada e a contagem que segura as três passa a não enxergar ela. A linha continua existindo, porque ela é o registro da tentativa. A exceção é a conta sem e-mail no cadastro: a tentativa conta, porque o problema não passa sozinho.
• Ainda assim, tentar sem parar tem um fim. Existe um segundo limite, de 30 tentativas nas mesmas 24 horas, que conta tudo, inclusive as devolvidas. Ele não é sobre você ter pedido demais, e por isso a resposta dele é indisponivel e não teto_do_dia: ele existe para uma queda longa do nosso lado não virar escrita sem fim no nosso banco. Se você chegou nele, o caminho é escrever para a Zera.
• Estourar o limite também faz barulho do nosso lado. Um 429 aqui pode ser alguém raspando as credenciais de uma conta, e não só um cliente apressado.

O e-mail ao dono da conta

Ele sai para o e-mail do cadastro da conta, no mesmo minuto, com o assunto A credencial do seu número foi exibida no painel. Dentro dele vão três coisas: qual número, a data e a hora no relógio de São Paulo, e o endereço de onde o pedido partiu. O token não vai nesse e-mail, nem um pedaço dele, nem a impressão digital dele.

O aviso não é formalidade e não pode ser desligado. Como a Zera não consegue revogar a credencial, ele é a única forma de alguém descobrir uma exibição indevida na hora, e não na fatura da Meta. É também por isso que ele trava: se o provedor de e-mail recusar a mensagem, a credencial não é entregue.

Onde fica o registro

Toda exibição vira uma linha na aba Atividade do número, com a frase A credencial da Cloud API deste número foi exibida no painel. A tela lista as dez últimas, e o que sai dali para o seu navegador é só a data: nem o token, nem a impressão dele, nem o endereço de onde o pedido partiu.

Do lado de dentro, o que fica gravado no registro é a impressão digital do token, que responde qual token foi usado aqui sem expor o valor, mais o endereço de origem. E se a consulta dessa lista falhar, a aba diz que não conseguiu ler, em vez de mostrar uma lista vazia: lista vazia é uma afirmação, e afirmar que a credencial nunca foi exibida seria mentira se ninguém perguntou.

Quando o token para de funcionar: erro 190

A Meta devolve 190 (OAuthException) quando a autorização deixou de valer, e 200 quando ela vale mas não alcança mais aquele recurso. Na prática, para quem integra, os dois querem dizer a mesma coisa: a chamada não passa mais e nenhuma tentativa de repetir resolve.

O que o painel faz sozinho

A leitura do estado do número na Meta, que o botão Atualizar agora do cartão Estado na Meta dispara na aba Detalhes, chama a Meta com a sua autorização. Quando a resposta vem 190 ou 200, isso conta como revogação, e só esses dois códigos contam: limite de chamadas e queda de rede não são o cliente removendo a integração, e somar tudo no mesmo contador derrubaria um número perfeitamente vivo depois de três instabilidades da Meta.

Na terceira falha seguida desse tipo, o número passa para o estado revogado, a operação da Zera recebe um alerta e a tela passa a dizer que a sua autorização parou de valer para aquele número, com o botão Reconectar o número. Até lá, a leitura é recusada com o mesmo aviso e o mesmo botão, sem mudar o estado.

O que fazer no seu lado

1. Se o erro apareceu no seu sistema, pare de repetir a chamada. 190 não melhora com nova tentativa, e cada repetição é ruído no seu orçamento na Meta.
2. Reconecte o número pelo painel. Depois disso, exiba a credencial de novo e troque o token no seu cofre: o valor antigo não volta a valer.
3. Se você suspeita de vazamento, o caminho é na Meta, e não com a Zera: entre no Gerenciador de Negócios, remova o acesso do aplicativo a este número e depois escreva para [email protected] para a Zera refazer a conexão junto com você.
4. Guarde o fbtrace_id que vem no corpo do erro. É o que o suporte da Meta pede.

O que cada código de erro quer dizer, inclusive os que não têm nada a ver com autorização, está em Erros.

O que não existe aqui, e por quê

• Gerar outra credencial pelo painel. Só a Meta emite e só a Meta revoga. Um botão que promete o que o sistema não cumpre é pior do que a ausência dele.
• Mostrar uma vez só. É consequência da linha acima: sem poder gerar outra, esconder para sempre trancaria o cliente fora do que ele comprou. A defesa escolhida foi o barulho, e não a trava.
• Buscar a credencial por chave de API. A entrega é de tela, com sessão recente do painel e aviso ao dono. Copie uma vez e guarde no seu cofre.
• Apontar o seu webhook por esta exibição. Ela é leitura: a resposta traz qual endereço está guardado e qual é o código de verificação, e a tela desenha o código. Quem aponta na Meta é o salvamento do endereço no painel, ou a rotina de operação da Zera para um endereço já guardado, e o caminho inteiro está em Receber mensagens.

A lista completa do que a Zera não faz, com o motivo de cada ausência, está em O que a Zera não faz.