Товары и запчасти

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

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

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

Назначение

Создание и ведение номенклатуры с артикулами, ценами, изготовителем, типом, гарантией и признаками учёта.

Доступные возможности и ограничения

Реализованы GET списка/карточки и POST для создания, изменения, архивирования и восстановления. Изменения используют обязательные Idempotency-Key и, кроме создания, If-Resource-Version. Записи об операциях сохраняются вместе с бизнес-записью и событием; повтор заново проверяет текущий доступ. Доступ к API — «Энтерпрайз», «Энтерпрайз Про» или действующий пробный период; «Энтерпрайз Лайт» не включает API.

Требуются products:read и текущее «Товары → Просмотр». Поле purchase_price читается по этому же праву и изменяется с «Товары → Изменение». filter[archived]=true дополнительно требует права удаления товара. external_id читается только для текущего подключения.

data.version — строка Unix-секунд из updated_at. Два изменения в одну секунду могут иметь одинаковую версию. Для проверки изменений используйте правила синхронизации. Карточка также возвращает отдельный ETag своего представления.

Признаки серийного учёта, маркировки и asset_tracking_type можно задать при создании. Изменение режима существующего товара пока возвращает 409 TRACKING_MODE_CHANGE_UNAVAILABLE. Изменение свойств обновляет updated_at товара.

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

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

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

products:read/write и «Товары → Просмотр, Изменение, Удаление»; purchase_price использует обычные права товара.

Фильтры: q, sku, barcode, manufacturer_id, product_type_id, category_id, external_id, updated_since, archived.

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

• Артикулы и штрихкоды — строки; сохраняются ведущие нули и внутренние символы.
• Изменение товарной карточки не создаёт поступление, продажу или списание.
• Архив сохраняет исторические строки документов и недоступен для новой продажи по умолчанию.
• Изменение режима серийного/маркированного учёта проверяется по существующим остаткам.
• Свойства принадлежат типу товара и принимаются по явной схеме.

Операции

POST /products

Создание.

Доступ. Разрешения подключения: products: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/products" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-catalog-products-store:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.catalog-products.store.json'

GET /products

Список с фильтрами и пагинацией.

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

Параметры

Ответы

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

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

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

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

POST /products/{id}/update

Изменение разрешённых полей.

Доступ. Разрешения подключения: products: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/products/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-catalog-products-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.catalog-products.update.json'

POST /products/{id}/archive

Архивация.

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

Параметры

Тело запроса

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/products/101/archive" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-catalog-products-archive:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.catalog-products.archive.json'

POST /products/{id}/restore

Возврат товара из архива.

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

Параметры

Тело запроса

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/products/101/restore" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-catalog-products-restore:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.catalog-products.restore.json'

GET /products/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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