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

Реселлерский API SHOP2TOPUP — это JSON REST API для продажи игровых пополнений, пополнений игровых счетов и кодов ваучеров из вашего собственного магазина, витрины или бота. В этом справочнике описан каждый публичный эндпоинт, его параметры и его ответы.

Базовый URL и транспорт

Каждый путь в этом справочнике указан относительно базового URL ниже. Запросы и ответы — JSON поверх HTTPS, суммы передаются строками, чтобы не возникало погрешностей округления, а все метки времени — UTC в формате ISO 8601.

https://shop2topup.com/api/endpoints/v1

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

Каждый запрос несёт один заголовок. Пара ключей выпускается на странице API Access в панели реселлера и может быть ограничена списком разрешённых IP; вызов с любого другого адреса отклоняется с IP_NOT_ALLOWED ещё до бизнес-логики.

Заголовок запроса

Authorization: Bearer <keyId>.<secret>

Первый вызов

Ничего устанавливать не нужно. Подставьте свой ключ — и это вернёт живые данные каталога.

Запрос — cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Соглашения ответов

Каждый ответ несёт булево поле success, поэтому одна ветка отделяет успешный сценарий от любого сбоя.
Ошибки возвращают объект error со стабильным code, понятным человеку message и необязательными details. Ветвитесь по коду, а не по сообщению.
Деньги — всегда десятичная строка вида "0.950000" в USD. Не превращайте её в двоичное число с плавающей точкой перед сравнением или суммированием.
Списочные эндпоинты возвращают объект pagination с полями page, limit, total и total_pages.
Создание заказа идемпотентно по переданному вами UUID в order_id, поэтому повтор не может списать дважды.

Ответ с ошибкой

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Разделы справочника

КаталогКаталог — это дерево из трёх уровней: большие категории содержат категории, категории содержат подкатегории, а подкатегория и есть тот товар, который вы покупаете. Эти эндпоинты позволяют перенести дерево в свою базу и узнать цену товара непосредственно перед заказом.Проверка игрокаПроверка игрока определяет игровой аккаунт до того, как пойдут деньги. Она подтверждает, что идентификатор существует для этого товара, возвращает игровое имя, чтобы покупатель мог его сверить, и показывает регион — так заказ в чужой регион отклоняется заранее, а не проваливается после оплаты.ЗаказыЗаказы создаются с UUID, который генерируете вы. Этот UUID и есть ключ идемпотентности: повтор с ним вернёт исходный заказ вместо второго списания. Статус потом читается по одному заказу, пакетами до пятидесяти или постраничным списком.Аккаунт и доступКаждый запрос несёт один заголовок. GET /account — тот эндпоинт, который вызывают, чтобы убедиться, что ключ работает, узнать баланс кошелька, с которого списываются заказы, и подтвердить, что аккаунт включён, перед запуском пакетного прогона.Коды ошибокКаждый отказ возвращает стабильный машиночитаемый код рядом с HTTP-статусом. Ветвитесь по коду, а не по тексту сообщения: сообщения написаны для людей и могут быть переформулированы, а коды — часть контракта.

Лимиты запросов

Лимиты считаются на аккаунт по скользящему окну. Эндпоинты каталога, заказов и аккаунта несут X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset, а ограниченный вызов отвечает 429 с заголовком Retry-After. Проверка игрока измеряется вашей суточной квотой проверок: она не отправляет заголовков X-RateLimit и сообщает квоту в теле ответа 429.

Маршрут	Запросов	Окно	Считается на
GET /catalog/* (все пять)	5000	60 с	на аккаунт
POST /orders/create	5000	60 с	на аккаунт
GET /orders/:orderId	3	60 с	на аккаунт + ID заказа
POST /orders/batch	2	60 с	на аккаунт
GET /orders	2	60 с	на аккаунт
GET /account	60	60 с	на аккаунт
POST /player/validate	суточный лимит проверок игроков	24 ч	на аккаунт (без заголовков X-RateLimit)

Вебхуки

Результаты заказов отправляются на зарегистрированный вами HTTPS-эндпоинт и подписываются HMAC-SHA256 по сырому телу. Список событий, список заголовков, форма тела и пример проверки описаны на обзорной странице API.

Открыть справочник по телу вебхука и подписи

Впервые на платформе? Начните с обзора API пополнения игр для реселлеров, а затем прочитайте обзор реселлерской программы SHOP2TOPUP, чтобы понять, как устроен партнёрский аккаунт.