Мастерские

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

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

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

Назначение

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

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

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

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

Чтение требует workshops:read и «Системные настройки → Базовый доступ к системе»; изменение — workshops:write и «Системные настройки → Информация о компании» для выбранной мастерской. Выборка пересекает текущие области ролей и workshop_ids подключения. Фильтры: q по названию, primary_process.

Создание требует workshops:write и организационного «Системные настройки → Информация о компании»: право настройки отдельной мастерской не разрешает создавать новые подразделения. В одной транзакции с созданием новый ID добавляется в workshop_ids текущего подключения. Остальные мастерские этим не открываются; повтор команды возвращает прежнюю карточку и не расширяет область повторно. Смена направления на installation/maintenance дополнительно проверяет доступность соответствующей возможности тарифа.

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

• При создании проверяется лимит мастерских тарифа.
• name, city, address и phone обязательны, не пусты и ограничены 255 символами. Обновление принимает только переданные публичные поля; null для этих строк не допускается.
• hourly_rate.amount — строка с точным числом дробных разрядов валюты организации; currency совпадает с валютой организации. Ставка должна помещаться в существующее хранение decimal(18,2) без округления.
• Основное направление мастерской и тип документа — отдельные настройки.
• Смена направления проходит штатное обеспечение модулей и справочников.
• При заполнении профиля могут создаваться статусы, работы, сценарии ТО, пункты чек-листа и дополнительные поля. Их изменения отражаются в событиях. В meta.affected_resources входят только доступные сотруднику объекты. Создание мастерской не требует отдельных разрешений чтения всех начальных записей.

Созданные при заполнении профиля работы, сценарии и дополнительные поля доступны через соответствующие ресурсы API. События доставляются только при наличии прав чтения этих ресурсов.

Операции

GET /workshops

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

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

Параметры

Ответы

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

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

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

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

POST /workshops

Создание.

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

GET /workshops/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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

POST /workshops/{id}/update

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

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