SReefox
Кабинет
Production API

От запроса до выдачи.

HTTP API для Telegram Stars и Premium. Партнёр пополняет TON-баланс, а Reefox рассчитывает цену, резервирует сумму и возвращает наблюдаемый статус заказа.

Base URL

https://starsconnect.ru/api/v1

HTTPS + Bearer

Серверная авторизация

JSON

Единый формат данных

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

Защита от дублей

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

Авторизация

Передавайте активный API-ключ партнёра в заголовке каждого запроса. Ключ предназначен только для backend-сервера — не размещайте его в браузере, мобильном приложении или публичном репозитории.

HTTP header
Authorization: Bearer sk_live_••••••••••••

Надёжность

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

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

HTTP header
Idempotency-Key: checkout_7812_attempt_1
POST

/orders

Получает свежую котировку, резервирует TON и ставит заказ в очередь выдачи. При недостаточном доступном балансе возвращает 402.

Запрос
curl https://starsconnect.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://…/api/v1/orders/ord_…"
}
GET

/orders/{id}

Возвращает текущее состояние и полную хронологию заказа. Опрашивайте метод до терминального статуса delivered или failed.

POST

/recipients/validate

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

GET

/balance

Возвращает доступный TON-баланс, сумму активных резервов и режим окружения.

Справочник

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

fulfillment_pending

TON зарезервирован, заказ ожидает выдачи

processing

Выдача отправлена провайдеру

delivered

Получатель получил товар, резерв списан

reconciliation_required

Результат неоднозначен, резерв сохраняется

failed

Безопасная окончательная ошибка, резерв освобождён

Справочник

Формат ошибок

Ошибки имеют единый JSON-формат. Используйте машинный code для логики, а message — только для журнала и диагностики.

Ошибка
{
  "ok": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was already used…"
  }
}