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.
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çalho | Quando | Valor |
|---|---|---|
Authorization | Em toda operação, exceto Baixar mídia | Bearer wag_live_…: a chave de API |
X-Api-Key | No lugar de Authorization, se preferir | wag_live_…: a mesma chave, sem o Bearer |
Content-Type | Só nas requisições com corpo | application/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"curl -s https://api.apiwpp.com/me \
-H "X-Api-Key: $API_KEY"- Sem nenhum dos dois, ou com uma chave desconhecida, revogada, expirada ou de um projeto desativado, a resposta é
401com{ "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
429comRetry-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ê envia | Resposta |
|---|---|
Content-Type: application/json e um JSON válido | A 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 é JSON | 400 com code: FST_ERR_CTP_INVALID_JSON_BODY |
Um corpo em outro formato, como application/x-www-form-urlencoded | 415 com code: FST_ERR_CTP_INVALID_MEDIA_TYPE |
| Um corpo com mais de 1 MiB | 413 com code: FST_ERR_CTP_BODY_TOO_LARGE |
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/disconnect \
-H "Authorization: Bearer $API_KEY"Na resposta
| Cabeçalho | Em quais respostas | Valor |
|---|---|---|
Retry-After | 429 dos limites que passam sozinhos; 503 de instância mudando; 409 not_pairing quando os QR codes terminam cedo demais | Segundos até valer a pena repetir |
X-Usage-Percent | 429 da cota do plano, só no envio | O uso da cota diária ou mensal, em porcentagem inteira |
X-Usage-Warning | Envios aceitos (202) a partir de 80% da cota | Approaching limit: 85% used |
X-RateLimit-Limit | Toda resposta contada pelo limite de requisições | As requisições permitidas por janela: 600, por padrão |
X-RateLimit-Remaining | Idem | Quantas ainda cabem na janela atual |
X-RateLimit-Reset | Idem | Segundos até a janela recomeçar |
Content-Type | Todas | application/json; em Baixar mídia, o tipo do arquivo |
Cache-Control | Baixar mídia | private, 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:
| Status | Quando |
|---|---|
429 | Requisições demais do mesmo IP (600 por minuto, por padrão) |
429 | Falhas de autenticação demais do mesmo IP (20 em 5 minutos, por padrão) |
429 new_recipient_cap_reached | O número alcançou o limite de destinatários novos das últimas 24 horas, no envio |
429 pairing_code_too_soon | Um código de pareamento pedido cedo demais |
429 | Verificações de proxy demais da organização (60 por hora), em Definir proxy |
503 | A instância do gateway que atende a conexão está mudando ou não responde |
409 not_pairing | Os 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-Warningvem nos envios aceitos (202) quando o uso passa de 80% do limite diário ou do mensal, por exemploApproaching limit: 85% used. É o aviso para agir antes do bloqueio.X-Usage-Percentvem no429da 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"}'// Node.js 18+: fetch nativo
const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ to: '5511988887777', message: 'Olá!', clientRef: 'pedido-1234' }),
})
const warning = res.headers.get('x-usage-warning')
if (warning) console.warn(`Cota de mensagens perto do fim: ${warning}`)
const remaining = Number(res.headers.get('x-ratelimit-remaining'))
if (remaining < 50) console.warn(`Restam ${remaining} requisições nesta janela`)
if (res.status === 429 || res.status === 503) {
const retryAfter = Number(res.headers.get('retry-after'))
const usagePercent = res.headers.get('x-usage-percent')
if (usagePercent) {
// Cota do plano esgotada: não repita
} else if (retryAfter > 0) {
// Espere retryAfter segundos e repita com o mesmo clientRef
}
}<?php
$ch = curl_init('https://api.apiwpp.com/connections/' . getenv('CONNECTION_ID') . '/send');
$headers = [];
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['to' => '5511988887777', 'message' => 'Olá!', 'clientRef' => 'pedido-1234']),
// Guarda os cabeçalhos da resposta, com o nome em minúsculas
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
$parts = explode(':', $line, 2);
if (count($parts) === 2) {
$headers[strtolower(trim($parts[0]))] = trim($parts[1]);
}
return strlen($line);
},
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if (isset($headers['x-usage-warning'])) {
error_log('Cota de mensagens perto do fim: ' . $headers['x-usage-warning']);
}
if (($status === 429 || $status === 503) && !isset($headers['x-usage-percent'])) {
$retryAfter = (int) ($headers['retry-after'] ?? 0);
// Espere $retryAfter segundos e repita com o mesmo clientRef
}# pip install requests
import os
import requests
res = requests.post(
f"https://api.apiwpp.com/connections/{os.environ['CONNECTION_ID']}/send",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"},
timeout=30,
)
# requests trata os nomes dos cabeçalhos sem diferenciar maiúsculas
if "X-Usage-Warning" in res.headers:
print("Cota de mensagens perto do fim:", res.headers["X-Usage-Warning"])
if res.status_code in (429, 503) and "X-Usage-Percent" not in res.headers:
retry_after = int(res.headers.get("Retry-After", "0") or 0)
# Espere retry_after segundos e repita com o mesmo clientRefHTTP/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% usedX-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çalho | Quando | Valor |
|---|---|---|
Content-Type | Sempre | application/json |
X-Webhook-Token | Sempre | O webhookToken do projeto |
X-Sales-Timestamp | Com um webhookSecret no projeto | Segundos unix do momento da tentativa; cada nova tentativa é assinada de novo |
X-Sales-Signature | Com um webhookSecret no projeto | sha256= + hex(HMAC-SHA256(webhookSecret, timestamp + "." + corpo bruto)) |
Os de webhookHeaders | Quando o projeto define cabeçalhos extras | Os valores definidos no projeto |
- Rejeite um
X-Sales-Timestampa 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
webhookHeaderspodem substituirContent-TypeeX-Webhook-Token, mas nuncaX-Sales-TimestampeX-Sales-Signature: esses são sempre os do gateway. - O evento de teste
pingtraz 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
- Autenticação: criar, rotacionar e revogar a chave que vai em
Authorization. - Códigos de erro: cada resposta que traz
Retry-Aftere o que fazer. - Webhooks e assinatura: verificar
X-Sales-Signaturepasso a passo. - Limites: os números por trás de
X-RateLimite dos429.