# Código de pareamento

Fonte: https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento
Seção: Conexões
Atualizado em: 2026-09-28

`POST /connections/{id}/pairing-code`

Pede ao WhatsApp um código de 8 caracteres que conecta `phone` à conexão quando é digitado nesse celular (WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone), em vez de escanear o QR code. O celular recebe um aviso. Escopo necessário: `connections:write`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número). |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `phone` | `string` | sim | O número a conectar, em formato internacional: código do país primeiro, depois o DDD e o número (por exemplo, `5511988887777`). `+`, espaços, hífens e parênteses são ignorados; o número precisa ter de 8 a 15 dígitos. (de 8 a 32 caracteres) |

## Exemplo de requisição

### cURL

```bash
curl -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

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/pairing-code`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '5511900000001',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections/{$connectionId}/pairing-code", [
        'phone' => '5511900000001',
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/connections/{connection_id}/pairing-code",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "phone": "5511900000001",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | `code`: o código de 8 caracteres a digitar no celular (o WhatsApp mostra em dois grupos de 4, como `K7QX-2M9P`). `phone`: o número que ele conecta, em E.164. `expiresAt`: até quando ele pode ser digitado (unix em milissegundos). |
| 400 |  | `phone` não é um número em formato internacional com 8 a 15 dígitos (`phone must be the number to link in international format…`). |
| 400 | `FST_ERR_VALIDATION` | A requisição não segue o schema da operação (por exemplo, um `id` que não é um UUID); `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 402 | `subscription_inactive` | A organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar. |
| 403 |  | A chave não tem o escopo `connections:write`; a mensagem de erro cita o escopo que falta. |
| 404 |  | A conexão não existe ou não é de quem chama: a de outra pessoa responde exatamente como uma que não existe (`Connection not found`). |
| 409 | `already_paired` | A conexão já está ligada a um número, ou um pareamento está terminando. Para conectar outro número, faça o logout antes ([POST /connections/{id}/logout](https://apiwpp.com/docs/api/conexoes/sair-do-whatsapp)). |
| 409 | `not_pairing` | A conexão não está pareando com um QR code na tela (a mensagem traz o status): conecte-a de novo, ou tente de novo em alguns segundos enquanto ela inicia. Com `Retry-After` quando os QR codes desta tentativa terminam cedo demais para o código ser digitado: peça de novo quando o próximo QR code aparecer. |
| 429 | `pairing_code_too_soon` | Um código foi pedido para esta conexão há menos de 30 segundos, ou este número já recebeu 5 códigos na última hora. Espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 500 |  | O pedido do código ao WhatsApp falhou de forma inesperada (`Failed to request a pairing code`). Pode repetir, mas o aviso pode ter chegado ao celular: o intervalo de 30 segundos entre códigos continua valendo. |
| 501 | `unsupported_by_provider` | O provedor da conexão não faz esta operação: o provedor dela não pareia por QR code, e o código de pareamento só existe nesse pareamento. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de `Retry-After` e tente de novo. Cabeçalhos: `Retry-After`. |

### 200 OK

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

## Detalhes

Só funciona enquanto a conexão está pareando com o QR code na tela (`GET /connections/{id}/qr` mostra um): crie a conexão, ou conecte-a de novo, antes.

O código vale até `expiresAt`, quando terminam os QR codes dessa tentativa (no máximo cerca de 2,5 minutos depois de eles aparecerem) e a conexão mostra QR codes novos: peça outro código então. Quando eles terminam cedo demais para o código ser digitado, a resposta é `409 not_pairing` com `Retry-After`, que diz quando os próximos aparecem.

Cada código gera um aviso no celular, então uma conexão pode pedir um código a cada 30 segundos, e um número recebe no máximo 5 por hora, qualquer que seja a conexão que pede (`429 pairing_code_too_soon` com `Retry-After`).

Depois de digitado, o pareamento termina como o do QR code: `status: open` e o webhook `connection.status` com `open`. **Um código de pareamento não evita a passkey**: quando o WhatsApp pede uma passkey ao celular depois do código digitado, o pareamento trava exatamente como depois da leitura do QR code, e a conexão para como `passkey_required`.

Uma falha inesperada ao pedir o código ao WhatsApp responde `500` (`Failed to request a pairing code`); o aviso pode ter chegado ao celular, então o intervalo de 30 segundos continua valendo.

Guia: [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).
