Статичные прокси для ваших клиентов: покупка, продление и подключение UDP.
Получите ключ в боте Proxy Soxy → «Управление прокси». Проверьте доступ, запросите ассортимент и цену, подтвердите покупку и получите реквизиты. Основной контракт — /v1/me/static/*: покупки списываются с вашего баланса Proxy Soxy после отдельного разрешения. Розничную цену и оплату ваших покупателей вы организуете самостоятельно.
Сейчас расходные операции этого контракта доступны для аккаунтов RU с балансом RUB. Английская документация и Accept-Language: en не включают оплату в USD. Статичный UDP можно купить вместе с прокси или отдельно. Ротационный трафик не продаётся через эти методы.
Все суммы — целые числа в минимальных единицах валюты: 1500 = 15,00 RUB. Примеры не являются прайсом. Сохраняйте operation_id и считайте выдачу завершённой только при state=COMPLETED. Неизвестные поля ответа можно игнорировать, идентификаторы храните без изменения.
От ключа до результата
Откройте бот Proxy Soxy → «Управление прокси» → «Помощь» → «API и интеграции» → «Общий API» → «Создать ключ». Сохраните секрет на сервере интеграции. При повторном входе виден идентификатор ключа, а не сам секрет.
Выполните GET https://api.soxydata.com/v1/whoami с Authorization: Bearer <ключ>. Для этого ключа ожидаются role: "client", environment: "live", sandbox: null.
На том же экране ключа нажмите «Разрешить покупки…» и подтвердите разрешение покупать с баланса Proxy Soxy. Это отдельное действие: выпуск ключа сам по себе не разрешает списания. Пополняйте баланс привычным способом в боте.
Прочитайте /me/static/catalog и /me/static/balance. Выберите страну, срок и количество из текущего каталога. Запросите котировку /me/static/quotes и покажите её итог покупателю.
Сохраните quote_id и свой неизменный Idempotency-Key, затем вызовите /me/static/confirm. Это шаг покупки. Сохраните полученный operation_id вида op-….
Дождитесь state: "COMPLETED". Получите /me/static/proxies с тем же customer_ref, если он был в покупке, и выберите proxy_ids операции. При неизвестном результате сверяйте эту же операцию — не покупайте заново.
Сейчас покупки, продления и UDP через этот контракт доступны для RU-аккаунта с балансом RUB. EN-текст и Accept-Language: en не меняют валюту. Запрос без UDP работает как прежде. Отдельной публичной песочницы с виртуальными деньгами нет.
Для покупок используйте RU-бот и ключ его аккаунта. В EN-боте выпуск ключа и чтение доступов доступны, но кнопка разрешения расходов не показывается: новый расходный контракт USD закрыт. Язык экрана определяется ботом; разрешение расходов включается русской кнопкой в RU-боте.
Безопасная первая проверка
Эти примеры выполняют только GET: проверку ключа, чтение каталога и баланса. Для двух последних сначала включите разрешение покупок. Они не покупают, не продлевают и не печатают реквизиты.
# 1. Проверка обычного ключа из бота.
: "${API_KEY:?Set API_KEY in your server environment}"
BASE="https://api.soxydata.com/v1"
curl --fail-with-body --max-time 30 -sS "$BASE/whoami" -H "Authorization: Bearer $API_KEY"
# 2. Каталог — после разрешения покупок через API.
curl --fail-with-body --max-time 30 -sS "$BASE/me/static/catalog" -H "Authorization: Bearer $API_KEY"
# 3. Чтение баланса; без покупки.
curl --fail-with-body --max-time 30 -sS "$BASE/me/static/balance" -H "Authorization: Bearer $API_KEY"
<?php
// PHP 7.4+ с расширением curl.
$key = getenv('API_KEY');
if (!$key) throw new RuntimeException('Set API_KEY on your server');
function getApi(string $path): array {
global $key;
$ch = curl_init('https://api.soxydata.com/v1' . $path);
curl_setopt_array($ch, [CURLOPT_HTTPHEADER=>["Authorization: Bearer $key"],
CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>30, CURLOPT_FOLLOWLOCATION=>false]);
$raw = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($raw === false || $code !== 200) throw new RuntimeException("API HTTP $code");
return json_decode($raw, true);
}
// 1. Проверка обычного ключа из бота.
echo json_encode(getApi('/whoami')), "\n";
// 2. Каталог — после разрешения покупок через API.
echo json_encode(getApi('/me/static/catalog')), "\n";
// 3. Чтение баланса; без покупки.
echo json_encode(getApi('/me/static/balance')), "\n";
// Node.js 18+ (встроенный fetch). Ключ и адрес — из окружения или из констант ниже.
const BASE = 'https://api.soxydata.com/v1';
const KEY = process.env.API_KEY;
if (!KEY) throw Error('Set API_KEY on your server');
async function get(path) {
const r = await fetch(BASE + path, {redirect:'error', signal:AbortSignal.timeout(30000),
headers:{Authorization:`Bearer ${KEY}`}});
const data = await r.json();
if (!r.ok) throw Error(`${r.status} ${data.error?.code || 'request_failed'}`);
return data;
}
(async () => {
// 1. Проверка обычного ключа из бота.
console.log(await get('/whoami'));
// 2. Каталог — после разрешения покупок через API.
console.log(await get('/me/static/catalog'));
// 3. Чтение баланса; без покупки.
console.log(await get('/me/static/balance'));
})().catch(e => { console.error(e.message); process.exitCode=1; });
# Python 3.8+, только стандартная библиотека.
import json, os, urllib.request, urllib.error
BASE = "https://api.soxydata.com/v1"
KEY = os.environ["API_KEY"]
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, *args):
raise RuntimeError("redirect refused")
opener = urllib.request.build_opener(NoRedirect())
def get(path):
req = urllib.request.Request(BASE + path, headers={"Authorization":"Bearer " + KEY})
try:
with opener.open(req, timeout=30) as r:
return json.load(r)
except urllib.error.HTTPError as e:
raise RuntimeError("API HTTP " + str(e.code)) from None
# 1. Проверка обычного ключа из бота.
print(json.dumps(get("/whoami")))
# 2. Каталог — после разрешения покупок через API.
print(json.dumps(get("/me/static/catalog")))
# 3. Чтение баланса; без покупки.
print(json.dumps(get("/me/static/balance")))
Рассчитать и купить
Все значения ниже — пример. Страну, срок и количество возьмите из своего каталога. customer_ref задаётся вашим сервером; это не Telegram ID.
POST /v1/me/static/quotes
Authorization: Bearer <API-ключ>
Content-Type: application/json
{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42"}
Котировка вернёт quote_id, amount_minor, currency, expires_at. Сумма в копейках; срок действия — 120 секунд. Не передавайте собственную закупочную цену. Котировка не резервирует прокси.
POST /v1/me/static/confirm
Authorization: Bearer <API-ключ>
Content-Type: application/json
Idempotency-Key: shop-order-42-purchase-v1
{"quote_id":"q-11111111111111111111111111111111"}
Подставьте настоящий quote_id. Повтор после потери ответа — тот же URL, тот же ключ идемпотентности и тот же quote_id. HTTP 200 может содержать незавершённый статус.
GET /v1/me/static/operations/op-22222222222222222222222222222222
Authorization: Bearer <API-ключ>
GET /v1/me/static/proxies?customer_ref=buyer-42
Authorization: Bearer <API-ключ>
host:port:login:password использует HTTP-порт из ответа. Для SOCKS5 — тот же host, порт 1081 и те же реквизиты. Пароли можно прочитать повторно с авторизованным ключом. Не публикуйте их в логах или уведомлениях.
Ключ, права и лимиты
Ключ обычного реселлера выпускается самостоятельно: бот Proxy Soxy → «Управление прокси» → «Помощь» → «API и интеграции» → «Общий API» → «Создать ключ». Под сообщением с выданными прокси в EN-боте кнопка называется “My proxies”; далее Help → API & integrations → General API → Create key.
Секрет psx_live_… показывается один раз. При следующем открытии доступны идентификатор, дата выпуска, «Перевыпустить» / “Replace key” и «Отозвать» / “Revoke”. Перевыпуск отзывает прежний обычный ключ, поэтому обновите его во всех своих интеграциях и Connect. Отозванный ключ не работает; история операций остаётся. Получить потерянный секрет повторно нельзя.
Разрешение покупок через API: на экране ключа нажмите «Разрешить покупки…», затем подтвердите списания с баланса Proxy Soxy. Без этого /me/static/* может отвечать 403 с просьбой включить API в экране ключа. «Запретить покупки» запрещает новые списания, не отзывая ключ и не отключая его обычные чтения и Connect. Новому ключу после перевыпуска нужно новое разрешение. Исполнение уже оплаченной операции проверяется отдельно; неизвестную оплату не повторяйте.
Передавайте ключ только в заголовке Authorization: Bearer … по HTTPS. Не передавайте его браузеру, покупателю реселлера, в URL или журнал. whoami проверяет ключ, но не возвращает его секрет и не является проверкой согласия на расходы.
Для покупок используйте RU-бот и ключ его аккаунта. В EN-боте выпуск ключа и чтение доступов доступны, но кнопка разрешения расходов не показывается: новый расходный контракт USD закрыт. Язык экрана определяется ботом; разрешение расходов включается русской кнопкой в RU-боте.
Боевой и тестовый ключ
В текущем интерфейсе выпускается обычный ключ psx_live_… с ролью client. Кнопки получения psx_test_… и публичного денежного тестового стенда нет. Поддержка environment: test в старом организационном контракте не означает, что её можно включить у ключа из бота. /me/static/* не принимает такой ключ как виртуальный кошелёк. Для проверки без расходов используйте чтения, котировки и собственные тесты интеграции; confirm на рабочем API может списать реальные деньги.
Действующие ограничения
Группа
Лимит на ключ
Обычные GET, включая /me/static/*
120 за 60 секунд
POST /me/static/*
30 за 60 секунд
Выбор доступов в одной операции
до 100; дополнительно действуют границы конкретного товара
Connect: создание сессии
10 за минуту
Connect: опрос прокси
120 за час, включая 304
Дополнительные проверки ёмкости и объёма партии применяются до исполнения. При 429 соблюдайте Retry-After и значения details.limit / details.window_sec, если они присутствуют. Не опрашивайте результат в тесном цикле.
Покупки, продление, UDP и история
Владельцы и покупатели
Ваш ключ связан с вашим аккаунтом и закупочным балансом Proxy Soxy. customer_ref — ваш стабильный идентификатор покупателя, от 1 до 64 символов A-Za-z0-9._@+-. Он изолирован внутри вашего аккаунта. Это не Telegram ID и не адрес получателя уведомления.
Без customer_ref покупка предназначена самому плательщику. С ним доступы принадлежат выбранному покупателю реселлера. Для чтения, продления и UDP передавайте тот же customer_ref. Нельзя объединять доступы разных покупателей в одном выборе. Ключом другого аккаунта нельзя прочитать чужую операцию или реквизиты.
Цена, валюта и сроки
Пополнение баланса остаётся обычным действием в боте Proxy Soxy; API-метода пополнения в этом контракте нет. Покупки через API и обычные покупки используют один баланс. Вашу розничную наценку API не рассчитывает.
/catalog возвращает текущие товары, допустимые сроки и количества. Котировка даёт точную сумму. При изменении цены или выбранных доступов исполнение не подставляет неожиданную новую сумму: запрос отклоняется или операция остаётся для сверки. После списания проверяйте её статус.
Активный купон не применяется молча: 409 с details.reason: active_coupon_requires_bot_checkout предлагает завершить купонную покупку в боте. Неоднозначная цена или непроверенная скидка также блокирует расчёт/списание. Параметров собственного курса, валюты, купона или скидки у котировки нет.
Срок обычного продления считается по правилам доступа: от более позднего из текущего окончания и момента продления. Освобождённый доступ продлить нельзя. Не рассчитывайте возможность продления по старому обещанию «три дня»: решающим является фактическое состояние доступа. UDP не продлевает основной прокси.
Оба тела отправляются в POST /v1/me/static/quotes, затем котировка подтверждается через /confirm с отдельным стабильным ключом идемпотентности. order_id означает исходную завершённую API-покупку. Вместо него можно выбрать proxy_ids, но не оба поля одновременно. Для смены пароля не передавайте days или собственный пароль; новый пароль создаёт сервер. Читайте результат и реквизиты заново.
Запросите /quotes. В ответе: proxy_amount_minor — прокси, udp_amount_minor — UDP, amount_minor — итог, currency, expires_at. Затем /confirm: одна операция и одно списание. Она становится COMPLETED только после сохранения и прокси, и всех UDP-прав. Без udp или с udp:false покупка обычная.
После /quotes подтвердите /confirm с новым ключом, например shop-order-42-udp-v1. Для UDP-докупки не передаются country, count и days: они определяются по доступам. proxy_amount_minor=0; udp.lines содержит сроки и цену по каждому доступу. На стадии выбора проверяются владелец, активность, совместимость, оплаченный срок и существующее право.
Цена UDP: сейчас 15 ₽ за доступ на 30 суток, пропорционально непокрытым секундам, с округлением каждой строки вверх до копейки. Итог берите из котировки, а не из локальной формулы. connect подключает отсутствующее или истёкшее право к действующему прокси. Уже активное UDP повторно не покупается. После отдельного продления прокси запросите udp_mode: "extend", чтобы покрыть оставшийся срок: только если есть действующее UDP-право и непокрытый промежуток. Сам основной срок не изменяется.
Прочитайте /me/static/proxies: udp.state, udp.until, udp.operation_id. active означает подтверждённое действующее право; expired, suspended, not_connected, unknown различаются. Неизвестное право нельзя считать включённым. UDP работает через SOCKS5 UDP ASSOCIATE на том же логине, не через HTTP-прокси; клиентская программа должна поддерживать этот протокол.
Частичный результат и восстановление
У покупки «прокси + UDP» core_proxy_ids может показывать уже созданные прокси, пока UDP ещё не подтверждён. items содержит результат по доступам. Это не завершённый комплект: ожидайте COMPLETED. При APPLYING, PAID_HELD, DEBIT_UNKNOWN или MANUAL_REVIEW сохраняйте исходный op-… и выполняйте штатную сверку. Не создавайте заменяющую покупку и не возвращайте деньги автоматически.
История и уведомления
В «Управление прокси» → «История покупок» API-покупки, продления и UDP отображаются с отметкой API и исходным op-…. Карточка и экспорт открываются после авторизации. Поддержка ищет op-…, ID плательщика, связанный доступ или строку прокси. API-операция не получает выдуманного номера обычной покупки бота.
После COMPLETED плательщик получает сообщение в связанном боте Proxy Soxy: операция, страна, количество, срок, сумма и кнопка покупки. Для прокси с UDP — одно итоговое сообщение, для докупки — отдельное с привязкой к исходным доступам. Операторы получают сообщение в настроенном канале без секретов. Отправка выполняется непосредственно через API Telegram; это уведомление, а не создание дополнительной покупки. Конечным покупателям реселлера сообщения не отправляются.
В истории переключатель «Уведомления API» отключает сообщения плательщику без отключения покупок. Сбой доставки не отменяет оплату или выдачу. /operations/{operationId}/notifications показывает статусы. Ручной /notifications/retry предназначен только для явно отклонённой доставки плательщику; он не повторяет покупку. UNKNOWN не рассылается вслепую. Старые операции доступны в истории без массовой отправки старых сообщений.
Методы
Основной сценарий реселлера использует ключ client из бота и /me/static/*. Далее приведены отдельные контракты Connect и организационного /orders; не смешивайте их поля, деньги и идентификаторы.
Все URL ниже относительно https://api.soxydata.com/v1. Для POST отправляйте Content-Type: application/json. Неизвестные поля котировки и неподдерживаемые query-параметры отклоняются. operation_id вида op-… — канонический номер API-операции; proxy_id — отдельный доступ; psx-… относится к старому организационному заказу.
GET/v1/whoami
Проверить ключ
Обычный ключ из бота: role=client, environment=live, sandbox=null, customer_id. Ответ не содержит секрет ключа и не подтверждает разрешение расходов.
Пример вызова
curl -X GET https://api.soxydata.com/v1/whoami \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
GET/v1/me/proxies
Собственные прокси и реквизиты
Ключ client. Возвращает пароль при каждом авторизованном чтении. Только собственные доступы; для customer_ref используйте /me/static/proxies. ETag / If-None-Match: 304 при отсутствии изменений.
Пример вызова
curl -X GET https://api.soxydata.com/v1/me/proxies \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/me/connect/session
Открыть сессию ProxyData Connect
Отдельный контракт приложения Connect. Не покупает прокси. Возвращает токен, список узлов, реквизиты и connect.allowed. Используйте token_expires_in, refresh_after и poll_after из ответа. Не передавайте токен третьим лицам.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
GET/v1/me/static/catalog
Ассортимент и текущие цены
Страны, сроки, товары, цены и ограничения количества. Каталог не резервирует наличие или цену; окончательную сумму вернёт quote. Нужна серверная привязка ключа, создаваемая при разрешении расходов.
Пример вызова
curl -X GET https://api.soxydata.com/v1/me/static/catalog \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/me/static/balance
Баланс Proxy Soxy
Тот же закупочный баланс, что в вашем аккаунте Proxy Soxy. balance_minor — копейки при currency=RUB. wallet — совместимое техническое значение, не отдельный кошелёк.
Пример вызова
curl -X GET https://api.soxydata.com/v1/me/static/balance \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/me/static/proxies
Реквизиты и UDP-право
Без customer_ref — собственные доступы плательщика. С customer_ref — только этот покупатель в области вашего аккаунта. Пароли возвращаются при каждом авторизованном чтении. port — HTTP; SOCKS5 использует тот же host и реквизиты, порт 1081. UDP требует SOCKS5 UDP ASSOCIATE и действующего udp.state=active.
Параметры
Имя
Где
Тип
Описание
customer_ref
query
string
Пример вызова
curl -X GET https://api.soxydata.com/v1/me/static/proxies \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/quotes
Рассчитать покупку, продление или UDP
Не списывает деньги и не выдаёт прокси. Срок котировки 120 секунд. Требует разрешения покупок. purchase: country/count/days, необязательно udp=true. renew: days + выбор доступов. credentials или udp: выбор, без days. Для udp режим connect по умолчанию, extend для доплаты до отдельно продлённого основного срока.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/confirm
Подтвердить котировку
Расходная операция. Сохраните quote_id и Idempotency-Key заранее. Повтор того же ключа и quote_id возвращает эту же операцию. HTTP 200 не означает COMPLETED. Цена и доступность проверяются до списания.
Работает с исходным operation_id. Может завершить подтверждённую оплатой выдачу, не создавая нового списания. Неподтверждённая оплата остаётся неизвестной. Для продолжения исполнения может потребоваться действующее разрешение расходов. Это не простой GET и не запрос возврата.
Только явно отклонённая FAILED-доставка при включённых уведомлениях, не более четырёх попыток суммарно. UNKNOWN и старые NOT_QUEUED автоматически не повторяются. Оплата и выдача не выполняются.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/webhook
Настроить вебхук
Публичный HTTPS URL, порт 443, без redirects. url=null отключает доставку. При установке возвращается новый secret один раз. Нужны права покупок; храните секрет на сервере.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/stock
Склад старого контракта
Отдельный /orders-контракт: addresses — число выходных IP, max_batch — предел партии, quota — доступная квота. Не заменяет ассортимент, цену или баланс /me/static.
Пример вызова
curl -X GET https://api.soxydata.com/v1/stock \
-H "Authorization: Bearer $API_KEY"
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/orders
Создать организационный заказ
Только организационный ключ partner/reseller; обычный ключ client получает 403. Отдельные расчёты и условия, не баланс /me/static. Ответ возвращает реквизиты.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/orders/{orderId}/renew
Продлить организационный заказ
Только организационный ключ. Продлевает существующие доступы по условиям этого контракта. После освобождения доступа продление невозможно. Не применяйте этот метод к op-…; используйте quote kind=renew.
{
"error": {
"code": "idempotency_conflict",
"message": "this Idempotency-Key was already used for a different request",
"details": {
"reason": "different_request",
"request_id": "req-0bteryb170cjg33c"
}
}
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/orders/{orderId}/credentials
Сменить пароль организационного заказа
Только организационный ключ. Меняет пароль выбранного заказа; ответ содержит новые реквизиты. Для /me/static используйте kind=credentials и выбор доступов.
{
"error": {
"code": "order_expired",
"message": "the order term and its grace period are over; renew it or create a new order",
"details": {
"proxies": [
"bott-3ogk4i5qfjwm"
],
"request_id": "req-0bteryb170cjg33c"
}
}
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
Схемы
WhoAmI
Поле
Тип
Описание
partner_id*
string
пример: "prt-example"
role*
string: partner | reseller | client
environment*
string: live | test
sandbox*
object | null
Для обычного ключа live — null. Поле test относится к отдельному старому контракту; самостоятельного выпуска тестового ключа и виртуальной оплаты в боте нет.
пример: null
Поле
Тип
Описание
proxies_max
integer
пример: 5
days
array of integer
пример: [7]
rate_limits
object
customer_id
string | null
пример: "cus-example"
api_version*
string
пример: "v1"
CountryCode
string
OrderId
string
Proxy
Прокси отдельного /orders-контракта. Пароль есть при создании/смене, но отсутствует в GET /orders/{id}. Это не ограничение /me/static/proxies.
Поле
Тип
Описание
proxy_id*
string
пример: "bott-3ogk4i5qfjwm"
host*
string
пример: "gate1024.psnode.me"
port*
integer
пример: 3130
ip*
string
пример: "192.0.2.10"
country*
CountryCode
пример: "DE"
login*
string
пример: "<proxy-login>"
password
string
пример: "<proxy-password>"
Order
Поле
Тип
Описание
id*
OrderId
пример: "psx-7fa2c9d14b03"
status*
string: active | expired
country*
CountryCode
пример: "DE"
count*
integer
days*
integer
created_at*
string
expires_at*
string
customer_id*
string
пример: "cus-4b81e0a2"
customer_ref
string
пример: "site-user-88412"
country_name*
string
пример: "Germany"
days_left
integer
пример: 24
active_count
integer
price_minor
integer
пример: 17500
currency
string
пример: "RUB"
proxies
array of Proxy
OrderWithPassword
Поле
Тип
Описание
id*
OrderId
пример: "psx-7fa2c9d14b03"
status*
string: active | expired
country*
CountryCode
пример: "DE"
count*
integer
days*
integer
created_at*
string
expires_at*
string
customer_id*
string
пример: "cus-4b81e0a2"
customer_ref
string
пример: "site-user-88412"
country_name*
string
пример: "Germany"
days_left
integer
пример: 24
active_count
integer
price_minor
integer
пример: 17500
currency
string
пример: "RUB"
proxies
array of Proxy
CreateOrderRequest
Поле
Тип
Описание
country*
CountryCode
пример: "DE"
count*
integer
days*
integer: 7 | 30 | 90
customer_ref*
string
password
string
пример: "<proxy-password>"
CreateOrderResponse
Поле
Тип
Описание
order*
OrderWithPassword
balance_minor_after
integer | null
OrderList
Поле
Тип
Описание
orders*
array of Order
next_cursor*
string | null
ClientProxy
Поле
Тип
Описание
proxy_id*
string
пример: "bott-tduaqez1ldye"
host*
string
пример: "gate.example.invalid"
port*
integer
Порт HTTP. SOCKS5: тот же host, порт 1081.
пример: 3130
login*
string
пример: "<proxy-login>"
password*
string
Доступен владельцу при каждом авторизованном чтении. Храните как секрет.
пример: "<proxy-password>"
country*
CountryCode
пример: "DE"
country_name*
string
пример: "Germany"
ip*
string
пример: "192.0.2.10"
expires*
integer
пример: 1794720000
expires_at*
string
active*
boolean
purchase*
string
Идентификатор группировки. Для API используйте канонический operation_id из истории и proxy_ids для сопоставления.
пример: "group-example"
ClientProxies
Поле
Тип
Описание
proxies*
array of ClientProxy
count*
integer
пример: 3
etag*
string
пример: "\"a1b2c3d4e5f60718293a\""
ConnectState
Поле
Тип
Описание
allowed*
boolean
пример: true
until*
integer | null
ConnectNode
Поле
Тип
Описание
ip*
string
пример: "192.0.2.10"
port*
integer
пример: 443
sni*
string
пример: "soxy-entry"
transport*
string: mtls | mwss
path
string
пример: "/ws"
ConnectSession
Поле
Тип
Описание
acct*
string
пример: "acct-bp2xznodclu0"
connect*
ConnectState
tunnel*
object
Поле
Тип
Описание
username*
string
пример: "acct-bp2xznodclu0"
token*
string
пример: "pdt_c3f1…"
token_expires_in*
integer
пример: 21600
refresh_after*
integer
пример: 10800
nodes*
array of ConnectNode
gateway*
string
пример: "192.0.2.10:3130"
proxies*
array of ClientProxy
etag*
string
пример: "\"a1b2c3d4e5f60718293a\""
poll_after*
integer
пример: 60
ConnectProxies
Поле
Тип
Описание
connect*
ConnectState
proxies*
array of ClientProxy
etag*
string
пример: "\"d4e5f6a7b8c90a1b2c3d\""
poll_after*
integer
пример: 60
Stock
Поле
Тип
Описание
countries*
array of object
Поле
Тип
Описание
code*
CountryCode
пример: "DE"
name*
string
пример: "Germany"
addresses*
integer
пример: 69
max_batch*
integer
пример: 100
quota*
object
Поле
Тип
Описание
scope*
string: partner | test_key
пример: "partner"
proxies_max*
integer | null
пример: 3000
proxies_live*
integer
пример: 120
proxies_pending*
integer
пример: 0
proxies_available*
integer | null
пример: 2880
next_free_at*
string | null
generated_at*
string
RenewRequest
Поле
Тип
Описание
days*
integer: 7 | 30 | 90
RenewResponse
Поле
Тип
Описание
order*
Order
renewal*
object
Поле
Тип
Описание
days*
integer
пример: 30
count*
integer
пример: 5
price_minor*
integer
пример: 15750
balance_minor_after
integer | null
CredentialsRequest
Поле
Тип
Описание
password
string
пример: "<proxy-password>"
CredentialsResponse
Поле
Тип
Описание
order*
OrderWithPassword
WebhookEvent
Отдельный формат старого /orders-контракта. Не используйте его вместо StaticEvent.
purchase: country/count/days; renew: days и ровно один из order_id/proxy_ids; credentials/udp: выбор без days. udp=true только для purchase. customer_ref должен совпадать с исходной покупкой.
Поле
Тип
Описание
kind*
any: purchase | renew | credentials | udp
udp
boolean
udp_mode
string: connect | extend
country
string
count
integer
days
integer
customer_ref
string
proxy_ids
array of string
order_id
string
operation_id завершённой исходной покупки, не номер заказа бота.
StaticQuote
Поле
Тип
Описание
quote_id*
string
proxy_amount_minor
integer
Стоимость прокси; возвращается для UDP-операции.
udp_amount_minor
integer
Стоимость UDP, включена в итог.
udp
object
Режим, цена и сроки UDP по доступам. lines[].order — идентификатор доступа; until/from/expires — Unix-секунды. Для новой покупки сроки появятся в items после выдачи.
Режим, цена и сроки UDP по доступам. lines[].order — идентификатор доступа; until/from/expires — Unix-секунды. Для новой покупки сроки появятся в items после выдачи.
amount_minor*
integer
Итог в копейках.
currency*
any: RUB
proxy_ids*
array of string
reason
string | null
needs_attention*
boolean
test_mode*
boolean
пример: false
items
array of object
kind
any: purchase | renew | credentials | udp
customer_ref
string | null
created_at
integer
updated_at
integer
core_proxy_ids
array of string
retry
string
UDPRight
Состояние оплаченного UDP-права. unknown — подтверждение недоступно, а не бесплатный доступ. until — Unix-секунды. operation_id=null у права, купленного вне API.
Поле
Тип
Описание
state*
any: not_connected | active | expired | suspended | unknown
until*
integer | null
operation_id*
string | null
StaticProxy
Поле
Тип
Описание
proxy_id*
string
пример: "bott-tduaqez1ldye"
host*
string
пример: "gate.example.invalid"
port*
integer
Порт HTTP. SOCKS5: тот же host, порт 1081.
пример: 3130
login*
string
пример: "<proxy-login>"
password*
string
Доступен владельцу при каждом авторизованном чтении. Храните как секрет.
пример: "<proxy-password>"
country*
CountryCode
пример: "DE"
country_name*
string
пример: "Germany"
ip*
string
пример: "192.0.2.10"
expires*
integer
пример: 1794720000
expires_at*
string
active*
boolean
purchase*
string
Идентификатор группировки. Для API используйте канонический operation_id из истории и proxy_ids для сопоставления.
пример: "group-example"
udp*
UDPRight
Состояние оплаченного UDP-права. unknown — подтверждение недоступно, а не бесплатный доступ. until — Unix-секунды. operation_id=null у права, купленного вне API.
StaticProxies
Поле
Тип
Описание
customer_ref*
string | null
proxies*
array of StaticProxy
StaticBalance
Поле
Тип
Описание
wallet*
string: BOT-T
Историческое значение внешнего поля. Означает ваш баланс Proxy Soxy; не другой кошелёк и не требование сторонней регистрации.
currency*
string: RUB | USD
Валюта привязанного аккаунта. Доступность чтения USD не означает разрешение расходных операций USD.
balance_minor*
integer
test_mode*
boolean
StaticOperationList
Поле
Тип
Описание
items*
array of StaticOperation
next_cursor*
integer | null
StaticEvent
Событие /me/static. data содержит operation_id/proxy_ids либо сведения об изменении доступа. Паролей нет. created_at — Unix-секунды.
Поле
Тип
Описание
event_id*
string
type*
string
пример: "order.issued"
created_at*
integer
data*
object
status
any: pending | delivered | dead
attempts
integer
StaticCatalogue
Используйте фактически возвращённые товары, сроки и границы количества. Состав дополнительных полей может расширяться.
Проверяйте HTTP-статус, error.code, details, а для созданной операции — её state и reason. Текст message может меняться. request_id, если он есть, помогает поддержке найти запрос. Не присылайте ключи и пароли.
HTTP
code
Что значит
Что делать
400
invalid_request
Неподдерживаемые поля, формат или выбор.
Исправьте запрос. Не повторяйте неизменённый отказ.
401
unauthorized
Нет действующего ключа.
Проверьте Bearer; при потере ключа перевыпустите его в боте.
403
forbidden
Неверная роль, нет разрешения расходов или операция недоступна аккаунту.
Проверьте whoami, экран ключа и RU/RUB. Не обходите ограничения.
404
not_found
Объект отсутствует либо не принадлежит выбранному аккаунту.
Проверьте op-…, proxy_ids и customer_ref.
409
idempotency_conflict
Конфликт операции, котировки, цены, права или удержанной незавершённой покупки.
Читайте reason и исходную операцию. Новый ключ не исправляет неизвестную оплату.
409
out_of_stock
Подходящие ресурсы недоступны.
До списания можно выбрать другой товар; после начала операции сначала проверьте её исход.
409
quota_exceeded
Недостаточно квоты ёмкости.
Проверьте пределы и состояние операции; не уменьшайте защиту повторов.
409
order_expired
Состояние или срок доступа запрещает выбранное действие.
Проверьте возможность продления; освобождённый доступ не восстанавливается сменой пароля.
402
insufficient_balance
Проверенный доступный баланс меньше нужной суммы.
Пополните баланс Proxy Soxy. Перед новой попыткой проверьте исход прежней операции.
429
rate_limited
Превышен лимит вызовов или выбранных единиц; смотрите details.
Соблюдайте Retry-After; не меняйте ключ идемпотентности.
500
internal
Запрос не завершился штатным ответом; финансовый исход может быть неизвестен.
Читайте и сверяйте исходный op-… без новой покупки.
Для UDP отказ возможен до списания: чужой/истёкший доступ, активная опция при connect, отсутствие действующего права или промежутка при extend, несовместимый продукт, изменённый срок/цена/право, недоступный маршрут, запрет расходов или нехватка баланса. Точный машинный reason, когда он предоставлен, сохраняйте. Не заменяйте все эти случаи сообщением «не хватает денег».
После таймаута, 5xx или частичного результата нельзя заключать «ничего не списано». Прочитайте исходную операцию и сверяйте её без новой покупки. COMPLETED — единственный окончательный успех выдачи. Общего API автоматического возврата этот контракт не предоставляет.
Идемпотентность и неизвестный результат
Основной контракт /me/static
Для POST /me/static/confirm обязателен Idempotency-Key: 8–128 символов A-Za-z0-9._-. Двоеточие здесь не допускается. Сохраните его вместе с quote_id до отправки. Один ключ — одна логическая операция в области плательщика; не используйте новый ключ для восстановления неизвестного результата.
Повтор с тем же quote_id возвращает исходную операцию и может продолжить её безопасное исполнение. Это актуальное состояние, не обещание побайтового повтора первого HTTP-ответа. Тот же ключ с другой котировкой — 409 idempotency_conflict. Завершённая операция не списывается и не выдаётся повторно. Канонический журнал не имеет автоматического 30-дневного срока удаления; сохраняйте номер у себя.
Если ответ confirm потерян до получения operation_id, повторите тот же confirm. Если номер известен — сначала GET /operations/{operationId}, затем при необходимости POST /operations/{operationId}/reconcile с {}. Сверка может завершить уже оплаченную выдачу, поэтому это не простое чтение. Не меняйте ключ, не создавайте новый quote для той же неизвестной оплаты, не определяйте оплату по одному уменьшению баланса.
state
Значение и действие
CREATED, PREFLIGHT
Подготовка; повтор/сверка исходной операции
DEBIT_PENDING, DEBIT_UNKNOWN
Ответ о списании ещё не подтверждён; сверять, не платить снова
PAID
Оплата подтверждена, исполнение ещё не завершено
PAID_HELD
Оплата есть, выдача удержана проверкой; сохранить ID, проверить причину и права
APPLYING
Исполнение или его результат ещё сверяется
COMPLETED
Все выбранные результаты подтверждены; можно выдавать реквизиты
DECLINED
Операция отклонена; проверьте reason, перед новой покупкой убедитесь в известном исходе
MANUAL_REVIEW
Частичный/неподтверждённый результат требует разбора; не повторять оплату
items описывает доступы по отдельности; наличие одного успешного элемента не означает успех всей покупки. Ошибка уведомления не меняет state покупки.
Отдельный /orders-контракт
У старых организационных POST другой формат: 1–64 символа A-Za-z0-9_.:-, включая двоеточие. Завершённый HTTP-ответ сохраняется 30 суток; повтор может иметь Idempotency-Replayed: true. details.reason: different_request и in_progress относятся к этому контракту. Не переносите его сроки и правила заголовков на /me/static/confirm.
События и вебхуки /me/static
Настройте свой публичный HTTPS-приёмник через POST /v1/me/static/webhook с {"url":"https://shop.example/webhooks/proxy-soxy"}. Ответ содержит новый secret один раз. Повторная настройка заменяет секрет; {"url":null} отключает доставку. Не используйте внутренние адреса, нестандартный порт или перенаправление.
События: order.issued, order.renewed, order.udp_connected, order.connection_changed, order.availability_changed, order.expiring, order.expired. Некоторые изменения наблюдаются периодически: мгновенная доставка и обнаружение каждого краткого перехода не гарантируются. order.refunded не объявляется работающим событием этого контракта.
Для изменений доступа data может содержать proxy_id, адрес и срок вместо operation_id. Паролей нет. За реквизитами обращайтесь авторизованным GET, не ждите Telegram или вебхук для определения успешности покупки.
Подпись и дубли
Заголовок X-Soxy-Signature: t=<unix>,v1=<hex> — HMAC-SHA256 секретом по <t>.<сырое UTF-8 тело>. Проверяйте подпись в постоянном времени до обработки JSON и допустимое отклонение времени, например 5 минут в обе стороны. X-Soxy-Event-Id соответствует event_id. Сохраняйте обработанные event_id, отвечайте успешно на уже обработанный дубль.
<?php
// PHP: проверка подписи вебхука. Сырое тело — из php://input, ДО json_decode.
function verifySoxySignature(string $header, string $rawBody, string $secret, int $toleranceSec = 300): bool {
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', trim($header), $m)) return false; // формат не тот
$t = (int)$m[1];
if (abs(time() - $t) > $toleranceSec) return false; // просрочено
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
return hash_equals($expected, $m[2]); // постоянное время
}
$raw = file_get_contents('php://input');
if (!verifySoxySignature($_SERVER['HTTP_X_SOXY_SIGNATURE'] ?? '', $raw, $WEBHOOK_SECRET)) {
http_response_code(400); exit;
}
$event = json_decode($raw, true);
// дедуп по $event['event_id'], затем обработка; быстро ответить 200
http_response_code(200);
// Node.js: проверка подписи вебхука. Считайте СЫРОЕ тело до разбора JSON.
const crypto = require('crypto');
function verifySoxySignature(header, rawBody, secret, toleranceSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header || '').trim());
if (!m) return false; // формат не тот
const t = Number(m[1]);
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false; // просрочено
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(m[2], 'hex');
return expected.length === given.length && crypto.timingSafeEqual(expected, given);
}
// Express: сырое тело через express.raw, затем проверка, дедуп по event.event_id, обработка, ответ 200.
// app.post('/hook', express.raw({ type: '*/*' }), (req, res) => {
// if (!verifySoxySignature(req.headers['x-soxy-signature'], req.body.toString('utf8'), SECRET)) return res.status(400).end();
// const event = JSON.parse(req.body);
// res.status(200).end();
// });
module.exports = { verifySoxySignature };
Успех доставки — HTTP 2xx; redirects не поддерживаются. Ответьте быстро: обработчик ограничивает попытку примерно 8 секундами. До восьми попыток на цикл с задержкой; после этого статус dead. GET /events/{eventId} показывает попытки, POST /events/{eventId}/retry {} повторно ставит то же dead-событие. Вебхук может прийти несколько раз. Это повторы доставки, не новые покупки.
Старый организационный /orders использует другой формат data.order и свой способ настройки. Он описан отдельно; не смешивайте два формата.
Другие контракты и спецификация
Организационный /orders и prepaid
Это отдельный контракт для уже настроенных организационных ключей partner/reseller, не быстрый старт с ключом из бота. Он использует psx-…, /stock, /orders, продление и смену пароля всего заказа. Его лимиты и предоплаченные расчёты не означают доступ к балансу Proxy Soxy в /me/static. Обычный ключ client не может создавать и изменять такие организационные заказы; возможные чтения ограничены его собственными объектами.
GET /orders/{id} не возвращает пароль; создание и смена пароля возвращают его. Это ограничение старого метода, а не /me/proxies или /me/static/proxies. Старый формат событий — data.order, не data.operation_id. Наличие схемы тестового организационного ключа в спецификации не предоставляет пользователю такую учётную запись.
Connect
/me/connect/session и /me/connect/proxies обслуживают приложение ProxyData Connect. Они не покупают доступы и не заменяют котировку. Проверяйте connect.allowed и сроки из ответа; не считайте это безусловной бесплатной услугой. Ключ и токен Connect — секреты. Наличие UDP-права на прокси само по себе не подтверждает поддержку UDP конкретной версией клиентской программы.
Машиночитаемый контракт и примеры
OpenAPI RU · OpenAPI EN описывает установленные методы. Примеры чтения и SDK используют обычный ключ из бота; архив примеров. Примеры покупки требуют явного действия вашего приложения, а не запускаются при чтении документации. Внутри v1 ответ может получить дополнительные поля. Секреты в примерах заменены заполнителями.