O que existe hoje?
| Recurso | Para quê | Onde |
|---|---|---|
| OpenAPI 3.1 | Gerar clientes, validar chamadas, documentação interativa | https://proxybox.com.br/api-whatsapp/openapi.json |
| Coleção do Postman | Testar rota a rota; também abre no Insomnia e no Bruno | https://proxybox.com.br/api-whatsapp/postman.json |
| Referência | Exemplo de pedido e resposta de cada rota | Esta documentação |
| Conector MCP | Operar a API por um assistente de IA | Pacote proxybox-mcp |
| Nós do n8n | Montar fluxos sem código | Pacote n8n-nodes-proxybox-whatsapp |
| Sandbox | Testar o cliente sem número | Painel |
As especificações ficam publicadas junto da página da API e abrem quando ela abre.
Como gero um cliente a partir do OpenAPI?
Com um gerador de código aberto, como o OpenAPI Generator, que lê a especificação e escreve um cliente:
# exemplo: cliente Python (confira a versão e as opções do gerador que você usa)
curl -o openapi.json https://proxybox.com.br/api-whatsapp/openapi.json
npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o ./cliente-wa
Dicas para o resultado funcionar bem:
- Autenticação: a especificação declara o esquema
apikey(cabeçalho). Configure-o no cliente gerado. - Repetição segura: todo
POST /messages/*aceita o cabeçalhoIdempotency-Key; garanta que o seu cliente consegue enviá-lo. - Campos desconhecidos: gere ou configure o cliente para ignorar campos que não conhece. A API acrescenta campos ao longo das versões.
- Teste no sandbox antes de apontar para uma instância real.
- Erros: todo erro tem
{ ok:false, error, message }; o códigoerroré estável, a frase pode mudar.
Não garantimos que um cliente gerado compile ou funcione em todas as linguagens e versões de gerador: não testamos todas. Se achar um problema na especificação, abra um ticket.
Cliente mínimo em Node
Sem dependência: Node 18 ou mais novo (tem fetch).
// wa.js
const BASE = "https://proxybox.com.br/api/whatsapp/v1";
export class WhatsApp {
constructor(apikey, { tentativas = 2 } = {}) {
this.apikey = apikey;
this.tentativas = tentativas;
}
async chamar(metodo, caminho, corpo, { idempotencia } = {}) {
const headers = { apikey: this.apikey, "Content-Type": "application/json" };
if (idempotencia) headers["Idempotency-Key"] = idempotencia;
for (let i = 0; ; i++) {
const r = await fetch(BASE + caminho, { method: metodo, headers, body: corpo ? JSON.stringify(corpo) : undefined, signal: AbortSignal.timeout(30000) });
const json = await r.json().catch(() => ({}));
// 429: espera o retry_after e repete; 502/503: nada saiu, repete; 504: NUNCA repete
if ((r.status === 429 || r.status === 502 || r.status === 503) && i < this.tentativas) {
await new Promise((ok) => setTimeout(ok, (json.retry_after ?? 2) * 1000));
continue;
}
if (!r.ok || json.ok === false) throw Object.assign(new Error(json.message || `HTTP ${r.status}`), { status: r.status, codigo: json.error, resposta: json });
return json;
}
}
texto(para, texto, chave) { return this.chamar("POST", "/messages/text", { to: para, text: texto }, { idempotencia: chave }); }
estado() { return this.chamar("GET", "/instance"); }
}
Uso: const wa = new WhatsApp(process.env.WA_KEY); await wa.texto("5547999999999", "Oi", "pedido-4512-aviso");
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisCliente mínimo em Python
Precisa só da biblioteca requests.
# wa.py
import time
import requests
BASE = "https://proxybox.com.br/api/whatsapp/v1"
class ErroWhatsApp(Exception):
def __init__(self, status, codigo, mensagem):
super().__init__(mensagem)
self.status, self.codigo = status, codigo
class WhatsApp:
def __init__(self, apikey, tentativas=2):
self.h = {"apikey": apikey}
self.tentativas = tentativas
def chamar(self, metodo, caminho, corpo=None, idempotencia=None):
h = dict(self.h)
if idempotencia:
h["Idempotency-Key"] = idempotencia
for i in range(self.tentativas + 1):
r = requests.request(metodo, BASE + caminho, headers=h, json=corpo, timeout=30)
try:
j = r.json()
except ValueError:
j = {}
# 429/502/503: repete; 504: nunca
if r.status_code in (429, 502, 503) and i < self.tentativas:
time.sleep(j.get("retry_after", 2))
continue
if not r.ok or j.get("ok") is False:
raise ErroWhatsApp(r.status_code, j.get("error"), j.get("message", f"HTTP {r.status_code}"))
return j
def texto(self, para, texto, chave=None):
return self.chamar("POST", "/messages/text", {"to": para, "text": texto}, chave)
Cliente mínimo em PHP
Precisa da extensão cURL (já vem na maioria das instalações).
<?php
final class WhatsApp
{
private const BASE = 'https://proxybox.com.br/api/whatsapp/v1';
public function __construct(private string $apikey, private int $tentativas = 2) {}
/** @return array<string,mixed> */
public function chamar(string $metodo, string $caminho, ?array $corpo = null, ?string $idempotencia = null): array
{
$headers = ['apikey: '.$this->apikey, 'Content-Type: application/json'];
if ($idempotencia) {
$headers[] = 'Idempotency-Key: '.$idempotencia;
}
for ($i = 0;; $i++) {
$ch = curl_init(self::BASE.$caminho);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => $corpo ? json_encode($corpo) : null,
]);
$resp = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$json = json_decode((string) $resp, true) ?: [];
// 429/502/503: repete; 504: nunca
if (in_array($status, [429, 502, 503], true) && $i < $this->tentativas) {
sleep((int) ($json['retry_after'] ?? 2));
continue;
}
if ($status >= 400 || ($json['ok'] ?? true) === false) {
throw new RuntimeException($json['message'] ?? "HTTP $status", $status);
}
return $json;
}
}
public function texto(string $para, string $texto, ?string $chave = null): array
{
return $this->chamar('POST', '/messages/text', ['to' => $para, 'text' => $texto], $chave);
}
}
Esses três arquivos são exemplos, não pacotes mantidos. Copie, adapte e teste. Trate o 504 à parte: ele significa "o WhatsApp demorou; a mensagem pode ter saído", e o certo é conferir antes de reenviar, como explica erros e limites.
Como escolho entre gerar o cliente e usar um mínimo?
Gere o cliente quando a sua equipe usa muitas rotas e quer tipos e validação automática: o gerador cria uma classe por rota e você não escreve a montagem de URL. Use um cliente mínimo, como os acima, quando o uso é pequeno (enviar texto, receber aviso, consultar o estado) e você prefere ter poucas linhas que entende por inteiro. Em ambos os casos, mantenha dois cuidados que valem mais que o estilo do código: repetir só o que é seguro (429, 502 e 503; nunca o 504) e usar Idempotency-Key em todo envio. E teste contra o sandbox antes de apontar para um número de verdade: lá o sandbox: true na resposta mostra que o cliente está falando com o ambiente certo.
E os SDKs oficiais?
O plano de produto é gerá-los do OpenAPI, para Node/TypeScript, Python e PHP, nessa ordem de prioridade, e só sob demanda para Go, Java, C# e Ruby. Isso depende de a especificação cobrir todas as rotas, de testar o gerador com o arquivo real, e de contas de publicação (npm, PyPI, Packagist). Não há data. Para Go, Java, C# e Ruby, a referência já traz exemplos prontos dos cinco usos principais.
Quando houver pacote, ele aparecerá aqui e no histórico de versões. Se um SDK em particular faz diferença na sua decisão de compra, diga ao suporte: pedidos de clientes entram na ordem de prioridade.
Onde ficam o OpenAPI, o Postman e a página de status?
Recurso em beta: pode mudar. Os três endereços abaixo são gerados do mesmo catálogo de operações da API e só abrem quando a página API de WhatsApp abre ao público. Antes disso, respondem 404.
Resposta curta: a especificação OpenAPI 3.1 fica em https://proxybox.com.br/api-whatsapp/openapi.json, a coleção do Postman em https://proxybox.com.br/api-whatsapp/postman.json e o estado do serviço em https://proxybox.com.br/api-whatsapp/status. Importe o primeiro ou o segundo no seu cliente de API, preencha apikey com a chave da instância e teste.
O que é cada arquivo?
| Endereço | O que é | Para que serve |
|---|---|---|
/api-whatsapp/openapi.json |
Especificação OpenAPI 3.1, em português, com exemplos por rota e o esquema do cabeçalho apikey |
Gerar cliente de código, importar em Insomnia e Bruno, validar chamadas |
/api-whatsapp/postman.json |
Coleção do Postman v2.1, com a variável {{apikey}} |
Testar as rotas à mão |
/api-whatsapp/status |
Página de estado do serviço e histórico de incidentes; ?format=json devolve o mesmo em JSON |
Saber se o problema é seu ou nosso |
Os arquivos são gerados do mesmo catálogo que alimenta o painel, o conector MCP e esta documentação. Quando uma rota muda, os três mudam juntos. Eles ficam fora do caminho /api/ de propósito, para os robôs de busca e de IA poderem lê-los.
Como importo no Postman?
- No Postman, clique em Import.
- Cole
https://proxybox.com.br/api-whatsapp/postman.jsone confirme. - Abra a coleção, vá em Variables e preencha
apikeycom a chave da instância (pbwa_…). - Abra GET /instance e clique em Send. Uma resposta com
"ok": truee o estado da instância mostra que a chave funciona.
Como importo no Insomnia?
- Em Create, escolha Import e From URL.
- Cole
https://proxybox.com.br/api-whatsapp/openapi.json. - Nas variáveis de ambiente, crie
apikeycom a sua chave, ou acrescente o cabeçalhoapikeyna coleção.
Como importo no Bruno?
- Em Collections, escolha Import collection e o tipo OpenAPI.
- Informe o endereço do
openapi.json(ou baixe o arquivo antes e escolha-o do disco). - Nas variáveis do ambiente, crie
apikey.
Os nomes dos menus mudam entre versões desses programas; o caminho é sempre importar por endereço ou por arquivo.
Como uso a especificação para gerar código?
Qualquer gerador de OpenAPI aceita o arquivo. Um exemplo com o gerador de linha de comando mais comum:
curl -o whatsapp-openapi.json https://proxybox.com.br/api-whatsapp/openapi.json
npx @openapitools/openapi-generator-cli generate -i whatsapp-openapi.json -g python -o ./cliente-whatsapp
O código gerado herda os campos to, media e schedule de cada rota. Para um uso simples, as chamadas diretas dos primeiros passos costumam ser menores.
Como leio a página de status?
A página de status mostra:
- O estado atual do serviço, tirado das verificações do próprio sistema: se está funcionando, com problema ou fora do ar.
- A porcentagem de instâncias respondendo, somando todas, sem dado de nenhum cliente.
- O histórico de incidentes, escrito pela equipe: o que aconteceu, quando começou e quando acabou.
curl "https://proxybox.com.br/api-whatsapp/status?format=json"
O que ela não mostra: o estado de um número seu (isso é GET /instance e GET /health) e se o WhatsApp está fora do ar no mundo todo. Um número desconectado quase sempre é assunto do número, não do serviço. A ordem para investigar é: GET /health, o histórico de erros e limites e, se tudo estiver bem do seu lado, a página de status.
E o llms.txt?
A ProxyBox publica um llms.txt com o resumo da API para assistentes de IA e agentes de código, apontando para estes arquivos e para os guias. Ele não substitui o OpenAPI: serve para quem lê em Markdown. O conector MCP é o caminho para quem trabalha dentro do Claude ou do Cursor.
E a mudança de versão?
A versão da API está no caminho (/v1). Mudanças que quebram código existente serão anunciadas no histórico de versões com data antes de entrar. A especificação sempre descreve a versão atual, e cada rota nova aparece como beta até ser provada em uso real.
Veja também
- Referência da API de WhatsApp v1.2: rotas
- Erros e limites da API de WhatsApp
- Enviar a 1ª mensagem pela API de WhatsApp
- MCP do WhatsApp para Claude e Cursor
Índice completo: índice dos guias.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Os clientes mínimos são exemplos sem garantia; os SDKs oficiais não existem ainda.