SteamPlus / API Docs
Руководство по API  v1.0

SteamPlus API — документация для интеграции

Версия: 1.0 · Адрес API: https://api.steamplus.cloud · Формат: HTTPS + JSON

Это руководство поможет подключить API SteamPlus к вашему сервису или программе для пополнения Steam. API позволяет узнать курсы, проверить доступный баланс, получить расчёт стоимости, создать заказ и отслеживать его состояние. Пополнение внутреннего баланса через API не предусмотрено — это делается в Telegram-боте.

Все приведённые токены, суммы и номера заказов — примеры. Замените <ВАШ_API_КЛЮЧ> собственным ключом. Примеры ответов показывают структуру и не означают, что заказ с указанными данными существует.

Обзор API

SteamPlus — HTTPS JSON API для пополнения баланса Steam по логину. Через API можно получить курс и стоимость, создать заказ и узнать результат. Стоимость заказов списывается с вашего заранее пополненного баланса SteamPlus.

Свойство Значение
Базовый адрес https://api.steamplus.cloud
Протокол / формат HTTPS, JSON
Авторизация X-API-Key
Валюты пополнения Steam RUB, KZT
Валюта внутреннего баланса USDT
Лимит по умолчанию 30 запросов в 60 секунд на ключ
Создание заказа POST /v1/steam/orders с Idempotency-Key
Пополнение баланса Через Telegram-бота, не через API

Как выглядит интеграция

  1. Отправляется запрос расчёта с API-ключом.
  2. SteamPlus проверяет логин, возвращает стоимость и короткоживущий quote_token.
  3. Отправляется запрос создания заказа с уникальным Idempotency-Key; полученный ID сохраняется.
  4. SteamPlus резервирует сумму из баланса и обрабатывает заказ.
  5. Запрашивается статус заказа. Отображается результат.

API-ключ никогда не должен попадать в клиентский JavaScript, исходный код мобильного приложения или публичный URL. Запросы с API-ключом должны выполняться на защищённой серверной стороне приложения (сервер-сервер).

Все публичные методы

Метод URL Назначение Ключ
GET /health Доступность API Нет
GET /v1/steam/rates Текущие курсы Да
GET /v1/balance Баланс USDT Да
POST /v1/steam/quote Расчёт и токен Да
POST /v1/steam/orders Создание заказа Да
GET /v1/steam/orders/{order_id} Получение заказа Да
GET /v1/steam/orders?limit=20 Последние заказы Да

Начало работы

Получение доступа

  1. Откройте Telegram-бот SteamPlus, нажмите /start. Баланс привязан к вашему Telegram-аккаунту.
  2. Передайте в поддержку свой числовой Telegram ID.
  3. Поддержка выдаёт уникальный API-ключ вида stm_... и назначает доступные операции, число запросов в минуту, дневной лимит и максимум одного заказа.
  4. Сохраните ключ в серверной конфигурации. Не вставляйте его в HTML/JavaScript сайта, мобильное приложение, публичный репозиторий или URL.
  5. Для работы заказов заранее пополните внутренний баланс через Telegram-бота.

При выдаче ключа ключ показывается один раз. При утрате обратитесь в поддержку для перевыпуска.

Авторизация и общие правила

Примеры Python используют библиотеку requests (pip install requests). API-ключ передавайте через переменную окружения STEAMPLUS_API_KEY, а не сохраняйте в коде. Примеры справа не выполняют запросы из браузера.

Передавайте ключ в HTTP-заголовке:

X-API-Key: <ВАШ_API_КЛЮЧ>

Используйте Content-Type: application/json для JSON-запросов. Все запросы — только по HTTPS. Основной способ авторизации — заголовок, а не URL. Для GET API технически допускает ?api_key=..., но это не рекомендуется из-за риска утечки в логи и историю браузера. В POST ключ через URL не принимается.

Для каждого ключа действует лимит запросов за скользящие 60 секунд (по умолчанию 30 запросов/мин, фактическое значение устанавливает поддержка; допустимый диапазон настройки 1–600/мин). При превышении возвращается HTTP 429. Заголовок Retry-After на текущий момент не предусмотрен: ориентируйтесь на ожидание до 61 секунды и избегайте одновременного возобновления большого числа запросов.

Суммы в USDT в актуальном обновлении отображаются строками с тремя знаками после точки (например, "1.025"). Денежные операции внутри системы сохраняют точность до 6 знаков; отображаемая строка может быть округлена для представления. Не вычисляйте итоговую стоимость самостоятельно — используйте ответ quote и токен расчёта.

Быстрый старт: от расчёта до заказа

  1. Получите курсы (GET /v1/steam/rates) и, при необходимости, баланс (GET /v1/balance).
  2. Передайте логин Steam, валюту и целую сумму в POST /v1/steam/quote.
  3. Отображается рассчитанная стоимость cost_usdt.
  4. Подтвердите создание заказа через POST /v1/steam/orders, передав quote_token и уникальный Idempotency-Key.
  5. Сохраните полученный order.id и периодически проверяйте GET /v1/steam/orders/{order_id} до завершения.

Важно: расчёт сам по себе не списывает баланс. Списание (резервирование) происходит только при успешном создании заказа.

Справочник методов

Проверка доступности — GET /health

Без API-ключа. Пример ответа:

{"status":"ok","service":"steam-api"}

Курсы — GET /v1/steam/rates

curl -sS 'https://api.steamplus.cloud/v1/steam/rates' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>'

Ответ содержит массив rates с установленными валютами и курсами. Форма отдельного элемента:

{"currency":"RUB","units_per_usdt":"82.29","updated_at":"2026-11-16T12:00:00+00:00"}

units_per_usdt — сколько RUB или KZT соответствует 1 USDT. Фактический курс может меняться; значения выше иллюстративные.

Баланс — GET /v1/balance

curl -sS 'https://api.steamplus.cloud/v1/balance' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>'

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

{"balance_usdt":"102.500","deposit_available_via":"telegram_only"}

Возвращается баланс Telegram-аккаунта, к которому привязан API-ключ, а не индивидуальный баланс ключа. Если у одного владельца несколько ключей, они могут использовать один баланс. Пополнение доступно только через Telegram-бота.

Расчёт заказа — POST /v1/steam/quote

Требуется право quote.

curl -sS -X POST 'https://api.steamplus.cloud/v1/steam/quote' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>' \
  -H 'Content-Type: application/json' \
  -d '{"steam_login":"example_login","currency":"RUB","amount":500}'

Поля:

Поле Тип Описание
steam_login string Логин для входа в Steam, не никнейм; 3–64 символа из A-Z, a-z, цифр, ., _, -
currency string RUB или KZT
amount integer Целое число единиц выбранной валюты: RUB 30–10000, KZT 250–55000

Пример структуры ответа:

{
  "quote_token": "<ПОДПИСАННЫЙ_ТОКЕН>",
  "expires_at": 1794840000,
  "login": "example_login",
  "currency": "RUB",
  "amount": 500,
  "rate": "82.29",
  "cost_micro": 6076073,
  "cost_usdt": "6.076"
}

expires_at — Unix-время окончания срока действия расчёта. Токен действителен 90 секунд. cost_micro — точная стоимость в миллионных долях USDT (1 USDT = 1 000 000 micro-USDT). cost_usdt — сумма для отображения. Если время истекло или изменился курс, запросите новый расчёт.

При расчёте сервис проверяет существование/допустимость логина Steam через внешний источник. Если проверка временно недоступна, возможен HTTP 503.

Создание заказа — POST /v1/steam/orders

Требуется право create_orders и заголовок Idempotency-Key — уникальный идентификатор операции длиной 8–128 символов, допустимы латинские буквы, цифры, ., _, :, -.

curl -sS -X POST 'https://api.steamplus.cloud/v1/steam/orders' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: partner-order-20261116-001' \
  -d '{"quote_token":"<ПОДПИСАННЫЙ_ТОКЕН>"}'

Пример успешного ответа (HTTP 201):

{
  "order": {
    "id": 125,
    "number": 12345,
    "steam_login": "example_login",
    "currency": "RUB",
    "amount": 500,
    "cost_usdt": "6.076",
    "status": "PENDING",
    "processing_status": "QUEUED",
    "created_at": "2026-11-16T12:00:00+00:00"
  },
  "idempotent_replay": false
}

Сумма cost_micro списывается с внутреннего баланса атомарно; заказ ставится в обработку. Повторение того же запроса с тем же ключом идемпотентности и тем же токеном не создаёт новый заказ и не списывает баланс повторно. В повторном ответе idempotent_replay будет true.

Если повторно использовать прежний Idempotency-Key с другим quote_token, сервер вернёт HTTP 409. Для нового заказа создавайте новый ключ. Если соединение оборвалось после отправки заказа и результат неизвестен, повторяйте с тем же ключом и токеном, не создавайте новую операцию.

Проверить заказ — GET /v1/steam/orders/{order_id}

curl -sS 'https://api.steamplus.cloud/v1/steam/orders/125' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>'

Возвращает объект order без обёртки (поля как у объекта order из ответа создания). order_id — внутренний числовой ID id, а не пятизначный number.

История заказов — GET /v1/steam/orders?limit=20

curl -sS 'https://api.steamplus.cloud/v1/steam/orders?limit=20' \
  -H 'X-API-Key: <ВАШ_API_КЛЮЧ>'

Ответ: {"orders":[...объекты заказов...]}. limit — от 1 до 100, по умолчанию 20; возвращаются новые заказы первыми.

Для всех методов просмотра заказов данные ограничены заказами, созданными через данный API-ключ. Даже другой ключ того же Telegram-аккаунта не получает к ним доступ через эти методы.

Справочник

Статусы заказов

Поле status — основной статус заказа:

status Значение
PENDING В очереди / в процессе
DONE Выполнен
CANCELLED Отменён; средства могут возвращаться по правилам сервиса
FAILED Ошибка выполнения, если такой статус установлен обработчиком

processing_status — дополнительное, не привязанное к конкретному поставщику обозначение этапа:

processing_status Значение
QUEUED Ожидает обработки
PROCESSING Обрабатывается
CHECKING Идёт проверка / нужна сверка
COMPLETED Выполнено
CANCELLED / FAILED Завершено отменой / ошибкой

Считайте успехом только основной статус DONE. processing_status=COMPLETED — дополнительный индикатор, а не независимое основание для зачисления услуги. Не считайте успехом PROCESSING и CHECKING. Для надёжности при интерпретации статусов ориентируйтесь прежде всего на status.

Ошибки и повторные запросы

HTTP Причина Что делать
400 Некорректный / истёкший токен, отсутствует Idempotency-Key Получить новый расчёт или исправить заголовок
401 Неверный либо отключённый API-ключ Проверить ключ, обратиться в поддержку
403 Операция запрещена настройками ключа Запросить необходимые права
404 Не найден заказ либо пользователь Убедиться в правильности id и привязке ключа
409 Конфликт повторного запроса, курс/лимит/баланс Не повторять создание с новым ключом без проверки; устранить причину
422 Неверный логин, валюта, сумма или limit Исправить входные данные
429 Превышен лимит запросов Сделать паузу; не создавать лишние запросы
503 Временно недоступна проверка логина Steam Повторить расчёт позднее

При HTTP 429 новый запрос не исполняется. Поскольку сервер не возвращает Retry-After, рекомендуется установить задержку до 61 секунды и экспоненциальный backoff при повторных ошибках. Не повторяйте заказы с новым Idempotency-Key после сетевого таймаута.

Для ошибок FastAPI часто возвращается JSON вида {"detail":"Описание проблемы"}; для ошибок валидации поле detail может быть массивом. В случае сетевого таймаута при создании заказа сохраните Idempotency-Key, попробуйте повторить идентичный запрос или проверить заказы.

Безопасность

Чек-лист перед запуском

  1. Получен ключ и известны лимиты.
  2. GET /v1/balance возвращает баланс.
  3. POST /v1/steam/quote успешно возвращает токен для тестового логина.
  4. Тестовый заказ создан с уникальным Idempotency-Key, получены id и number.
  5. Повтор идентичного запроса не списывает деньги второй раз.
  6. Интеграция отслеживает status до DONE либо конечного негативного статуса.
  7. Настроены безопасное хранение ключей, таймауты, ограничение частоты и обработка ошибок.

Контакт по доступам и вопросам интеграции: поддержка SteamPlus через существующие каналы связи. Ключ выдаёт поддержка, не публичная форма на сайте.