Склады

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

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

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

Назначение

Доступные склады, включая общие склады организации и выездные склады сотрудников.

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

Публичное поле	Формат и смысл	Доступ
`id, name`	`id` и название	только чтение
`workshop_id`	id/null; null — общий склад	только чтение
`assigned_user_id`	id/null владельца выездного склада	только чтение
`is_active, is_default, description`	доступность, основной склад, описание	только чтение

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

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

stocks:read и право просмотра складских данных; ограничение мастерских применяется и к общим складам по действующим правилам.

Фильтры: workshop_id, assigned_user_id, is_active.

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

Подключение видит только разрешённые склады; null workshop_id не означает доступ к любому складу.
Выбор склада при добавлении товара проверяется заново.
Настройка инфраструктуры склада не смешивается с CRUD товарной карточки.

Операции

Метод	Путь	Назначение
GET	`/stocks`	Список доступных складов
GET	`/stocks/{id}`	Карточка склада

GET /stocks

Список доступных складов.

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

Параметры

Имя	Где	Тип	Обязательно	null	Ограничения
`Authorization`	заголовок	строка	да	нет	`Bearer <SERVICEAPP_TOKEN>`
`sort`	параметр запроса	строка	нет	нет	Допустимо: `"id"`, `"-id"`, `"updated_at,id"`, `"-updated_at,-id"`
`page[size]`	параметр запроса	целое число	нет	нет	≥ 1; ≤ 100
`page[cursor]`	параметр запроса	строка	нет	нет	не более 8192 символов
`filter[workshop_id]`	параметр запроса	целое число	нет	нет	≥ 1
`filter[assigned_user_id]`	параметр запроса	целое число	нет	нет	≥ 1
`filter[is_active]`	параметр запроса	строка	нет	нет	Допустимо: `"true"`, `"false"`

Ответы

HTTP	Назначение и схема
200	Успех. Полная схема и пример
401	Требуется действующий Bearer. Коды и формат ошибки
403	Недостаточно допуска. Коды и формат ошибки
404	Не найдено или недоступно. Коды и формат ошибки
409	Конфликт состояния или повтора. Коды и формат ошибки
422	Ошибка входных данных. Коды и формат ошибки
429	Лимит запросов, Retry-After. Коды и формат ошибки
503	Временно недоступно. Коды и формат ошибки

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

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

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

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

GET /stocks/{id}

Карточка склада.

Параметры

Имя	Где	Тип	Обязательно	null	Ограничения
`Authorization`	заголовок	строка	да	нет	`Bearer <SERVICEAPP_TOKEN>`
`id`	путь	строка	да	нет	Шаблон: `^(?:[0-9]+)$`
`If-None-Match`	заголовок	строка	нет	нет	—

Ответы

HTTP	Назначение и схема
200	Успех. Полная схема и пример
304	Представление не изменилось, без тела. Условный GET
401	Требуется действующий Bearer. Коды и формат ошибки
403	Недостаточно допуска. Коды и формат ошибки
404	Не найдено или недоступно. Коды и формат ошибки
409	Конфликт состояния или повтора. Коды и формат ошибки
422	Ошибка входных данных. Коды и формат ошибки
429	Лимит запросов, Retry-After. Коды и формат ошибки
503	Временно недоступно. Коды и формат ошибки

HTTP	Заголовок ответа	Тип	Описание
200	`ETag`	строка
304	`ETag`	строка

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

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