ППР, прогнозы и надёжность

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

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

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

Назначение

График обслуживания, план/факт, прогноз расходных материалов и показатели простоев в пределах разрешённых данных.

Параметры GET

Обязательны from и to в формате YYYY-MM-DD, от первого до последнего дня включительно. Максимум 366 календарных дней; обратный и более длинный период — 422 VALIDATION_FAILED. DATE сохраняет исходный день без пересчёта часового пояса. Для времён простоев границы дня определяются в поясе организации.

Дополнительные параметры всех отчётов: equipment_ids[]=42 (до 100 различных положительных ID), customer_id=7, workshop_ids[]=2 (до 100 различных ID). Явно запрошенное недоступное оборудование, клиент или мастерская — 404; сочетание equipment_ids с чужим customer_id также возвращает 404. Без фильтров используется разрешённый состав. Оборудованию не назначается вымышленная мастерская: ограничения мастерских применяются к планам, заявкам и связанным актам.

Только parts принимает необязательный stock_id; только reliability — include_costs=true или false (по умолчанию false). Неизвестные поля, sort/page/filter и параметры другого отчёта — 422 UNKNOWN_QUERY_PARAMETER. Отчёты не используют пагинацию по курсору.

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

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

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

Разрешение подключения maintenance_reports:read требует «ТОиР — Обслуживание → Просмотр», «ТОиР — Оборудование → Просмотр» и доступ к модулю ТОиР. Обычный отчёт не требует финансовых прав. Исходные запросы учитывают доступные мастерские токена и роли, оборудование и его клиента до агрегации.

Parts дополнительно требует products:read, «Товары → Просмотр» и «Акты приёма оборудования → Просмотр»: потребность выводится из последнего доступного завершённого ТО оборудования, без цен товара. Выбор stock_id требует stock_levels:read и «Остатки → Просмотр» для выбранного склада. Без stock_id потребность рассчитывается, а покрытие резервами/выдачей остаётся null с пояснением; общий склад не выбирается автоматически.

Reliability с include_costs=true дополнительно требует «Деньги → Просмотр» и «Акты приёма оборудования → Просмотр». Финансовые мастерские роли ограничивают стоимость независимо от состава технического отчёта. Стоимость учитывается только у простоя со связанным доступным актом разрешённой финансовой мастерской. Стоимость без такого акта остаётся неизвестной; её нельзя отнести к разрешённой мастерской. Общая стоимость акта используется как запасной, только если он покрывает одну единицу оборудования, и учитывается один раз. В ответах без include_costs денежные поля отсутствуют.

Формат результатов

Обёртка каждого результата: data={from,to,items,totals,explanation}, meta={}. explanation=null при наличии данных. Нет доступных наблюдений — пояснение и null для долей/средних, а не выдуманный ноль. Число записей может быть 0. Заметки клиентов, закупочные цены и служебные настройки не возвращаются.

• Calendar: каждый item содержит kind=schedule/forecast, schedule_id/plan_id, equipment_id, workshop_id, date, deadline_at, status, cycle, conditional и reason. Прогноз содержит расчётный срок и пояснение условности из штатного расчёта. totals: existing, forecast, undated_plans, truncated. Лимит 5000 существующих заявок и стандартные лимиты 500 планов/5000 прогнозных строк отражаются в truncated; это число возвращённых строк, не полный итог за пределами лимита.
• План и факт: items содержит месяцы в формате YYYY-MM с полями planned, completed и completion_rate. Последнее может быть null. Поля totals: planned, completed, on_time, completion_rate, on_time_rate, mean_days_to_complete, mean_days_between_services. Доли выражены в процентах, средние — в днях. Учитываются завершения в границах периода.
• Parts: items сгруппированы по product_id, measure_id и date. Поля name, quantity, reserved_quantity, issued_quantity, uncovered_quantity. Количества — десятичные строки с тремя знаками; разные меры не складываются. Без склада последние три поля null. totals: lines, stock_id, stock_explanation. Начальный день включает открытые просроченные потребности по правилам штатного прогноза; расчёт не является историческим остатком склада.
• Надёжность: элементы items по equipment_id содержат failures, repeats, active, unplanned_hours, planned_hours и waiting_hours. В totals также входят mean_restore_hours и mean_operating_hours, которые могут быть null. Время выражено в часах. При запросе стоимости добавляется costs с полями amount, currency, known_observations, unknown_observations, explanation. amount — десятичная строка или null, если данных о стоимости нет. Период заканчивается не позже текущего момента.

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

• Расчёт будущего графика не создаёт заявки.
• Агрегаты и прогнозы ограничиваются теми же правами, что исходные записи.
• Нет фактических наблюдений — null/пояснение, а не выдуманный ноль.
• Итоги рассчитываются только по доступным записям с учётом переданных фильтров.

Операции

GET /maintenance-reports/calendar

Прогноз и существующие работы за ограниченный период.

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

Параметры

Ответы

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

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

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

curl --silent --show-error --globoff --get \
  --data-urlencode 'from=2026-11-04' \
  --data-urlencode 'to=2026-11-04' \
  "$API/maintenance-reports/calendar" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

GET /maintenance-reports/plan-fact

План/факт и исполнение ППР.

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

Параметры

Ответы

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

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

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

curl --silent --show-error --globoff --get \
  --data-urlencode 'from=2026-11-04' \
  --data-urlencode 'to=2026-11-04' \
  "$API/maintenance-reports/plan-fact" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

GET /maintenance-reports/parts

Прогноз потребности в расходниках.

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

Параметры

Ответы

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

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

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

curl --silent --show-error --globoff --get \
  --data-urlencode 'from=2026-11-04' \
  --data-urlencode 'to=2026-11-04' \
  "$API/maintenance-reports/parts" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

GET /maintenance-reports/reliability

Отказы, простои и показатели восстановления.

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

Параметры

Ответы

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

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

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

curl --silent --show-error --globoff --get \
  --data-urlencode 'from=2026-11-04' \
  --data-urlencode 'to=2026-11-04' \
  "$API/maintenance-reports/reliability" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"