XyraNet Wholesale

XyraNet Wholesale API

Подробный человекочитаемый гайд по интеграции, сценариям покупки, reseller-заказам и работе с балансом Wholesale API.

Открыть SwaggerВернуться в кабинет

Wholesale API

Подробная документация по Wholesale API XyraNet.

Этот API нужен для тех, кто:

1. Что умеет Wholesale API

Через Wholesale API можно:

Через Wholesale API нельзя пополнять баланс напрямую. Пополнение делается через сайт или Telegram-бота, а API работает уже с тем балансом, который доступен у пользователя.

Мобильная связь / LTE

Тариф «Мобильная связь» (lte_monthly) входит в Wholesale API:

Для wholesale-интеграции источником истины всегда является GET /api/wholesale/tariffs: покупайте только те code, которые пришли в этом ответе. У LTE нет лимита одновременных подключений, зато есть месячная квота трафика в поле included_traffic_bytes.

2. Базовый URL

Все методы находятся под префиксом:

/api/wholesale

Пример полного URL:

https://xyranet.pro/api/wholesale/summary

3. Аутентификация

Wholesale API использует персональный API-ключ.

Передавайте его в заголовке:

X-API-Key: xyr_your_api_key_here

Пример:

curl -X GET "https://xyranet.pro/api/wholesale/summary" \
  -H "X-API-Key: xyr_your_api_key_here"

4. Режимы доступа API-ключа

У API-ключа есть 2 режима:

Only read

Подходит для безопасной интеграции, если нужно только читать данные.

Разрешает:

Не разрешает:

Read + write

Даёт всё из Only read, плюс разрешает:

5. Allowlist IP

Если для API-ключа настроен allowlist IP, запросы должны приходить только с разрешённых IP-адресов или CIDR-сетей.

Если IP не подходит, API вернёт:

{
  "detail": "API key is not allowed from this IP"
}

со статусом 403.

6. Rate limit

На API-ключ действуют лимиты запросов.

При превышении лимита API вернёт 429 Too Many Requests и заголовок Retry-After.

7. Формат ошибок

Обычный формат ошибок:

{
  "detail": "Описание ошибки"
}

Частые статусы:

8. Сценарии покупки подписки

Метод:

POST /api/wholesale/purchase

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

8.1. Купить подписку владельцу API-ключа

Если не передавать ни telegram_id, ни login, подписка будет куплена самому владельцу API-ключа.

Пример:

curl -X POST "https://xyranet.pro/api/wholesale/purchase" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xyr_your_api_key_here" \
  -d '{
    "tariff_code": "lite_monthly"
  }'

8.2. Купить подписку пользователю Telegram-бота

Передайте telegram_id.

Пример:

{
  "tariff_code": "pro_1y",
  "telegram_id": 123456789
}

8.3. Купить подписку пользователю сайта по логину

Передайте login.

Пример:

{
  "tariff_code": "lite_3m",
  "login": "demo_user"
}

Важно:

9. Ответ на успешную покупку

Пример:

{
  "status": "completed",
  "target_telegram_id": 123456789,
  "target_login": null,
  "balance": "5240.00",
  "currency": "RUB",
  "purchase": {
    "charged_amount": "949.00",
    "balance_after": "5240.00",
    "subscription": {
      "plan_family": "lite",
      "subscription_url": "https://x.xyranet.pro/...",
      "tariff_code": "lite_1y",
      "started_at": "2026-03-30T10:00:00Z",
      "expire_at": "2027-03-30T10:00:00Z",
      "ip_limit": 2,
      "status": "active"
    }
  },
  "subscriptions": [
    {
      "plan_family": "lite",
      "subscription_url": "https://x.xyranet.pro/...",
      "tariff_code": "lite_1y",
      "started_at": "2026-03-30T10:00:00Z",
      "expire_at": "2027-03-30T10:00:00Z",
      "ip_limit": 2,
      "status": "active"
    }
  ]
}

10. Сводка и тарифы

GET /api/wholesale/summary

Показывает:

GET /api/wholesale/tariffs

Возвращает список доступных тарифов с полями:

Именно code из этого ответа нужно использовать в покупке и продлении.

Для LTE сейчас используется код lte_monthly. Докупка LTE-трафика не передаётся как тарифный code, для неё есть отдельные методы /api/wholesale/traffic/....

GET /api/wholesale/tiers

Возвращает всю лестницу уровней:

11. Reseller-заказы

Reseller-заказ — это отдельный объект, который вы создаёте для своих клиентов или своей витрины.

11.1. Создать заказ

POST /api/wholesale/orders

Пример:

{
  "tariff_code": "pro_monthly"
}

Для LTE-заказа:

{
  "tariff_code": "lte_monthly"
}

В ответе вы получите:

11.2. Получить заказ

GET /api/wholesale/orders/{order_id}

Используйте этот метод, если нужно:

11.3. Продлить заказ

POST /api/wholesale/orders/{order_id}/renew

Варианты:

Пример без смены тарифа:

{}

Пример со сменой периода:

{
  "tariff_code": "pro_1y"
}

11.4. Перевыпустить заказ

POST /api/wholesale/orders/{order_id}/reissue

Используйте, если:

12. Увеличение IP limit

Wholesale API умеет не только покупать подписки, но и отдельно увеличивать количество одновременных подключений.

Это относится к Lite и Premium. У LTE нет лимита одновременных подключений в этой модели, поэтому для LTE используйте докупку трафика.

Есть 2 шага:

12.1. Сначала посчитать цену

POST /api/wholesale/ip-limit/quote

Сценарии:

Пример для пользователя:

{
  "telegram_id": 123456789,
  "family_code": "lite",
  "extra_ip_count": 2,
  "months": 3,
  "full_period": false
}

Пример для reseller-заказа на весь оставшийся срок:

{
  "order_id": "order_demo_1",
  "extra_ip_count": 1,
  "full_period": true
}

12.2. Потом купить увеличение

POST /api/wholesale/ip-limit/purchase

Параметры совпадают с quote.

После успешной покупки:

13. Докупка LTE-трафика

LTE-трафик покупается отдельно от продления подписки. Сначала считайте цену, потом выполняйте покупку.

13.1. Сначала посчитать цену

POST /api/wholesale/traffic/quote

Сценарии:

Пример для владельца API-ключа:

{
  "family_code": "lte",
  "gigabytes": 10
}

Пример для пользователя сайта:

{
  "family_code": "lte",
  "gigabytes": 20,
  "login": "demo_user"
}

Пример для reseller-заказа:

{
  "gigabytes": 15,
  "order_id": "order_demo_1"
}

В ответе quote вернёт:

13.2. Потом купить трафик

POST /api/wholesale/traffic/purchase

Параметры совпадают с quote.

После успешной покупки:

14. Практические сценарии

Сценарий A. Быстро купить доступ пользователю сайта

1. Получить тарифы через /api/wholesale/tariffs 2. Выбрать code, например pro_monthly 3. Вызвать:

{
  "tariff_code": "pro_monthly",
  "login": "demo_user"
}

Сценарий B. Создать отдельный заказ для перепродажи

1. Вызвать /api/wholesale/orders 2. Сохранить order_id 3. Отображать клиенту его ссылку из ответа 4. Для продления использовать /api/wholesale/orders/{order_id}/renew 5. Для новой ссылки использовать /api/wholesale/orders/{order_id}/reissue

Сценарий C. Увеличить лимит подключений

1. Сначала вызвать /api/wholesale/ip-limit/quote 2. Показать цену в интерфейсе 3. После подтверждения вызвать /api/wholesale/ip-limit/purchase

Сценарий D. Купить LTE и докупить трафик

1. Получить тарифы через /api/wholesale/tariffs 2. Купить lte_monthly через /api/wholesale/purchase 3. Если клиенту нужна дополнительная квота, сначала вызвать /api/wholesale/traffic/quote 4. После подтверждения вызвать /api/wholesale/traffic/purchase

15. Что важно учесть в интеграции

16. Минимальный набор методов для старта

Если вы только начинаете интеграцию, обычно достаточно этих методов:

1. GET /api/wholesale/summary 2. GET /api/wholesale/tariffs 3. POST /api/wholesale/purchase

Если вы строите reseller-витрину:

1. GET /api/wholesale/tariffs 2. POST /api/wholesale/orders 3. GET /api/wholesale/orders/{order_id} 4. POST /api/wholesale/orders/{order_id}/renew 5. POST /api/wholesale/orders/{order_id}/reissue

Если вы продаёте увеличения подключений:

1. POST /api/wholesale/ip-limit/quote 2. POST /api/wholesale/ip-limit/purchase

Если вы продаёте LTE-трафик:

1. POST /api/wholesale/traffic/quote 2. POST /api/wholesale/traffic/purchase

17. Где смотреть живую схему

Для живой схемы запросов и ответов используйте Swagger / OpenAPI вашего сервиса.

Но для интеграции лучше держать рядом и эту документацию: она объясняет не только поля, но и саму бизнес-логику сценариев.