# Definir proxy

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

`PUT /connections/{id}/proxy`

Traga o seu próprio proxy: a partir de agora, o socket de WhatsApp da conexão e os uploads e downloads de mídia (os dela e as buscas que o gateway faz nas URLs das suas mídias) saem por ele, nunca por fora dele. 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 |
| --- | --- | --- | --- |
| `url` | `string` | sim | URL do proxy: `socks5://`, `socks5h://` (nos dois, é o proxy que resolve os nomes de host), `http://` ou `https://` (os dois últimos por HTTP CONNECT), com `usuario:senha@` opcional. Só esquema, credenciais, host e porta, sem caminho, query ou fragmento; o host precisa ser público. É gravada criptografada e nunca volta em nenhuma resposta. (de 1 a 2048 caracteres) |
| `country` | `string \| null` | não | País de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, `BR`). Omitido ou `null`: qualquer país. (formato `^[A-Za-z]{2}$`) |

## Exemplo de requisição

### cURL

```bash
curl -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 ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'socks5://usuario:senha@br.proxy.example.com:1080',
    country: 'BR',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->put("https://api.apiwpp.com/connections/{$connectionId}/proxy", [
        'url' => 'socks5://usuario:senha@br.proxy.example.com:1080',
        'country' => 'BR',
    ]);
```

### Python

```python
import requests

response = requests.put(
    f"https://api.apiwpp.com/connections/{connection_id}/proxy",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": "socks5://usuario:senha@br.proxy.example.com:1080",
        "country": "BR",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | O proxy como foi salvo (`proxy`, sem as credenciais, com a saída verificada em `exit`) e `reconnecting`: `true` quando um socket novo pelo proxy está a caminho; `false` quando a conexão está parada e usa o proxy na próxima conexão, quando o proxy é o mesmo de antes (só o país mudou), ou quando a verificação antes do pareamento o recusou e a conexão foi parada (o `lastError` dela diz por quê). |
| 400 |  | A URL do proxy não é aceita: não é uma URL, o esquema não é `socks5`, `socks5h`, `http` ou `https`, tem caminho, query ou fragmento, tem senha sem usuário, o host não é público, ou `country` não tem duas letras. |
| 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: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`). |
| 422 |  | A verificação pelo proxy falhou, e a mensagem diz só como: o proxy não foi alcançado ou não alcançou o serviço que informa o IP de saída (`the proxy could not be reached…`, inclusive por tempo esgotado), recusou as credenciais (`the proxy refused the credentials`), não disse de onde sai (`the IP echo endpoint did not tell where the proxy exits`) ou sai em outro país que não o de `country`. |
| 429 |  | As verificações de proxy da organização nesta hora acabaram (`Too many proxy checks: at most 60 an hour…`), ou o limite por IP de origem: espere os segundos de `Retry-After`. |
| 501 | `unsupported_by_provider` | O provedor da conexão não faz esta operação: o provedor dela não guarda uma sessão do WhatsApp e não usa proxy. |
| 503 |  | Este gateway não consegue guardar URLs de proxy, porque nenhuma chave de criptografia está configurada. Nada é salvo. |

### 200 OK

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

## Detalhes

Antes de ser salvo, o host do proxy precisa ser público, e uma requisição por ele precisa dizer por onde ele sai (e, com `country`, sair nesse país). A mesma verificação roda de novo antes de o número parear, e nenhum QR code é mostrado a partir de uma saída não verificada.

Numa conexão ativa, ou a caminho de ficar ativa, um proxy novo é uma reconexão planejada por ele (`reconnecting: true`). Uma conexão parada passa a usá-lo na próxima vez que conectar. O mesmo proxy de novo, só com um `country` novo, não reconecta nada.

Cada `PUT` é uma verificação, e cada organização tem até 60 verificações por hora (`429` com `Retry-After` depois disso). Para uma conexão nova usar um proxy desde o primeiro socket, informe-o ao [criar a conexão](https://apiwpp.com/docs/api/conexoes/criar-conexao).

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