Места хранения

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

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

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

Назначение

Справочник мест хранения: чтение, создание, изменение и контролируемое удаление.

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

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

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

reference:read/write/delete и «Справочники → Просмотр, Изменение, Удаление»; дополнительные ограничения связанных сущностей сохраняются. Значения финансовых справочников не дают права читать или проводить деньги.

Фильтры: stock_id, is_active, q

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

Для создания обязателен непустой name до 255 символов. По умолчанию stock_id, rack_id, row_number, column_number, barcode и description равны null, is_active=true. При изменении отсутствующие поля сохраняются. barcode — строка до 255 символов или null; description — строка до 10000 символов или null; is_active — логическое значение JSON. Идентификаторы и координаты передаются целыми числами JSON. row_number и column_number положительны и задаются вместе. Если указан rack_id, проверяются его склад и допустимые номера рядов и столбцов. Сменить склад занятого места нельзя: 409 RESOURCE_IN_USE.

Создание возвращает 201 с карточкой, изменение — 200. Удаление принимает {} и возвращает 200 с признаком удаления. Изменение и удаление требуют If-Resource-Version места; создание не требует версии. Некорректные связи или координаты возвращают 422, недоступный склад или место — 404. События place.created, place.updated и place.deleted содержат идентификатор, версию и признак удаления. При повторе запроса проверяется доступ к исходному складу.

• Склад, rack_id и пространственные координаты должны описывать одну согласованную структуру хранения.
• Изменение места не перемещает товар; складское движение остаётся отдельной операцией.
• Одинаковое имя само по себе не является уникальным бизнес-ключом; сопоставление интеграции задаётся явно.
• Idempotency-Key защищает создание и изменение, включая параллельные запросы; GET не создаёт записи по умолчанию.

Операции

GET /reference/places

Список.

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

Параметры

Ответы

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

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

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

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

POST /reference/places

Создание записи.

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

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

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

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

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

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

curl --silent --show-error --globoff --request POST \
  "$API/reference/places" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-places-store:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.places.store.json'

GET /reference/places/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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

POST /reference/places/{id}/update

Изменение.

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

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

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

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

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

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

curl --silent --show-error --globoff --request POST \
  "$API/reference/places/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-places-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.places.update.json'

POST /reference/places/{id}/delete

Удаление при отсутствии запрещённых зависимостей.

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

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Тело — пустой JSON-объект {}. Другие ключи не принимаются.

Ответы

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

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

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

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

curl --silent --show-error --globoff --request POST \
  "$API/reference/places/101/delete" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-reference-places-destroy:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.reference.places.destroy.json'