Остатки и доступность товаров

Все операции. Авторизация. Запросы и повторы.

Все пути в этом файле дополняют /api/v1 на домене организации.

Описание и ограничения

Назначение

Раздельное чтение физического количества, резервов и свободной доступности без ручного изменения учётных агрегатов.

Поля и назначение

Обязательность и null указаны в схемах каждой операции ниже.

Доступ и выборка

stock_levels:read и «Остатки → Просмотр»; обе связи должны быть доступны.

Фильтры: product_id, q; ограниченный набор товаров для пакетного чтения.

Правила и связи

• Доступность считается действующим складским сервисом, а не независимым API-счётчиком.
• available может быть отрицательным после мягкого резервирования сверх физического количества; API не ограничивает его нулём и не выдаёт за фактическое списание. Это quantity минус активный reserved по одному согласованному чтению.
• GET не исправляет резервы и не выполняет переучёт.
• Запись материала в акт проводится через act-products; прямой POST для quantity/reserved отсутствует.

Серийные резервы и старые данные

Общий складской сервис сохраняет выбранные серийные номера в снимке резерва и закрепляет имеющийся экземпляр за одним активным резервом. Мягкая бронь не уменьшает физический остаток. Приход ожидаемого номера связывается с сохранённым снимком, а не с текущим текстом строки документа. Снятие резерва освобождает экземпляр; выдача разрешена его владельцу. Перемещение, инвентаризация и отмена прихода не обходят действующую бронь. Отключение партионного учёта не разрешает списать серийный товар с такими резервами через старый путь.

У нового резерва пустой список серийных номеров означает резерв количества без выбора экземпляров. У старой записи null означает, что принадлежность экземпляров неизвестна. Операция с таким резервом может вернуть 409 SERIAL_UNAVAILABLE: пересохраните исходные строки документа, чтобы заново сформировать резерв. Чтение остатков само по себе не исправляет такие записи.

Складские изменения применяются целиком. При конфликте параллельных операций запрос может завершиться ошибкой; частичный успех не возвращается.

Операции

GET /stocks/{stock_id}/levels

Позиции и доступность склада.

Доступ. Разрешения подключения: stock_levels:read. Права сотрудника: «Остатки → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/stocks/101/levels" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

GET /stocks/{stock_id}/levels/{product_id}

Остаток конкретного товара.

Доступ. Разрешения подключения: stock_levels:read. Права сотрудника: «Остатки → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/stocks/101/levels/101" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"