Обзор API

Публичный REST API Lumi для автоматизации: смотри данные аккаунта, проверяй и покупай ресурсы, пополняй баланс. У каждого продукта свой API и свой ключ.

Продукт	Базовый URL	Документация
Домены	`https://scamprojecttest.xyz/api/v1`	Домены
Прокси	`https://panel.scamprojecttest.xyz/proxy/api/v1`	Прокси

Ключ одного продукта работает только с этим продуктом. Для доменов и прокси выпускаются разные ключи. Ключ выдаёт оператор, напиши в @lumisup_robot.

Авторизация

Каждый запрос передаёт ключ в заголовке:

Authorization: Bearer lumi_domains_XXXXXXXXXXXXXXXXXXXX

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

Типы ключей

Тип	Доступ	Привязка
`reseller`	Только данные одного пользователя	Жёстко привязан к одному аккаунту
`operator`	Все пользователи	Не привязан; полный доступ

Reseller: все запросы автоматически ограничены его аккаунтом. Чужой user_id вернёт 404 (существование чужих аккаунтов не раскрывается).
Operator: указывает user_id явно (в теле или ?user_id=); для денежных операций это обязательно.

Права (scopes)

Reseller-ключу выдаётся набор прав. Operator-ключ имеет все права неявно.

Scope	Что разрешает
`domains:read` / `proxy:read`	Чтение: списки, статусы, цены, каталог
`domains:write` / `proxy:write`	Управление своими объектами
`domains:buy` / `proxy:buy`	Покупка и продление (списывает баланс)
`deposits:write`	Создание счетов на пополнение
`admin:*`	Только operator-ключ; кросс-пользовательские операции

Недостающее право → 403 forbidden_scope.

Денежные операции

Эндпоинты, которые двигают деньги (создание счёта, покупка, продление), подчиняются дополнительным правилам.

Денежные операции работают, только когда на деплое включён флаг API_MONEY_ENABLED. Пока он выключен, такие запросы возвращают 403 money_disabled, даже если у ключа есть нужный scope.

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

Каждый денежный POST обязан нести заголовок Idempotency-Key (8–200 символов):

Idempotency-Key: a1b2c3d4-orders-2026-06-09

Повтор запроса с тем же ключом вернёт исходный ответ, не выполняя операцию заново.
Два одновременных одинаковых запроса не выполнятся дважды: проигравший получит 409 in_progress.
Без заголовка → 400 idempotency_key_required.

Дневной лимит трат

У ключа может быть дневной лимит в USD (или общий по умолчанию). По его достижении денежные операции возвращают 402 daily_cap_exceeded до начала следующих суток (UTC). Operator-ключи лимиту не подчиняются.

Подпись запросов (опционально)

Если ключ выпущен с требованием подписи, каждый денежный запрос должен нести заголовок:

X-Signature: HMAC-SHA256(signing_secret, raw_request_body)

Подпись считается по точным байтам тела запроса. Так утечка одного Bearer-ключа не даёт двигать деньги без второго секрета. Без корректной подписи → 401 invalid_signature.

import hmac, hashlib, requests

KEY = "lumi_domains_XXX"
SIGNING = "your_signing_secret"  # выдаётся вместе с ключом, если включена подпись
body = b'{"amount_usd":"5","provider":"cryptobot"}'
sig = hmac.new(SIGNING.encode(), body, hashlib.sha256).hexdigest()

requests.post(
    "https://scamprojecttest.xyz/api/v1/deposits",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Idempotency-Key": "dep-2026-06-09-001",
        "X-Signature": sig,
        "Content-Type": "application/json",
    },
    data=body,
)

Лимиты запросов

Класс	Лимит по умолчанию
Обычные запросы	120 запросов / 60 с на ключ
Денежные запросы	20 запросов / 60 с на ключ

Bulk-запрос расходует столько денежных «токенов», сколько в нём позиций. При превышении → 429 rate_limited с заголовком Retry-After (секунды).

Пагинация

Списочные эндпоинты используют курсор:

GET /v1/domains?limit=50&cursor=eyJ...

limit: 1–200 (по умолчанию 50).
Ответ: { "items": [...], "next_cursor": "...", "has_more": true }. Передай next_cursor в cursor для следующей страницы. next_cursor: null означает, что страниц больше нет.

Массовые операции (bulk)

Bulk-эндпоинты принимают массив и возвращают по-позиционный результат. Операции не атомарны: ошибка одной позиции не откатывает остальные.

{
  "total": 2,
  "ok": 1,
  "failed": 1,
  "items": [
    { "ref": "a.com", "status": "ok", "result": { "...": "..." } },
    { "ref": "b.com", "status": "failed", "error": { "code": "...", "message": "..." } }
  ]
}

Лимит позиций в одном запросе: 500, иначе 413 batch_too_large. Долгие bulk-покупки выполняются асинхронно: эндпоинт возвращает 202 с batch_id, статус опрашивается через GET /v1/batches/{batch_id}.

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

Все ошибки приходят единым JSON:

{ "error": { "code": "forbidden_scope", "message": "Key lacks the required scope 'domains:buy'." } }

HTTP	code	Когда
401	`missing_bearer`	Нет заголовка Authorization
401	`invalid_key`	Ключ неизвестен, отозван или истёк
401	`invalid_signature`	Требуется подпись, а её нет/неверна
402	`daily_cap_exceeded`	Достигнут дневной лимит трат
403	`forbidden_scope`	У ключа нет нужного права
403	`money_disabled`	Денежные операции выключены на деплое
404	`not_found`	Объект не найден (или чужой, если ключ reseller)
409	`in_progress`	Идентичный запрос ещё выполняется
413	`batch_too_large`	Слишком много позиций в bulk
422	`validation_error`	Некорректное тело/параметры
429	`rate_limited`	Превышен лимит запросов
503	`api_disabled`	API выключен на деплое

Деньги в ответах

Денежные суммы всегда приходят строками ("5.15"), а не числами с плавающей точкой, чтобы не терять точность. Передавай суммы в запросах тоже строками.

Здоровье сервиса

GET /healthz   →  { "status": "ok", "service": "api" }

Без авторизации; только проверка живости.

Начало

Аккаунт

API

Обзор API

Авторизация

Типы ключей

Права (scopes)

Денежные операции

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

Дневной лимит трат

Подпись запросов (опционально)

Лимиты запросов

Пагинация

Массовые операции (bulk)

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

Деньги в ответах

Здоровье сервиса

​Авторизация

​Типы ключей

​Права (scopes)

​Денежные операции

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

​Дневной лимит трат

​Подпись запросов (опционально)

​Лимиты запросов

​Пагинация

​Массовые операции (bulk)

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

​Деньги в ответах

​Здоровье сервиса

Авторизация

Типы ключей

Права (scopes)

Денежные операции

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

Дневной лимит трат

Подпись запросов (опционально)

Лимиты запросов

Пагинация

Массовые операции (bulk)

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

Деньги в ответах

Здоровье сервиса