Reefox

Reefox Stars API

HTTP API для продажи Telegram Stars и Premium из вашего бота, магазина или сервиса. Вы пополняете TON-баланс в кабинете Reefox, а API считает цену, резервирует сумму и доводит заказ до получателя.

Как это работает

Вы пополняете TON-баланс в кабинете reefox.ru и получаете API-ключ.

Ваш сервер проверяет получателя и, если нужно, узнаёт цену.

Ваш сервер создаёт заказ. Reefox резервирует сумму на балансе и ставит заказ в очередь выдачи.

Вы опрашиваете статус заказа, пока он не станет delivered или failed. Резерв списывается только после выдачи.

Адрес API

https://reefox.ru/api/v1

Все запросы и ответы — JSON в UTF-8. Каждый ответ содержит поле ok: true при успехе, false при ошибке.

Авторизация

Передавайте API-ключ в заголовке каждого запроса:

Authorization: Bearer sk_live_••••••••••••
  • sk_live_… — боевой ключ, заказы выдаются по-настоящему.
  • sk_test_… — тестовый ключ, заказы проходят все статусы, но ничего не выдаётся.

Ключ — только на сервере

Не размещайте ключ в браузере, мобильном приложении или публичном репозитории: с ним можно тратить ваш баланс. Ключ показывается в кабинете один раз. Перевыпуск сразу отзывает прежний.

Идемпотентность

Для каждого нового заказа передавайте уникальный ключ:

Idempotency-Key: checkout_7812_attempt_1

Если соединение оборвалось и вы не знаете, создался ли заказ, повторите тот же запрос с тем же ключом — Reefox вернёт исходный заказ, а не создаст второй. Если с уже использованным ключом прислать другие параметры, вернётся ошибка 409 idempotency_conflict.

Какой ключ брать

Удобно строить ключ из номера заказа в вашей системе, например shop-<id заказа>. Тогда один и тот же заказ невозможно отправить дважды, даже если его по ошибке обработают два процесса.

Первый заказ

curl https://reefox.ru/api/v1/orders \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Idempotency-Key: checkout_7812" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "stars",
    "recipient": "@username",
    "quantity": 100,
    "external_id": "order-7812"
  }'

Ответ 201:

{
  "ok": true,
  "id": "ord_…",
  "status": "fulfillment_pending",
  "amount": { "value": "1.275", "currency": "TON" },
  "status_url": "https://reefox.ru/api/v1/orders/ord_…"
}

Дальше опрашивайте status_url, пока статус не станет конечным. Все методы описаны в разделе Методы API, статусы и ошибки — в разделе Статусы и ошибки.

На этой странице

Как это работаетАдрес APIАвторизацияИдемпотентностьПервый заказ