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 |
| 409 | Version/state/transition conflict | Перечитать состояние, согласовать изменение |
| 422 | Валидация | Исправить поля по violations |
| 503 | Модуль/зависимость недоступны | Диагностика с request ID, управляемый повтор |