# 🔌 OpenAPI

A EProxies expõe 5 endpoints HTTP (extração de proxies em modo whitelist e gerenciamento da whitelist). Esta página é uma referência rápida; para uso detalhado, veja [Extração via API (modo whitelist)](https://www.eproxies.io/docs/usage/api-extraction).

> Definição legível por máquina: [openapi.json](https://www.eproxies.io/docs/openapi.json) — uma especificação OpenAPI 3.0 que você pode importar direto no Postman / Swagger UI / Insomnia, ou entregar a um agente de IA para chamadas automáticas.

## Informações básicas

| Item | Valor |
| --- | --- |
| URL base | `https://api.eproxies.net` |
| Auth (extração) | A requisição deve partir de um **IP na whitelist**; sem credenciais |
| Auth (gerenciamento) | Parâmetros `userName` + `userKeyValue` (chave do usuário, no painel) |
| Gateway de proxy | `proxy.eproxies.net:23333` (HTTP/HTTPS/SOCKS5 — fora desta API HTTP) |

## Lista de endpoints

### `GET /gateway_api/extract_ip`

Extrair proxies — Extrai um lote de endpoints de proxy. A requisição deve partir de um IP na whitelist; os proxies retornados são usados diretamente, sem credenciais.

**Parâmetros da requisição**

| Campo | Tipo | Obrigatório | Valores aceitos | Descrição |
| --- | --- | --- | --- | --- |
| `count` | integer | Sim | `1` ~ N | Quantidade de proxies a extrair |
| `country` | string | Não | `US` `GB` `JP` … / `Global` | Código de país ISO 3166-1 alfa-2; `Global` = qualquer país |
| `protocol` | string | Não | `http` / `socks5` | Protocolo do proxy |
| `format` | string | Não | `txt` / `json` | Formato da resposta; `json` retorna array de objetos, `txt` retorna linhas de texto |
| `separator` | string | Não | `crlf` `br` `cr` `lf` `tab` | Separador para o formato `txt`: `\r\n`, `</br>`, `\r`, `\n`, `\t` respectivamente |
| `st` | string | Não | — | Separador personalizado; substitui `separator` quando informado |
| `session` | string | Não | `sticky` / `random` | Tipo de IP: `sticky` reutiliza o mesmo lote, `random` retorna aleatórios |

**Campos da resposta**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `ipAddress` | string | Endereço IP do proxy |
| `portValue` | integer | Porta do proxy |

Com `format=json` a resposta é um array dos objetos acima; com `format=txt` são linhas `IP:porta` separadas por `separator`.

**Exemplo**

```bash
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"
```

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

### `GET /gateway_api/country-list`

Lista de países suportados — Lista todos os países disponíveis para extração em modo whitelist.

**Parâmetros da requisição**

Sem parâmetros de requisição.

**Campos da resposta**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `country` | string | Código ISO 3166-1 alfa-2 — use como parâmetro `country` de `extract_ip` |
| `name` | string | Nome do país |
| `flag_url` | string | URL do ícone da bandeira |

**Exemplo**

```bash
curl "https://api.eproxies.net/gateway_api/country-list"
```

```json
[
  { "country": "US", "name": "United States", "flag_url": "https://file.eproxies.net/flags/us.png" }
]
```

### `GET /gateway_api/add-ip`

Adicionar IP à whitelist — Adiciona um IP de saída à whitelist; esse IP passa a extrair proxies sem credenciais.

**Parâmetros da requisição**

| Campo | Tipo | Obrigatório | Valores aceitos | Descrição |
| --- | --- | --- | --- | --- |
| `userName` | string | Sim | — | Nome de usuário da conta |
| `userKeyValue` | string | Sim | — | Chave do usuário, obtida no painel |
| `ipAddress` | string | Sim | — | Endereço IP a incluir na whitelist |

**Campos da resposta**

Retorna um objeto de resultado; considere a resposta real.

**Exemplo**

```bash
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/del-ip`

Remover IP da whitelist — Remove um IP da whitelist; ele deixa de poder extrair sem credenciais.

**Parâmetros da requisição**

| Campo | Tipo | Obrigatório | Valores aceitos | Descrição |
| --- | --- | --- | --- | --- |
| `userName` | string | Sim | — | Nome de usuário da conta |
| `userKeyValue` | string | Sim | — | Chave do usuário, obtida no painel |
| `ipAddress` | string | Sim | — | IP da whitelist a remover |

**Campos da resposta**

Retorna um objeto de resultado; considere a resposta real.

**Exemplo**

```bash
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/lists-ip`

Consultar a whitelist — Lista todas as entradas da whitelist da conta atual.

**Parâmetros da requisição**

| Campo | Tipo | Obrigatório | Valores aceitos | Descrição |
| --- | --- | --- | --- | --- |
| `userName` | string | Sim | — | Nome de usuário da conta |
| `userKeyValue` | string | Sim | — | Chave do usuário, obtida no painel |

**Campos da resposta**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `ipAddress` | string | IP na whitelist |
| `remarkText` | string | Observação |

**Exemplo**

```bash
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

## Chamada rápida

```bash
# Extrair 10 proxies HTTP dos EUA (JSON, IPs fixos)
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Adicionar o IP do servidor atual à whitelist
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

## Uso a partir de um agente de IA

Aponte seu agente para a URL da especificação e ele deduz sozinho todos os parâmetros e formatos de resposta:

```
https://www.eproxies.io/docs/openapi.json
```

Junto com a [Referência rápida para Agents](https://www.eproxies.io/docs/agent-reference) (sintaxe de parâmetros do username no gateway), isso cobre toda a superfície de integração.