# Proxy e IP dedicado

Fonte: https://apiwpp.com/docs/guias/proxy-e-ip-dedicado
Seção: Guias
Atualizado em: 2026-09-29

Por onde cada número sai para o WhatsApp: o IP brasileiro compartilhado, um proxy seu por conexão ou um IP dedicado (PRO), e como verificar cada um.

O WhatsApp vê o endereço IP de onde cada número se conecta. Milhares de sessões saindo de poucos IPs de datacenter são um sinal conhecido de automação, e por isso a apiwpp dá a cada conexão, sempre que pode, uma saída própria para a internet. O socket do WhatsApp, os uploads e os downloads de mídia da conexão, incluindo as buscas que a apiwpp faz nas URLs de mídia que você envia, saem todos pelo mesmo caminho.

## As três saídas

| Saída | Como se obtém | Quem divide o IP |
| --- | --- | --- |
| IP brasileiro compartilhado | Automático no pareamento, quando o pool de proxies da apiwpp tem um IP brasileiro com espaço para o projeto. | No máximo alguns outros números do mesmo projeto; nunca números de outro projeto. |
| Proxy próprio | Você informa um proxy seu na criação da conexão ou com `PUT /connections/{id}/proxy`. | Quem você decidir. |
| IP dedicado (PRO) | Contratado por número no painel. | Ninguém: um IP fixo de provedor residencial brasileiro só para esse número. |

O proxy próprio tem prioridade sobre os outros dois: uma conexão com proxy próprio nunca recebe um IP da apiwpp, nem mesmo o dedicado. O IP compartilhado é dado só no pareamento. Se nesse momento o pool não tem um IP com espaço para o projeto, o número pareia sem proxy da apiwpp e se conecta direto do IP do servidor do gateway; ele continua assim até ser pareado de novo. Para garantir a saída, use um proxy próprio ou um IP dedicado.

Um IP compartilhado não muda por baixo de um número já pareado, a não ser que o proxy dele pare de funcionar: a apiwpp verifica esses proxies periodicamente e move os números de um proxy que caiu para outro.

## Proxy próprio

Use um proxy seu quando o número precisa sair de um IP que você controla, por exemplo o mesmo IP em que ele já opera fora da apiwpp. O corpo é o mesmo em todos os lugares que aceitam um proxy:

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `url` | string, obrigatório | `socks5://`, `socks5h://`, `http://` ou `https://` (os dois últimos usam HTTP CONNECT), com `usuario:senha@` opcional. Até 2048 caracteres, só esquema, credenciais, host e porta: sem caminho, query ou fragmento. Com `socks5://` e com `socks5h://`, é o proxy que resolve os nomes de host. |
| `country` | string ou `null` | O país de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, `BR`). Omitido ou `null`: qualquer país. |

> **A URL não volta nunca**
>
> A `url` é gravada criptografada e nenhuma resposta a devolve: a API mostra só o esquema, o host, a porta e se há credenciais (`hasCredentials`). Guarde a URL completa, com a senha, no seu cofre de segredos.

### Na criação da conexão

O jeito mais seguro é informar o proxy ao criar a conexão: ele é verificado antes de qualquer coisa ser criada e gravado antes do primeiro socket, então nem o primeiro QR code sai por fora dele. Se a verificação falhar, a resposta é `400`, `422` ou `503` e nenhuma conexão é criada.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$TENANT_ID'",
    "proxy": { "url": "socks5://usuario:senha@br.proxy.example.com:1080", "country": "BR" }
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.apiwpp.com/connections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tenantId: process.env.TENANT_ID,
    proxy: { url: process.env.PROXY_URL, country: 'BR' },
  }),
})
const { connectionId } = await res.json()
```

`POST /tenants/{id}/connections` aceita o mesmo campo `proxy` (veja [Criar conexão no projeto](https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto)).

### Numa conexão que já existe

`PUT /connections/{id}/proxy` define ou troca o proxy (escopo `connections:write`). Numa conexão ativa, ou a caminho de ficar ativa, um proxy novo provoca uma reconexão planejada por ele; uma conexão parada passa a usá-lo na próxima vez que conectar. Mandar de novo o mesmo proxy, mudando só o `country`, não reconecta nada.

**cURL**

```bash
curl -s -X PUT https://api.apiwpp.com/connections/$CONNECTION_ID/proxy \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "socks5://usuario:senha@br.proxy.example.com:1080", "country": "BR"}'
```

**Node.js**

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/proxy`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: process.env.PROXY_URL, country: 'BR' }),
})
if (res.status === 429) {
  const wait = Number(res.headers.get('retry-after'))
  // Espere `wait` segundos antes da próxima verificação.
}
const { proxy, reconnecting } = await res.json()
```

Resposta `200`

```json
{
  "proxy": {
    "scheme": "socks5",
    "host": "br.proxy.example.com",
    "port": 1080,
    "hasCredentials": true,
    "country": "BR",
    "exit": { "ip": "203.0.113.7", "country": "BR", "checkedAt": "2026-09-24T12:00:00.000Z" }
  },
  "reconnecting": true
}
```

`exit` é onde a última verificação viu o proxy sair: o IP em que o WhatsApp enxerga o número. `reconnecting: true` quer dizer que um socket novo, pelo proxy novo, está a caminho. `false` quer dizer que a conexão está parada e usa o proxy na próxima conexão, que o proxy é o mesmo de antes (só o país mudou), ou que a verificação antes do pareamento o recusou e a conexão foi parada; nesse último caso, o `lastError` da conexão diz por quê.

### A verificação

Antes de gravar o proxy, a apiwpp confere que:

1. o host do proxy é público (endereços privados e de rede local são recusados com `400`);
2. uma requisição feita através dele a um serviço que informa o IP de saída responde em até 10 segundos e diz de onde ele sai;
3. com `country`, a saída fica nesse país.

A mesma verificação roda de novo antes de o número parear: nenhum QR code é mostrado a partir de uma saída não verificada. E uma conexão com proxy nunca se conecta por fora dele: se o proxy parar de funcionar, o socket não abre.

Quando a verificação falha, o `422` diz só o tipo de falha, nunca o que a rede respondeu. As três primeiras chegam como `Proxy check failed for <proxy>: <motivo>`:

| Falha | Mensagem |
| --- | --- |
| Inalcançável | `the proxy could not be reached, or did not reach the IP echo endpoint` (inclui o tempo esgotado) |
| Credenciais recusadas | `the proxy refused the credentials` |
| Sem endereço de saída | `the IP echo endpoint did not tell where the proxy exits` |
| Outro país | `The proxy exits at <ip> in <país>, not in <country>`: o IP e o país por onde o proxy sai, e o `country` que você pediu |

Cada `PUT` é uma verificação, e cada organização tem até 60 verificações por hora. Passando disso, a resposta é `429` com `Retry-After` em segundos. Os proxies informados na criação da conexão não entram nessa conta.

### Consultar e remover

`GET /connections/{id}/proxy` (escopo `connections:read`) devolve o mesmo objeto `proxy` sem as credenciais, ou `{"proxy": null}` quando a conexão não tem proxy próprio. `DELETE /connections/{id}/proxy` (escopo `connections:write`) remove o proxy e a conexão passa a se conectar diretamente: uma conexão ativa se reconecta sem ele, e a resposta é `{"proxy": null, "reconnecting": true}`. Remover quando não há proxy também responde `200`.

**Consultar e remover**

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

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

### Erros

| Status | Quando |
| --- | --- |
| `400` | A URL não é aceita: vazia, inválida, esquema não suportado, com caminho ou query, senha sem usuário, host que não é público, ou `country` que não tem duas letras. |
| `404` | A conexão não existe ou é de outra organização. |
| `422` | A verificação através do proxy falhou (tabela acima). Nada foi salvo. |
| `429` | As 60 verificações de proxy da organização nesta hora acabaram, ou o limite de requisições por IP. Espere o `Retry-After`. |
| `500` | Só no `GET`: o proxy gravado não pode ser aberto. É um problema do nosso lado: fale com o suporte. |
| `501` | `unsupported_by_provider`: o provedor da conexão não usa proxy (as APIs oficiais não mantêm uma sessão própria). |
| `503` | O gateway não consegue guardar segredos (nenhuma chave de criptografia configurada). Nada foi salvo. |

A página [Erros](https://apiwpp.com/docs/guias/erros) explica o formato do corpo e quando tentar de novo.

## IP dedicado

> **Recurso PRO**
>
> O IP dedicado é um adicional do plano PRO (recurso `dedicated_ip`), contratado por número. Não está disponível durante o período de teste.

Com o IP dedicado, o número sai por um IP fixo de provedor residencial brasileiro só dele, em vez do IP que divide com alguns outros números do mesmo projeto. Os donos e administradores da organização contratam o adicional **no painel**, na conexão: ele entra na assinatura mensal da organização, com o restante do mês cobrado de forma proporcional. A compra e o cancelamento não existem na API com chave.

Depois da contratação, o número passa para o IP dedicado em poucos minutos, numa reconexão planejada, ou assim que um IP é comprado para ele. Quando o adicional termina, o número volta para um IP compartilhado do projeto.

Pela API, `GET /connections/{id}/dedicated-ip` (escopo `connections:read`) diz em que pé está o adicional da conexão: o que está em uso (`provisioning` ou `active`) ou, se não houver, o mais recente. Sem nenhum, a resposta é `{"dedicatedIp": null}`.

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

Resposta `200`

```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
  }
}
```

| `status` | O que quer dizer |
| --- | --- |
| `awaiting_payment` | A contratação ainda não foi paga. |
| `provisioning` | Pago; o número ainda não está no IP dedicado. |
| `active` | O número sai por um IP só dele. |
| `canceled` | O adicional terminou; o número voltou para um IP compartilhado. |

`waived: true` indica um adicional concedido pela nossa equipe, sem cobrança. Quando o adicional não está ativo, `lastError` diz por quê:

| `lastError` | O que quer dizer |
| --- | --- |
| `waiting_for_proxy` | O IP dedicado do número está sendo comprado. |
| `own_proxy` | A conexão usa um proxy próprio, que tem prioridade sobre o IP dedicado. |
| `connection_deleted` | A conexão foi excluída. |
| `duplicate` | Um segundo adicional foi pago para uma conexão que já tinha um. |
| `unplaced` | O adicional terminou e ainda não há um IP compartilhado com espaço para o número. |

A resposta nunca mostra o IP nem o proxy do adicional.

## Próximos passos

- [Definir proxy](https://apiwpp.com/docs/api/conexoes/definir-proxy), [Consultar proxy](https://apiwpp.com/docs/api/conexoes/consultar-proxy) e [Remover proxy](https://apiwpp.com/docs/api/conexoes/remover-proxy): os campos e as respostas completos.
- [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero): o QR code, o código de pareamento e os status da conexão.
- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): o ritmo e o aquecimento que protegem o número, qualquer que seja o IP.
- [Projetos e conexões](https://apiwpp.com/docs/guias/projetos-e-conexoes): criar, reconectar e excluir conexões.
