ProxySoxyДокументация
Оглавление

Proxy Soxy Partner API

Статичные прокси для ваших клиентов: покупка, продление и подключение UDP.

Получите ключ в боте Proxy Soxy → «Управление прокси». Проверьте доступ, запросите ассортимент и цену, подтвердите покупку и получите реквизиты. Основной контракт — /v1/me/static/*: покупки списываются с вашего баланса Proxy Soxy после отдельного разрешения. Розничную цену и оплату ваших покупателей вы организуете самостоятельно.

Сейчас расходные операции этого контракта доступны для аккаунтов RU с балансом RUB. Английская документация и Accept-Language: en не включают оплату в USD. Статичный UDP можно купить вместе с прокси или отдельно. Ротационный трафик не продаётся через эти методы.

Все суммы — целые числа в минимальных единицах валюты: 1500 = 15,00 RUB. Примеры не являются прайсом. Сохраняйте operation_id и считайте выдачу завершённой только при state=COMPLETED. Неизвестные поля ответа можно игнорировать, идентификаторы храните без изменения.

От ключа до результата

  1. Откройте бот Proxy Soxy → «Управление прокси» → «Помощь» → «API и интеграции» → «Общий API» → «Создать ключ». Сохраните секрет на сервере интеграции. При повторном входе виден идентификатор ключа, а не сам секрет.
  2. Выполните GET https://api.soxydata.com/v1/whoami с Authorization: Bearer <ключ>. Для этого ключа ожидаются role: "client", environment: "live", sandbox: null.
  3. На том же экране ключа нажмите «Разрешить покупки…» и подтвердите разрешение покупать с баланса Proxy Soxy. Это отдельное действие: выпуск ключа сам по себе не разрешает списания. Пополняйте баланс привычным способом в боте.
  4. Прочитайте /me/static/catalog и /me/static/balance. Выберите страну, срок и количество из текущего каталога. Запросите котировку /me/static/quotes и покажите её итог покупателю.
  5. Сохраните quote_id и свой неизменный Idempotency-Key, затем вызовите /me/static/confirm. Это шаг покупки. Сохраните полученный operation_id вида op-….
  6. Дождитесь 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 не продлевает основной прокси.

Продлить или сменить пароль

{"kind":"renew","customer_ref":"buyer-42","order_id":"op-22222222222222222222222222222222","days":30}
{"kind":"credentials","customer_ref":"buyer-42","proxy_ids":["bott-example001","bott-example002"]}

Оба тела отправляются в POST /v1/me/static/quotes, затем котировка подтверждается через /confirm с отдельным стабильным ключом идемпотентности. order_id означает исходную завершённую API-покупку. Вместо него можно выбрать proxy_ids, но не оба поля одновременно. Для смены пароля не передавайте days или собственный пароль; новый пароль создаёт сервер. Читайте результат и реквизиты заново.

Купить прокси сразу с UDP

{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42","udp":true}

Запросите /quotes. В ответе: proxy_amount_minor — прокси, udp_amount_minor — UDP, amount_minor — итог, currency, expires_at. Затем /confirm: одна операция и одно списание. Она становится COMPLETED только после сохранения и прокси, и всех UDP-прав. Без udp или с udp:false покупка обычная.

Докупить UDP к нескольким доступам

{"kind":"udp","customer_ref":"buyer-42","proxy_ids":["bott-example001","bott-example002"],"udp_mode":"connect"}

Либо выберите всю исходную покупку:

{"kind":"udp","customer_ref":"buyer-42","order_id":"op-22222222222222222222222222222222"}

После /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"

Ответы

200Ответ; проверяйте состояние в теле

Схема: WhoAmI

401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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"

Ответы

200Ответ; проверяйте состояние в теле

Схема: ClientProxies

304Ошибка; проверяйте error.code и исходную операцию
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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 из ответа. Не передавайте токен третьим лицам.

Тело запроса (необязательно)

ПолеТипОписание
client_versionstring
пример: "1.1.0"
platformstring
пример: "windows"
instancestring

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/connect/session \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: ConnectSession

401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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/connect/proxies

Обновить список для Connect

Ключ client, действующее разрешение Connect. Поддерживает If-None-Match и 304.

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/connect/proxies \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: ConnectProxies

304Ошибка; проверяйте error.code и исходную операцию
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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"

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticCatalogue

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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"

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticBalance

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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_refquerystring

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/proxies \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticProxies

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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 для доплаты до отдельно продлённого основного срока.

Тело запроса

StaticQuoteInput

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/quotes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42"}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticQuote

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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. Цена и доступность проверяются до списания.

Параметры

ИмяГдеТипОписание
Idempotency-Key*headerstring

Тело запроса

ПолеТипОписание
quote_id*string

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/confirm \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q-11111111111111111111111111111111"}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticOperation

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations

История API-операций

Покупки, продления, смены реквизитов и UDP-операции владельца ключа. Возвращает items и next_cursor; передавайте курсор до null.

Параметры

ИмяГдеТипОписание
cursorqueryinteger

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/operations \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticOperationList

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations/{operationId}

Состояние исходной операции

Чтение без списания, выдачи или повторной отправки уведомления. Чужая и отсутствующая операция дают 404.

Параметры

ИмяГдеТипОписание
operationId*pathstring

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222 \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticOperation

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/operations/{operationId}/reconcile

Сверить неизвестный результат

Работает с исходным operation_id. Может завершить подтверждённую оплатой выдачу, не создавая нового списания. Неподтверждённая оплата остаётся неизвестной. Для продолжения исполнения может потребоваться действующее разрешение расходов. Это не простой GET и не запрос возврата.

Параметры

ИмяГдеТипОписание
operationId*pathstring

Тело запроса

object

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/reconcile \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: StaticOperation

400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations/{operationId}/notifications

Состояние уведомлений

Статусы доставки плательщику и операторам, без отправки. ACCEPTED означает принятие API доставки, не прочтение человеком.

Параметры

ИмяГдеТипОписание
operationId*pathstring

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/notifications \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле
400Request rejected

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Request rejected

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Request rejected

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Request rejected

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Request rejected

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Request rejected

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Unknown response

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/operations/{operationId}/notifications/retry

Повторить отклонённое уведомление плательщику

Только явно отклонённая FAILED-доставка при включённых уведомлениях, не более четырёх попыток суммарно. UNKNOWN и старые NOT_QUEUED автоматически не повторяются. Оплата и выдача не выполняются.

Параметры

ИмяГдеТипОписание
operationId*pathstring

Тело запроса

object

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/notifications/retry \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы

200Ответ; проверяйте состояние в теле
400Request rejected

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Request rejected

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Request rejected

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Request rejected

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Request rejected

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Request rejected

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Unknown response

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/events

Список событий

items и next_cursor. События относятся только к вашему аккаунту.

Параметры

ИмяГдеТипОписание
cursorqueryinteger

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/events \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле
400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/events/{eventId}

Событие и попытки доставки

Возвращает event, attempts и next_cursor.

Параметры

ИмяГдеТипОписание
eventId*pathstring
cursorqueryinteger

Пример вызова

curl -X GET https://api.soxydata.com/v1/me/static/events/evt-33333333333333333333333333333333 \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле
400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/events/{eventId}/retry

Повторить доставку dead-события

Тот же event_id, без повторной покупки. Pending/delivered не создаются повторно. Приёмник обязан устранять дубли по event_id.

Параметры

ИмяГдеТипОписание
eventId*pathstring

Тело запроса

object

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/events/evt-33333333333333333333333333333333/retry \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы

200Ответ; проверяйте состояние в теле
400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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 один раз. Нужны права покупок; храните секрет на сервере.

Тело запроса

ПолеТипОписание
url*string | null

Пример вызова

curl -X POST https://api.soxydata.com/v1/me/static/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example/webhooks/proxy-soxy"}'

Ответы

200Ответ; проверяйте состояние в теле
400Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Ошибка; проверяйте error.code и исходную операцию

Схема: Error

{
  "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"

Ответы

200Ответ; проверяйте состояние в теле

Схема: Stock

401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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/orders

Заказы организационного контракта

Список доступных ключу старых заказов. API-операции op-… находятся в /me/static/operations, не здесь.

Параметры

ИмяГдеТипОписание
customer_refquerystring
statusquerystring: active | expired | all по умолчанию active
countryqueryCountryCode
limitqueryinteger по умолчанию 50
cursorquerystring

Пример вызова

curl -X GET https://api.soxydata.com/v1/orders \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: OrderList

400Ошибка BadRequest; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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. Ответ возвращает реквизиты.

Параметры

ИмяГдеТипОписание
Idempotency-Key*headerstring

Тело запроса

CreateOrderRequest

Пример вызова

curl -X POST https://api.soxydata.com/v1/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"country":"DE","count":5,"days":30,"customer_ref":"site-user-88412"}'

Ответы

201Ответ; проверяйте состояние в теле

Схема: CreateOrderResponse

400Ошибка BadRequest; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
402Ошибка InsufficientBalance; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient prepaid balance; nothing was issued or charged",
    "details": {
      "required_minor": 17500,
      "balance_minor": 1000,
      "currency": "RUB",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Ошибка CreateConflict; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "out_of_stock",
    "message": "no addresses available in DE",
    "details": {
      "country": "DE",
      "available": 0,
      "reason": "addresses",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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"
    }
  }
}
500Ошибка Internal; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "internal",
    "message": "internal error",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}

GET /v1/orders/{orderId}

Организационный заказ

Идентификатор psx-…, не op-…. Текущие адреса без паролей.

Пример вызова

curl -X GET https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03 \
  -H "Authorization: Bearer $API_KEY"

Ответы

200Ответ; проверяйте состояние в теле

Схема: Order

401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Ошибка NotFound; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Ошибка RateLimited; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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.

Параметры

ИмяГдеТипОписание
Idempotency-Key*headerstring

Тело запроса

RenewRequest

Пример вызова

curl -X POST https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03/renew \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: RenewResponse

400Ошибка BadRequest; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
402Ошибка InsufficientBalance; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient prepaid balance; nothing was issued or charged",
    "details": {
      "required_minor": 17500,
      "balance_minor": 1000,
      "currency": "RUB",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Ошибка NotFound; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Ошибка IdempotencyConflict; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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

{
  "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 и выбор доступов.

Параметры

ИмяГдеТипОписание
Idempotency-Key*headerstring

Тело запроса (необязательно)

CredentialsRequest

Пример вызова

curl -X POST https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03/credentials \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответы

200Ответ; проверяйте состояние в теле

Схема: CredentialsResponse

400Ошибка BadRequest; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Ошибка Unauthorized; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Ошибка Forbidden; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Ошибка NotFound; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Ошибка CredentialsConflict; проверьте тело ответа и состояние исходной операции.

Схема: Error

{
  "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

{
  "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_maxinteger
пример: 5
daysarray of integer
пример: [7]
rate_limitsobject
customer_idstring | 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>"
passwordstring
пример: "<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_refstring
пример: "site-user-88412"
country_name*string
пример: "Germany"
days_leftinteger
пример: 24
active_countinteger
price_minorinteger
пример: 17500
currencystring
пример: "RUB"
proxiesarray 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_refstring
пример: "site-user-88412"
country_name*string
пример: "Germany"
days_leftinteger
пример: 24
active_countinteger
price_minorinteger
пример: 17500
currencystring
пример: "RUB"
proxiesarray of Proxy

CreateOrderRequest

ПолеТипОписание
country*CountryCode
пример: "DE"
count*integer
days*integer: 7 | 30 | 90
customer_ref*string
passwordstring
пример: "<proxy-password>"

CreateOrderResponse

ПолеТипОписание
order*OrderWithPassword
balance_minor_afterinteger | 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
pathstring
пример: "/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_afterinteger | null

CredentialsRequest

ПолеТипОписание
passwordstring
пример: "<proxy-password>"

CredentialsResponse

ПолеТипОписание
order*OrderWithPassword

WebhookEvent

Отдельный формат старого /orders-контракта. Не используйте его вместо StaticEvent.

ПолеТипОписание
event_id*string
пример: "evt-9c1f3a8e2b04"
type*string: order.issued
created_at*string
data*object
ПолеТипОписание
order*Order

Error

ПолеТипОписание
error*object
ПолеТипОписание
code*string: invalid_request | unauthorized | forbidden | not_found | idempotency_conflict | out_of_stock | quota_exceeded | order_expired | insufficient_balance | rate_limited | internal
message*string
detailsobject

StaticQuoteInput

purchase: country/count/days; renew: days и ровно один из order_id/proxy_ids; credentials/udp: выбор без days. udp=true только для purchase. customer_ref должен совпадать с исходной покупкой.

ПолеТипОписание
kind*any: purchase | renew | credentials | udp
udpboolean
udp_modestring: connect | extend
countrystring
countinteger
daysinteger
customer_refstring
proxy_idsarray of string
order_idstringoperation_id завершённой исходной покупки, не номер заказа бота.

StaticQuote

ПолеТипОписание
quote_id*string
proxy_amount_minorintegerСтоимость прокси; возвращается для UDP-операции.
udp_amount_minorintegerСтоимость UDP, включена в итог.
udpobjectРежим, цена и сроки UDP по доступам. lines[].order — идентификатор доступа; until/from/expires — Unix-секунды. Для новой покупки сроки появятся в items после выдачи.
amount_minor*integerИтог в копейках.
currency*any: RUB
expires_at*integer
test_mode*boolean
пример: false
proxy_idsarray of string
kindany: purchase | renew | credentials | udp
customer_refstring | null
countinteger

StaticOperation

ПолеТипОписание
operation_id*string
state*any: CREATED | PREFLIGHT | DEBIT_PENDING | DEBIT_UNKNOWN | PAID | PAID_HELD | APPLYING | COMPLETED | DECLINED | MANUAL_REVIEW
proxy_amount_minorintegerСтоимость прокси; возвращается для UDP-операции.
udp_amount_minorintegerСтоимость UDP, включена в итог.
udpobjectРежим, цена и сроки UDP по доступам. lines[].order — идентификатор доступа; until/from/expires — Unix-секунды. Для новой покупки сроки появятся в items после выдачи.
amount_minor*integerИтог в копейках.
currency*any: RUB
proxy_ids*array of string
reasonstring | null
needs_attention*boolean
test_mode*boolean
пример: false
itemsarray of object
kindany: purchase | renew | credentials | udp
customer_refstring | null
created_atinteger
updated_atinteger
core_proxy_idsarray of string
retrystring

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
statusany: pending | delivered | dead
attemptsinteger

StaticCatalogue

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

ПолеТипОписание
productstring: static
protocolsarray of string
currencystring
countriesarray of object
ПолеТипОписание
countrystring
addressesinteger
indexed_addressesinteger
daysarray of integer
renewalobject
purchase_productsarray | null
purchase_availableboolean
max_countinteger
stock_is_reservationboolean
geo_versionany
health_checked_atany
pricing_versionstring

Ошибки

{"error":{"code":"forbidden","message":"API spending disabled","details":{"request_id":"req-example"}}}

Проверяйте HTTP-статус, error.code, details, а для созданной операции — её state и reason. Текст message может меняться. request_id, если он есть, помогает поддержке найти запрос. Не присылайте ключи и пароли.

HTTPcodeЧто значитЧто делать
400invalid_requestНеподдерживаемые поля, формат или выбор.Исправьте запрос. Не повторяйте неизменённый отказ.
401unauthorizedНет действующего ключа.Проверьте Bearer; при потере ключа перевыпустите его в боте.
403forbiddenНеверная роль, нет разрешения расходов или операция недоступна аккаунту.Проверьте whoami, экран ключа и RU/RUB. Не обходите ограничения.
404not_foundОбъект отсутствует либо не принадлежит выбранному аккаунту.Проверьте op-…, proxy_ids и customer_ref.
409idempotency_conflictКонфликт операции, котировки, цены, права или удержанной незавершённой покупки.Читайте reason и исходную операцию. Новый ключ не исправляет неизвестную оплату.
409out_of_stockПодходящие ресурсы недоступны.До списания можно выбрать другой товар; после начала операции сначала проверьте её исход.
409quota_exceededНедостаточно квоты ёмкости.Проверьте пределы и состояние операции; не уменьшайте защиту повторов.
409order_expiredСостояние или срок доступа запрещает выбранное действие.Проверьте возможность продления; освобождённый доступ не восстанавливается сменой пароля.
402insufficient_balanceПроверенный доступный баланс меньше нужной суммы.Пополните баланс Proxy Soxy. Перед новой попыткой проверьте исход прежней операции.
429rate_limitedПревышен лимит вызовов или выбранных единиц; смотрите details.Соблюдайте Retry-After; не меняйте ключ идемпотентности.
500internalЗапрос не завершился штатным ответом; финансовый исход может быть неизвестен.Читайте и сверяйте исходный 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 не объявляется работающим событием этого контракта.

{"event_id":"evt-33333333333333333333333333333333","type":"order.issued","created_at":1794720000,"data":{"operation_id":"op-22222222222222222222222222222222","proxy_ids":["bott-example001"],"customer_ref":"buyer-42"}}

Для изменений доступа 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 ответ может получить дополнительные поля. Секреты в примерах заменены заполнителями.