O2ProxyСПРАВОЧНИК РАЗРАБОТЧИКА
O2PROXY / СПРАВОЧНИК РАЗРАБОТЧИКА

Документация прокси API

Прокси под управлением вашего кода.

Получайте список IP, управляйте прокси-услугами и их продлением из своей системы. Здесь описан действующий API O2Proxy — с параметрами, примерами запросов и форматами ответов.

17 методовPOSTJSON

Этот API предназначен для прокси и связанных операций с балансом и счетами. API управления VPS, выделенными серверами и арендой диапазонов здесь не предоставляется.

01

Быстрый старт

Первый запрос — чтение баланса. Он не создаёт услугу и не списывает деньги.

  1. 01

    Создайте ключ в разделе «API прокси» и скопируйте свой ID клиента. Это номер аккаунта, а не email и не ID пользователя.

  2. 02

    Задайте O2_USER_ID и O2_API_HASH в окружении своего сервера. В hash передаётся выданный ключ; вычислять хеш самостоятельно не нужно.

  3. 03

    Отправьте my_balance. Проверяйте JSON-ответ, затем переходите к списку услуг и параметрам конкретной прокси-услуги.

Адрес серверных запросов
https://my.virty.io/includes/client_api/index.phpPOST · form-data / URL-encoded · JSON в ответе
export O2_USER_ID=YOUR_CLIENT_ID
export O2_API_HASH=YOUR_API_KEY

Подставьте свои значения. Не добавляйте ключ в публичный репозиторий или браузерный JavaScript.

curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=my_balance'
02

Авторизация

Все методы используют три общих поля в теле POST. Заголовок Bearer и JSON-тело не заменяют эти поля. Проверка TLS должна оставаться включённой.

ПараметрТипОписание
actionОбязательныйstringТочное имя метода из справочника.
useridОбязательныйintegerВаш ID клиента из кабинета.
hashОбязательныйstringВыданный API-ключ. Передавайте его только серверным запросом по HTTPS.

Список разрешённых IP ограничивает источник API-запросов для ключа. При создании ключа пустой список разрешает любой IP. Параметр accessips в add_service задаёт другой список: доступ к самим прокси без пароля.

03

Методы API

Все ID, IP, суммы, пароли и локации в примерах демонстрационные. Порты и доступы берите из ответа для своей услуги.

ЧтениеИзменяет настройкиФинансовая операцияУдаляет ресурсыСовместимость
POST

my_balance

Узнать баланс

Чтение

Возвращает текущий кредитный баланс аккаунта в поле credit. Подходит для первого запроса и проверки остатка перед заказом.

Дополнительные параметры

Дополнительных параметров нет: достаточно action, userid и hash.

Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=my_balance'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "credit": "1000.00"
}
POST

get_account_services

Список прокси-услуг

Чтение

Возвращает услуги, найденные среди прокси аккаунта. В services ключ объекта — ID услуги; это не список всех услуг биллинга.

При отсутствии прокси services может быть null. Обрабатывайте пустой результат.

Дополнительные параметры
ПараметрТипОписание
statusНеобязательныйstringНеобязательный фильтр статуса прокси, например active.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=get_account_services' \
  --data-urlencode 'status=active'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "services": {
    "12345": {
      "id": "12345",
      "status": "active"
    }
  }
}
POST

get_service_info

IP и доступы к услуге

Чтение

Возвращает IP, логин, пароль, порты HTTP/SOCKS5, срок действия и связанные счета.

Ответ содержит сведения и счета только ваших прокси-услуг. Ссылки proxylist и пароль — секреты подключения.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=get_service_info' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "ips": "192.0.2.10,192.0.2.11",
  "login": "example-login",
  "password": "EXAMPLE_PROXY_PASSWORD",
  "socks5_port": "24532",
  "http_port": "24531",
  "expired_time": 1794787200,
  "service_status": "active",
  "socks5_url_proxylist": "https://my.virty.io/proxy_list/proxies.php?hash=EXAMPLE_LIST_HASH&type=socks5&format=format1",
  "http_url_proxylist": "https://my.virty.io/proxy_list/proxies.php?hash=EXAMPLE_LIST_HASH&type=http&format=format1",
  "serviceid": "12345",
  "invoices": []
}
POST

get_available_locations

Доступные локации

Чтение

Возвращает значения страна:город из доступного пула. Подставляйте подходящее значение в proxy_location.

Пример не является актуальным списком стран. Наличие IP меняется; чтение списка ничего не резервирует.

Дополнительные параметры

Дополнительных параметров нет: достаточно action, userid и hash.

Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=get_available_locations'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "available_locations": [
    "RU:",
    "RU:MSK"
  ]
}
POST

get_ips_access_list

IP доступа к API

Чтение

Возвращает ограничение IP для текущего ключа в строке ips_access_list. Пустая строка означает отсутствие ограничения.

Это доступ к API, а не список IP для подключения к прокси без пароля.

Дополнительные параметры

Дополнительных параметров нет: достаточно action, userid и hash.

Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=get_ips_access_list'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "ips_access_list": "192.0.2.50,198.51.100.10"
}
POST

add_service

Создать прокси-услугу

Финансовая операция

Создаёт услугу на партнёрском API-тарифе и возвращает serviceid, invoiceid и added_proxyes_count. После создания запросите get_service_info.

Вызов может оформить заказ, списать баланс и включить дальнейшее автопродление. manual_prolong меняет порядок будущего продления, но не делает первоначальный заказ бесплатным. При low balance проверьте остаток: суммы «впритык» текущему обработчику может быть недостаточно.

Дополнительные параметры
ПараметрТипОписание
countОбязательныйintegerКоличество прокси для новой услуги: положительное целое число.
prolong_typeНеобязательныйstringauto_prolong — автоматическое продление с баланса, это значение по умолчанию. manual_prolong — создание счёта и ручная оплата продления.
service_nameНеобязательныйstringНазвание создаваемой услуги.
proxy_locationНеобязательныйstringЛокация в формате RU или RU:MSK. Доступные значения запрашивайте через get_available_locations; список не резервирует IP.
typecancelНеобязательныйstringПри создании услуги: End of Billing Period — запросить отмену в конце периода. При отсутствии этого поля отмена заранее не запрашивается.
noemailНеобязательныйboolean1 — не отправлять письмо о создании услуги. По умолчанию письмо разрешено.
noinvoiceemailНеобязательныйboolean1 — не отправлять письмо о новом счёте. По умолчанию письмо разрешено.
accessipsНеобязательныйstringIP доступа к прокси без пароля, через запятую. Поддерживаются IPv4 и сети /23–/32.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=add_service' \
  --data-urlencode 'count=3' \
  --data-urlencode 'prolong_type=manual_prolong' \
  --data-urlencode 'service_name=integration-example' \
  --data-urlencode 'proxy_location=RU' \
  --data-urlencode 'typecancel=End of Billing Period' \
  --data-urlencode 'noemail=1' \
  --data-urlencode 'noinvoiceemail=1' \
  --data-urlencode 'accessips=192.0.2.50'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "balance": 700,
  "added_proxyes_count": "3",
  "proxy_country": "RU",
  "serviceid": "12345",
  "invoiceid": "67890"
}
POST

suspend_service

Приостановить прокси

Изменяет настройки

Вызывает приостановку прокси-услуги. После ответа проверьте service_status через get_service_info.

Приостановка не является отменой и сама по себе не останавливает расчётный период.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=suspend_service' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "result": "success"
}
POST

unsuspend_service

Возобновить прокси

Изменяет настройки

Возобновляет работу приостановленной прокси-услуги. Проверьте итоговый статус отдельным запросом.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=unsuspend_service' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "result": "success"
}
POST

change_service_pass

Сменить пароль прокси

Изменяет настройки

Генерирует новый пароль и возвращает его в new_pass вместе с логином.

Также меняется hash ссылки экспорта прокси. Обновите пароль и ссылки в своей системе; это не смена ключа API.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=change_service_pass' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "login": "example-login",
  "new_pass": "EXAMPLE_NEW_PASSWORD",
  "serviceid": "12345"
}
POST

update_ips_access_list

Заменить IP доступа к API

Изменяет настройки

Полностью заменяет разрешённые IP для ключа, которым выполнен запрос.

Укажите адрес своего сервера в новом списке, чтобы сохранить доступ. Пустая строка в действующем обработчике отклоняется; обещание старой документации об очистке списка этим запросом не применимо.

Дополнительные параметры
ПараметрТипОписание
ips_access_listОбязательныйstringНепустой список IPv4 без пробелов, через запятую. Полностью заменяет разрешённые IP текущего API-ключа.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=update_ips_access_list' \
  --data-urlencode 'ips_access_list=192.0.2.50,198.51.100.10'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "ips_access_list": "192.0.2.50,198.51.100.10"
}
POST

prolong_service

Создать счёт на продление

Финансовая операция

Работает для API-тарифа manual_prolong. Возвращает счёт и сроки продления услуги.

По умолчанию autoapplycredit=Y может списать средства. В примере явно задано N. Не считайте услугу продлённой только по успешному ответу: проверьте invoice_status и фактический срок действия.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
autoapplycreditНеобязательныйstringY — применять баланс при продлении, значение по умолчанию. N — создать счёт без автоматического списания.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=prolong_service' \
  --data-urlencode 'serviceid=12345' \
  --data-urlencode 'autoapplycredit=N'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "invoiceid": 67890,
  "invoice_status": "Unpaid",
  "invoice_due_date": "2026-12-06",
  "service_id": "12345",
  "service_due_date": "2026-12-06 12:00:00",
  "service_expired_time": 1796558400
}
POST

applycredit

Оплатить счёт с баланса

Финансовая операция

Применяет кредитный баланс к указанному счёту. У метода нет отдельного параметра суммы.

Это списание денег. До вызова отдельно подтвердите точный счёт и сумму, проверьте принадлежность, статус и остаток баланса. Не повторяйте запрос при неизвестном результате или для уже оплаченного счёта; проверьте оплату в кабинете.

Дополнительные параметры
ПараметрТипОписание
invoiceidОбязательныйintegerID вашего неоплаченного счёта. Номер и сумму необходимо проверить до оплаты.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=applycredit' \
  --data-urlencode 'invoiceid=67890'
Пример ответа
{
  "code": "2001",
  "status": "successful"
}
POST

add_typecancel

Запросить отмену

Изменяет настройки

Создаёт запрос отмены для прокси-услуги. Для новой интеграции используйте этот метод вместо set_type_cancel.

Запрос отмены и фактическое отключение — разные события. Проверьте статус услуги; запрос не означает возврат средств.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
typeНеобязательныйstringEnd of Billing Period — запрос отмены в конце периода, по умолчанию. Immediate — запрос немедленной отмены.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=add_typecancel' \
  --data-urlencode 'serviceid=12345' \
  --data-urlencode 'type=End of Billing Period'
Пример ответа
{
  "code": "2001",
  "status": "successful"
}
POST

terminate_typecancel

Отозвать запрос отмены

Изменяет настройки

Удаляет существующий запрос отмены услуги. Если запрос не найден, возможен ответ с ошибкой.

Не восстанавливает уже удалённую услугу и не выполняет возврат денег.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=terminate_typecancel' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "code": "2001",
  "status": "successful"
}
POST

del_ips_from_service

Удалить часть IP

Удаляет ресурсы

Удаляет выбранные прокси и возвращает оставшийся список в ips_list. Пересчитывает стоимость дальнейшего продления.

Выбранные IP перестанут работать. Для удаления всех IP нужен terminate_service. Автоматическая компенсация за неиспользованный период этим методом не предусмотрена.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
ips_for_delОбязательныйstringIPv4 через запятую. Все адреса должны принадлежать услуге; удалить все IP этим методом нельзя.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=del_ips_from_service' \
  --data-urlencode 'serviceid=12345' \
  --data-urlencode 'ips_for_del=192.0.2.10'
Пример ответа
{
  "code": "2001",
  "status": "successful",
  "ips_list": "192.0.2.11"
}
POST

terminate_service

Отключить прокси-услугу

Удаляет ресурсы

Вызывает немедленное отключение ресурсов услуги. Для плановой отмены используйте add_typecancel.

Прокси перестанут работать. Проверяйте результат отдельно; операция не является автоматической компенсацией или возвратом средств.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=terminate_service' \
  --data-urlencode 'serviceid=12345'
Пример ответа
{
  "result": "success"
}
POST

set_type_cancel

Старый запрос отмены

Совместимость

Оставлен для совместимости. Для нового кода используйте add_typecancel.

В старой справке поле названо typecancel, но установленный обработчик читает type. Семантику отмены через этот старый маршрут согласуйте с поддержкой; не используйте его для новых сценариев.

Дополнительные параметры
ПараметрТипОписание
serviceidОбязательныйintegerID принадлежащей вам прокси-услуги.
typeНеобязательныйstringEnd of Billing Period — запрос отмены в конце периода, по умолчанию. Immediate — запрос немедленной отмены.
Запрос и ответ
curl --request POST \
  --url 'https://my.virty.io/includes/client_api/index.php' \
  --data-urlencode "userid=${O2_USER_ID}" \
  --data-urlencode "hash=${O2_API_HASH}" \
  --data-urlencode 'action=set_type_cancel' \
  --data-urlencode 'serviceid=12345' \
  --data-urlencode 'type=End of Billing Period'
Пример ответа

Формат ответа зависит от старого обработчика отмены. Для новой интеграции используйте add_typecancel и проверяйте статус услуги после запроса.

04

Ответы и ошибки

HTTP 200 сам по себе не подтверждает успех операции. Обычный ответ: code = 2001 и status = successful. Методы модуля могут возвращать result = success. При result = error читайте message; при status = error — mess. Код и ID могут приходить строками или числами.

При таймауте изменяющего запроса сначала проверьте фактический результат. Автоматический повтор может создать вторую услугу или повторить финансовую операцию. У этого API нет документированного ключа идемпотентности.

codeОписание
1000Некорректный IPv4 или ошибка конкретной операции; смотрите mess.
1001Не прошла проверка hash. Проверьте ключ и ID клиента.
1002IP отправителя не входит в разрешённые IP ключа.
1003Неверный userid/serviceid или услуга недоступна этому клиенту.
1004Некорректный или неизвестный запрос.
1005Некорректное количество прокси.
1006Недостаточно средств для операции.
1007Ошибка создания заказа. Перед повтором проверьте, не появилась ли услуга.
1008Общая ошибка операции. Уточните результат перед повтором.
1009Не указан или неверен serviceid.
1010IP услуги не найдены; возможно, она уже отключена.
1011Ключ имеет статус read_only: разрешены только операции чтения.
1012Прокси-услуга не найдена.
1013Тариф не поддерживает запрошенное ручное продление.
1014Не передан список удаляемых IP.
1015В списке удаления есть некорректный IPv4.
1016IP не принадлежат услуге либо операция удаления отклонена.
1017Запрошено удаление всех IP либо произошла ошибка удаления.
1018Ключ приостановлен, доступ к API запрещён.
1019Не указан или неверен invoiceid.
1020Счёт уже оплачен либо отсутствует ips_access_list. В старом обработчике код используется повторно — проверяйте mess.

Доступ и условия

Стоимость прокси и условия партнёрского доступа зависят от подключённого тарифа. Уточните их в поддержке перед автоматизацией заказов. Создание ключа не гарантирует индивидуальную цену.