Статусы актов и переходы

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

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

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

Назначение

Создание и настройка статусов для каждого типа акт, включая завершение, SLA, доступ сотрудников и допустимые переходы.

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

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

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

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

Фильтры: act_type, completes_act.

Общие статусы и команды настройки

Для создания требуются name, color и act_type, причём явный null создаёт общий статус; отсутствие act_type не выбирает тип автоматически. name — непустая строка до 255 символов; color — имя цвета из латинских букв, цифр, _ и - (до 32 символов) либо #RRGGBB. Значения по умолчанию: completes_act=false, accrues_wages=false, sort_order=0. filter[act_type]=repair возвращает общие и ремонтные статусы, аналогично другим типам. filter[act_type]=shared выбирает только общие; отсутствие фильтра — все доступные. В ответе общего статуса act_type=null. Изменить тип после создания нельзя. Типы installation/maintenance выдаются и принимаются только при доступности соответствующего модуля.

transitions принимает { "next_status_ids": [1, 2] } и If-Resource-Version статуса. Список заменяется целиком; допускается не более 100 уникальных идентификаторов. Статус определённого типа может переходить в общие статусы и статусы того же типа. Общий статус может ссылаться на статусы разных типов; при переходе акта учитываются его тип и права сотрудника. Повторная установка текущего статуса не меняет данные. Пустой next_status_ids снимает ограничения переходов, а не запрещает выход из статуса.

access требует оба массива { "role_ids": [], "user_ids": [] }, If-Resource-Version статуса; оба набора заменяются атомарно. Доступ получает сотрудник из user_ids либо с одной из role_ids. Оба пустых массива снимают ограничение установки статуса. Возможность администратора с «Системные настройки → Информация о компании» менять статус сохраняется. Роли для выбора читаются через GET /reference/roles; этот маршрут не раскрывает permissions и не разрешает управление ролями. Настройка чужих прав требует «Системные настройки → Информация о компании» дополнительно к reference:write, а не обычного права использовать статус.

Все команды настройки возвращают 200 с новой карточкой/version и фактическими next_status_ids/role_ids/user_ids. Удаление принимает {}, статус с актами, заказами или входящими переходами других статусов — 409 RESOURCE_IN_USE. Изменение completes_act или accrues_wages у статуса, уже связанного с актами или заказами, возвращает 409 STATUS_SEMANTICS_IN_USE; массовая миграция смысла существующих документов этим update не выполняется.

Логические значения JSON передаются как true или false. Поле accrues_wages при создании и изменении требует права «Помощник расчёта зарплаты → Форма расчета зарплаты», в том числе при значении false. Команды access и transitions принимают не более 100 уникальных положительных целых идентификаторов в каждом массиве. Для выбора доступны только действующие роли и сотрудники разрешённых мастерских.

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

• Право изменения справочника не выдаёт автоматически права переводить акт в любой статус.
• Нельзя перенести используемый статус между типами актов или бесконтрольно удалить его из истории.
• Изменение completes_act у используемого статуса требует отдельной доменной проверки существующих актов; не пересчитывать их молча.
• Переходы и допуск назначаются только на существующие доступные записи.

Операции

GET /reference/statuses

Список статусов с фильтром act_type.

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

Параметры

Ответы

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

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

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

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

POST /reference/statuses

Создание.

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

GET /reference/statuses/{id}

Карточка статуса.

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

Параметры

Ответы

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

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

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

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

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

POST /reference/statuses/{id}/transitions

Настройка доступных следующих статусов.

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

POST /reference/statuses/{id}/access

Настройка допуска ролей/сотрудников.

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

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