# Extração via API (modo whitelist)

No modo whitelist, você extrai proxies em lote no formato `IP:porta` por meio de requisições HTTP GET e os usa em conexão direta, sem usuário e senha. A própria whitelist também pode ser gerenciada via API, permitindo automatizar o fluxo de ponta a ponta.

## Pré-requisitos

1. Ter um plano de Proxies Residenciais ativo.
2. O IP de saída do seu servidor já estar na whitelist (pela página "Whitelist" do painel ou pela API de gerenciamento da whitelist abaixo).

## Endpoint de extração

```
GET https://api.eproxies.net/gateway_api/extract_ip
```

| Parâmetro | Obrigatório | Valores possíveis | Descrição |
| --- | --- | --- | --- |
| `count` | sim | número | quantidade extraída por chamada |
| `country` | não | código do país / `Global` | região, como `US`; `Global` significa sem restrição de país |
| `protocol` | não | `http` / `socks5` | protocolo do proxy |
| `format` | não | `txt` / `json` | formato de retorno |
| `session` | não | `sticky` / `random` | tipo de IP: `sticky` fixo (reutiliza o mesmo lote de IPs) / `random` aleatório |
| `separator` | não | `crlf` / `br` / `cr` / `lf` / `tab` | separador do formato txt: `\r\n`, `</br>`, `\r`, `\n`, `\t` |
| `st` | não | string personalizada | separador personalizado (no lugar de `separator`) |

Exemplos:

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

# Extrai 5 proxies SOCKS5 de países aleatórios, em txt, um por linha
curl "https://api.eproxies.net/gateway_api/extract_ip?count=5&protocol=socks5&format=txt&separator=lf&session=random"
```

Com `format=json`, o retorno é um array de objetos, cada um com os campos `ipAddress` e `portValue`:

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

```python
import requests

resp = requests.get(
    "https://api.eproxies.net/gateway_api/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "sticky"},
    timeout=30,
)
proxy_list = resp.json()

# Os proxies extraídos são usados em conexão direta, sem usuário e senha
first = proxy_list[0]
endpoint = f"{first['ipAddress']}:{first['portValue']}"
proxies = {"http": f"http://{endpoint}", "https": f"http://{endpoint}"}
print(requests.get("https://ipinfo.io", proxies=proxies, timeout=30).json())
```

Lista de países disponíveis para extração (retorna `country` código do país, `name` nome e `flag_url` ícone da bandeira):

```
GET https://api.eproxies.net/gateway_api/country-list
```

> A requisição de extração precisa partir de um IP presente na whitelist; caso contrário, será recusada. A página "Extração via API" do painel oferece um gerador visual de links.

## API de gerenciamento da whitelist

A adição, a remoção e a consulta da whitelist funcionam por API pura, o que facilita a manutenção automática quando o IP de saída muda. Os três endpoints autenticam com `userName` (nome de usuário) + `userKeyValue` (chave do usuário, obtida no painel):

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

# Remove um IP da whitelist
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Consulta a whitelist atual
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

Fluxo típico de automação (para ambientes com IP de saída variável):

```python
import requests

BASE = "https://api.eproxies.net/gateway_api"
AUTH = {"userName": "USERNAME", "userKeyValue": "USER_KEY"}

# 1. Obtém o IP de saída atual desta máquina
my_ip = requests.get("https://ipinfo.io/json", timeout=30).json()["ip"]

# 2. Adiciona esse IP à whitelist
requests.get(f"{BASE}/add-ip", params={**AUTH, "ipAddress": my_ip}, timeout=30)

# 3. Extrai os proxies e usa
proxies = requests.get(
    f"{BASE}/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "random"},
    timeout=30,
).json()
print(proxies)
```

## Modo usuário/senha ou modo de extração: qual escolher

| | Modo usuário/senha | Extração via API (whitelist) |
| --- | --- | --- |
| Granularidade de segmentação | país/estado/cidade/ASN | país |
| Controle de sessão | controle fino com sid/ttl | `session=sticky/random` por lote |
| Aplicabilidade | requer software com suporte a autenticação de proxy | qualquer software com suporte a proxy |
| Cenários recomendados | integração em código, coleta refinada | ferramentas legadas, distribuição em lote, ambientes sem autenticação |

## Especificação OpenAPI

Uma definição legível por máquina de todos os endpoints desta página está disponível em [openapi.json](https://www.eproxies.io/docs/openapi.json) — importe no Postman / Swagger UI ou carregue a partir de um agente de IA.