Акты ремонта, монтажа и ТО

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

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

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

Назначение

Акт — основной рабочий документ СервисАпп. API позволяет создавать и изменять акты ремонта, монтажа и ТО, добавлять работы, товары и оборудование, а также выполнять допустимые переходы статуса.

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

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

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

Карточка содержит ссылки только для чтения: links.edit, links.portal, links.public: страницу редактирования с учётом типа акта, карточку в клиентском кабинете и короткую клиентскую ссылку. Правила доступа и null описаны в общих правилах.

acts:read/write/delete; «Акты приёма оборудования → Просмотр, Изменение, Удаление»; тариф и направление мастерской; права смены статуса и клиента.

customer_note, internal_note и result читаются с обычным правом «Акты приёма оборудования → Просмотр» и изменяются с «Акты приёма оборудования → Изменение», включая очистку значением null. Для смены customer_id у существующего акта дополнительно нужно «Акты приёма оборудования → Смена клиента у документа».

Фильтры: type, number, customer_id, workshop_id, status_id, manager_id, technician_id, external_id, created_from/to, updated_since.

Схемы команд

Для создания обязательны type, customer_id и workshop_id. Если status_id не передан, выбирается первый доступный незавершающий статус подходящего типа по настроенному порядку. Если такого статуса нет, возвращается 409 INITIAL_STATUS_UNAVAILABLE. Создать завершённый акт нельзя. По умолчанию manager_id указывает на владельца токена, если назначение допустимо, technician_id=null, а defect_ids, device_part_ids и custom_fields — пустые массивы. Склад выбирается из доступных складов мастерской. Если склад по умолчанию недоступен, передайте stock_id явно.

Defect_ids/device_part_ids — множества максимум из 100 ID; переданный массив заменяет связь целиком, [] очищает, отсутствие при изменении сохраняет. customer_note/internal_note/result — до 10000 символов/null. Для создания и изменения остальные связи, типы и права проверяются до записи; изменение клиента/мастерской/склада с несовместимым существующим составом даёт 409 ACT_RELATIONS_CONFLICT, а не переносит историю молча.

При duplicate обычные публичные поля и разрешённые дополнительные поля копируются; internal_note/result копируются по обычным правам акта. Ремонт сохраняет доступные связи оборудования; монтаж создаёт новые pending_install без физических серийных/инвентарных номеров и дат эксплуатации, связывая их с новыми товарными строками. ТО создаёт новые planned-заявки и свежие чек-листы без отметок выполнения. Суммы строк сохраняются, а недопустимые стандартные quantity/unit/money отклоняют команду целиком с ACT_COMPOSITION_CONFLICT до создания копии. Склад применяется один раз по текущему режиму; допустимые штатные предупреждения сохраняются, недопустимая нехватка в режиме учёта без партий откатывает операцию. Разные ключи могут создать разные копии неизменённого источника.

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

• Тип документа и основное направление мастерской — разные настройки. Обычная команда изменения не меняет тип акта.
• Завершение монтажа вводит подготовленное оборудование в эксплуатацию; завершение ТО согласует заявки, результаты проверок и договор обслуживания.
• Смена статуса вызывает единый доменный путь: разрешённый переход, согласование сметы, склад, гарантии и уведомления.
• Если для акта подготовлено или подтверждено списание бонусов внешней программы, новые команды смены статуса, удаления, копирования, применения комплекта и изменения состава возвращают 409 EXTERNAL_EFFECT_RECONCILIATION_REQUIRED. Встроенная бонусная программа и акты без внешнего списания обрабатываются по обычным правилам.
• status поддерживает ремонтные акты с выездами, работами и обычными товарами: штатный переход фиксирует гарантии работ и зарплатные начисления, завершает отложенное списание либо сохраняет немедленное, а при возврате в работу восстанавливает резерв. В affected_resources входят акт, все связанные выезды и товары, а также впервые завершённые работы. Штатные складские предупреждения сохраняются в записи об операции; недоступный явно выбранный серийный номер отклоняет весь переход. Повтор не создаёт второе списание, начисление или SMS-задачу.
• Завершение монтажа вводит оборудование со статусом pending_install в эксплуатацию. Сохраняется ручная гарантия или срок из товара связанной строки продажи. Оборудование добавляется в единственный подходящий договор; если открытой заявки ещё нет, создаётся первое ТО с чек-листом. День ввода определяется по последнему фактическому выезду в часовом поясе организации; end_date остаётся календарной датой. Все изменения оборудования, договоров, заявок и чек-листов перечислены в meta.affected_resources. Нужны equipment:read/write, для товара — products:read, для изменения состава договора — service_contracts:read/write, для создания ТО — maintenance_schedules:read/write, для чек-листа — maintenance_checklists:read/write и соответствующие права сотрудника. Автоматически выбранный договор и существующая заявка также должны быть доступны. Ошибка любой единицы отменяет весь переход. Повтор запроса не выполняет ввод, ТО или списание заново. Возврат акта в работу сохраняет ввод и гарантию. При утрате прав или смене принадлежности оборудования и договора сохранённый ответ становится недоступен.
• Смена статуса акта ТО учитывает связанные заявки, сценарии, индивидуальные и автоматические планы, договоры и результаты проверок. При завершении проверяются обязательные поля и чек-лист, применяются сохранённые правила, обновляются сроки и наработка оборудования, изменяется или создаётся план сценария. Фактически изменённые заявки, результаты и планы входят в meta.affected_resources. Нужны maintenance_schedules:read/write и equipment:read/write; для сценария — maintenance_scenarios:read, для плана — maintenance_plans:read/write, для договора — service_contracts:read и права просмотра клиента и договора. Изменение результатов требует maintenance_checklists:read/write. Проверяются мастерская, клиент, связи и состав оборудования договора. Завершение не начисляет абонентскую плату и не выполняет оплату. Любая ошибка отменяет весь переход. При повторе запроса доступ к исходным и текущим записям проверяется заново. Возврат старого ТО в работу не отменяет более позднее завершение оборудования или цикла плана. Версии сохраняют секундную точность.
• Товарные строки, связанные с оборудованием или заявкой ТО, создают или снимают оснащение: компоненты, лицензии и сертификаты с общим или серийным учётом. Проверяются текущие товар, оборудование, заявка и существующее оснащение. Нужны products:read, equipment:read/write, equipment_assignments:read/write, а для связи с заявкой — maintenance_schedules:read. Если история продления защищена, возвращается 409 ASSIGNMENT_HISTORY_LOCKED. Повтор запроса не создаёт вторую запись оснащения.
• Гарантийная цепочка проверяется как источник чтения: предыдущий документ и прямые гарантийные дочерние акты могут иметь любой допустимый тип. Нужны acts:read, право просмотра и доступ к их мастерским; право записи источника не требуется. Оборудование ремонта дополнительно требует equipment:read. Исходная и текущая цепочки входят в закрытый контекст записи об операции; изменение клиентской принадлежности, связей или видимости запрещает replay. Связанные документы не изменяются самим переходом.
• Существующие оплаты, счета, онлайн-счета, складские документы, УПД и заказы сохраняются при смене статуса и переоткрытии: эта команда не меняет их и не раскрывает финансовые карточки. Проект монтажа требует acts:read и текущего доступа к направлению/мастерской; явный договор — service_contracts:read и право просмотра. Их клиент и мастерская должны соответствовать акту. Исходные ссылки и контекст сохраняются для проверки повторные запросы, в том числе при наличии бот-уведомления. Некорректные связи дают 409 ACT_RELATIONS_CONFLICT; смена контекста после принятия запрещает запись об операции.
• При смене статуса задания на уведомление через подключённые Telegram и MAX сохраняются вместе с результатом команды. Ответ 200 подтверждает сохранение изменений и заданий, но не доставку сообщений. Повтор запроса не создаёт второе уведомление. Перед отправкой проверяются текущие права, клиент, получатель и актуальность перехода. При неизвестном результате отправки автоматический повтор прекращается.
• Клиент не задаёт признаки согласования, время завершения, расчётные показатели и токены клиентских ссылок.
• Работы и товары изменяются через вложенные ресурсы; итоги и ЗП вычисляет сервер.
• Изменение строк, связей, дополнительных полей и вложений обновляет updated_at акта в той же транзакции.
• GET не создаёт клиентскую ссылку, просмотр клиента, оборудование или чек-лист.

Пример входных данных

{
  "external_id": "crm-act-301",
  "type": "repair",
  "customer_id": 12,
  "workshop_id": 2,
  "manager_id": 5,
  "manufacturer_id": 3,
  "model_name": "Модель А",
  "serial_number": "SN-001",
  "customer_note": "Не включается"
}

Операции

POST /acts/{id}/apply-kit

Применение комплекта работ и товаров.

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

POST /acts/{id}/duplicate

Копирование по обычным правилам.

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

GET /acts

Акты доступных мастерских с фильтрами и пагинацией по курсору.

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

Параметры

Ответы

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

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

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

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

POST /acts

Создание открытого акта ремонта, монтажа или ТО.

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

GET /acts/{id}

Карточка акта, включая служебную заметку и результат работ.

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

Параметры

Ответы

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

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

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

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

POST /acts/{id}/update

Изменить разрешённые поля акта, сохраняя отсутствующие значения.

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

POST /acts/{id}/status

Смена статуса акта с согласованным обновлением склада, гарантий и обслуживания.

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

POST /acts/{id}/delete

Удалить акт без зависимостей; повтор возвращает сохранённый tombstone.

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