Recurso em beta: pode mudar (rotas de QR, código, reinício e desconexão pela API). Provado em 10/11/2026: o pareamento por código em um número real e o reinício do relé do IP, que reconectou em cerca de 1 segundo, sem ler o QR. Ainda não provados: o pareamento por QR, a chave de acesso (passkey) e a troca para outro IP real de provedor.
Resposta curta: para conectar o número, abra o WhatsApp no celular dele, entre em Aparelhos conectados e leia o QR do painel, ou digite o código de pareamento de 8 caracteres. Pela API, GET /instance/qr devolve o QR e POST /instance/pair-code devolve o código. Se o WhatsApp pedir a chave de acesso, confirme no celular.
Como conecto pelo painel?
- No painel, abra API de WhatsApp e a instância. Quando o estado for Aguardando a leitura do QR, o QR aparece e se renova sozinho.
- No celular do número: Configurações, Aparelhos conectados, Conectar um aparelho, e leia o QR.
- Se a câmera não ler, escolha Conectar com número de telefone no celular e, no painel, Gerar código. Digite o código que o painel mostra.
- O estado muda para Conectado e o número aparece.
O código só deve ser gerado depois que o celular estiver na tela de digitar o código: ele vale poucos minutos, e na prova de 10/11/2026 a primeira tentativa expirou por isso. O botão do painel só gera o código quando clicado.
Como conecto pela API?
Todas as rotas usam o mesmo cabeçalho apikey e a base https://proxybox.com.br/api/whatsapp/v1.
Ver em que passo está
GET /instance informa o estado e, quando precisa de leitura, uma dica de próximo passo:
curl "https://proxybox.com.br/api/whatsapp/v1/instance" -H "apikey: SUA_CHAVE"
{
"ok": true,
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja", "status": "awaiting_qr", "connected": false, "phone": null, "plan": "with_ip" },
"passkey": false,
"signal": { "level": "ok", "label": "Funcionando", "until": null },
"qr_hint": "Chame GET /api/whatsapp/v1/instance/qr (ou POST /instance/pair-code) e leia o QR com o WhatsApp do número."
}
Pedir o QR
curl "https://proxybox.com.br/api/whatsapp/v1/instance/qr" -H "apikey: SUA_CHAVE"
{ "ok": true, "png_base64": "iVBORw0KGgoAAAANSUhEUgAA…", "expires_in": 20 }
png_base64 é a imagem do QR em PNG; mostre-a ao usuário (<img src="data:image/png;base64,...">). expires_in diz em quantos segundos ele deixa de valer. Se vier code, é o texto do QR. Depois de expires_in, peça outro. Se o número já está conectado, a resposta é 409 already_connected.
Pedir o código de pareamento
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/pair-code" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"phone":"5547999999999"}'
{ "ok": true, "code": "ABCD-1234" }
O phone é o número que está no celular. Peça o código quando o usuário já estiver na tela de digitar; ele vale poucos minutos. Telefone inválido devolve 422 invalid_request com fields: ["phone"].
Reconectar e desconectar
POST /instance/restartpede a reconexão da sessão (o mesmo que o botão do painel). Útil quando o estado ficou preso. Não precisa ler o QR de novo se a sessão está válida.POST /instance/logoutdesconecta o número: depois disso só lendo o QR de novo. Por segurança, exige{"confirm": true}no corpo; sem isso devolve422 confirmation_required.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/logout" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" -d '{"confirm":true}'
Quais são os limites?
| Rota | Limite por instância |
|---|---|
GET /instance/qr e POST /instance/pair-code |
12 por minuto |
POST /instance/restart |
5 por minuto |
POST /instance/logout |
3 por hora |
Passou do limite: 429. A API não faz laço de renovação por você: se o seu sistema mostra o QR, peça um novo só depois do expires_in, e pare depois de algumas tentativas sem leitura.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisO que é a chave de acesso (passkey)?
Alguns aparelhos, em especial iPhones, podem pedir uma chave de acesso do WhatsApp (passkey) para confirmar a conexão de um aparelho novo, no lugar do código. Quando isso acontece, a conexão fica esperando a confirmação no celular.
A API só informa o estado: GET /instance traz passkey verdadeiro quando a instância está esperando essa confirmação. A ação em si é feita no painel e no celular do número, não por chamada de API. No teste de 10/11/2026, o pareamento por código num iPhone não pediu a chave de acesso; o fluxo com a chave ainda não foi provado.
O que fazer se não conecta?
| Sintoma | O que fazer |
|---|---|
| O QR expira antes de ler | Peça outro e leia logo; mostre a imagem grande |
| O código foi recusado | Ele expirou ou foi gerado cedo demais. Gere outro quando o celular estiver na tela de digitar |
409 already_connected |
O número já está conectado; para trocar de número, POST /instance/logout e leia o QR do novo |
| O WhatsApp pede a chave de acesso | Confirme no celular; o painel mostra o aviso |
| Cai de novo logo depois de conectar | Veja number.logged_out e signal; o WhatsApp pode ter desconectado o número |
| Estado preso em "Conectando" | POST /instance/restart |
| Número restrito para contato novo | Conecta normalmente; a restrição afeta só os envios: restrição 463 |
Depois de conectado, o IP brasileiro dedicado já é o de saída da instância. Reiniciar o relé do IP reconectou em cerca de 1 segundo, sem QR (prova de 10/11/2026). A troca para outro IP de provedor real ainda não foi provada: o WhatsApp pode pedir a leitura do QR outra vez.
Próximo passo: a primeira mensagem. Se o número já tinha um código de pareamento pendente, o glossário explica os termos.
Veja também
- Enviar a 1ª mensagem pela API de WhatsApp
- Erro 463 do WhatsApp (contato novo): o que fazer
- Nono dígito e @lid na API de WhatsApp
- Segurança da API de WhatsApp: chave e IPs
Índice completo: índice dos guias. Sobre o produto: API de WhatsApp com IP brasileiro dedicado.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Pareamento por código provado em 10/11/2026; rotas da API descritas conforme o adendo 8.1 da versão 1.1, revisadas em 11/11/2026.