# Извлечение по API (режим белого списка)

В режиме белого списка прокси извлекаются пачками через HTTP GET-запрос в виде `IP:порт` — подключение напрямую, без логина и пароля. Самим белым списком тоже можно управлять через API, что позволяет автоматизировать весь процесс от начала до конца.

## Предварительные условия

1. Куплен тариф динамических резидентных прокси.
2. Выходной IP вашего сервера добавлен в белый список (на странице «Белый список» личного кабинета или через API управления белым списком, описанный ниже).

## Эндпоинт извлечения

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

| Параметр | Обязательный | Значения | Описание |
| --- | --- | --- | --- |
| `count` | да | число | количество за одно извлечение |
| `country` | нет | код страны / `Global` | регион, например `US`; `Global` — без ограничения по стране |
| `protocol` | нет | `http` / `socks5` | протокол прокси |
| `format` | нет | `txt` / `json` | формат ответа |
| `session` | нет | `sticky` / `random` | тип IP: `sticky` — липкие (переиспользуется один и тот же набор IP) / `random` — случайные |
| `separator` | нет | `crlf` / `br` / `cr` / `lf` / `tab` | разделитель строк для формата txt: `\r\n`, `</br>`, `\r`, `\n`, `\t` |
| `st` | нет | произвольная строка | пользовательский разделитель (вместо `separator`) |

Примеры:

```bash
# Извлечь 10 HTTP-прокси из США, формат JSON, липкие IP
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Извлечь 5 SOCKS5-прокси из случайных стран, формат txt, по одному в строке
curl "https://api.eproxies.net/gateway_api/extract_ip?count=5&protocol=socks5&format=txt&separator=lf&session=random"
```

При `format=json` возвращается массив объектов, каждый с двумя полями — `ipAddress` и `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()

# Извлечённые прокси используются напрямую, без логина и пароля
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())
```

Список стран, доступных для извлечения (в ответе — код страны `country`, название `name` и иконка флага `flag_url`):

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

> Запрос извлечения должен исходить с IP из белого списка, иначе он будет отклонён. На странице «Извлечение по API» личного кабинета есть визуальный генератор ссылок.

## API управления белым списком

Добавление, удаление и просмотр записей белого списка доступны чисто через API — удобно для автоматического обслуживания при смене выходного IP. Все три эндпоинта аутентифицируются парой `userName` (имя пользователя) + `userKeyValue` (ключ пользователя, берётся в личном кабинете):

```bash
# Добавить IP в белый список
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Удалить IP из белого списка
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Получить текущий белый список
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

Типовой сценарий автоматизации (среда с непостоянным выходным IP):

```python
import requests

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

# 1. Узнаём текущий выходной IP этой машины
my_ip = requests.get("https://ipinfo.io/json", timeout=30).json()["ip"]

# 2. Добавляем его в белый список
requests.get(f"{BASE}/add-ip", params={**AUTH, "ipAddress": my_ip}, timeout=30)

# 3. Извлекаем прокси и используем
proxies = requests.get(
    f"{BASE}/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "random"},
    timeout=30,
).json()
print(proxies)
```

## Что выбрать: логин/пароль или извлечение

| | Логин и пароль | Извлечение по API (белый список) |
| --- | --- | --- |
| Гранулярность таргетинга | страна/штат/город/ASN | страна |
| Управление сессиями | точное, через sid/ttl | `session=sticky/random`, по партиям извлечения |
| Применимость | нужна поддержка аутентификации прокси в ПО | любое ПО с поддержкой прокси |
| Рекомендуемые сценарии | интеграция в код, тонко настроенный парсинг | устаревшие инструменты, массовая раздача, среды без аутентификации |

## Спецификация OpenAPI

Машиночитаемое описание всех эндпоинтов этой страницы доступно по адресу [openapi.json](https://www.eproxies.io/docs/openapi.json) — импортируйте его в Postman / Swagger UI или загрузите из ИИ-агента.