Справочник работ

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

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

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

Назначение

Каталог работ: наименование, категория, гарантия, продолжительность и фиксированная цена либо нормочасы.

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

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

Нужны operations:read и «Справочники → Просмотр». Доступ к мастерской определяется правами сотрудника и ограничениями подключения. Общие работы доступны по правилам организации. filter[archived]=true также требует права удаления работы. fixed_price, labor_hours, hourly_rate и calculated_price зависят от режима цены и ставки мастерской.

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

Смена ставки мастерской меняет hourly_rate и calculated_price, даже если карточка работы не редактировалась. ETag отражает новый ответ, а data.version может остаться прежней. Фильтр updated_since не гарантирует обнаружение таких изменений.

Для фиксированной цены fixed используются денежные поля; для почасовой hourly — labor_hours. Чтение архивной записи и её сохранённого ответа требует действующего права удаления. Уведомление об архивировании содержит только идентификатор и версию и требует права чтения. Эти команды не добавляют работы в акты и не выполняют складские движения.

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

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

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

operations:read/write и «Справочники → Просмотр, Изменение, Удаление». Для нормочасов проверяется доступ к выбранной мастерской.

Фильтры: q, category_id, workshop_id, pricing_type, updated_since, archived.

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

• fixed_price и labor_hours взаимоисключающи и зависят от pricing_type; двусмысленный price в публичном вводе отсутствует.

• Создание работы не добавляет выполненную работу в акт.

• Смена ставки мастерской меняет расчёт текущего каталога по действующим правилам, но не исторические строки документов.

Операции

POST /operations

Создание.

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

GET /operations

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

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

Параметры

Ответы

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

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

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

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

POST /operations/{id}/update

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

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

POST /operations/{id}/archive

Архивация.

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

POST /operations/{id}/restore

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

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

GET /operations/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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