Pular para o conteúdo

Cabeçalhos

Os cabeçalhos HTTP da API: os que você envia (a chave e o Content-Type), os que as respostas trazem e os que chegam em cada entrega de webhook.

Ver em Markdown

A API usa poucos cabeçalhos próprios. Na requisição, você envia a chave de API e, quando há corpo, o Content-Type. Nas respostas, os cabeçalhos dizem quanto esperar antes de repetir e quanto da cota já foi usado. Nas entregas de webhook, eles trazem o token e a assinatura do projeto. Os nomes não diferenciam maiúsculas de minúsculas.

Na requisição

CabeçalhoQuandoValor
AuthorizationEm toda operação, exceto Baixar mídiaBearer wag_live_…: a chave de API
X-Api-KeyNo lugar de Authorization, se preferirwag_live_…: a mesma chave, sem o Bearer
Content-TypeSó nas requisições com corpoapplication/json

A chave de API

A chave vai em um dos dois cabeçalhos; os dois valem para todas as operações. Ela tem o formato wag_live_<prefixo de 8 caracteres>_<segredo de 43 caracteres> e é mostrada uma única vez, quando é criada. Veja Autenticação.

curl -s https://api.apiwpp.com/me \
  -H "Authorization: Bearer $API_KEY"
  • Sem nenhum dos dois, ou com uma chave desconhecida, revogada, expirada ou de um projeto desativado, a resposta é 401 com { "error": "Unauthorized" }.
  • Se você enviar os dois cabeçalhos, eles precisam trazer a mesma chave. Chaves diferentes respondem 401.
  • Cada chave errada conta para o limite de falhas de autenticação do IP: 20 em 5 minutos, por padrão, e depois 429 com Retry-After. A chave certa continua funcionando nesse período.
  • Baixar mídia não pede chave: a própria URL, assinada e com validade, é a credencial.

O corpo em JSON

As operações com corpo recebem JSON. Envie Content-Type: application/json só quando houver corpo:

O que você enviaResposta
Content-Type: application/json e um JSON válidoA operação é atendida
Content-Type: application/json e corpo vazio (por exemplo, num POST de desconectar, que não tem corpo)400 com code: FST_ERR_CTP_EMPTY_JSON_BODY
Content-Type: application/json e um corpo que não é JSON400 com code: FST_ERR_CTP_INVALID_JSON_BODY
Um corpo em outro formato, como application/x-www-form-urlencoded415 com code: FST_ERR_CTP_INVALID_MEDIA_TYPE
Um corpo com mais de 1 MiB413 com code: FST_ERR_CTP_BODY_TOO_LARGE
bashOperação sem corpo: sem Content-Type
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/disconnect \
  -H "Authorization: Bearer $API_KEY"

Na resposta

CabeçalhoEm quais respostasValor
Retry-After429 dos limites que passam sozinhos; 503 de instância mudando; 409 not_pairing quando os QR codes terminam cedo demaisSegundos até valer a pena repetir
X-Usage-Percent429 da cota do plano, só no envioO uso da cota diária ou mensal, em porcentagem inteira
X-Usage-WarningEnvios aceitos (202) a partir de 80% da cotaApproaching limit: 85% used
X-RateLimit-LimitToda resposta contada pelo limite de requisiçõesAs requisições permitidas por janela: 600, por padrão
X-RateLimit-RemainingIdemQuantas ainda cabem na janela atual
X-RateLimit-ResetIdemSegundos até a janela recomeçar
Content-TypeTodasapplication/json; em Baixar mídia, o tipo do arquivo
Cache-ControlBaixar mídiaprivate, max-age=…: até 1 hora, e nunca além da validade da URL

Retry-After

Quando a resposta traz Retry-After, espere esse número de segundos e repita a mesma requisição. Ele aparece em:

StatusQuando
429Requisições demais do mesmo IP (600 por minuto, por padrão)
429Falhas de autenticação demais do mesmo IP (20 em 5 minutos, por padrão)
429 new_recipient_cap_reachedO número alcançou o limite de destinatários novos das últimas 24 horas, no envio
429 pairing_code_too_soonUm código de pareamento pedido cedo demais
429Verificações de proxy demais da organização (60 por hora), em Definir proxy
503A instância do gateway que atende a conexão está mudando ou não responde
409 not_pairingOs QR codes do pareamento terminam cedo demais para alguém digitar um código

O 429 da cota do plano não traz Retry-After: repetir não adianta até a cota renovar ou o plano mudar. Veja Códigos de erro.

X-Usage-Percent e X-Usage-Warning

Os dois só aparecem em POST /connections/{id}/send e medem a cota de mensagens da organização, somando as já enviadas de todos os projetos dela e as que estão na fila.

  • X-Usage-Warning vem nos envios aceitos (202) quando o uso passa de 80% do limite diário ou do mensal, por exemplo Approaching limit: 85% used. É o aviso para agir antes do bloqueio.
  • X-Usage-Percent vem no 429 da cota esgotada, com a porcentagem do limite que bloqueou. O bloqueio acontece com 10% de tolerância acima do limite, então o valor passa de 100 (por exemplo, 110).

Uma repetição com o mesmo clientRef de um envio já aceito responde 200 antes da verificação de cota e não traz esses cabeçalhos.

# -i mostra o status e os cabeçalhos da resposta
curl -si -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"}'
202
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 41
X-Usage-Warning: Approaching limit: 85% used

X-RateLimit

As respostas contadas pelo limite de requisições trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. O limite é por IP de origem, não por chave: todas as chaves que saem do mesmo IP dividem a mesma janela. Quando ela acaba, a resposta é 429 com X-RateLimit-Remaining: 0 e Retry-After. Veja Limites de envio.

Nas entregas de webhook

Cada entrega de evento ao webhookBaseUrl do projeto é um POST com estes cabeçalhos:

CabeçalhoQuandoValor
Content-TypeSempreapplication/json
X-Webhook-TokenSempreO webhookToken do projeto
X-Sales-TimestampCom um webhookSecret no projetoSegundos unix do momento da tentativa; cada nova tentativa é assinada de novo
X-Sales-SignatureCom um webhookSecret no projetosha256= + hex(HMAC-SHA256(webhookSecret, timestamp + "." + corpo bruto))
Os de webhookHeadersQuando o projeto define cabeçalhos extrasOs valores definidos no projeto
  • Rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio e compare a assinatura em tempo constante, sobre os bytes do corpo como chegaram.
  • Os cabeçalhos extras de webhookHeaders podem substituir Content-Type e X-Webhook-Token, mas nunca X-Sales-Timestamp e X-Sales-Signature: esses são sempre os do gateway.
  • O evento de teste ping traz os mesmos cabeçalhos das entregas reais.

A verificação completa, com código em Node.js, PHP e Python, está em Webhooks e assinatura.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026