Оборудование клиентов

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

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

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

Назначение

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

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

Нужны equipment:read, «ТОиР — Оборудование → Просмотр» и доступ к ТОиР. GET не создаёт историю, чек-листы или заявки. Для GET /equipment/{id}/history используйте filter[kind]=maintenance-schedules или acts; по умолчанию возвращаются заявки ТО. Каждый вид использует пагинацию по идентификатору и требует разрешения на чтение соответствующего ресурса и прав сотрудника. Календарные даты возвращаются как Y-m-d без перевода часового пояса. Дополнительные поля следуют правилам типов. technical_specs принимает JSON-объект или null: до 32 КиБ, не более восьми уровней вложенности. Типы значений сохраняются. GET возвращает объект, а для старых текстовых паспортов — прежнюю строку или null.

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

updated_since и updated_before выбирают записи по updated_at: нижняя граница включается (>=), верхняя исключается (<). Эти фильтры не гарантируют обнаружение всех изменений наработки, обслуживания и связанных данных. Используйте события и полную сверку по правилам синхронизации.

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

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

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

Карточка содержит ссылки только для чтения: links.edit, links.portal, links.public: редактирование в панели, карточку клиентского кабинета и существующий QR-паспорт. У старой записи без public_token публичная ссылка равна null; GET не генерирует токен. Для pending_install ссылки в портал и на публичный паспорт равны null. Отключённый раздел портала возвращает links.portal=null.

equipment:read/write и «ТОиР — Оборудование → Просмотр, Изменение»; тариф модуля; для истории актов также право их чтения.

Фильтры: customer_id, customer_site_id, equipment_model_id, manufacturer_id, device_type_id, status, serial_number, external_id, updated_since, updated_before.

Настройка счётчика

usage_unit_id можно задать при создании и при первом изменении. При создании обязательны customer_id и name. По умолчанию status=active, usage_reading=0; usage_unit_id и maintenance_interval равны null, если не настроены. Для ненулевого maintenance_interval нужна единица наработки. После создания показания записываются отдельной командой наработки. Поле usage_reading не принимается при создании и обычном изменении.

Смена или очистка единицы разрешена только пока usage_current=0, usage_at_last_service=0 и нет связанных usage/hybrid-планов, регламентов или истории выполнения с наработкой. Иначе 409 USAGE_UNIT_IN_USE; API не меняет смысл прежние показания. Возврат той же единицы допустим. maintenance_interval относится к существующему механизму обслуживания по умолчанию; интервалы индивидуальных планов настраиваются через maintenance-plans, и ответ usage показывает их отдельно.

POST /equipment/{id}/status принимает { "status": "inactive" } с If-Resource-Version. Допустимы active/inactive/decommissioned/repair с доменными проверками; pending_install доступен только через монтаж. Ответ 200 — актуальная карточка. При конфликте открытых процессов — 409 EQUIPMENT_STATE_CONFLICT.

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

• Объект принадлежит клиенту; новое назначение проверяет актуальную неархивированную запись под блокировкой. Прежняя связь с архивным объектом сохраняется при изменении других полей. Каталожная модель и экземпляр оборудования остаются разными сущностями.
• Смена клиента/объекта оборудования не может нарушить уже согласованный состав договора обслуживания: конфликт возвращает 422 с полем customer_id или customer_site_id. Штатная запись проверяет то же правило. Перенос самой площадки к другому клиенту разрешён только без оборудования и остальных зависимостей, с текущей блокировкой площадки; правила описаны в customer-sites.md.
• pending_install создаётся доменным путём монтажа, а не произвольным изменением status.
• Списание/деактивация оборудования не удаляет планы и историю обслуживания.
• scenario_state, act_product_id, производные даты и сохранённый снимок не принимаются командой изменения.
• Запись показаний и дата завершения ТО проходят свои операции; нельзя обойти их через technical_specs.

Операции

GET /equipment/{id}/history

История обслуживания и связанных актов.

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

Параметры

Ответы

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

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

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

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

POST /equipment

Создание.

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

GET /equipment

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

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

Параметры

Ответы

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

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

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

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

POST /equipment/{id}/update

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

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

POST /equipment/{id}/status

Смена эксплуатационного состояния.

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

GET /equipment/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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