Ротор.Склад — документация API

Учёт остатков по движениям — точно, без люфта и ухода в минус

Доступ

Каждый запрос к /api/* требует ключ в заголовке X-Api-Key. Административные операции (управление ключами) требуют заголовок X-Admin-Key. Ключи заводит администратор; новый ключ показывается один раз.

Остаток считается по движениям

Остаток = приходы − списания − резервы + снятия резервов

Приход и списание меняют физический остаток. Резерв уменьшает доступный остаток, снятие резерва возвращает его. Отрицательный доступный остаток запрещён — сервис отвечает 409 Conflict.

Эндпоинты

POST/api/auth/check

Проверить API-ключ из заголовка X-Api-Key.

GET/api/products

Список и поиск товаров по артикулу и названию (?search=).

GET/api/products/{id}

Карточка товара с вычисленным остатком.

POST/api/products

Создать товар (артикул, название, цена, единица).

PATCH/api/products/{id}

Изменить цену, единицу или другие поля товара.

GET/api/suppliers

Список поставщиков.

GET/api/suppliers/{id}

Получить поставщика по id.

POST/api/suppliers

Создать поставщика.

PATCH/api/suppliers/{id}

Изменить поставщика.

POST/api/movements

Создать движение: income (приход), expense (списание), reserve (резерв) или unreserve (снятие резерва).

GET/api/movements

История движений с фильтрами (product_id, movement_type, from, to).

GET/api/products/{id}/movements

История движений по конкретному товару.

GET/api/reports/stock

Текущие остатки по всем товарам.

GET/api/reports/stock-on-date

Отчёт остатков на дату в JSON (?date=2026-09-06).

GET/api/admin/keys

Только X-Admin-Key. Список ключей.

POST/api/admin/keys

Только X-Admin-Key. Создать ключ (показывается один раз).

PATCH/api/admin/keys/{id}

Только X-Admin-Key. Отозвать или активировать ключ.

Ошибки

Каждая ошибка — машиночитаемый JSON с code, message и request_id.

{
  "code": "negative_stock",
  "message": "Отрицательный остаток запрещён",
  "request_id": "a1b2c3d4e5f6a7b8",
  "conflict_reason": "negative_stock",
  "current_available": 0,
  "shortage": 5
}

Коды: 401 — неверный ключ, 403 — нет прав администратора, 404 — запись не найдена, 409 — отрицательный остаток или дубликат артикула, 422/400 — ошибка валидации входных данных.