Autenticação

A API usa Bearer token por instância. Cada instância (número de WhatsApp) tem o seu próprio token, e é ele que diz qual número envia ou recebe. Não há header de instância separado.

Header

Envie o token no header Authorization em toda requisição. O token identifica a instância e a conta, o número usado na operação é o dono do token.

Gere e rotacione tokens no painel, em Credenciais.

Headers da requisição

HTTP

Authorization: Bearer zd_live_a93f2c10e7b4
Content-Type: application/json

Tipos de chave

Dois ambientes, distinguidos pelo prefixo do token:

Prefixo	Ambiente	Descrição
zd_live_	Produção	Mensagens são entregues de verdade e contam no uso do plano.
zd_test_	Teste (em breve)	Simula respostas sem entregar mensagens. Ideal para CI.

Cuidado

Nunca exponha seu token zd_live_. Ele dá acesso à instância. Não comite em repositórios, não use em apps front-end e não envie por canais inseguros.

Boas práticas

• Guarde tokens em variáveis de ambiente (ZAPDEV_TOKEN), nunca no código.
• Rotacione a chave no painel imediatamente se suspeitar de vazamento, a antiga é invalidada na hora.
• Use tokens separados por aplicação para facilitar a rotação.

Erros de autenticação

Requisições sem token, ou com token inválido/revogado, retornam 401 Unauthorized com o envelope de erro padrão. Veja todos os códigos em Erros.

error.code	Quando
missing_token	Header Authorization ausente
invalid_token	Token inválido ou de instância inexistente
expired_token	Token expirado

Resposta · 401

401 Unauthorized

{
  "error": {
    "code": "invalid_token",
    "message": "Token de API inválido ou revogado.",
    "requestId": "req_abc123"
  }
}