Оборудование в акте

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

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

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

Назначение

Состав оборудования акта и создание монтируемых единиц без смешения связей act_equipment, заявок ТО и продаж со склада.

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

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

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

acts:read/write + equipment:read/write; для ТО также maintenance_schedules:write; для продажи со склада — права товара и склада.

Режимы добавления

GET использует общую курсорную пагинацию и сортировки оборудования. Каждая строка data содержит equipment (публичную карточку из контракта equipment), act_product_id и maintenance_schedules. Ссылка на строку продажи возвращается только для текущего акта; исходная продажа из другого акта не раскрывается. Заявки ограничены текущим актом и собственными правами чтения: каждая содержит id, status, checklist: {completed, total} и version. Без maintenance_schedules:read или права «ТОиР — Обслуживание → Просмотр» массив пуст; скрытые заявки не участвуют в прогрессе. Чтение не создаёт чек-листы, записи об операции или события и не изменяет даты.

Все режимы требуют mode и If-Resource-Version акта. Общий максимум атомарного состава — 100 единиц, без скрытого разбиения на частично успешные запросы.

• existing: ровно equipment_ids или maintenance_schedule_ids, непустой массив уникальных ID, плюс expected_versions каждого выбранного объекта. Заявки разрешены только для акта ТО; оборудование проходит соответствующий доменный путь данного типа акта. Нельзя незаметно заменить выбранную открытую заявку новой.
• client_unit: обязательный unit с name; разрешены equipment_model_id, manufacturer_id, device_type_id, model_name, serial_number, inventory_number, customer_site_id, manufacture_date, installation_date, warranty_expires_at, location, note и custom_fields по equipment. customer_id выводится из акта. Product_id/quantity/equipment_ids запрещены. Для монтажа создаётся одна pending_install единица, для ТО — одна единица и её заявка.
• sold_unit: только монтаж; product_id обязателен, quantity=1 по умолчанию. Объект unit содержит паспортные сведения, кроме клиента, названия, товара каталога и статуса. При quantity>1 нельзя передавать серийный номер в unit: для серийного товара нужен массив serial_numbers из quantity уникальных номеров. На каждую единицу создаются отдельные строки продажи и карточки оборудования. Для несерийного товара serial_numbers не передаётся. Цена берётся из каталога; ручная замена цены в этой команде не поддерживается.

В ответе 201 для новых единиц или 200 для присоединения существующих: data.equipment_ids, data.maintenance_schedule_ids и data.act_product_ids; meta.affected_resources содержит версии. Удаление принимает {} с If-Resource-Version акта, возвращает 200 с фактически оставшимся составом; защищённая история — 409. Удаляется связь/допустимая pending единица согласно домену, а не безусловно карточка существующего оборудования.

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

• Каждая единица принадлежит клиенту акта; нельзя просто синхронизировать произвольные equipment_ids.
• Удаление из состава не означает безусловное удаление карточки оборудования.

Операции

GET /acts/{act_id}/equipment

Оборудование акта и состояние выполнения ТО.

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

Параметры

Ответы

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

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

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

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

POST /acts/{act_id}/equipment

Добавление существующих или новых единиц по явному режиму.

Доступ. Разрешения подключения: acts:write, equipment:read, equipment:write. Права сотрудника: «Акты приёма оборудования → Изменение», «ТОиР — Оборудование → Просмотр», «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

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

Условные требования: existing: equipment_ids XOR maintenance_schedule_ids + expected_versions; client_unit: unit.name; sold_unit: product_id. См. описание ресурса.

Ответы

Каждый ответ содержит новый 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/acts/101/equipment" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-act-equipment-store:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.act-equipment.store.json'

POST /acts/{act_id}/equipment/{equipment_id}/remove

Удаление единицы из состава с проверкой последствий.

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