Документация прокси API
Прокси под управлением вашего кода.
Получайте список IP, управляйте прокси-услугами и их продлением из своей системы. Здесь описан действующий API O2Proxy — с параметрами, примерами запросов и форматами ответов.
Этот API предназначен для прокси и связанных операций с балансом и счетами. API управления VPS, выделенными серверами и арендой диапазонов здесь не предоставляется.
Быстрый старт
Первый запрос — чтение баланса. Он не создаёт услугу и не списывает деньги.
- 01
Создайте ключ в разделе «API прокси» и скопируйте свой ID клиента. Это номер аккаунта, а не email и не ID пользователя.
- 02
Задайте O2_USER_ID и O2_API_HASH в окружении своего сервера. В hash передаётся выданный ключ; вычислять хеш самостоятельно не нужно.
- 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'Авторизация
Все методы используют три общих поля в теле POST. Заголовок Bearer и JSON-тело не заменяют эти поля. Проверка TLS должна оставаться включённой.
| Параметр | Тип | Описание |
|---|---|---|
actionОбязательный | string | Точное имя метода из справочника. |
useridОбязательный | integer | Ваш ID клиента из кабинета. |
hashОбязательный | string | Выданный API-ключ. Передавайте его только серверным запросом по HTTPS. |
Список разрешённых IP ограничивает источник API-запросов для ключа. При создании ключа пустой список разрешает любой IP. Параметр accessips в add_service задаёт другой список: доступ к самим прокси без пароля.
Методы API
Все ID, IP, суммы, пароли и локации в примерах демонстрационные. Порты и доступы берите из ответа для своей услуги.
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"
}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"
}
}
}get_service_info
IP и доступы к услуге
ЧтениеВозвращает IP, логин, пароль, порты HTTP/SOCKS5, срок действия и связанные счета.
Ответ содержит сведения и счета только ваших прокси-услуг. Ссылки proxylist и пароль — секреты подключения.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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": []
}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"
]
}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"
}add_service
Создать прокси-услугу
Финансовая операцияСоздаёт услугу на партнёрском API-тарифе и возвращает serviceid, invoiceid и added_proxyes_count. После создания запросите get_service_info.
Вызов может оформить заказ, списать баланс и включить дальнейшее автопродление. manual_prolong меняет порядок будущего продления, но не делает первоначальный заказ бесплатным. При low balance проверьте остаток: суммы «впритык» текущему обработчику может быть недостаточно.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
countОбязательный | integer | Количество прокси для новой услуги: положительное целое число. |
prolong_typeНеобязательный | string | auto_prolong — автоматическое продление с баланса, это значение по умолчанию. manual_prolong — создание счёта и ручная оплата продления. |
service_nameНеобязательный | string | Название создаваемой услуги. |
proxy_locationНеобязательный | string | Локация в формате RU или RU:MSK. Доступные значения запрашивайте через get_available_locations; список не резервирует IP. |
typecancelНеобязательный | string | При создании услуги: End of Billing Period — запросить отмену в конце периода. При отсутствии этого поля отмена заранее не запрашивается. |
noemailНеобязательный | boolean | 1 — не отправлять письмо о создании услуги. По умолчанию письмо разрешено. |
noinvoiceemailНеобязательный | boolean | 1 — не отправлять письмо о новом счёте. По умолчанию письмо разрешено. |
accessipsНеобязательный | string | IP доступа к прокси без пароля, через запятую. Поддерживаются 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"
}suspend_service
Приостановить прокси
Изменяет настройкиВызывает приостановку прокси-услуги. После ответа проверьте service_status через get_service_info.
Приостановка не является отменой и сама по себе не останавливает расчётный период.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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"
}unsuspend_service
Возобновить прокси
Изменяет настройкиВозобновляет работу приостановленной прокси-услуги. Проверьте итоговый статус отдельным запросом.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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"
}change_service_pass
Сменить пароль прокси
Изменяет настройкиГенерирует новый пароль и возвращает его в new_pass вместе с логином.
Также меняется hash ссылки экспорта прокси. Обновите пароль и ссылки в своей системе; это не смена ключа API.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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"
}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"
}prolong_service
Создать счёт на продление
Финансовая операцияРаботает для API-тарифа manual_prolong. Возвращает счёт и сроки продления услуги.
По умолчанию autoapplycredit=Y может списать средства. В примере явно задано N. Не считайте услугу продлённой только по успешному ответу: проверьте invoice_status и фактический срок действия.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
autoapplycreditНеобязательный | string | Y — применять баланс при продлении, значение по умолчанию. 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
}applycredit
Оплатить счёт с баланса
Финансовая операцияПрименяет кредитный баланс к указанному счёту. У метода нет отдельного параметра суммы.
Это списание денег. До вызова отдельно подтвердите точный счёт и сумму, проверьте принадлежность, статус и остаток баланса. Не повторяйте запрос при неизвестном результате или для уже оплаченного счёта; проверьте оплату в кабинете.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
invoiceidОбязательный | integer | ID вашего неоплаченного счёта. Номер и сумму необходимо проверить до оплаты. |
Запрос и ответ
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"
}add_typecancel
Запросить отмену
Изменяет настройкиСоздаёт запрос отмены для прокси-услуги. Для новой интеграции используйте этот метод вместо set_type_cancel.
Запрос отмены и фактическое отключение — разные события. Проверьте статус услуги; запрос не означает возврат средств.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
typeНеобязательный | string | End 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"
}terminate_typecancel
Отозвать запрос отмены
Изменяет настройкиУдаляет существующий запрос отмены услуги. Если запрос не найден, возможен ответ с ошибкой.
Не восстанавливает уже удалённую услугу и не выполняет возврат денег.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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"
}del_ips_from_service
Удалить часть IP
Удаляет ресурсыУдаляет выбранные прокси и возвращает оставшийся список в ips_list. Пересчитывает стоимость дальнейшего продления.
Выбранные IP перестанут работать. Для удаления всех IP нужен terminate_service. Автоматическая компенсация за неиспользованный период этим методом не предусмотрена.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
ips_for_delОбязательный | string | IPv4 через запятую. Все адреса должны принадлежать услуге; удалить все 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"
}terminate_service
Отключить прокси-услугу
Удаляет ресурсыВызывает немедленное отключение ресурсов услуги. Для плановой отмены используйте add_typecancel.
Прокси перестанут работать. Проверяйте результат отдельно; операция не является автоматической компенсацией или возвратом средств.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
Запрос и ответ
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"
}set_type_cancel
Старый запрос отмены
СовместимостьОставлен для совместимости. Для нового кода используйте add_typecancel.
В старой справке поле названо typecancel, но установленный обработчик читает type. Семантику отмены через этот старый маршрут согласуйте с поддержкой; не используйте его для новых сценариев.
Дополнительные параметры
| Параметр | Тип | Описание |
|---|---|---|
serviceidОбязательный | integer | ID принадлежащей вам прокси-услуги. |
typeНеобязательный | string | End 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 и проверяйте статус услуги после запроса.
Ответы и ошибки
HTTP 200 сам по себе не подтверждает успех операции. Обычный ответ: code = 2001 и status = successful. Методы модуля могут возвращать result = success. При result = error читайте message; при status = error — mess. Код и ID могут приходить строками или числами.
При таймауте изменяющего запроса сначала проверьте фактический результат. Автоматический повтор может создать вторую услугу или повторить финансовую операцию. У этого API нет документированного ключа идемпотентности.
| code | Описание |
|---|---|
1000 | Некорректный IPv4 или ошибка конкретной операции; смотрите mess. |
1001 | Не прошла проверка hash. Проверьте ключ и ID клиента. |
1002 | IP отправителя не входит в разрешённые IP ключа. |
1003 | Неверный userid/serviceid или услуга недоступна этому клиенту. |
1004 | Некорректный или неизвестный запрос. |
1005 | Некорректное количество прокси. |
1006 | Недостаточно средств для операции. |
1007 | Ошибка создания заказа. Перед повтором проверьте, не появилась ли услуга. |
1008 | Общая ошибка операции. Уточните результат перед повтором. |
1009 | Не указан или неверен serviceid. |
1010 | IP услуги не найдены; возможно, она уже отключена. |
1011 | Ключ имеет статус read_only: разрешены только операции чтения. |
1012 | Прокси-услуга не найдена. |
1013 | Тариф не поддерживает запрошенное ручное продление. |
1014 | Не передан список удаляемых IP. |
1015 | В списке удаления есть некорректный IPv4. |
1016 | IP не принадлежат услуге либо операция удаления отклонена. |
1017 | Запрошено удаление всех IP либо произошла ошибка удаления. |
1018 | Ключ приостановлен, доступ к API запрещён. |
1019 | Не указан или неверен invoiceid. |
1020 | Счёт уже оплачен либо отсутствует ips_access_list. В старом обработчике код используется повторно — проверяйте mess. |
Доступ и условия
Стоимость прокси и условия партнёрского доступа зависят от подключённого тарифа. Уточните их в поддержке перед автоматизацией заказов. Создание ключа не гарантирует индивидуальную цену.