Обзор

Rotating Proxy API предоставляет программный доступ к ротационным резидентским прокси: поиск гео-таргетов, создание доступов к прокси (sub-users), чтение текущего тарифа и баланса трафика, получение статистики использования и управление авторизацией по IP.

Вся бизнес-логика, биллинг и учет трафика идентичны панели управления платформы — API это просто другой способ работать с тем же продуктом.

Базовый URL

Все endpoint'ы Rotating Proxy API находятся под префиксом v2:

https://app.cyberyozh.com/api/v2/rotating-proxies/

Аутентификация

API использует аутентификацию по API ключу, передаваемому в заголовке X-Api-Key. Это та же система ключей, что используется во всем CyberYozh API — отдельные учетные данные не требуются.

-H 'X-Api-Key: your_api_key_here'

Как получить API ключ

1. Войдите на https://app.cyberyozh.com.
2. Откройте меню профиля и перейдите в раздел API Keys.
3. Нажмите Generate и скопируйте ключ (он показывается один раз).
4. Передавайте его в заголовке X-Api-Key в каждом запросе.

Запрос без действительного ключа возвращает 403 Forbidden:

{
  "detail": "Invalid API key provided."
}

Как работают ротационные прокси

Подключение к ротационному прокси состоит из трех частей:

1. Хост и порты шлюза — фиксированная точка входа в прокси-сеть. Читайте их из GET /subscription/ (proxy_host, proxy_port для HTTP, proxy_port_socks5 для SOCKS5).
2. Учетные данные — real_login и password доступа к прокси (sub-user). Создавайте и читайте их через /sub-users/.
3. Суффиксы таргетинга — параметры гео, ротации/сессии и IP-фильтра кодируются в имени пользователя путем добавления суффиксов к real_login. Отдельного вызова «сгенерировать строку прокси» нет; вы составляете имя пользователя сами, точно так же, как это делает панель управления.

Грамматика имени пользователя

<real_login>[-<country>][-<region>][-<city>][-<zip>][-<isp>][-<session>][-<ttl>][-<filter>]

• Части соединяются через - и предваряются ведущим -.
• Гео-суффиксы (country, region, city, zip, isp) берутся из поля suffix гео-endpoint'ов.
• Сессия (sticky IP): опустите для полной ротации; для sticky IP добавьте s-<id>, где <id> — случайная 8-символьная строка [A-Za-z0-9], плюс суффикс TTL ttl-5m / ttl-10m / ttl-15m / ttl-30m (или ttl-<minutes>m для произвольной длительности).
• Фильтр-суффиксы (filter-speed, filter-iqs, filter-speed+iqs) берутся из GET /session-options/.

Пример имени пользователя с таргетингом на суффикс страны us, 5-минутной sticky-сессией и фильтром качества:

u12ab-us-s-Ab3xK9pQ-ttl-5m-filter-iqs

Итоговая строка подключения тогда — username:password@proxy_host:proxy_port. Полные примеры см. в разделе Подключение.

Endpoint'ы кратко

Ресурс	Метод и путь	Назначение
Страны	GET /geo/countries/	Список доступных стран
Регионы	GET /geo/regions/	Список регионов страны
Города	GET /geo/cities/	Список городов страны
ZIP-коды	GET /geo/zips/	Список ZIP-кодов
Провайдеры (ISP)	GET /geo/isps/	Список ISP-провайдеров
Параметры сессии	GET /session-options/	Типы ротации, длительности сессий, IP-фильтры
Подписка	GET /subscription/	Тариф, баланс трафика, данные подключения
Доступы	GET/POST /sub-users/	Список / создание доступов к прокси
Доступ	GET/PATCH/DELETE /sub-users/{id}/	Чтение / изменение / отзыв доступа
Статистика	GET /stats/	Статистика использования трафика
Whitelist	GET/PUT /whitelist/	Список / замена авторизованных IP
Запись whitelist	PATCH/DELETE /whitelist/{id}/	Изменение / удаление авторизованного IP

Интерактивная документация (Swagger)

Каждый endpoint также доступен в интерактивном Swagger UI, где можно авторизоваться с вашим API ключом и выполнять запросы напрямую:

https://app.cyberyozh.com/docs/

Откройте Authorize, вставьте ваш ключ в ApiKeyAuth (X-Api-Key) и используйте Try it out для любой операции rotating-proxy.

Типичные ошибки

HTTP	Значение
400	Неверные параметры запроса или тело
403	Отсутствует или недействителен API ключ
404	Нет активной подписки на ротационный прокси, либо ресурс не найден
409	Логин уже существует (при создании доступа)
429	Превышен лимит запросов — повторите через указанную задержку
502	Шлюз прокси временно недоступен