Автоматизация прокси через API: whitelist, покупка и продление из скрипта

Ключ и лимиты

Ключ передаётся заголовком Authorization в форме Bearer. Он создаётся в личном кабинете и отзывается там же — отозванный перестаёт работать сразу, поэтому ротация ключей не требует простоя: создайте новый, переключите скрипт, отзовите старый.

Лимиты стоит знать до того, как их упрёте: 300 запросов в минуту и 5000 в час на ключ. У двух действий свои отдельные лимиты, более строгие: покупка — 60 в час, запрос учётных данных — 30 в час. Последнее важно для скриптов, которые тянут логин и пароль перед каждым запуском: тридцати раз в час хватает, но не для цикла по сотне задач.

Whitelist заменяется целиком

Это главная ловушка, и она стоит первой. Запрос на whitelist — PUT, и он записывает переданный список вместо прежнего, а не добавляет к нему. Скрипт, который отправляет один свой адрес, стирает все остальные: сервер, который работал по whitelist, теряет доступ в момент, когда ноутбук обновил свой адрес.

KEY="..."; SVC="..."; ME=$(curl -s https://api.ipify.org)

# 1. Читаем текущий список
curl -s -H "Authorization: Bearer $KEY" \
  "https://op-proxy.com/api/v1/services/$SVC" \
  | jq '.data.whitelist'

# 2. Заменяем только свою запись (по метке), остальные сохраняем
curl -s -X PUT -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  "https://op-proxy.com/api/v1/services/$SVC/whitelist" \
  -d "{\"whitelisted_ips\":[\"$ME\",\"203.0.113.10\"],\"labels\":[\"laptop\",\"ci\"]}" \
  | jq '.data.whitelist'

Ограничения, о которых лучше узнать заранее

• Не больше 50 адресов на услугу. При превышении приходит ошибка too_many_ips, список не меняется.
• Только IPv4. Адрес проверяется как IPv4, и IPv6-адрес отклоняется с ошибкой invalid_ip. Если исходящий адрес вашей машины — IPv6, whitelist не подойдёт, работайте по логину и паролю.
• Метки необязательны, обрезаются до 64 символов и сопоставляются с адресами по порядку в массиве.
• Повторы в списке отбрасываются молча — дубликат не ошибка.
• Whitelist есть только у ротационных услуг; для другого типа придёт not_found.

Динамический адрес: один вызов из cron

Это и есть та задача, ради которой стоит браться за API. Скрипт узнаёт свой текущий внешний адрес, сравнивает с записанным по своей метке и, если он изменился, отправляет обновлённый список. Раз в пять минут по cron — и авторизация по IP перестаёт быть проблемой для домашнего или мобильного подключения.

Одна деталь про надёжность: сравнивайте перед записью. Безусловный PUT каждые пять минут работает, но тратит лимит и переписывает список, когда ничего не менялось, — а значит любая ошибка в формировании списка успевает примениться прежде, чем вы её заметите.

Покупка и продление

Покупка — POST с типом услуги и идентификатором тарифа; страна и режим ротации необязательны. Здесь есть асимметрия, которую стоит помнить: для ipv4_rotating страну передавать нельзя — эти услуги всегда идут через один шлюз, и в ответ придёт unsupported_for_type. Для ipv6_rotating страна выбирается.

# Список доступных тарифов с их идентификаторами
curl -s -H "Authorization: Bearer $KEY" \
  https://op-proxy.com/api/v1/catalog/plans | jq '.data'

# Покупка: страну указываем только для ipv6_rotating
curl -s -X POST -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  https://op-proxy.com/api/v1/purchase \
  -d '{"type":"ipv6_rotating","plan_id":"...","country":"de"}'

# Продление списывает стоимость с баланса
curl -s -X POST -H "Authorization: Bearer $KEY" \
  "https://op-proxy.com/api/v1/services/$SVC/extend"

Продление списывает стоимость с баланса аккаунта. Если денег не хватает, приходит insufficient_balance со статусом 402, и услуга не продлевается. Списание и продление связаны: если продлить не удалось, средства возвращаются на баланс, так что повторный вызов после ошибки не приводит к двойному списанию.

Ротация

Режим ротации меняется отдельным запросом и задаётся коротким кодом. Для ipv4_rotating этого запроса нет: там ротация происходит на каждый запрос всегда, и попытка задать режим вернёт ошибку с объяснением, а не молчаливое игнорирование. Это осознанное поведение — молчаливое игнорирование настройки хуже отказа.

Ошибки приходят кодом, а не текстом

Ответ всегда содержит поле статуса, а при ошибке — код и человекочитаемое сообщение. Ветвиться в скрипте нужно по коду: сообщения мы можем переформулировать, коды — нет. Практически полезные: invalid_ip и too_many_ips при whitelist, insufficient_balance при продлении, unsupported_for_type при покупке не того сочетания, not_found при чужом или несуществующем идентификаторе услуги.

Полное описание всех методов доступно машиночитаемо — спецификация OpenAPI отдаётся тем же API, так что клиент можно сгенерировать, а не писать руками.