Документация API

Ниже — краткое текстовое описание API сервиса fork.by. Для интерактивного просмотра используйте Swagger UI, а исходный JSON доступен по адресу /v3/api-docs.

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

Аутентификация выполняется через логин/пароль и выдачу JWT токена.

Важно: все защищённые запросы (в частности, весь раздел BackOffice) выполняются с заголовком Authorization в формате Bearer <token>.

Authorization: Bearer <JWT_TOKEN>

• POST /api/1.0/login — вход. Тело запроса: { "username": "...", "password": "..." }. Ответ: token, tokenType, expiresIn и данные пользователя.
• GET /api/1.0/test-auth — проверка, что запрос аутентифицирован (возвращает строку при успехе).

BackOffice (управление каталогом)

Раздел предназначен для администраторов каталога. Во многих методах используется параметр пути {id} — идентификатор компании.

Авторизация обязательна: каждый запрос в этом разделе должен включать заголовок Authorization: Bearer <JWT_TOKEN>.

Меню (позиции)

Ниже — 4 операции для работы с позициями меню. Во всех URL параметр {id} — идентификатор компании/каталога.

Поля MenuItem (что означают)

• id: string — идентификатор позиции (как правило, выдаётся сервером).
• catId: string — id каталога/компании (если используется на бэкенде).
• title: string — название позиции.
• description: string — описание/состав.
• price: number(double) — цена.
• weight: integer(int32) — вес (обычно граммы).
• bzhu: string — Б/Ж/У (например "10/5/20").
• ccal: number(double) — калорийность (ккал).
• createdDate: string(date-time) — дата создания (обычно выставляется сервером).
• status: string — статус: ACTIVE / PAUSED / HIDDEN.
• categoryId: string — id категории, к которой относится позиция.
• image: string[] — массив ссылок/путей к изображениям (часто — URL из /api/1.0/backoffice/upload).

Получение меню

GET /api/1.0/backoffice/{id}/menu

Пример ответа 200 (CatalogDetails)

{
  "menu": [
    {
      "id": "m1",
      "title": "Паста карбонара",
      "description": "Сливочный соус, бекон, пармезан",
      "catId": "catalog1",
      "createdDate": "2026-01-08T10:41:02.753+00:00",
      "price": 18.5,
      "weight": 350,
      "bzhu": "12/14/28",
      "ccal": 420,
      "status": "ACTIVE",
      "categoryId": "c1",
      "image": ["/uploads/menu/m1.jpg"]
    }
  ],
  "categories": [
    { "id": "c1", "companyIds": ["cmp1"], "name": "Паста", "order": { "cmp1": 1 }, "images": ["/uploads/menu/pasta.jpg"] }
  ]
}

Добавление позиции меню

POST /api/1.0/backoffice/{id}/menu

Если нужно добавить/обновить фото, сначала загрузите изображение через /api/1.0/backoffice/upload, а затем положите полученный путь в image[] у MenuItem.

{
  "message": "File uploaded successfully",
  "filePath": "/uploads/menu-items/6d6b7f44-4018-4072-bbc9-829e519705fe.jpg"
}

Пример запроса (MenuItem)

{
  "title": "Салат Цезарь",
  "description": "Курица, салат ромэн, пармезан, соус",
  "price": 12.9,
  "weight": 250,
  "bzhu": "18/10/12",
  "ccal": 310,
  "status": "ACTIVE",
  "categoryId": "c2",
  "image": ["/uploads/menu-items/6d6b7f44-4018-4072-bbc9-829e519705fe.jpg"]
}

Редактирование позиции меню

PUT /api/1.0/backoffice/{id}/menu/{menuItemId}

Пример запроса (MenuItem)

{
  "id": "m1",
  "title": "Паста карбонара (большая порция)",
  "description": "Сливочный соус, бекон, пармезан",
  "price": 20.5,
  "weight": 450,
  "bzhu": "14/16/32",
  "ccal": 520,
  "status": "PAUSED",
  "categoryId": "c1",
  "image": ["/uploads/menu/m1.jpg"]
}

В случае, если нужно обновить только часть полей (например только цену), можно отправить только те поля, которые нужно изменить.

Пример частичного обновления (только цена)

{
  "price": 19.9
}

Удаление позиции меню

DELETE /api/1.0/backoffice/{id}/menu/{menuItemId}

Тело запроса отсутствует — удаление выполняется по параметрам пути.

Категории

Поля Category (что означают)

• id: string — идентификатор категории (обычно выдаётся сервером).
• companyIds: string[] — компании/каталоги, использующие эту категорию.
• name: string — название категории (например: “Пицца”, “Салаты”).
• order: object — порядок отображения по компаниям (companyId → order, меньше = выше в списке).
• images: string[] — ссылки на изображения из позиций меню этой категории.

• GET /api/1.0/backoffice/{id}/categories — получить список категорий компании.
• POST /api/1.0/backoffice/{id}/categories — добавить категорию (если имя уже есть — компания добавляется в companyIds).
• PUT /api/1.0/backoffice/{id}/categories/{categoryId} — обновить категорию. Смена имени создаёт/присоединяет категорию с новым именем, переносит позиции меню компании и убирает компанию из старой категории.
• DELETE /api/1.0/backoffice/{id}/categories/{categoryId} — убрать компанию из companyIds (документ удаляется, если список пуст).

Заказы

• GET /api/1.0/backoffice/{id}/orders — получить заказы по каталогу. Поддерживаются query-параметры: sort (date_desc/date_asc/status_asc/status_desc) и status (повторяемый фильтр, например status=CREATED&status=CONFIRMED).
• PATCH /api/1.0/backoffice/{id}/orders/{orderId} — обновить статус заказа. Тело запроса: объект с одним ключом status.

Загрузка файлов

• POST /api/1.0/backoffice/upload — загрузить файл. Формат: multipart/form-data, поля: file (binary), folder (например menu). Ответ: объект с данными о загруженном файле (например, URL/путь).

Ошибки

Для большинства backoffice-методов возможны ответы с ошибками 400, 403, 404, 500. Формат ошибки: { errorMessage, code, reasonPhrase } (см. ErrorResponse).

Примечания

• Полный список полей моделей и точные типы смотрите в OpenAPI JSON.
• Если вы используете JWT, передавайте токен в заголовке Authorization согласно настройкам сервера (обычно Bearer <token>).