# QR code e status

Fonte: https://apiwpp.com/docs/api/conexoes/qr-code-e-status
Seção: Conexões
Atualizado em: 2026-09-28

`GET /connections/{id}/qr`

O QR code atual (quando há um) e o status da conexão. Escanear o QR code pelo WhatsApp do celular (Aparelhos conectados › Conectar um aparelho) conecta o número à conexão. Escopo necessário: `connections:read`.

## Cabeçalhos

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

## Parâmetros de caminho

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

## Exemplo de requisição

### cURL

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

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/qr`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/connections/{$connectionId}/qr");
```

### Python

```python
import requests

response = requests.get(
    f"https://api.apiwpp.com/connections/{connection_id}/qr",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | `qr`: o texto do QR code a desenhar (por exemplo, com uma biblioteca de QR code), ou `null` quando não há um ou quando a chave não tem `connections:write`. `status`: `connecting`, `open`, `close` ou `passkey_required`. |
| 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:read`; 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`). |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 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
{
  "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,5oVt8yRk3uEi1wQz7xNm4cPl0dFg6hJs=,Zx9Cv8Bn7Ma6Sd5Fg4Hj3Kl2",
  "status": "connecting"
}
```

## Detalhes

O QR code só aparece para quem tem o escopo `connections:write`: escaneá-lo conecta um número à conexão, como faz `POST /connections/{id}/pairing-code`. Só com `connections:read`, `qr` vem `null` e o status continua disponível.

O WhatsApp troca o QR code a cada poucos segundos enquanto a conexão pareia: consulte a cada 2 a 5 segundos e mostre sempre o último, porque um código antigo não pareia. Quando os QR codes de uma tentativa acabam sem leitura, a conexão fecha (`connection.status` com `reason: qr_not_scanned`); conecte-a de novo para mostrar QR codes novos.

`status: passkey_required`: o QR code foi escaneado, mas o pareamento não terminou porque o WhatsApp pediu uma passkey (chave de acesso) ao celular, o que este gateway ainda não consegue concluir. A conexão fica parada, sem QR codes novos, até ser conectada de novo, inclusive depois de reinícios (o status é gravado); o número pode ser pareado mais tarde, ou outro número pode ser usado. Veja [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).

Uma conexão que não está rodando (depois de um logout, de QR codes expirados ou de `POST /connections/{id}/disconnect`) responde `qr: null` e `status: close`.

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