Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey

Dá para conectar um número na API não oficial do WhatsApp sem QR Code: o POST /{key}/instance/pairing-code devolve um código que você digita no próprio celular, e para contas que exigem passkey existe o WAME Passkey, um app desktop que aprova o login e envia a sessão para a sua instância. O QR Code continua disponível, mas deixou de ser o único caminho — e isso muda muito quando quem precisa conectar é o seu cliente, do outro lado do país.

Neste guia você vê os três métodos, quando usar cada um, como acompanhar a conexão por webhook e o que fazer quando a sessão cai.

Por que existem três jeitos de conectar

A API não oficial conecta o seu número como um aparelho vinculado, igual ao WhatsApp Web ou ao WhatsApp Desktop. O WhatsApp oferece mais de uma forma de vincular um aparelho, e cada uma resolve um problema:

Nenhum deles exige criar app na Meta, verificar empresa ou aprovar número — é uma das grandes vantagens da camada não oficial.

A camada não oficial da WAME é independente e não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Antes de tudo: configure os webhooks

Conectar é um processo assíncrono — o QR expira e é renovado, a pessoa leva um tempo para digitar o código. Em vez de ficar consultando, receba os eventos. O PUT /{key}/instance define para onde cada tipo de evento vai:

curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookQrCode": "https://seusistema.com/wame/qrcode",
    "webhookConnection": "https://seusistema.com/wame/conexao",
    "webhookMessage": "https://seusistema.com/wame/mensagens",
    "webhookFormat": "meta"
  }'

• webhookQrCode recebe cada QR Code novo (útil para mostrar no seu painel).
• webhookConnection avisa quando a instância conecta, desconecta ou faz logout.
• webhookMessage é onde as mensagens vão chegar depois.

Método 1: QR Code

O clássico. Um POST inicia a conexão e devolve o QR Code:

curl -X POST "https://us.api-wa.me/SUA_KEY/instance"

No celular: WhatsApp > Aparelhos conectados > Conectar um aparelho, e escaneie. Se você configurou o webhookQrCode, os QR renovados chegam lá automaticamente — mostre sempre o mais recente no seu painel, porque um QR antigo não funciona.

Funciona muito bem quando você está conectando o seu próprio número. Fica ruim quando você precisa instruir um cliente por telefone a abrir uma tela, achar o QR e apontar a câmera.

Método 2: código de pareamento

Aqui você informa o número que vai conectar e recebe um código curto:

curl -X POST "https://us.api-wa.me/SUA_KEY/instance/pairing-code" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "5511999999999" }'

No celular: WhatsApp > Aparelhos conectados > Conectar um aparelho > Conectar com número de telefone, e digite o código. O número deve estar no formato internacional, só com dígitos, e precisa ser o mesmo número do celular onde o código será digitado.

Por que isso é tão útil:

• Onboarding remoto. Você manda o código por e-mail, SMS ou pelo seu painel, e o cliente digita. Nada de videochamada para "mostrar o QR".
• Sem câmera. Celular com câmera quebrada, tela pequena, pessoa com dificuldade de enquadrar o QR — o código resolve.
• Automatizável. Seu SaaS pode ter um fluxo "digite seu número → receba o código → conecte", todo dentro do seu produto.

Um fluxo típico de onboarding em Node.js:

const BASE = 'https://us.api-wa.me';

// 1. Cliente informa o número no seu painel
app.post('/onboarding/whatsapp', async (req, res) => {
  const { key, telefone } = req.body; // key da instância deste cliente
  const r = await fetch(`${BASE}/${key}/instance/pairing-code`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phoneNumber: telefone }),
  });
  // A resposta traz o código em `code` e, em `isConnected`,
  // se a instância já está conectada.
  const { code, isConnected } = await r.json();
  res.json({ code, isConnected }); // mostre `code` na tela do cliente
});

// 2. Webhook de conexão avisa quando terminou
app.post('/wame/conexao', (req, res) => {
  res.sendStatus(200);
  // Atualize o status do cliente no seu banco e libere o próximo passo
});

Se você provisiona instâncias para muitos clientes, esse é o fluxo que mais reduz chamados de suporte. Mais sobre a gestão de várias contas em provisionar WhatsApp para vários clientes por API.

Método 3: WAME Passkey

O WhatsApp passou a exigir passkey — chave de acesso confirmada por biometria ou PIN do aparelho — para aprovar o login de algumas contas. Como o passkey fica no dispositivo do dono da conta, ele não pode ser aprovado por uma API remota diretamente.

O WAME Passkey resolve isso. É um app desktop gratuito e open-source, para macOS, Windows e Linux:

1. Você abre o app no computador; ele abre o WhatsApp Web.
2. Escaneia o QR com o celular e aprova o passkey (biometria ou PIN).
3. O app envia a sessão com segurança para a sua instância, pelo endpoint POST /{key}/instance/web-session.

A partir daí, a instância funciona como qualquer outra. O endpoint existe na API, mas o caminho recomendado é usar o app — ele cuida da exportação da sessão para você.

Verificando o estado da conexão

A qualquer momento, consulte a instância:

curl "https://us.api-wa.me/SUA_KEY/instance"

A resposta traz o estado da conexão, se há QR disponível e informações do perfil. Use isso num health check do seu painel, e não num loop de alguns segundos — para mudanças em tempo real, o webhookConnection é o caminho.

Quando a sessão cai: reiniciar vs desconectar

Duas operações que parecem parecidas e não são:

# Reiniciar: recarrega a instância mantendo a sessão (não precisa de QR de novo)
curl -X POST "https://us.api-wa.me/SUA_KEY/instance/restart"

# Desconectar: faz logout e apaga a autenticação (precisa conectar de novo)
curl -X DELETE "https://us.api-wa.me/SUA_KEY/instance"

Na dúvida, reinicie antes de desconectar. O DELETE é definitivo: a sessão sai da lista de aparelhos conectados e você volta ao QR, ao código ou ao Passkey.

Em quedas temporárias de rede, a WAME reconecta sozinha com espaçamento crescente e aleatório entre as tentativas, para evitar uma rajada de reconexões simultâneas — um dos sinais que o WhatsApp observa. Isso faz parte da camada de anti-detecção da plataforma, junto com a identidade de dispositivo única por instância e coerente com o país do número. É um dos motivos pelos quais a taxa de bloqueio é muito baixa para quem usa do jeito certo; os detalhes estão em anti-detecção na API não oficial.

Uma regra importante: se a instância recebeu logout (e não uma queda temporária), não fique reconectando em loop. Descubra o motivo antes. Insistir num número restrito piora a situação — veja os sinais de que o número está em risco e o que fazer se o número foi bloqueado.

E se eu não quiser usar celular nenhum?

Os três métodos acima vinculam a API a um WhatsApp que existe num celular. Existe ainda um quarto caminho: registrar o número direto na API, sem instalar o app, recebendo o código de verificação por SMS ou ligação. É outro fluxo, com outros endpoints — explicado em WhatsApp sem celular: registrar um número pela API.

Conclusão

Conectar um número na API não oficial do WhatsApp não depende mais de apontar uma câmera para a tela. O código de pareamento torna o onboarding remoto e automatizável, o WAME Passkey resolve contas que exigem biometria e o QR Code continua lá para quem está na frente do computador. Com os webhooks de QR e de conexão configurados, o processo inteiro vira um fluxo do seu produto — sem aprovação da Meta, sem template, sem espera. Veja os próximos passos em API não oficial do WhatsApp: recursos e exemplos e todos os parâmetros na documentação.