# Parear um número

Fonte: https://apiwpp.com/docs/guias/parear-um-numero
Seção: Guias
Atualizado em: 2026-09-29

Conecte um número de WhatsApp por QR code ou por código de pareamento, acompanhe o status da conexão e saiba o que fazer quando o WhatsApp pede uma passkey.

Uma conexão é um **aparelho conectado** do número, como o WhatsApp Web. Você a pareia uma vez, por QR code ou por um código de 8 caracteres digitado no celular. Depois disso, a sessão fica guardada na apiwpp: reinícios e reconexões não pedem um novo QR code.

> **Antes de começar**
>
> Você precisa de uma chave com os escopos `connections:read` e `connections:write` (veja [Autenticação](https://apiwpp.com/docs/autenticacao)) e do `id` do projeto (`$TENANT_ID`). Só uma chave com `connections:write` recebe o QR code e pede o código de pareamento, porque os dois conectam um número à conta. Nos exemplos, `$CONNECTION_ID` é a conexão, e o endereço base é `https://api.apiwpp.com`.

## 1. Crie a conexão

[`POST /connections`](https://apiwpp.com/docs/api/conexoes/criar-conexao) cria a conexão no projeto e já começa o pareamento. Guarde o `connectionId` da resposta. O `externalId` é opcional: é o seu identificador para a conexão (o id do cliente no seu sistema, por exemplo) e volta em todos os webhooks dela. Criar de novo com um `externalId` que já existe no projeto conecta aquela conexão, sem criar outra.

**Criar a conexão**

```bash
curl -s -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "'$TENANT_ID'", "externalId": "loja-42"}'
```

Resposta `200`

```json
{ "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f", "externalId": "loja-42" }
```

Cada conexão ocupa um dos números que a sua organização contratou até ser excluída. Além deles, a resposta é `402` com `code: number_limit_reached`. Com a assinatura parada (o período de teste acabou, ou uma fatura venceu e passou da carência), é `402` com `code: subscription_inactive`. A conexão também pode ter um proxy próprio desde a criação: veja [Proxy e IP dedicado](https://apiwpp.com/docs/guias/proxy-e-ip-dedicado).

## 2. Mostre o QR code

Consulte [`GET /connections/{id}/qr`](https://apiwpp.com/docs/api/conexoes/qr-code-e-status) a cada 2 a 5 segundos enquanto o pareamento estiver na tela:

**Buscar o QR code**

```bash
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/qr \
  -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }
```

O `qr` é o **conteúdo** do QR code, não uma imagem: gere a imagem com uma biblioteca de QR code. O WhatsApp troca o código a cada poucos segundos e um código antigo não pareia, então mostre sempre o mais recente. Com uma chave que só tem `connections:read` (um sistema de monitoramento, por exemplo), `qr` vem `null` e o `status` continua disponível.

**Node.js**

```js
import QRCode from 'qrcode'

const base = 'https://api.apiwpp.com'
const headers = { Authorization: `Bearer ${process.env.API_KEY}` }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function waitForPairing(connectionId, showQr) {
  for (;;) {
    const res = await fetch(`${base}/connections/${connectionId}/qr`, { headers })
    if (res.status === 503) {
      // A instância da conexão está mudando: espere o Retry-After
      await sleep(Number(res.headers.get('retry-after') ?? 5) * 1000)
      continue
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)

    const { qr, status } = await res.json()
    if (status === 'open') return
    if (status === 'passkey_required' || status === 'close') throw new Error(`Pareamento parado: ${status}`)
    if (qr) showQr(await QRCode.toDataURL(qr)) // data URL PNG para um <img src>
    await sleep(3000)
  }
}
```

**Python**

```python
import os
import time

import qrcode  # pip install qrcode[pil]
import requests

BASE = "https://api.apiwpp.com"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

def wait_for_pairing(connection_id, show_qr):
    while True:
        res = requests.get(f"{BASE}/connections/{connection_id}/qr", headers=HEADERS, timeout=30)
        if res.status_code == 503:
            time.sleep(int(res.headers.get("Retry-After", "5")))
            continue
        res.raise_for_status()
        body = res.json()
        if body["status"] == "open":
            return
        if body["status"] in ("passkey_required", "close"):
            raise RuntimeError(f"Pareamento parado: {body['status']}")
        if body["qr"]:
            show_qr(qrcode.make(body["qr"]))
        time.sleep(3)
```

Se preferir a imagem pronta, [`GET /tenants/{id}/connections/{connId}/qr`](https://apiwpp.com/docs/api/projetos/qr-code-como-imagem) responde `qrCode` como data URL PNG, para usar direto num `<img src>`, com a mesma regra: `null` sem `connections:write`.

## 3. Escaneie no celular

No celular do número, abra **WhatsApp › Aparelhos conectados › Conectar um aparelho** e aponte a câmera para o QR code.

## 4. Espere o open

Quando o pareamento termina, o `status` passa a `open`, o `qr` volta a `null` e o projeto recebe o webhook [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status) com o número pareado:

**connection.status**

```json
{
  "type": "connection.status",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-09-29T12:00:00.000Z",
  "data": { "status": "open", "phoneNumber": "5511900000001" }
}
```

A partir daqui o número envia e recebe mensagens. Se ninguém escanear, os QR codes da tentativa acabam e a conexão fecha com `reason: qr_not_scanned`: conecte de novo (veja abaixo) para uma nova tentativa.

## Os status da conexão

`GET /connections/{id}/qr` responde um destes status:

| `status` | O que quer dizer | O que fazer |
| --- | --- | --- |
| `connecting` | Abrindo o socket ou esperando o QR ser escaneado (`qr` preenchido) | Mostrar o QR code |
| `open` | Pareada e conectada: pode enviar e receber | Nada |
| `close` | Sem socket ativo: desconectada, sessão encerrada ou pareamento interrompido | Conectar de novo |
| `passkey_required` | O QR foi escaneado, mas o WhatsApp pediu uma passkey ao celular | Veja a próxima seção |

[`GET /connections`](https://apiwpp.com/docs/api/conexoes/listar-conexoes) lista as conexões dos seus projetos com o status atual, e as rotas de projeto ([consultar uma conexão](https://apiwpp.com/docs/api/projetos/consultar-conexao), por exemplo) mostram o status gravado, em minúsculas. Nelas também podem aparecer `pending` (criada, esperando o QR ser escaneado) e `failed` (falhou de vez; `GET /connections` só a lista com `includeFailed=true`). O histórico das verificações de saúde de cada conexão está em [`GET /tenants/{id}/connections/{connId}/heartbeats`](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats).

## Quando o WhatsApp pede uma passkey

Desde meados de 2026, o WhatsApp pede a alguns celulares uma **passkey** (chave de acesso) logo depois da leitura do QR code. A apiwpp ainda não consegue concluir essa etapa, então o pareamento não termina. A plataforma percebe a situação (o QR foi lido e a conexão não abriu em 60 segundos, ou fechou duas vezes com erro enquanto o QR estava na tela) e:

- para de gerar QR codes, em vez de ficar em ciclo;
- responde `status: passkey_required` em `GET /connections/{id}/qr`, também depois de um reinício;
- envia `connection.status` com `{ "status": "close", "reason": "passkey_required" }`, sem `phoneNumber`.

A conexão fica parada até ser conectada de novo. Tente mais tarde com [`POST /tenants/{id}/connections/{connId}/connect`](https://apiwpp.com/docs/api/projetos/reconectar-conexao), ou use outro número. Números já pareados não são afetados: a passkey só aparece em pareamentos novos.

## Pareamento por código

Em vez de escanear o QR code, o dono do número pode digitar no celular um código de 8 caracteres. É útil quando o celular não está perto da tela que mostra o QR.

1. **Comece o pareamento** como no QR code (crie a conexão ou conecte de novo) e espere o `qr` aparecer em `GET /connections/{id}/qr`: o código só pode ser pedido enquanto o QR code está na tela.
2. **Peça o código** com [`POST /connections/{id}/pairing-code`](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento), informando o número que vai ser conectado no formato internacional (código do país primeiro, de 8 a 15 dígitos; `+`, espaços, traços e parênteses são ignorados).
3. **Digite o código no celular** do número: **WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone**. O campo separa o código em dois grupos de 4 (`K7QX-2M9P`), e o celular também recebe um aviso do pedido.
4. **Espere o `open`**, como no QR code.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/pairing-code \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+5511900000001"}'
```

**Node.js**

```js
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/pairing-code`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '+5511900000001' }),
})
if (res.status === 409 || res.status === 429) {
  const retryAfter = res.headers.get('retry-after') // segundos, quando vier
  const { error } = await res.json() // already_paired, not_pairing ou pairing_code_too_soon
  throw new Error(`${error}; tente de novo em ${retryAfter ?? '?'} s`)
}
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
const { code, expiresAt } = await res.json()
console.log(`Digite ${code.slice(0, 4)}-${code.slice(4)} até ${new Date(expiresAt).toISOString()}`)
```

Resposta `200`

```json
{ "code": "K7QX2M9P", "phone": "+5511900000001", "expiresAt": 1790251365000 }
```

O código vale até `expiresAt`, em milissegundos desde 1970. É quando terminam os QR codes dessa tentativa (no máximo cerca de 2,5 minutos depois de o primeiro aparecer), e a conexão passa a mostrar QR codes novos. Depois disso, o código não conecta mais: peça outro. Se faltarem menos de 30 segundos, o pedido é recusado com `409` `not_pairing` e `Retry-After`, o tempo até os próximos QR codes aparecerem.

Como cada pedido gera um aviso no celular, uma conexão pode pedir **um código a cada 30 segundos**, e um mesmo número recebe **no máximo 5 códigos por hora**, qualquer que seja a conexão que pede.

| Resposta | Quando |
| --- | --- |
| `200` | O código, o número que ele conecta (`phone`, em E.164) e até quando ele vale (`expiresAt`) |
| `400` | `phone` não é um número no formato internacional |
| `402` `subscription_inactive` | A assinatura da organização está parada |
| `409` `not_pairing` | A conexão não está pareando com o QR code na tela: conecte de novo e peça o código. Com `Retry-After`: os QR codes dessa tentativa terminam em menos de 30 segundos; peça de novo depois desse tempo |
| `409` `already_paired` | A conexão já está pareada com um número, ou um pareamento está terminando: faça logout para conectar outro |
| `429` `pairing_code_too_soon` | Um código foi pedido para a conexão há menos de 30 segundos, ou o número já recebeu 5 códigos na última hora: espere `Retry-After` segundos |
| `501` `unsupported_by_provider` | O provedor da conexão não oferece pareamento por código |
| `503` | A instância que roda a conexão está mudando: espere `Retry-After` segundos |

Nos erros com código, o corpo traz `error` com o código e `message` com a explicação, como em `{ "error": "not_pairing", "message": "…" }`.

> **O código não evita a passkey**
>
> Se o WhatsApp pedir uma passkey ao celular depois que o código for digitado, o pareamento trava do mesmo jeito que depois da leitura do QR code, e a conexão para como `passkey_required` (veja a seção acima).

## Os primeiros 14 dias de um número

Um número recém-pareado envia mais devagar durante 14 dias e alcança poucas pessoas novas por dia: é nessa fase que o WhatsApp mais restringe quem começa conversas com desconhecidos. Os limites sobem por etapas:

| Desde o pareamento | Por hora | Por dia | Destinatários novos por 24 horas |
| --- | --- | --- | --- |
| Até 6 horas | 5 | 20 | 5 |
| 6 a 24 horas | 10 | 50 | 10 |
| 1 a 3 dias | 20 | 100 | 20 |
| 3 a 7 dias | 30 | 150 | 30 |
| 7 a 14 dias | 45 | 200 | 50 |

Nenhuma etapa passa dos limites normais da plataforma. Parear outro número, ou o mesmo depois de um logout, começa o aquecimento de novo. Os detalhes estão em [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).

## Desconectar, reconectar e trocar de número

| Chamada | Efeito |
| --- | --- |
| [`POST /connections/{id}/disconnect`](https://apiwpp.com/docs/api/conexoes/desconectar) | Fecha a conexão e **guarda a sessão**: reconecte sem QR code |
| [`POST /tenants/{id}/connections/{connId}/connect`](https://apiwpp.com/docs/api/projetos/reconectar-conexao) | Reconecta com a sessão guardada, ou começa um pareamento se não houver sessão |
| [`POST /connections/{id}/logout`](https://apiwpp.com/docs/api/conexoes/sair-do-whatsapp) | Sai do WhatsApp e **apaga a sessão**: o próximo pareamento pede um QR code novo. Use para trocar o número |
| [`DELETE /tenants/{id}/connections/{connId}`](https://apiwpp.com/docs/api/projetos/excluir-conexao) | Sai do WhatsApp e exclui a conexão, com a sessão, os templates e o histórico. Não pode ser desfeito; se o logout falhar, nada é excluído (`409`) e você pode tentar de novo |

Desconectar, fazer logout e excluir funcionam mesmo com a assinatura parada, para que você sempre possa liberar um número. Criar, conectar, buscar o QR code e pedir o código de pareamento respondem `402` `subscription_inactive` nesse caso. Todas essas chamadas podem responder `503` com `Retry-After` enquanto a instância que roda a conexão muda (um reinício, por exemplo): espere e repita.

Para trocar o número de uma conexão: faça logout, conecte de novo e pareie o número novo.

## Acompanhe pelo webhook connection.status

Toda mudança da conexão chega como [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status). Num fechamento, `reason` diz por quê e `willReconnect` diz se a plataforma reconecta sozinha:

| `reason` | `willReconnect` | O que fazer |
| --- | --- | --- |
| `transient` | `true` | Nada: a plataforma tenta de novo sozinha e avisa com `open` |
| `restart_required` | `true` | Nada: a plataforma reinicia o socket sozinha |
| `replaced` | `false` | Outra sessão assumiu o lugar desta: conecte de novo |
| `qr_not_scanned` | `false` | Ninguém escaneou o QR a tempo: conecte de novo e mostre o QR |
| `logged_out` | `false` | O aparelho foi desconectado pelo celular: conecte de novo e pareie com um QR novo |
| `manual` | `false` | A conexão foi desconectada pela API ou pelo painel: conecte de novo quando quiser |
| `passkey_required` | — | O WhatsApp pediu uma passkey: veja a seção sobre passkey |

Os motivos `reachout_timelock` e `reachout_timelock_lifted` avisam um bloqueio temporário de novas conversas, que não fecha a conexão; veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): texto, mídia, localização, templates e a fila.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): receber e verificar os eventos, `connection.status` incluído.
- [Projetos e conexões](https://apiwpp.com/docs/guias/projetos-e-conexoes): o projeto, as conexões dele e o limite de números.
