# IP dedicado

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

`GET /connections/{id}/dedicated-ip`

Se o número tem o adicional de IP dedicado: um IP fixo de provedor residencial brasileiro só dele, em vez de um IP que ele divide com, no máximo, alguns outros números do mesmo projeto. 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/dedicated-ip \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

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

### PHP

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

### Python

```python
import requests

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

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | `dedicatedIp`: o adicional em andamento (`provisioning` ou `active`), senão o último que a conexão teve, ou `null` quando ela nunca teve um. |
| 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"}`. |
| 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`. |

### 200 OK

```json
{
  "dedicatedIp": {
    "id": "f5a6b7c8-d9e0-4f1a-8b2c-3d4e5f6a7b8c",
    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
    "status": "active",
    "waived": false,
    "lastError": null,
    "requestedAt": "2026-09-24T12:00:00.000Z",
    "paidAt": "2026-09-24T12:00:00.000Z",
    "activatedAt": "2026-09-24T12:00:00.000Z",
    "canceledAt": null
  }
}
```

## Detalhes

O IP dedicado é um recurso PRO (`dedicated_ip`) comprado por número pelos donos e administradores da organização no painel, numa assinatura mensal; a API só o consulta. Depois do pagamento, o número passa para o IP dedicado em poucos minutos (uma reconexão planejada), ou assim que um IP é comprado para ele.

`status`: `awaiting_payment` (o pagamento ainda não foi feito), `provisioning` (pago, e o número ainda não está no IP dedicado), `active` (o número sai por um IP só dele) ou `canceled` (a assinatura terminou, e o número voltou para um IP compartilhado). `waived: true`: concedido pela equipe, sem assinatura.

`lastError` diz por que o adicional não está ativo: `waiting_for_proxy` (o IP dedicado está sendo comprado), `own_proxy` (a conexão sai pelo proxy próprio, que tem prioridade), `connection_deleted`, `duplicate` (um segundo adicional pago para uma conexão que já tem um) ou `unplaced` (terminou, e ainda nenhum IP compartilhado tem lugar para o número).

Guia: [Proxy e IP dedicado](https://apiwpp.com/docs/guias/proxy-e-ip-dedicado).
