H
HoReCa Cloud OS API v1.0.0
Interactive Developer Portal & Reference
OpenAPI JSON ← На главную

HoReCa Cloud OS REST API Спецификация

Полный набор программных интерфейсов для создания мобильных приложений (iOS/Android Flutter, React Native), внешних кассовых терминалов, кухонных экранов KDS и интеграции с агрегаторами доставки.

🔐 Авторизация & Профили (Telegram, SMS, Password)

Двойной механизм входа гостей (Telegram 1-sec Login & Kyrgyz SMS 2FA) и вход сотрудников.

POST /api/v1/auth/telegram
1-секундный вход через Telegram (WebApp / Widget)

Мгновенная авторизация гостя через Telegram WebApp initData или Login Widget с проверкой HMAC-SHA256.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "init_data": "query_id=AAHdF6IQAAAAAN0XohDhrPqy&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Nurbek%22%2C%22username%22%3A%22nurbek_kg%22%7D&auth_date=1787264000&hash=d8904f..."
}
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/auth/sms/send-otp
Отправка SMS-кода (Kyrgyz SMS / Nikita Online)

Отправляет 4-значный код подтверждения на номер (+996) с защитой от спама (Rate Limiting).

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "phone": "+996700123456",
    "provider": "kyrgyz_sms"
}
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/auth/sms/verify-otp
Верификация SMS-кода гостя

Проверяет введенный OTP код и выполняет вход или регистрацию гостя.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "phone": "+996700123456",
    "code": "1234",
    "name": "Нурбек"
}
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/auth/login
Вход по телефону и паролю/PIN (Сотрудники/Админы)

Аутентифицирует сотрудника или управляющего и возвращает токен доступа.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "phone": "+996550112233",
    "password": "password"
}
ОТВЕТ СЕРВЕРА (200 OK):
GET /api/v1/auth/me
Данные текущего пользователя

Возвращает профиль активного пользователя и его роли в заведении.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):

🏙 Заведения, Маркетплейс & White-Label Config

Получение списка всех заведений, филиалов и динамической темы White-Label.

GET /api/v1/tenants
Список всех заведений на платформе

Возвращает все активные ресторанные сети с филиалами и фото.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):
GET /api/v1/sierra/config
Динамический White-Label Config заведения

Отдает фирменные цвета, логотип, настройки валюты и флаг White-Label для мобильного приложения.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):

🔌 Шлюз интеграции с внешними кассами (1C / iiko / Poster)

Защищенный API для внешних кассовых систем с верификацией TOTP QR и фиксацией чеков.

POST /api/v1/pos/verify-customer
Сканирование QR / Поиск гостя на кассе (1C/iiko/Poster)

Кассир сканирует 60-секундный TOTP QR код -> касса получает tier, баланс кэшбека и штампы.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "qr_token": "HORECA-TOTP:nurbek:591240:1787264000",
    "pos_type": "1c"
}
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/pos/commit-transaction
Фиксация чека, расчет скидки и начисление бонусов

Списывает баллы гостя, рассчитывает скидку, начисляет кэшбек и штампы 7+1 в реальном времени.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "pos_type": "1c",
    "external_receipt_id": "1C-CHK-98124",
    "receipt_total": 580,
    "points_to_burn": 100,
    "customer_phone": "+996700123456",
    "items": [
        {
            "name": "Флэт Уайт Specialty",
            "quantity": 2,
            "price": 200,
            "is_stamp_eligible": true
        }
    ]
}
ОТВЕТ СЕРВЕРА (200 OK):

☕ Меню & B2C Предзаказы

Номенклатура блюд, модификаторы, оформление заказов и проверка статуса.

GET /api/v1/menu
Каталог меню и стоп-листы

Возвращает все категории, блюда, группы модификаторов и стоп-листы.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/orders/checkout
Оформление заказа (PWA / Mobile)

Создает заказ со статусом NEW, модификаторами, бонусами и генерирует ELQR.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "branch_id": "branch-uuid",
    "order_type": "takeaway",
    "pickup_time": "Через 15 минут",
    "guest_name": "Азамат",
    "guest_phone": "+996700123456",
    "payment_method": "elqr",
    "items": [
        {
            "item_id": "item-uuid-1",
            "quantity": 1,
            "modifiers": [
                {
                    "name": "Овсяное молоко",
                    "price": 60
                }
            ]
        }
    ]
}
ОТВЕТ СЕРВЕРА (200 OK):

💎 Лояльность & Антифрод TOTP

Генерация защищенного 60s QR-кода, баланс штампов 7+1 и кэшбек.

GET /api/v1/loyalty
Профиль лояльности гостя

Возвращает текущий кэшбек, баланс баллов и прогресс штамп-карты.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):
GET /api/v1/loyalty/totp
Генерация динамического 60s QR

Формирует защищенный временный токен по алгоритму RFC 6238 TOTP.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):

🍳 KDS Экран Кухни & Бара (Real-Time)

Живая лента кухонных заказов с поддержкой авто-опроса (2.5s) и сменой статусов.

GET /api/v1/kds/orders
Список активных заказов кухни

Возвращает заказы в статусах new, preparing, ready.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):
POST /api/v1/kds/orders/{order}/status
Смена статуса приготовления блюда

Переводит заказ по пайплайну: new -> preparing -> ready -> completed.

ПАРАМЕТРЫ ЗАПРОСА: 
{
    "status": "preparing"
}
ОТВЕТ СЕРВЕРА (200 OK):

👑 Платформа SuperAdmin & SaaS Биллинг KGS

Аналитика MRR, управление тарифами Standard (10 000 сом) и White-Label Pro (12 000 сом).

GET /api/v1/superadmin/metrics
Ключевые метрики платформы

MRR в сомах (KGS), активные заведения, распределение тарифов.

ПАРАМЕТРЫ ЗАПРОСА:
Тело запроса не требуется (GET запрос)
ОТВЕТ СЕРВЕРА (200 OK):