# Consultar conexão

Fonte: https://apiwpp.com/docs/api/projetos/consultar-conexao
Seção: Projetos
Atualizado em: 2026-09-28

`GET /tenants/{id}/connections/{connId}`

Os detalhes de uma conexão do projeto, com os 50 eventos mais recentes dela, do mais recente ao mais antigo. Os heartbeats bem-sucedidos ficam de fora: eles estão no [histórico de heartbeats](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats). 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 do projeto (`tenantId`). |
| `connId` | `string · uuid` | sim | Identificador da conexão (o número) no projeto. |

## Exemplo de requisição

### cURL

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

### Node.js

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

### PHP

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

### Python

```python
import requests

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

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A conexão e os eventos recentes dela em `events`, do mais recente ao mais antigo. |
| 400 | `FST_ERR_VALIDATION` | `id` ou `connId` não é um UUID; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde `401`. |
| 403 |  | A chave não tem o escopo `connections:read`; a mensagem de erro cita o escopo que falta. |
| 404 |  | O projeto ou a conexão não existe, ou não é de quem chama (`Tenant not found`, `Connection not found`). A conexão precisa ser do projeto do caminho. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "status": "open",
  "phoneNumber": "5511900000001",
  "lastHeartbeat": "2026-09-24T12:00:00.000Z",
  "lastConnectedAt": "2026-09-24T08:00:00.000Z",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "events": [
    {
      "id": "e4f5a6b7-c8d9-4e0f-8a1b-2c3d4e5f6a7b",
      "eventType": "CONNECTED",
      "details": {
        "phoneNumber": "5511900000001"
      },
      "createdAt": "2026-09-24T08:00:00.000Z"
    }
  ]
}
```

## Detalhes

`status` é o gravado, em minúsculas (`pending`, `connecting`, `open`, `close`, `failed` ou `passkey_required`). `events[].eventType` é um de `CREATED`, `QR_GENERATED`, `QR_SCANNED`, `CONNECTED`, `DISCONNECTED`, `RECONNECTING`, `RECONNECTED`, `ERROR`, `HEARTBEAT_FAILED`, `SESSION_EXPIRED` e `LOGGED_OUT`, e `details` traz o contexto de cada evento.

Os eventos de conexão ficam guardados por 30 dias, por padrão.

Guia: [Projetos e conexões](https://apiwpp.com/docs/guias/projetos-e-conexoes).
