ModernERP EAM / Рабочая инструкция

API EAM: аутентификация, версии объектов и примеры запросов

Подключитесь к API оборудования, работ и отчётов, сохранив tenant-scope, корректные повторы и обработку конфликтов.

Редакция от 21 ноября 2026 года. Действия и ограничения сверены с исходниками EAM; установленная версия и права могут отличаться.

Перед началом

Кому нужен доступ

Отдельный API-пользователь с нужными ролями и grants. Bearer-токен создаёт доверенный администратор через app:eam:user --rotate-token; cookie браузера не является API-учётными данными.

Что подготовить

HTTPS URL EAM, защищённое хранение токена, tenant UUID, допустимые объекты и согласованный сценарий. Не используйте один admin-токен для всех внешних сервисов.

1. Настройте аутентификацию и контур

База API — /api/eam/v1. Передавайте Authorization: Bearer и X-Tenant-ID при нескольких memberships; tenant не является произвольно доверенным полем payload. Токен храните в окружении или secret storage.

Проверьте результат: GET оборудования возвращает только разрешённую структуру. Токен не попал в URL, Git, лог запроса или снимок экрана.

2. Прочитайте объект перед изменением

Для существующих объектов используйте version последнего ответа и reason там, где их требует workflow. Списки поддерживают пагинацию и фильтры; пределы различаются: maintenance-списки до 100, отчётные группы до 200.

Проверьте результат: Изменение опирается на актуальную версию. Запрос не пытается перезаписать изменения другого пользователя.

3. Вызывайте операции жизненного цикла

Создание заявки, её триаж/конвертация, start/complete/close наряда и confirm/finish простоя имеют отдельные маршруты и правила. Не заменяйте их произвольной установкой status через PATCH.

Проверьте результат: Сохранены проверка прав, обязательные поля, аудит и связанные события. Закрытие наряда не подменено повтором завершения.

4. Различайте безопасный повтор и новое действие

Импорт commit и конвертация заявки имеют собственную идемпотентность; meter reading использует requestId, а APS event — eventId и бизнес-версию. Не добавляйте выдуманный универсальный Idempotency-Key ко всем маршрутам.

Проверьте результат: После неопределённого ответа прочитан текущий объект. Повторный workflow-переход не принят автоматически за новый успешный переход.

5. Запрашивайте отчёты с явным периодом

from/to задаются RFC3339, to исключается, период не больше 366 дней. Фильтры отчётов ограничивают, но не расширяют права. CSV доступен на /reports/{kind}.csv в том же API-префиксе.

Проверьте результат: Временные границы URL-encoded; выгрузка относится к ожидаемой организации и не превышает лимит групп.

6. Разберите ошибку по контракту

Сохраняйте X-Request-ID и correlationId из error envelope без токенов и чувствительного payload. 409 требует проверки version/состояния, 422 — исправления входных данных. Чужой или невидимый ID может давать 404.

Проверьте результат: Нет бесконечного повтора конфликта или некорректного запроса. Ротация/отзыв токена выполняется с сохранением полных ролей и grants membership.

7. Обрабатывайте асинхронные команды обеспечения

GET /work-orders/{id}/resources показывает состояние, затраты и version. Изменение потребности возвращает 202 и pending: это ещё не складской факт. Перед следующим действием перечитайте version, поскольку подтверждение ERP тоже меняет её. Повтор действия при ожидающем ответе даёт 409; повтор доставки использует прежний commandId.

Проверьте результат: Клиент различает отправку команды и подтверждение ERP, не создаёт новую выдачу при потере ответа. Полный контракт и ограничения приведены в инструкции обеспечения ремонта.

Ограничения и ошибки

Автоматическое истечение API-токенов не реализовано. API не предоставляет произвольный DELETE ремонтной истории и не выполняет установку администратора или запуск demo/cron через публичный endpoint. Scope фильтра не является проверкой полномочий сам по себе.

Если действие недоступно, проверьте роль, разрешения, принадлежность к участку и статус документа. При ошибке сохраните номер документа, время и текст сообщения; передайте их ответственному, прежде чем повторять изменяющую операцию.

Примеры и команды

Выдать API-токен для чтения

Административная операция в нужной установке. Токен будет показан однократно: сохраните его в secret storage, не в логах CI. Команда заменяет membership, поэтому передайте полный согласованный набор ролей/grants. Показанный viewer — только чтение, не право изменять наряды.

php bin/console app:eam:user \
  --email=integration@example.test --tenant=TENANT_UUID \
  --roles=viewer --organizations=ORG_UUID --sites=SITE_UUID \
  --rotate-token

Чтение оборудования

Учебный домен. Переменные заранее задаются безопасно; команда читает данные, не создаёт оборудование. Не включайте shell trace или verbose-вывод заголовков с токеном.

curl --fail-with-body \
  -H "Authorization: Bearer $EAM_API_TOKEN" \
  -H "X-Tenant-ID: $EAM_TENANT_ID" \
  "https://eam.example.org/api/eam/v1/equipment?page=1&limit=20"

CSV по простоям за ноябрь

Период показан с местным смещением. curl кодирует параметры; проверьте ответ и полномочия до передачи CSV другим сотрудникам.

curl --fail-with-body --get \
  -H "Authorization: Bearer $EAM_API_TOKEN" \
  -H "X-Tenant-ID: $EAM_TENANT_ID" \
  --data-urlencode "from=2026-11-01T00:00:00+03:00" \
  --data-urlencode "to=2026-12-01T00:00:00+03:00" \
  "https://eam.example.org/api/eam/v1/reports/downtime.csv" \
  --output downtime-november.csv

Ошибки и действия клиента

HTTPСмыслЧто делать
401Нет аутентификацииПроверить токен без вывода его значения
403Действие запрещеноПроверить роль и назначение
404Нет объекта или он не виденПроверить tenant и scope; не перебирать ID
409Version/state/transition conflictПеречитать состояние, согласовать изменение
422ВалидацияИсправить поля по violations
503Модуль/зависимость недоступныДиагностика с request ID, управляемый повтор