Business API

Квантовая случайность, которую можно встроить в ваш продукт

REST API для розыгрышей, честного выбора, CSV/JSON отчётов и публичных сертификатов. Подходит для CRM, лендингов, Mini App, Web3 и внутренних админок.

1 000/dayлимит Business API на ключ
JSON/CSVрезультаты для систем и отчётов
Certificate IDпубличная проверка результата
QRNGANU, NIST и каскад публичной проверки

Обзор

Quantum Random Bot Business API даёт доступ к проверяемой случайности и сценариям розыгрышей без ручного Telegram-flow.

Каждый важный результат может быть связан с публичным Certificate ID, verify URL и PDF-сертификатом для участников, юристов, спонсоров или внутреннего аудита.

Авторизация

Все запросы требуют заголовок Authorization: Bearer <key>. Ключ создаётся в боте на тарифе Business.

Plaintext ключ показывается только при создании. Храните его как секрет и не отправляйте в клиентский браузер.

Authorization: Bearer qrng_xxxxxxxxxxxxxxxxx

Идентификаторы запросов

X-Request-ID — технический идентификатор одного HTTP-запроса. Передайте свой идентификатор длиной до 128 символов из латинских букв, цифр и знаков . _ : - или не указывайте заголовок — тогда сервер сгенерирует его. Ответ возвращает итоговый X-Request-ID, в том числе при обрабатываемых ошибках API.

request_id в JSON — идентификатор отдельной QRNG-операции получения случайности. Он не равен X-Request-ID и нужен для проверки источника случайности.

qrng_request_ids содержит все QRNG-идентификаторы, когда один HTTP-запрос выполняет несколько операций. Например, /random/int с count=3 возвращает три значения; request_id при этом содержит идентификатор последней операции.

При обращении в поддержку передавайте X-Request-ID из заголовка ответа. Для вопросов о конкретной случайной выборке дополнительно приложите request_id или qrng_request_ids из JSON.

Запрос:
X-Request-ID: order-2026-00042

Ответ:
X-Request-ID: order-2026-00042

Random endpoints

GET /api/v1/me информация о ключе +

Возвращает план, лимиты и статистику текущего API-ключа.

Пример
{
  "plan": "business",
  "key_prefix": "qrng_J5b8aB",
  "requests_today": 42,
  "daily_limit": 1000
}
GET /api/v1/random/int случайное число без modulo bias +

Генерирует от 1 до 100 целых чисел во включительном диапазоне min–max. Значение min должно быть меньше max, а ширина диапазона не должна превышать 1 000 000 000. Числа выбираются без modulo bias.

Пример
GET /api/v1/random/int?min=1&max=100&count=3

{
  "numbers": [42, 7, 91],
  "count": 3,
  "range": {"min": 1, "max": 100},
  "qrng_source": "anu",
  "request_id": "c46bd22a-de82-466e-9571-8fc56d655b3e",
  "qrng_request_ids": [
    "8f3d9251-33ad-4930-a6f3-115740b5e7d1",
    "68f0348e-a965-4e7a-a121-80f3be21d108",
    "c46bd22a-de82-466e-9571-8fc56d655b3e"
  ]
}

Выбирает один или несколько элементов из списка.

Пример
{
  "items": ["Alice", "Bob", "Charlie"],
  "count": 1,
  "unique": true
}

{
  "chosen": ["Bob"],
  "count": 1,
  "from_total": 3,
  "qrng_source": "nist",
  "request_id": "2d2babbb-5cc4-4a63-b514-6505836c78bd"
}

Перемешивает массив через Fisher-Yates с квантовым источником случайности.

Пример
{
  "items": ["A", "B", "C", "D"]
}

{
  "shuffled": ["C", "A", "D", "B"],
  "count": 4,
  "qrng_source": "anu",
  "request_id": "31d20e70-da21-4773-b979-460ab68eacc2"
}

Возвращает hex-байты для токенов и ключей: секретная системная энтропия с quantum-mix при наличии внешнего источника.

Пример
GET /api/v1/random/bytes?n=32&format=hex

{
  "bytes": "3f9a2b8c...",
  "format": "hex",
  "length": 32,
  "qrng_source": "anu",
  "request_id": "51c8d364-6a66-405c-ad8b-af6bd14c5160",
  "pool": "crypto"
}

Giveaway endpoints

GET /api/v1/giveaways создание и список розыгрышей +

Возвращает или создаёт розыгрыши, связанные с пользователем или API-ключом.

Пример
{
  "giveaways": [
    {
      "public_id": "A1B2C3D4",
      "title": "My Giveaway",
      "status": "active",
      "participants_count": 500
    }
  ],
  "total": 1
}

Возвращает или создаёт розыгрыши, связанные с пользователем или API-ключом.

Пример
{
  "title": "My API Giveaway",
  "winners_count": 3,
  "description": "Optional campaign copy"
}
POST /api/v1/giveaways/{id}/draw выбор победителей +

Проводит выбор победителей и возвращает данные для публичной проверки.

Пример
{
  "winners": [
    {"username": "alice", "telegram_id": 123456}
  ],
  "certificate_id": "17d58bb5...",
  "verify_url": "https://quantum-bot.space/verify/17d58bb5...",
  "qrng_source": "anu",
  "request_id": "..."
}

CSV-отчёт для спонсоров, юристов, бухгалтерии и внутреннего аудита.

Пример
telegram_id,username,first_name,joined_at,is_winner
123456,alice,Alice,2026-05-05T12:00:00,true
789012,bob,Bob,2026-05-05T12:05:00,false

Проверка и доверие

Публичный verify URL

Участник открывает страницу сертификата и видит источник случайности, алгоритм, hash и победителей.

Audit trail

Business получает данные, достаточные для отчёта и внутренней проверки результата.

Каскад устойчивости

Если один внешний источник недоступен, запрос переходит на следующий уровень, а использованный источник фиксируется.

Ошибки

400 — параметры или тело запроса некорректны.

401 — ключ отсутствует, неверен или отозван.

403 — тариф не поддерживает Business API или ресурс принадлежит другому пользователю.

404 — запрошенный ресурс не найден.

422 — параметр имеет неверный тип или формат.

429 — дневной лимит API исчерпан.

500 — непредвиденная внутренняя ошибка сервиса.

503 — сервис QRNG временно недоступен. Повторите запрос с экспоненциальным backoff.

Готовы подключить проверяемую случайность?

Начните с Business-плана, создайте ключ в боте и подключите API к вашей кампании, CRM или продукту.