Обзор

Авторизация

API поддерживает три способа авторизации. Передавайте один из заголовков в каждом запросе.

Bearer
Токен
Основной способ для пользовательских запросов. Передаётся в заголовке Authorization: Bearer <token> (POST) или query-параметром ?token= (GET). Получить токен — auth.createToken.
SecretKey
Secret Key · используется Telegram-ботом
HMAC-подпись, которую генерирует бот из user_id и secret_key из конфига. Позволяет боту обращаться к любому методу API от имени пользователя без хранения токенов. Передаётся в заголовке SecretKey: <value>.
InitData
Telegram Init Data · для Mini Apps
Данные из window.Telegram.WebApp.initData. Передаётся в заголовке InitData: <value> (POST) или query-параметром ?init_data= (GET).
Как работает SecretKey
python · bot/tools/tools..py 
# secret_key берётся из config.toml
# результат encode() передаётся в заголовке SecretKey каждого запроса

def encode(user_id) -> str:
    sig = hmac.new(
        config.secret_key.encode(),
        str(user_id).encode(),
        hashlib.sha256
    ).hexdigest()
    raw = f"{user_id}:{sig}"
    return base64.urlsafe_b64encode(raw.encode()).decode()
POST

auth.createToken

Путь: /auth/createToken

Обменивает одноразовый код на постоянный токен доступа. Код действителен 5 минут с момента создания. После успешного обмена код уничтожается.

Авторизация не требуется
Параметры запроса (JSON body)
Параметр Тип Обязательный Описание
code integer required Одноразовый 4-значный код, полученный через бота командой /code
Ответ
● 200 OK
json 
{
  "status": "success",
  "data": {
    "token": cc1bad5404f....,
    "ok": true
  }
}
POST

auth.createCode

Путь: /auth/createCode

Генерирует одноразовый 4-значный код для авторизации. Код действует 5 минут. Если сессия уже существует — вернёт ошибку 409.

Только через Telegram-бота · SecretKey
Параметры

— нет —

Ответ
● 200 OK
json 
{
  "status": "success",
  "data": {
    "code": 4821,
    "ok": true
  }
}
GET

report.get

Путь: /api/report/get

Возвращает список отчётов по смене с пагинацией. Поддерживает фильтрацию по дате и типу смены.

Требует авторизацию
Query параметры
ПараметрТипОбязательныйОписание
limit integer optional Кол-во записей. По умолчанию 30, макс. 100
offset integer optional Смещение для пагинации. По умолчанию 0
date string optional Фильтр по дате в формате YYYY-MM-DD
report_type string optional Тип смены: day или night
token string optional Токен авторизации (альтернатива заголовку)
POST

report.create

Путь: /api/report/create

Создаёт отчёт по смене. Принимает JSON или multipart/form-data (если прикладываются фото). За один день можно создать один дневной и один ночной отчёт. Ночной отчёт автоматически относится к предыдущей дате.

Требует авторизацию
Параметры (JSON body / form-data)
ПараметрТипОбязательныйОписание
report_type string required day или night
money integer required Товарооборот за смену в рублях
checks integer required Количество чеков за смену
itph float required ITPH
sos integer required Время обслуживания в секундах
sos_delivery integer required Время обслуживания доставки в секундах
guest_experience integer required Количество негативных отзывов
comments string required Комментарий к смене
photo0, photo1... file optional Фотографии (только multipart/form-data). Макс. 50 МБ
Ответ
● 200 OK
json 
{
  "status": "success",
  "data": { "ok": true }
}
GET

credit.get

Путь: /api/credit/get

Возвращает список долгов между ресторанами. Активные долги идут первыми, затем закрытые. Внутри каждой группы — сортировка по дате убыванию.

Требует авторизацию
Query параметры
ПараметрТипОбязательныйОписание
limit integer optional Кол-во записей. По умолчанию 30, макс. 100
offset integer optional Смещение для пагинации. По умолчанию 0
Ответ
● 200 OK
json 
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "date": "2026-03-11",
        "restaurant": 1088,
        "what_take": "Булки",
        "measurement_unit": "кс.",
        "count": 5.0,
        "credit_type": "взяли",
        "repayment_date": "2026-03-15",
        "is_transfer": false,
        "is_active": true
      }
    ],
    "ok": true
  }
}
POST

credit.create

Путь: /api/credit/create

Создаёт запись о долге между ресторанами. После создания уведомление автоматически отправляется в Telegram-чат.

Требует авторизацию
Параметры (JSON body)
ПараметрТипОбязательныйОписание
restaurant integer required Номер ресторана
what_take string required Что взяли / отдали
measurement_unit string required Единица измерения (шт., кс., кг., сл.)
count integer required Количество
credit_type string required take — взяли, give — отдали
is_transfer boolean required Является ли операция трансфером
repayment_date string optional Дата возврата в формате ISO 8601
Ответ
● 200 OK
json 
{
  "status": "success",
  "data": { "ok": true }
}
GET

credit.toggle

Путь: /api/credit/toggle

Переключает статус долга между активным и закрытым. Если долг был активным — закрывает его, и наоборот.

Требует авторизацию
Query параметры
ПараметрТипОбязательныйОписание
credit_id integer required ID долга из credit.get
Ответ
● 200 OK
json 
{
  "status": "success",
  "data": { "ok": true }
}
GET

user.get

Путь: /api/user/get

Возвращает информацию о текущем авторизованном пользователе.

Требует авторизацию
Параметры

— нет —

Ответ
● 200 OK
json 
{
  "status": "success",
  "data": {
    "tg_id": 123456789,
    "full_name": "Иван Иванов",
    "short_name": "Иван И.",
    "role": "admin",
    "ok": true
  }
}