Методы API
Все методы Reefox Stars API — создание и статус заказа, проверка получателя, цена и баланс. Параметры, примеры запросов и ответов.
Пять методов покрывают весь путь заказа: проверить получателя, узнать цену, создать заказ, следить за ним и смотреть баланс.
Товары и количество
product | quantity |
|---|---|
stars | Любое целое число от 50 до 10 000 — не только круглые значения, как во Fragment |
premium | Ровно 3, 6 или 12 — срок подписки в месяцах |
Получатель (recipient) — публичный username в Telegram, с @ или без.
POST /orders
Создаёт заказ: получает свежую цену, резервирует сумму на балансе и ставит заказ в очередь выдачи. Обязателен заголовок Idempotency-Key.
| Поле | Тип | Описание |
|---|---|---|
product | строка | stars или premium |
recipient | строка | Username получателя |
quantity | число | Количество, см. таблицу выше |
external_id | строка | Ваш номер заказа, до 128 символов. Вернётся в ответах |
Ответ 201:
{
"ok": true,
"id": "ord_…",
"external_id": "order-7812",
"product": "stars",
"recipient": "@username",
"quantity": 100,
"amount": { "value": "1.275", "currency": "TON" },
"status": "fulfillment_pending",
"created_at": "…",
"updated_at": "…",
"status_url": "https://reefox.ru/api/v1/orders/ord_…"
}Если доступного баланса не хватает, вернётся 402 insufficient_balance, и заказ не создастся.
GET /orders/{id}
Текущее состояние заказа и его хронология в поле events. Опрашивайте, пока статус не станет delivered или failed. Разумный интервал — раз в 5–15 секунд.
curl https://reefox.ru/api/v1/orders/ord_… \
-H "Authorization: Bearer sk_live_••••••••••••"Поля те же, что у POST /orders, плюс events — массив событий заказа по порядку.
POST /recipients/validate
Проверяет, что username существует и может получить выбранный товар. Вызывайте до оплаты, чтобы клиент не заплатил за подарок несуществующему аккаунту.
{ "product": "premium", "recipient": "@username", "quantity": 3 }Ответ 200:
{
"ok": true,
"recipient": { "username": "username", "display_name": "Имя", "eligible": true }
}Если получатель не найден или не может получить товар — 400 recipient_invalid.
GET /quote
Цена заказа в TON на текущий момент — то, что спишется с вашего баланса. Нужна, чтобы показать клиенту цену в рублях до оплаты.
curl "https://reefox.ru/api/v1/quote?product=stars&quantity=100" \
-H "Authorization: Bearer sk_live_••••••••••••"{
"ok": true,
"product": "stars",
"quantity": 100,
"amount": { "value": "1.275", "currency": "TON" },
"expires_at": "…"
}Цена меняется
Цена зависит от курса TON и действует до expires_at. При создании заказа Reefox берёт свежую цену, поэтому итоговая сумма может немного отличаться от той, что вы запросили раньше. Закладывайте запас в свою наценку.
GET /balance
Доступный баланс, сумма активных резервов и режим ключа.
{
"ok": true,
"balance": { "value": "42.5", "reserved": "1.275", "currency": "TON" },
"mode": "live"
}value — сколько можно потратить прямо сейчас. reserved — сумма заказов, которые ещё выдаются.