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

Conectar o número: QR, código de pareamento e chave de acesso (passkey)

Como conectar o número da instância por QR, código de pareamento ou chave de acesso (passkey), pelo painel ou pela API, com limites de tentativas.

6 min de leitura Atualizado em 14 de novembro de 2026

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?

  1. 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.
  2. No celular do número: Configurações, Aparelhos conectados, Conectar um aparelho, e leia o QR.
  3. 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.
  4. 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:

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance" -H "apikey: SUA_CHAVE"
json
{
  "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

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance/qr" -H "apikey: SUA_CHAVE"
json
{ "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

bash
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"}'
json
{ "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/restart pede 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/logout desconecta o número: depois disso só lendo o QR de novo. Por segurança, exige {"confirm": true} no corpo; sem isso devolve 422 confirmation_required.
bash
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átis

O 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

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

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