Работы в акте
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Работы, добавленные в акт: количество, цена, исполнители и связь с конкретной единицей ТО. Это работы документа; общий каталог описан отдельно в справочнике работ.
Доступные возможности и ограничения
Исторические строки читаются по доступу к акту: последующее архивирование каталога или отзыв права просмотра справочника не скрывают состав документа. Новый выбор работы требует текущего доступа к ней. Ручные unit_price и discount изменяются с обычным правом «Акты приёма оборудования → Изменение». Поля автора, состава исполнителей и количества не принимаются под другими именами.
Для акта с активным внешним списанием лояльности новая команда возвращает 409 EXTERNAL_EFFECT_RECONCILIATION_REQUIRED до изменения строки. Протокол восстановления изменений во внешних системах пока не реализован. Уже принятая команда повторяется по сохранённой записи об операции после проверки текущего доступа.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
id |
id строки |
только чтение |
operation_id |
обязательный id работы |
чтение и запись |
quantity |
положительная десятичная строка | чтение и запись |
unit_id |
код единицы из /reference | чтение и запись |
unit_price, discount |
денежная цена за единицу и денежная скидка на всю строку, не процент | чтение и запись |
note |
строка до 10000/null | чтение и запись |
assigned_user_ids |
список исполнителей | чтение и запись |
maintenance_schedule_id, equipment_id |
связи с единицей ТО | чтение и запись |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
acts:read/write и права просмотра/изменения актов; ручная цена и скидка используют обычное право изменения акта.
Для создания требуются operation_id и quantity (положительная десятичная строка). Для fixed базовая цена единицы — фиксированная цена работы, unit_id по умолчанию 0 (шт.); для hourly quantity означает нормочасы, unit_id=12 (н/ч), а базовая цена единицы — ставка часа мастерской, не рассчитанная стоимость всей работы. Отсутствующие unit_price/discount рассчитываются штатным ценообразованием строки акта с учётом договора/клиентской скидки и фиксируются при принятии; явная ручная цена/скидка требует обычного права изменения акта. assigned_user_ids=[] по умолчанию. Единица должна быть допустимой из quantity-units; для hourly смена на нечасовую единицу — 422. discount применяется один раз после quantity × unit_price; отрицательная или превышающая стоимость строки скидка — 422. Изменение сохраняет отсутствующие поля; изменение operation_id не разрешает незаметно переоценить историческую строку.
assigned_user_ids — множество до 100 доступных сотрудников. Maintenance_schedule_id/equipment_id задаются согласованной парой либо обе null. Для создания требуются If-Resource-Version акта; изменение и удаление требуют версии строки по правилам версий. Успех создание — 201, изменение — 200 с карточкой, delete=200 запись с признаком удаления; версия акта также меняется. Все связи и исполнители сохраняются в одной транзакции.
Правила и связи
- line_id всегда разрешается внутри
act_id; связанная заявка и оборудование должны входить в акт. - Завершённый документ защищён теми же правилами редактирования, что и панель.
- Повтор применения комплекта/добавления строки не дублирует работу и начисления.
- Изменение справочника работ не переписывает цену исторической строки.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| GET | /acts/{act_id}/operations |
Список с фильтрами и пагинацией |
| POST | /acts/{act_id}/operations |
Создание |
| GET | /acts/{act_id}/operations/{id} |
Карточка |
| POST | /acts/{act_id}/operations/{id}/update |
Изменение разрешённых полей |
| POST | /acts/{act_id}/operations/{id}/delete |
Удаление с проверкой зависимостей |
GET /acts/{act_id}/operations
Список с фильтрами и пагинацией.
Доступ. Разрешения подключения: acts:read. Права сотрудника: «Акты приёма оборудования → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
act_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
sort |
параметр запроса | строка | нет | нет | Допустимо: "id", "-id", "updated_at,id", "-updated_at,-id" |
page[size] |
параметр запроса | целое число | нет | нет | ≥ 1; ≤ 100 |
page[cursor] |
параметр запроса | строка | нет | нет | не более 8192 символов |
Ответы
| 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/acts/101/operations" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
POST /acts/{act_id}/operations
Создание.
Доступ. Разрешения подключения: acts:write. Права сотрудника: «Акты приёма оборудования → Изменение», «Акты приёма оборудования → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
act_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
operation_id |
целое число | да | нет | ≥ 1 |
quantity |
строка | да | нет | Шаблон: ^(?:0|[1-9][0-9]{0,8})(?:\.[0-9]{1,3})?$ |
unit_id |
целое число | нет | нет | Допустимо: 0, 12, 1, 11, 10, 2, 3, 4, 5, 6, 7, 8, 9 |
note |
строка / null | нет | да | не более 10000 символов |
assigned_user_ids |
массив | нет | нет | не более 100 элементов; Без повторов |
assigned_user_ids[] |
целое число | да | нет | ≥ 1 |
maintenance_schedule_id |
целое число / null | нет | да | ≥ 1 |
equipment_id |
целое число / null | нет | да | ≥ 1 |
unit_price |
объект | нет | нет | Только перечисленные ключи |
unit_price.amount |
строка | да | нет | Шаблон: ^(?:0|[1-9][0-9]{0,15})(?:\.[0-9]{1,4})?$; Условие: required_with:unit_price |
unit_price.currency |
строка | да | нет | не менее 3 символов; не более 3 символов; Условие: required_with:unit_price |
discount |
объект | нет | нет | Только перечисленные ключи |
discount.amount |
строка | да | нет | Шаблон: ^(?:0|[1-9][0-9]{0,15})(?:\.[0-9]{1,4})?$; Условие: required_with:discount |
discount.currency |
строка | да | нет | не менее 3 символов; не более 3 символов; Условие: required_with:discount |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 201 | Создано. Полная схема и пример |
| 400 | Некорректный запрос. Коды и формат ошибки |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 413 | Превышен размер. Коды и формат ошибки |
| 415 | Неподдерживаемый Content-Type. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 500 | Внутренняя ошибка, исход нужно уточнить. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 201 | Location |
строка |
Каждый ответ содержит новый 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/operations" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-act-operations-store:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.act-operations.store.json'
GET /acts/{act_id}/operations/{id}
Карточка.
Доступ. Разрешения подключения: acts:read. Права сотрудника: «Акты приёма оборудования → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
act_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
If-None-Match |
заголовок | строка | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 304 | Представление не изменилось, без тела. Условный GET |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | ETag |
строка | |
| 304 | ETag |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/acts/101/operations/101" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
POST /acts/{act_id}/operations/{id}/update
Изменение разрешённых полей.
Доступ. Разрешения подключения: acts:write. Права сотрудника: «Акты приёма оборудования → Изменение», «Акты приёма оборудования → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
act_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
operation_id |
целое число | нет | нет | ≥ 1 |
quantity |
строка | нет | нет | Шаблон: ^(?:0|[1-9][0-9]{0,8})(?:\.[0-9]{1,3})?$ |
unit_id |
целое число | нет | нет | Допустимо: 0, 12, 1, 11, 10, 2, 3, 4, 5, 6, 7, 8, 9 |
note |
строка / null | нет | да | не более 10000 символов |
assigned_user_ids |
массив | нет | нет | не более 100 элементов; Без повторов |
assigned_user_ids[] |
целое число | да | нет | ≥ 1 |
maintenance_schedule_id |
целое число / null | нет | да | ≥ 1 |
equipment_id |
целое число / null | нет | да | ≥ 1 |
unit_price |
объект | нет | нет | Только перечисленные ключи |
unit_price.amount |
строка | да | нет | Шаблон: ^(?:0|[1-9][0-9]{0,15})(?:\.[0-9]{1,4})?$; Условие: required_with:unit_price |
unit_price.currency |
строка | да | нет | не менее 3 символов; не более 3 символов; Условие: required_with:unit_price |
discount |
объект | нет | нет | Только перечисленные ключи |
discount.amount |
строка | да | нет | Шаблон: ^(?:0|[1-9][0-9]{0,15})(?:\.[0-9]{1,4})?$; Условие: required_with:discount |
discount.currency |
строка | да | нет | не менее 3 символов; не более 3 символов; Условие: required_with:discount |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 400 | Некорректный запрос. Коды и формат ошибки |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 413 | Превышен размер. Коды и формат ошибки |
| 415 | Неподдерживаемый Content-Type. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 500 | Внутренняя ошибка, исход нужно уточнить. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | Location |
строка |
Каждый ответ содержит новый 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/operations/101/update" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-act-operations-update:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.act-operations.update.json'
POST /acts/{act_id}/operations/{id}/delete
Удаление с проверкой зависимостей.
Доступ. Разрешения подключения: acts:write. Права сотрудника: «Акты приёма оборудования → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
act_id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
Тело — пустой JSON-объект {}. Другие ключи не принимаются.
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 400 | Некорректный запрос. Коды и формат ошибки |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 413 | Превышен размер. Коды и формат ошибки |
| 415 | Неподдерживаемый Content-Type. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 500 | Внутренняя ошибка, исход нужно уточнить. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | Location |
строка |
Каждый ответ содержит новый 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/operations/101/delete" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-act-operations-delete:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.act-operations.delete.json'