Быстрый старт

Shop API поддерживает Telegram Stars, Telegram Premium, пополнения игр/аккаунтов и цифровые коды. Запросы отправляются с вашего сервера в JSON; все суммы — в USD.

:::info Публикация перед запуском

Документация описывает реализованный API. Публичный деплой и сквозное тестирование на рабочем окружении — следующий этап. ID, названия и цены в примерах условные; актуальные значения получайте из каталога.

:::

1. Подготовьте интеграцию

Создайте интеграцию Shop API в дашборде и откройте настройки. Понадобятся:

api_key_id — числовой ID интеграции.
X-Api-Key — секретный API-ключ.

Перед покупкой пополните баланс интеграции. Храните ключ на бекенде, не размещайте в браузере, открытом репозитории или приложении, распространяемом среди клиентов. При сбросе ключа в дашборде для следующих запросов нужен новый ключ.

2. Проверьте баланс

Базовый адрес: https://shop-api.adaptgroup.pro.

Все десять публичных маршрутов используют POST, Content-Type: application/json, заголовок X-Api-Key и api_key_id в теле JSON.

curl --request POST 'https://shop-api.adaptgroup.pro/balance/check' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{"api_key_id":1}'

Пример ответа:

{
  "success": true,
  "api_key_id": 1,
  "balance": "25.0000",
  "currency": "USD",
  "balance_updated_at": "2026-09-26T12:00:00"
}

Денежные значения передаются десятичными строками. Для расчётов используйте десятичную арифметику, а не двоичный float. Время — UTC; у дат заказа и баланса может отсутствовать суффикс часового пояса.

3. Выберите модуль

Модуль	Что покупаем	Откуда брать параметры
`stars`	От 50 до 100000 Telegram Stars	Цена одной звезды из `/modules/list`; username получателя
`tg_premium`	Telegram Premium на 3, 6 или 12 месяцев	Цены из `/modules/list`; username получателя
`topups`	Номинал пополнения игры/аккаунта	`/catalog/list` → `/catalog/details` → `/catalog/nominal`
`codes`	Номинал цифрового кода	Те же маршруты каталога; получатель не нужен

Каталог содержит товары, настроенные на платформе, а не весь каталог поставщика. item_id обозначает товар, nominal_id — конкретный номинал внутри него. Используйте ID, которые возвращает этот API.

4. Проверьте, рассчитайте и купите

Для Stars, Premium и пополнений соберите данные получателя и вызовите Проверку получателя. Для кодов этот шаг не нужен.
Через Расчёт цены получите текущую итоговую сумму.
Один раз вызовите Создание заказа для нужной покупки. Актуальная цена спишется автоматически; цену передавать не нужно.
Сохраните order_id. Получите результат через Статус заказа или Вебхуки.

Примеры по модулям, работа с полями и неопределённым результатом — на странице Процесс покупки.

Ограничения и ошибки

Общий лимит интеграции — 100 запросов за 60 секунд по всем публичным маршрутам. У разных интеграций отдельные счётчики. При превышении возвращается HTTP 429; отдельных лимитов на каждый маршрут нет.

Лишние поля запроса запрещены. Целые числа передавайте JSON-числами, а ID клиента и данные получателя — строками там, где это указано. Вариант запроса определяется полем module.

HTTP-статус	Значение
`200`	Получен результат операции. Учитывайте `success`, `status`, `valid` и `supported` в зависимости от маршрута
`400`	Отказ по условиям покупки: недостаточный баланс, недоступный номинал, неверный получатель или количество
`401`	Нет ключа, ключ или ID неверны, интеграция отключена
`404`	Товар, номинал или заказ не найден
`422`	Ошибка валидации запроса
`429`	Превышен лимит запросов
`500`	Непредвиденная ошибка сервера
`502`, `503`, `504`	Некорректный ответ внешнего сервиса, временная недоступность или таймаут

У большинства ошибок detail — строка:

{"detail":"Insufficient balance"}

У ошибок валидации detail — массив:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "api_key_id"],
      "msg": "Input should be greater than or equal to 1",
      "input": 0,
      "ctx": {"ge": 1}
    }
  ]
}

При ошибке создания detail может содержать order_id. Сохраните его и проверьте заказ. Не повторяйте покупку автоматически после таймаута, обрыва соединения или неопределённого ответа. Подробнее — в Процессе покупки.

Спецификация API

Скачать OpenAPI на русском · Скачать OpenAPI на английском

Оба файла описывают одинаковые маршруты, поля и ограничения. Отличается только язык документации; параметра языка в публичных запросах API нет.

1. Подготовьте интеграцию​

2. Проверьте баланс​

3. Выберите модуль​

4. Проверьте, рассчитайте и купите​

Ограничения и ошибки​

Спецификация API​