---
title: "Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey"
description: "Três jeitos de conectar um número na API não oficial do WhatsApp: QR Code, código de pareamento de 8 caracteres e WAME Passkey. Com cURL, webhooks e reconexão."
url: "https://wame.api.br/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-28"
modified_time: "2026-09-28"
author: "Raphael Serafim"
keywords: "api whatsapp não oficial, api não oficial whatsapp, conectar whatsapp sem qr code, código de pareamento whatsapp, pairing code whatsapp api, whatsapp passkey api, conectar whatsapp api"
reading_time: "8 min de leitura"
---

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

> Três jeitos de conectar um número na API não oficial do WhatsApp: QR Code, código de pareamento de 8 caracteres e WAME Passkey. Com cURL, webhooks e reconexão.

**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:

| Método | Como funciona | Melhor para |
| --- | --- | --- |
| QR Code | Escanear uma imagem com o celular | Quem está na frente da tela |
| Código de pareamento | Digitar um código no celular | Conexão remota, suporte, onboarding de cliente |
| WAME Passkey | App desktop aprova passkey | Contas que exigem biometria/PIN |

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:

```bash
curl -X PUT "https://server.wame.api.br/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:

```bash
curl -X POST "https://server.wame.api.br/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:

```bash
curl -X POST "https://server.wame.api.br/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:

```js
const BASE = 'https://server.wame.api.br';

// 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](/blog/provisionar-whatsapp-multiplos-clientes-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](/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:

```bash
curl "https://server.wame.api.br/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:

```bash
# Reiniciar: recarrega a instância mantendo a sessão (não precisa de QR de novo)
curl -X POST "https://server.wame.api.br/SUA_KEY/instance/restart"

# Desconectar: faz logout e apaga a autenticação (precisa conectar de novo)
curl -X DELETE "https://server.wame.api.br/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](/blog/anti-deteccao-api-whatsapp-nao-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](/blog/sinais-numero-whatsapp-risco-bloqueio) e [o que fazer se o número foi bloqueado](/blog/numero-bloqueado-whatsapp-o-que-fazer).

## 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](/blog/whatsapp-sem-celular-conexao-mobile-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](/blog/api-nao-oficial-whatsapp-recursos-exemplos) e todos os parâmetros na [documentação](/docs).

## Perguntas frequentes

### Dá para conectar o WhatsApp na API sem escanear QR Code?

Sim. Na WAME API, o POST /{key}/instance/pairing-code com o phoneNumber gera um código de pareamento que você digita no próprio celular, em Aparelhos conectados > Conectar com número de telefone. Não precisa de câmera nem de estar na frente da tela.

### Qual a diferença entre QR Code e código de pareamento?

O resultado é o mesmo: o número fica conectado à instância como um aparelho vinculado. O QR Code exige escanear uma imagem; o código de pareamento é um texto curto digitado no celular, o que facilita conectar remotamente — por exemplo, quando o cliente está em outra cidade.

### O que é o WAME Passkey?

É um app desktop gratuito e open-source (macOS, Windows e Linux) para contas em que o WhatsApp passou a exigir passkey — biometria ou PIN do aparelho — para aprovar o login. Ele abre o WhatsApp Web, você aprova a chave de acesso no celular e a sessão é enviada com segurança para a sua instância.

### Como sei que a instância conectou?

Configure o webhookConnection pelo PUT /{key}/instance para receber o evento de mudança de conexão, ou consulte GET /{key}/instance, que devolve o estado atual da conexão e informações do perfil.

### Preciso manter o celular ligado depois de conectar?

Não para o funcionamento do dia a dia: a sessão de aparelho vinculado funciona com o celular desligado. Mas o número precisa continuar ativo no aplicativo principal. Se o aparelho ficar muito tempo sem abrir o WhatsApp, o próprio app pode desconectar os aparelhos vinculados.