Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Integrações

SDKs, OpenAPI e Postman: o que existe hoje para a API de WhatsApp?

Sem SDK publicado ainda: gere um cliente do OpenAPI 3.1, importe o Postman, veja a página de status e copie clientes mínimos em Node, Python e PHP.

5 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
A ProxyBox ainda não publica SDKs. O plano é gerar clientes de Node, Python e PHP a partir da especificação, mas não há data e esta página só será mudada quando eles existirem. Enquanto isso, você tem a especificação OpenAPI 3.1 para gerar um cliente na linguagem que quiser, a coleção do Postman, o conector de IA e os nós do n8n, e três clientes mínimos de uma página, nesta página, para copiar. Aqui também estão o OpenAPI 3.1, a coleção do Postman e a página de status, com o passo a passo de importação. Atualização de 12/11/2026: pacotes 0.1.0 de Node, Python e PHP já foram gerados do OpenAPI e testados com servidor de mentira, mas ainda não estão publicados em npm, PyPI ou Packagist; quando estiverem, o endereço aparece aqui.

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:

sh
# 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:

  1. Autenticação: a especificação declara o esquema apikey (cabeçalho). Configure-o no cliente gerado.
  2. Repetição segura: todo POST /messages/* aceita o cabeçalho Idempotency-Key; garanta que o seu cliente consegue enviá-lo.
  3. Campos desconhecidos: gere ou configure o cliente para ignorar campos que não conhece. A API acrescenta campos ao longo das versões.
  4. Teste no sandbox antes de apontar para uma instância real.
  5. Erros: todo erro tem { ok:false, error, message }; o código error é 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).

js
// 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átis

Cliente mínimo em Python

Precisa só da biblioteca requests.

python
# 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
<?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?

  1. No Postman, clique em Import.
  2. Cole https://proxybox.com.br/api-whatsapp/postman.json e confirme.
  3. Abra a coleção, vá em Variables e preencha apikey com a chave da instância (pbwa_…).
  4. Abra GET /instance e clique em Send. Uma resposta com "ok": true e o estado da instância mostra que a chave funciona.

Como importo no Insomnia?

  1. Em Create, escolha Import e From URL.
  2. Cole https://proxybox.com.br/api-whatsapp/openapi.json.
  3. Nas variáveis de ambiente, crie apikey com a sua chave, ou acrescente o cabeçalho apikey na coleção.

Como importo no Bruno?

  1. Em Collections, escolha Import collection e o tipo OpenAPI.
  2. Informe o endereço do openapi.json (ou baixe o arquivo antes e escolha-o do disco).
  3. 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:

bash
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.
bash
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

Í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.

Perguntas frequentes

Existe um pacote oficial no npm, PyPI ou Packagist?
Ainda não. Os SDKs de Node, Python e PHP serão gerados a partir do OpenAPI, mas não há data nem compromisso de lançamento. Esta página será atualizada quando existirem.
Posso gerar um cliente sozinho?
Sim. O OpenAPI 3.1 está em /api-whatsapp/openapi.json, e geradores como o OpenAPI Generator produzem clientes em dezenas de linguagens. Confira o resultado com a sua versão do gerador antes de depender dele.
A API muda e quebra o meu cliente gerado?
Acrescentar campos não é mudança que quebra. Mudanças que quebram serão avisadas no histórico de versões, com data. Programe o cliente para ignorar campos desconhecidos.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp