API RestoPOS для разработчиков

Обзор

Все методы живут под /api/v1 и отвечают JSON. Организация определяется по токену — передавать её идентификатор не нужно и нельзя.

Данные разделены на двух уровнях. Организация берётся из токена: увидеть чужие данные нельзя даже при подстановке идентификаторов. Филиал для большинства методов задаётся заголовком X-Branch-Id — токен может иметь доступ к нескольким филиалам, и система должна понимать, о каком идёт речь.

Аутентификация

Bearer-токены Sanctum. Токен передаётся заголовком Authorization: Bearer <token> в каждом запросе.

{
  "login":       "manager@example.com",
  "password":    "secret",
  "device_name": "Integration server"
}

{
  "message": "Успешная авторизация.",
  "data": {
    "user":       { "id": 12, "name": "Иван Петров", "…": "…" },
    "token":      "17|xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expires_at": "2026-09-06T10:00:00+05:00"
  }
}

{ "message": "Ошибка авторизации.", "errors": { "login": ["…"] } }

Токены для интеграций

Для сервер-серверных интеграций логин с паролем не нужен и вреден: пароль сотрудника меняется, токен умирает. Вместо этого выпускается служебный токен с ограниченными правами — командой на стороне ресторана:

php artisan integration:create-token

Такой токен получает права integration:read и integration:write. Метод приёма заказов требует именно integration:write — обычный пользовательский токен его не откроет.

Заголовки

Ответы и ошибки

Успешный ответ содержит data, ошибка — message и подробности. Списки приходят с пагинацией: параметры page и per_page, максимум 100 на страницу.

{ "success": true, "data": { "…": "…" }, "message": "Order accepted" }

{
  "success": false,
  "error": {
    "code":    "UNKNOWN_PRODUCTS",
    "message": "Товары не найдены: 412, 980.",
    "details": { "product_ids": [412, 980] }
  }
}

{ "message": "…", "errors": { "items": ["Заказ не может быть пустым."] } }

Лимиты

При превышении приходит 429 с заголовком Retry-After. Если интеграции штатно не хватает 60 запросов в минуту — это повод обсудить лимит, а не обходить его несколькими токенами.

Приём заказов

Главный метод для внешних витрин и агрегаторов. Заказ приходит без стола, кассира и открытой смены — у него отдельная точка входа, а не «подогнанный» обычный метод.

{
  "external_id": "SHOP-2026-000123",
  "source":      "lolotea",
  "type":        "delivery",
  "branch_id":   2,

  "customer": {
    "name":  "Иван Петров",
    "phone": "+998901234567",
    "email": "ivan@example.com"
  },

  "items": [
    {
      "product_id": 434,
      "quantity":   2,
      "unit_price": 22000,
      "notes":      "без сахара",
      "modifiers": [
        { "modifier_id": 89, "quantity": 1, "price_delta": 3000 }
      ]
    }
  ],

  "totals": {
    "subtotal":     44000,
    "discount":     0,
    "delivery_fee": 10000,
    "total":        54000,
    "currency":     "UZS"
  },

  "payment": {
    "method":                  "click",
    "status":                  "paid",
    "paid_amount":             54000,
    "external_transaction_id": "clk_88213"
  },

  "delivery": {
    "address":      "Ташкент, ул. Амира Темура, 5",
    "lat":          41.311081,
    "lng":          69.240562,
    "scheduled_at": "2026-08-07T18:30:00+05:00"
  },

  "notes": "Позвонить за 10 минут"
}

{
  "success": true,
  "data": {
    "order": {
      "id":           "973053a3-008f-47a7-ba3d-9598cc95dd4f",
      "order_number": "20260807-0002",
      "external_id":  "SHOP-2026-000123",
      "status":       "new",
      "type":         "delivery"
    }
  },
  "message": "Order accepted"
}

Обязательные поля

Повторная отправка

Сеть рвётся, ответ теряется — повторяйте запрос с тем же Idempotency-Key. Тот же ключ с тем же телом вернёт исходный заказ и код 200 вместо 201, второй заказ на кухню не уйдёт. Тот же ключ с другим телом — это ошибка на вашей стороне, и она честно возвращается конфликтом.

Меню

Категории, товары и модификаторы. Требуют X-Branch-Id.

Категории и товары также поддерживают POST, PUT и DELETE по стандартной схеме REST-ресурса.

Заказы

Работа с заказами в зале. Для приёма заказов извне используйте отдельный метод — этот рассчитан на кассира и открытую смену.

Клиенты

Склад

Учёт ведётся по ингредиентам, а не по готовым блюдам — остаток товара выводится из техкарты.

Доставка

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

Отчёты и финансы

Все методы ядра

Кроме перечисленного, в API есть разделы залов и столов, бронирований, KDS, сотрудников, принтеров и уведомлений — они рассчитаны на внутренние приложения и в этот справочник не вынесены.

Полная машинописная спецификация лежит в репозитории: docs/api_specification.yaml, формат OpenAPI 3.0.3 — её можно открыть в любом редакторе Swagger и сгенерировать клиент.