MineFlow Core API (0.1.0)

Download OpenAPI specification:Download

HTTP API ядра MineFlow (PRD, EAM, SCM, HR, IAM, Notifications)

Health

Liveness/readiness probes для Kubernetes

Liveness probe (процесс жив)

Kubernetes livenessProbe — возвращает 200 если процесс API отвечает.

Authorizations:

bearer

Responses

Response samples

200

Content type

application/json

{"status": "ok",
"service": "string",
"version": "string",
"at": "2019-08-24T14:15:22Z"
}

Liveness probe (alias)

Алиас корневого liveness endpoint для k8s.

Authorizations:

bearer

Responses

Response samples

200

Content type

application/json

{"status": "ok"
}

Readiness probe (Postgres + Redis + Keycloak + MinIO)

Kubernetes readinessProbe — проверяет доступность всех зависимостей.

Authorizations:

bearer

Responses

Response samples

200
503

Content type

application/json

{"status": "ok",
"info": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
},
"error": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
},
"details": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
}
}

Deep dependencies check (alias readiness)

Расширенная проверка зависимостей (alias readiness).

Authorizations:

bearer

Responses

Response samples

200
503

Content type

application/json

{"status": "ok",
"info": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
},
"error": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
},
"details": {"property1": {"status": "up",
"property1": null,
"property2": null
},
"property2": {"status": "up",
"property1": null,
"property2": null
}
}
}

Observability

Метрики Prometheus и системные эндпоинты

Prometheus scrape endpoint

Возвращает текстовый snapshot всех зарегистрированных prom-client метрик в exposition-формате Prometheus. Эндпоинт публичный, потребляется prometheus-сервером.

Authorizations:

bearer

Responses

Response samples

200

Content type

application/json

"string"

Refs / registry

Общий справочник реестров системы

Реестр зарегистрированных справочников

Discovery-список всех справочников, зарегистрированных через RefRegistry (ADR-0014). Возвращает module, entity, displayName, ownerModule и readPath для UI и интеграций.

Authorizations:

bearer

Responses

Response samples

Content type

application/json

[{"module": "core",
"entity": "production-objects",
"displayName": "Производственные объекты",
"ownerModule": "core",
"readPath": "/api/v1/core/refs/production-objects"
}
]

Admin / Organizations

Управление организациями (multi-tenancy)

Создать новую организацию (super-admin)

Onboarding нового арендатора платформы. Slug должен быть уникальным; при коллизии возвращается 409. Создаёт пустую организацию — seed справочников выполняется отдельным шагом per-tenant.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

slug required	string [ 3 .. 50 ] characters ^[a-z0-9](?:[a-z0-9-]{1,48}[a-z0-9])?$ Стабильный URL-safe идентификатор арендатора
name required	string [ 1 .. 200 ] characters Человекочитаемое название организации

Responses

Request samples

Payload

Content type

application/json

{"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions"
}

Response samples

Content type

application/json

{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}

Список всех организаций (super-admin)

Возвращает все организации платформы. Доступно только super-admin.

Authorizations:

bearer

Responses

Response samples

Content type

application/json

{"items": [{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}
]
}

Карточка организации

Super-admin видит любую; обычный Admin видит только свою собственную (user.organizationId === id).

Authorizations:

bearer

path Parameters

id

required

string

Example: 00000000-0000-4000-8000-000000000001

UUID организации

Responses

Response samples

Content type

application/json

{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}

Обновить организацию (super-admin)

Меняет только name. Slug — иммутабельный URL-key, для смены slug нужно создать новую организацию и мигрировать данные.

Authorizations:

bearer

path Parameters

id

required

string

Example: 00000000-0000-4000-8000-000000000001

UUID организации

Request Body schema: application/json
required

name	string [ 1 .. 200 ] characters Новое человекочитаемое название. Slug менять нельзя — он URL-key.

Responses

Request samples

Payload

Content type

application/json

{"name": "ТОО Explosion Solutions International"
}

Response samples

Content type

application/json

{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}

Деактивировать организацию (super-admin)

Помечает статус как deactivated. ВНИМАНИЕ: сегодня deactivated НЕ блокирует API-вход пользователей этой организации (требует cached org-status lookup в OrgScopeInterceptor — отдельный ADR). Сейчас это operator-visible маркер.

Authorizations:

bearer

path Parameters

id

required

string

UUID организации

Responses

Response samples

Content type

application/json

{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}

Реактивировать организацию (super-admin)

Возвращает status в active. Парная операция к deactivate.

Authorizations:

bearer

path Parameters

id

required

string

UUID организации

Responses

Response samples

Content type

application/json

{"id": "00000000-0000-4000-8000-000000000001",
"slug": "explosion-solutions",
"name": "ТОО Explosion Solutions",
"status": "active",
"createdAt": "2026-05-21T08:00:00.000Z"
}

Admin / Sagas DLQ

Просмотр и переотправка задач из DLQ саг

Список failed jobs в DLQ саг

BullMQ failed jobs из очередей steps и compensate.

Authorizations:

bearer

query Parameters

limit

number

Максимум записей на каждую очередь (default 50)

Responses

Response samples

Content type

application/json

{"entries": [{"queue": "mineflow-saga-steps",
"jobId": "8b1f5e2a-44a7-4e6e-9d61-7c0c9c45f4c7:mark-asset-decommissioned",
"sagaName": "eam.asset.decommission",
"sagaId": "8b1f5e2a-44a7-4e6e-9d61-7c0c9c45f4c7",
"stepName": "mark-asset-decommissioned",
"failedReason": "Asset is already decommissioned",
"attemptsMade": 5,
"attemptsLimit": 5,
"finishedOn": "2026-05-20T08:14:33.122Z"
}
],
"truncated": true
}

Счётчики job-ов по статусам

Метрики для алертов: failed / waiting / active / delayed / completed.

Authorizations:

bearer

Responses

Response samples

Content type

application/json

{"queues": [{"queue": "mineflow-saga-steps",
"failed": 9007199254740991,
"waiting": 9007199254740991,
"active": 9007199254740991,
"delayed": 9007199254740991,
"completed": 9007199254740991
}
]
}

Перезапустить failed job из DLQ

BullMQ переводит job из failed в waiting; attempts счётчик сбрасывается. Используется когда downstream сервис восстановлен.

Authorizations:

bearer

path Parameters

queue required	string Enum: "mineflow-saga-steps" "mineflow-saga-compensate"
jobId required	string BullMQ jobId (формат `${sagaId}__${stepName}` — двойной underscore, не двоеточие; BullMQ 5.x запрещает `:` в jobId)

Responses

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

Удалить failed job из DLQ

Job удаляется навсегда. Используется когда retry бессмыслен.

Authorizations:

bearer

path Parameters

queue required	string Enum: "mineflow-saga-steps" "mineflow-saga-compensate"
jobId required	string BullMQ jobId

Responses

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

Admin / Trash

Soft-deleted записи и восстановление

Список supported entity types для soft-delete trash

Возвращает Prisma model names (PascalCase) которые поддерживают soft-delete (имеют колонку deletedAt). Используется UI для построения dropdown.

Authorizations:

bearer

Responses

Response samples

Content type

application/json

{"entities": ["string"
]
}

Soft-deleted rows entity-типа

Per-tenant выборка rows с deletedAt != null. Сортировка по deletedAt DESC. Limit 1..200 (default 50). entity — URL slug в kebab-case (production-objects, asset-classes, brigades, etc.).

Authorizations:

bearer

path Parameters

entity

required

string

Entity slug (kebab-case)

query Parameters

limit

number

1..200, default 50

Responses

Response samples

Content type

application/json

{"entity": "string",
"rows": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"deletedAt": "2019-08-24T14:15:22Z"
}
],
"count": 0
}

Восстановить soft-deleted row

Снимает deletedAt; re-checks unique constraints (см. KNOWN_UNIQUE_CHECKS). Если bizkey уже занят активной записью — 409 TRASH_RESTORE_UNIQUE_CONFLICT.

Authorizations:

bearer

path Parameters

entity required	string Entity slug (kebab-case)
id required	string <uuid> UUID restored row

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Audit

Доступ к журналу аудита действий

История изменений сущности

Cursor-пагинированный список audit-записей по конкретной сущности (entityType + entityId). Сортировка по at DESC (новые сверху). Используется на detail-страницах для отображения «кто и когда менял».

Authorizations:

bearer

query Parameters

entityType required	string [ 1 .. 64 ] characters Example: entityType=asset Тип сущности
entityId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: entityId=11111111-1111-4111-8111-111111111111 UUID сущности (v4)
limit	number [ 1 .. 200 ] Default: 50 Example: limit=50 1–200, default 50
cursor	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: cursor=2026-05-25T08:30:15.123Z ISO-timestamp из nextCursor предыдущей страницы

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"entity": "asset",
"entityId": "22222222-2222-4222-8222-222222222222",
"action": "decommission-saga",
"actorId": "33333333-3333-4333-8333-333333333333",
"at": "2026-05-25T08:30:15.123Z",
"before": {"status": "operational"
},
"after": {"status": "decommissioned"
},
"metadata": {"correlationId": "44444444-4444-4444-8444-444444444444"
}
}
],
"nextCursor": "2026-05-25T08:30:15.123Z"
}

Documents

Прикреплённые документы (MinIO)

Инициировать загрузку документа (presigned PUT URL)

Создаёт запись документа в статусе pending и возвращает presigned PUT URL. Роли: Engineer, Mechanic, Foreman, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

entityType required	string [ 1 .. 100 ] characters Тип сущности-владельца (например eam.asset)
entityId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID сущности-владельца
filename required	string [ 1 .. 255 ] characters Имя файла с расширением
mimeType	string [ 1 .. 200 ] characters MIME-тип (опционально, для Content-Type при PUT)
bucket	string Enum: "documents" "hse-photos" "reports" "asset-passports" MinIO bucket для хранения файла

Responses

Request samples

Payload

Content type

application/json

{"entityType": "eam.asset",
"entityId": "22222222-2222-4222-8222-222222222222",
"filename": "passport-scan.pdf",
"mimeType": "application/pdf",
"bucket": "documents"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"uploadUrl": "https://minio.example/presigned-put",
"expiresIn": 300
}

Подтвердить загрузку после PUT в MinIO

Проверяет наличие объекта, virus scan, переводит документ в ready. Роли: Engineer, Mechanic, Foreman, CEO.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID документа

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

sha256

string = 64 characters

SHA-256 хеш загруженного файла (hex, 64 символа)

Responses

Request samples

Payload

Content type

application/json

{"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"status": "ready",
"size": 1024
}

Получить presigned GET URL для скачивания

Возвращает временный URL для скачивания готового документа.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID документа

Responses

Response samples

Content type

application/json

{"downloadUrl": "https://minio.example/presigned-get",
"expiresIn": 300
}

Sagas

Статусы и метаданные исполнения саг

Прогресс любой саги по sagaId

Универсальный endpoint для опроса async-саг. После запуска саги (например, POST /eam/sagas/asset-decommission или approve shift-report) FE получает sagaId и опрашивает этот endpoint до тех пор, пока последний шаг не примет терминальный статус (completed/failed/compensated). Cross-org изоляция: возвращаются только шаги саг своей организации.

Authorizations:

bearer

path Parameters

sagaId

required

string <uuid>

UUID саги, возвращённый при запуске

Responses

Response samples

Content type

application/json

{"sagaId": "11111111-1111-4111-8111-111111111111",
"steps": [{"stepName": "reserveAsset",
"status": "completed",
"at": "2026-05-25T08:30:15.123Z",
"error": null
},
{"stepName": "markDecommissioned",
"status": "completed",
"at": "2026-05-25T08:30:16.456Z",
"error": null
}
]
}

PRD / Shift Reports

Сменные отчёты буровзрывных работ

Список сменных отчётов с фильтрами и пагинацией

Cursor pagination (по createdAt desc). Фильтры: status, productionObjectId, shiftDateFrom, shiftDateTo. Роли: Engineer, Foreman, CEO.

Authorizations:

bearer

query Parameters

status	string Enum: "draft" "submitted" "approved" "rejected"
productionObjectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID
shiftDateFrom	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... YYYY-MM-DD
shiftDateTo	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... YYYY-MM-DD
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID
limit	number [ 1 .. 100 ] Default: 20 1..100, default 20

Responses

Response samples

Content type

application/json

{"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day",
"status": "draft",
"submittedBy": "a641a425-2470-49a5-92c2-5825c2833a34",
"submittedAt": "string",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "string",
"approveSagaId": "06106995-2439-4b39-8e3c-8433c7579030",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "string",
"rejectReason": "string",
"createdAt": "string",
"updatedAt": "string"
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Создать черновик сменного отчёта

Один черновик на (organization, productionObject, shiftDate, shiftType). Дубль → 409. Idempotent через заголовок Idempotency-Key.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

productionObjectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID производственного объекта (карьера/участка)
shiftDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Календарный день смены (YYYY-MM-DD)
shiftType required	string Enum: "day" "night" Тип смены: day \| night

Responses

Request samples

Payload

Content type

application/json

{"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day",
"status": "draft",
"submittedBy": "a641a425-2470-49a5-92c2-5825c2833a34",
"submittedAt": "string",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "string",
"approveSagaId": "06106995-2439-4b39-8e3c-8433c7579030",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "string",
"rejectReason": "string",
"createdAt": "string",
"updatedAt": "string"
}

Получить сменный отчёт по ID

Возвращает 404 если отчёт не найден или принадлежит другой организации.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сменного отчёта

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day",
"status": "draft",
"submittedBy": "a641a425-2470-49a5-92c2-5825c2833a34",
"submittedAt": "string",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "string",
"approveSagaId": "06106995-2439-4b39-8e3c-8433c7579030",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "string",
"rejectReason": "string",
"createdAt": "string",
"updatedAt": "string"
}

Подать черновик на утверждение

FSM draft → submitted. Подавать может Foreman (заполнял) или Engineer.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сменного отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day",
"status": "draft",
"submittedBy": "a641a425-2470-49a5-92c2-5825c2833a34",
"submittedAt": "string",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "string",
"approveSagaId": "06106995-2439-4b39-8e3c-8433c7579030",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "string",
"rejectReason": "string",
"createdAt": "string",
"updatedAt": "string"
}

Утвердить сменный отчёт (запускает 6-шаговую approve-сагу)

FSM submitted → approved. Возвращает sagaId; следите за прогрессом через GET /sagas/:sagaId/status. Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сменного отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"sagaId": "d171ccc5-4e45-4ee5-8129-c6924a02cf9a",
"status": "enqueued"
}

Отклонить сменный отчёт ИЗ submitted (без сторно-саги)

FSM submitted → rejected. Применяется когда инженер увидел проблему до approve. Approve-сага ещё не запускалась, компенсация не требуется — это простой статус-переход с reason. Доступно Engineer и CEO. Idempotent. После rejected мастер может создать новый отчёт на ту же смену (partial unique).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сменного отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 5 .. 500 ] characters

Причина отклонения — не менее 5 символов, попадает в audit_log + событие

Responses

Request samples

Payload

Content type

application/json

{"reason": "Отсутствуют замеры топлива на 3 машины"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"productionObjectId": "3a0a4af6-394b-45a9-92bd-735ed933b284",
"shiftDate": "2026-05-20",
"shiftType": "day",
"status": "draft",
"submittedBy": "a641a425-2470-49a5-92c2-5825c2833a34",
"submittedAt": "string",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "string",
"approveSagaId": "06106995-2439-4b39-8e3c-8433c7579030",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "string",
"rejectReason": "string",
"createdAt": "string",
"updatedAt": "string"
}

Сторно утверждённого сменного отчёта (запускает обратную сагу)

FSM approved → rejected. Запускает 6-шаговую сторно-сагу prd.shift-report.reject-after-approve. Применяется когда после approve обнаружена ошибка и нужно откатить все эффекты (топливо, ТМЦ, моточасы, КТГ/КИО, статистика, табель). Возвращает rejectSagaId + originalApproveSagaId для трассировки. Idempotent. Доступно только CEO (двойное согласование).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сменного отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 10 .. 500 ] characters

Причина сторно — не менее 10 символов, попадает в audit_log и reject-сагу

Responses

Request samples

Payload

Content type

application/json

{"reason": "Ошибочно учтены моточасы из-за сбоя датчика"
}

Response samples

Content type

application/json

{"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"rejectSagaId": "de64eefe-15a8-40ca-9b7d-5ca22190d775",
"originalApproveSagaId": "f8d8d7fa-5387-48c6-a2e9-e2de8173ae00",
"status": "enqueued"
}

Снимок всех child entries отчёта

Возвращает personnel, asset-usages, drilling, blasting, fuel, downtime, tmcUsage одним запросом. Используется сагой и админ-просмотром.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

Responses

Response samples

Content type

application/json

{"personnel": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"personnelId": "430ebe5f-1db2-4480-bb3a-6df8655231f8",
"positionId": "da3402dc-13f8-45f9-83a6-bde06dd8eb35",
"hoursWorked": 0,
"downtimeHours": 0,
"createdAt": "string",
"updatedAt": "string"
}
],
"assetUsages": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetId": "9179b887-04ef-4ce5-ab3a-b5bbd39ea3c8",
"operatorPersonnelId": "a2bc08b5-d34a-49ca-9fa6-8702a73bbbde",
"hoursWorked": 0,
"meterReadingStart": 0,
"meterReadingEnd": 0,
"createdAt": "string",
"updatedAt": "string"
}
],
"drilling": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"holesDrilled": -9007199254740991,
"depthMeters": 0,
"drillBitWearPercent": 0,
"createdAt": "string"
}
],
"blasting": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"blocksBlasted": -9007199254740991,
"explosiveType": "string",
"explosiveKg": 0,
"permitId": "64d20f38-151e-42d0-9ba0-57274d8c8075",
"createdAt": "string"
}
],
"fuel": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tankId": "3b32d356-ac69-4c5f-ac39-eee74f13db7b",
"fuelType": "diesel",
"litersIssued": 0,
"litersConsumed": 0,
"createdAt": "string"
}
],
"downtime": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"reasonCode": "breakdown",
"startedAt": "string",
"endedAt": "string",
"description": "string",
"createdAt": "string"
}
],
"tmcUsage": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tmcItemId": "85836b85-d3d9-4915-84ec-5fbcd0cd4ec4",
"quantity": 0,
"unit": "string",
"createdAt": "string"
}
]
}

Добавить запись о сотруднике в смене (Q2)

Добавляет shift-personnel в отчёт в статусе draft. После approve запись становится иммутабельной.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

personnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID работника (hr.personnel)
positionId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID должности (soft-ref)
hoursWorked required	number [ 0 .. 24 ] Отработанные часы в смене (0..24)
downtimeHours required	number [ 0 .. 24 ] Часы простоя сотрудника (0..24)

Responses

Request samples

Payload

Content type

application/json

{"personnelId": "430ebe5f-1db2-4480-bb3a-6df8655231f8",
"positionId": "da3402dc-13f8-45f9-83a6-bde06dd8eb35",
"hoursWorked": 24,
"downtimeHours": 24
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"personnelId": "430ebe5f-1db2-4480-bb3a-6df8655231f8",
"positionId": "da3402dc-13f8-45f9-83a6-bde06dd8eb35",
"hoursWorked": 0,
"downtimeHours": 0,
"createdAt": "string",
"updatedAt": "string"
}

Добавить использование актива в смене (Q2)

Регистрирует факт работы единицы оборудования в смене. Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID актива (eam.assets)
	string or null UUID оператора (опционально)
hoursWorked required	number [ 0 .. 24 ]
meterReadingStart required	number >= 0
meterReadingEnd required	number >= 0

Responses

Request samples

Payload

Content type

application/json

{"assetId": "9179b887-04ef-4ce5-ab3a-b5bbd39ea3c8",
"operatorPersonnelId": "a2bc08b5-d34a-49ca-9fa6-8702a73bbbde",
"hoursWorked": 24,
"meterReadingStart": 0,
"meterReadingEnd": 0
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetId": "9179b887-04ef-4ce5-ab3a-b5bbd39ea3c8",
"operatorPersonnelId": "a2bc08b5-d34a-49ca-9fa6-8702a73bbbde",
"hoursWorked": 0,
"meterReadingStart": 0,
"meterReadingEnd": 0,
"createdAt": "string",
"updatedAt": "string"
}

Добавить запись о бурении (Q2)

Фиксирует объёмы бурения и износ долота. Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetUsageId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID соответствующего ShiftAssetUsage
holesDrilled required	integer ( 0 .. 2147483647 ] Количество пробуренных скважин (1..2^31-1)
depthMeters required	number > 0 Глубина бурения, м
	number or null Износ долота, % (0..100); null если не замерили

Responses

Request samples

Payload

Content type

application/json

{"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"holesDrilled": 15,
"depthMeters": 0,
"drillBitWearPercent": 100
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"holesDrilled": -9007199254740991,
"depthMeters": 0,
"drillBitWearPercent": 0,
"createdAt": "string"
}

Добавить запись о взрывных работах (Q2)

Фиксирует взрывные работы и расход ВВ. Может ссылаться на разрешение (permit). Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

blocksBlasted required	integer [ 0 .. 2147483647 ] Количество взорванных блоков (0..2^31-1)
explosiveType required	string [ 1 .. 80 ] characters Тип ВВ (например, ANFO, Emulsion)
explosiveKg required	number >= 0 Масса ВВ, кг
	string or null UUID разрешения hse.permits (опц.)

Responses

Request samples

Payload

Content type

application/json

{"blocksBlasted": 12,
"explosiveType": "string",
"explosiveKg": 0,
"permitId": "64d20f38-151e-42d0-9ba0-57274d8c8075"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"blocksBlasted": -9007199254740991,
"explosiveType": "string",
"explosiveKg": 0,
"permitId": "64d20f38-151e-42d0-9ba0-57274d8c8075",
"createdAt": "string"
}

Добавить запись о расходе топлива (Q2)

Регистрирует расход топлива/смазочных материалов в смене. Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetUsageId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID соответствующего ShiftAssetUsage
tankId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID резервуара ДТ (scm/fuel.FuelTank) — обязательно
fuelType required	string Enum: "diesel" "gasoline" "lubricant" Тип топлива/смазки
litersIssued required	number >= 0 Выдано, литры
litersConsumed required	number >= 0 Израсходовано, литры (<= litersIssued)

Responses

Request samples

Payload

Content type

application/json

{"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tankId": "3b32d356-ac69-4c5f-ac39-eee74f13db7b",
"fuelType": "diesel",
"litersIssued": 0,
"litersConsumed": 0
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tankId": "3b32d356-ac69-4c5f-ac39-eee74f13db7b",
"fuelType": "diesel",
"litersIssued": 0,
"litersConsumed": 0,
"createdAt": "string"
}

Добавить событие простоя (Q2)

Фиксирует интервал простоя оборудования с причиной. Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

	string or null UUID ShiftAssetUsage (опц.); null если простой не привязан к технике
reasonCode required	string Enum: "breakdown" "maintenance" "no_fuel" "weather" "other"
startedAt required	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... ISO 8601 момент начала
endedAt required	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... ISO 8601 момент конца, должен быть > startedAt
	string or null

Responses

Request samples

Payload

Content type

application/json

{"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"reasonCode": "breakdown",
"startedAt": "2019-08-24T14:15:22Z",
"endedAt": "2019-08-24T14:15:22Z",
"description": "string"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"reasonCode": "breakdown",
"startedAt": "string",
"endedAt": "string",
"description": "string",
"createdAt": "string"
}

Добавить расход материала (Q2)

Регистрирует расход ТМЦ (запчастей/расходников) в смене. Допускается только в статусе draft.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID отчёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

	string or null UUID ShiftAssetUsage (опц.)
tmcItemId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID позиции ТМЦ (scm soft-ref)
quantity required	number > 0 Количество (> 0)
unit required	string [ 1 .. 20 ] characters Единица измерения (л, шт, кг, ...)

Responses

Request samples

Payload

Content type

application/json

{"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tmcItemId": "85836b85-d3d9-4915-84ec-5fbcd0cd4ec4",
"quantity": 0,
"unit": "string"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"shiftReportId": "182d8849-6881-41ef-8195-03d54008fea2",
"assetUsageId": "45cf15f4-0b7d-4176-8eeb-93df63812a87",
"tmcItemId": "85836b85-d3d9-4915-84ec-5fbcd0cd4ec4",
"quantity": 0,
"unit": "string",
"createdAt": "string"
}

EAM / Assets

Активы (техника, оборудование)

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

Курсорная пагинация. Фильтрация по objectId и status. Роли: Engineer, Mechanic, Foreman, CEO.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=11111111-1111-4111-8111-111111111111 Фильтр по производственному объекту
status	string Enum: "operational" "maintenance" "conserved" "decommissioned" Example: status=operational Фильтр по статусу FSM
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}
],
"nextCursor": null
}

Создать актив

Создание актива с паспортом. Idempotent. Роли: Mechanic, Engineer.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

inventoryNumber required	string [ 5 .. 20 ] characters ^[А-ЯA-Z]{2,3}-\d{3,5}$ Инвентарный номер актива (БС-001, КОМ-12345)
name required	string [ 2 .. 200 ] characters Наименование актива
assetClassId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID класса актива
currentObjectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID объекта размещения
responsibleMechanicId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID ответственного механика
commissionedAt required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата ввода в эксплуатацию (не в будущем, EAM-INV-07)
required	object (CreateAssetDtoAssetPassportInput) Паспортные данные при создании актива

Responses

Request samples

Payload

Content type

application/json

{"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"commissionedAt": "2026-05-18",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

Получить актив по id

Возвращает актив с паспортом. Object scope по id.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID актива

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

Переместить актив на другой объект

FSM: operational → operational на другом объекте. Idempotent. Роли: Mechanic, Engineer, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID актива

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

toObjectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID целевого производственного объекта
reason	string <= 1000 characters Комментарий к операции (до 1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"toObjectId": "33333333-3333-4333-8333-333333333333",
"reason": "Перемещение на участок Борлы"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

Отправить актив в ТО

FSM: operational → maintenance. Idempotent. Роли: Mechanic, Engineer, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID актива

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 2 .. 500 ] characters

Причина отправки в ТО

Responses

Request samples

Payload

Content type

application/json

{"reason": "Плановое ТО по моточасам"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

Списать актив (требует двойного согласования)

FSM → decommissioned. Требует coApprovedBy (CEO/Engineer). Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID актива

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

required	string or "" (string) UUID второго согласующего (CEO/Engineer); пустая строка → 422
reason required	string [ 5 .. 1000 ] characters Обоснование списания

Responses

Request samples

Payload

Content type

application/json

{"reason": "Списание по износу",
"coApprovedBy": "44444444-4444-4444-8444-444444444444"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"inventoryNumber": "БС-001",
"name": "Atlas Copco DM45 №1",
"assetClassId": "22222222-2222-4222-8222-222222222222",
"currentObjectId": "33333333-3333-4333-8333-333333333333",
"responsibleMechanicId": "44444444-4444-4444-8444-444444444444",
"status": "operational",
"commissionedAt": "2026-05-18T08:00:00.000Z",
"passport": {"manufacturer": "Atlas Copco",
"model": "DM45",
"productionYear": 2020,
"specifications": {"engineHours": 12500
}
}
}

EAM / Maintenance

Техобслуживание и ремонты активов

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

Курсорная пагинация. Фильтрация по assetId и status. Роли: Engineer, Mechanic, Foreman, CEO.

Authorizations:

bearer

query Parameters

assetId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: assetId=11111111-1111-4111-8111-111111111111 Фильтр по UUID актива
status	string Enum: "scheduled" "inProgress" "completed" "cancelled" Example: status=scheduled Фильтр по статусу FSM ТО
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}
],
"nextCursor": null
}

Запланировать ТО

Создание записи ТО в статусе scheduled. Idempotent. Роли: Mechanic, Engineer, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID актива для планового ТО
scheduledAt required	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Плановая дата и время ТО (ISO 8601, не в прошлом)
reason required	string [ 2 .. 500 ] characters Причина / описание планового ТО

Responses

Request samples

Payload

Content type

application/json

{"assetId": "22222222-2222-4222-8222-222222222222",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"reason": "Плановое ТО по моточасам"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}

Получить ТО по id

Возвращает запись ТО. Object scope по id.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи ТО

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}

Начать ТО

FSM: scheduled → inProgress. Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи ТО

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

object (Start maintenance request)

Начало ТО (пустое тело; идемпотентность по Idempotency-Key)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}

Завершить ТО

FSM: inProgress → completed. Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи ТО

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

notes

string <= 2000 characters

Заметки по завершённому ТО (до 2000 символов)

Responses

Request samples

Payload

Content type

application/json

{"notes": "Замена масла и фильтров выполнена"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}

Отменить ТО

Отмена из scheduled или inProgress. Idempotent. Роли: Engineer, CEO.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи ТО

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 2 .. 500 ] characters

Причина отмены ТО

Responses

Request samples

Payload

Content type

application/json

{"reason": "Актив списан — ТО не требуется"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"status": "scheduled",
"scheduledAt": "2026-05-18T08:00:00.000Z",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"cancelledBy": null,
"cancellationReason": null,
"reason": "Плановое ТО по моточасам",
"performedBy": "44444444-4444-4444-8444-444444444444"
}

EAM / Movements

Перемещения активов между объектами

Журнал перемещений с фильтрами

Курсорная пагинация. Фильтры: assetId, objectId, op, status, dateFrom/dateTo. Роли: CEO, Engineer, Foreman (object), Mechanic (object/all), Admin.

Authorizations:

bearer

query Parameters

assetId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: assetId=11111111-1111-4111-8111-111111111111 Фильтр по UUID актива
objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=11111111-1111-4111-8111-111111111111 Фильтр по from/to productionObjectId
op	string Enum: "conservation" "from_conservation" "to_repair" "from_repair" "transfer_audit" Example: op=conservation Фильтр по типу операции
status	string Enum: "draft" "applied" "failed" "cancelled" Example: status=applied Фильтр по статусу FSM
dateFrom	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Нижняя граница opDate (ISO 8601)
dateTo	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Верхняя граница opDate (ISO 8601)
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"op": "conservation",
"status": "applied",
"fromObjectId": null,
"toObjectId": null,
"opDate": "2026-05-18T08:00:00.000Z",
"responsibleId": "44444444-4444-4444-8444-444444444444",
"reason": "Сезонная консервация — нерабочий период",
"relatedMaintenanceId": null,
"sourceEventId": null,
"appliedAt": "2026-05-18T08:00:00.000Z",
"failureReason": null,
"cancelledAt": null,
"cancelledBy": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": null
}

Зарегистрировать операцию (conservation / reactivation / repair)

Создаёт AssetMovement в draft и атомарно применяет side-effect на Asset. При отказе Asset FSM guard → status=failed (HTTP 409). Idempotent.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID актива
op required	string Enum: "conservation" "from_conservation" "to_repair" "from_repair" Операция: conservation \| from_conservation \| to_repair \| from_repair. transfer_audit фиксируется автоматически.
reason	string [ 2 .. 500 ] characters Причина — обязательна для conservation и to_repair
opDate	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата операции (ISO 8601). По умолчанию — now()
relatedMaintenanceId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID связанной записи ТО (опционально)

Responses

Request samples

Payload

Content type

application/json

{"assetId": "22222222-2222-4222-8222-222222222222",
"op": "conservation",
"reason": "Сезонная консервация — нерабочий период",
"opDate": "2026-05-18T08:00:00.000Z"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"op": "conservation",
"status": "applied",
"fromObjectId": null,
"toObjectId": null,
"opDate": "2026-05-18T08:00:00.000Z",
"responsibleId": "44444444-4444-4444-8444-444444444444",
"reason": "Сезонная консервация — нерабочий период",
"relatedMaintenanceId": null,
"sourceEventId": null,
"appliedAt": "2026-05-18T08:00:00.000Z",
"failureReason": null,
"cancelledAt": null,
"cancelledBy": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Получить запись movement по id

Object scope через asset.currentObjectId.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи movement

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"op": "conservation",
"status": "applied",
"fromObjectId": null,
"toObjectId": null,
"opDate": "2026-05-18T08:00:00.000Z",
"responsibleId": "44444444-4444-4444-8444-444444444444",
"reason": "Сезонная консервация — нерабочий период",
"relatedMaintenanceId": null,
"sourceEventId": null,
"appliedAt": "2026-05-18T08:00:00.000Z",
"failureReason": null,
"cancelledAt": null,
"cancelledBy": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Отменить draft/failed movement (до apply)

Отмена применённой записи невозможна (append-only audit).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи movement

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

string [ 2 .. 500 ] characters

Причина отмены (опционально, для аудита)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Ошибочная регистрация — отменяем до применения"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "22222222-2222-4222-8222-222222222222",
"op": "conservation",
"status": "applied",
"fromObjectId": null,
"toObjectId": null,
"opDate": "2026-05-18T08:00:00.000Z",
"responsibleId": "44444444-4444-4444-8444-444444444444",
"reason": "Сезонная консервация — нерабочий период",
"relatedMaintenanceId": null,
"sourceEventId": null,
"appliedAt": "2026-05-18T08:00:00.000Z",
"failureReason": null,
"cancelledAt": null,
"cancelledBy": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

EAM / Sagas

Саги домена EAM (декомиссия, миграция)

Запустить сагу декомиссии актива

Reference-сага из 2 шагов с компенсацией. Возвращает sagaId — для опроса используйте GET /sagas/:sagaId/status. Idempotent. Роли: Engineer, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID актива для декомиссии
coApprovedBy required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID второго согласующего (CEO/Engineer)
reason required	string [ 3 .. 500 ] characters Обоснование списания актива

Responses

Request samples

Payload

Content type

application/json

{"assetId": "11111111-1111-4111-8111-111111111111",
"coApprovedBy": "44444444-4444-4444-8444-444444444444",
"reason": "Списание по износу"
}

Response samples

Content type

application/json

{"sagaId": "22222222-2222-4222-8222-222222222222",
"status": "enqueued"
}

EAM / refs / asset-classes

Справочник классов активов

Список справочника asset-classes

Возвращает записи справочника asset classes. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "DRILL",
"name": "Буровая установка",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи asset-classes по id

Возвращает одну запись справочника asset classes по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника asset-classes

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "DRILL",
"name": "Буровая установка",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись asset-classes

Частичное обновление записи справочника asset classes. Роли: Admin, CEO. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника asset-classes

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "DRILL",
"name": "Буровая установка",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: eam/asset-classes

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: eam/asset-classes

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: eam/asset-classes

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

EAM / refs / fuel-consumption-norms

Нормы расхода ДТ по активам

Preview bulk-import: eam/fuel-consumption-norms

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: eam/fuel-consumption-norms

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: eam/fuel-consumption-norms

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Список нормативов расхода ГСМ

По умолчанию — активные «сейчас». Передай asOf (ISO datetime) для point-in-time, includeHistory=true для всех версий.

Authorizations:

bearer

query Parameters

assetClassCode	string non-empty Example: assetClassCode=DRILL Фильтр по коду класса актива
norm	string non-empty Example: norm=engine-oil-500h Фильтр по коду норматива
asOf	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: asOf=2026-05-18T08:00:00.000Z Точка во времени для temporal-выборки
includeHistory	boolean Example: includeHistory=false Включить исторические (неактивные) записи

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"assetClassCode": "DRILL",
"norm": "engine-oil-500h",
"value": 500,
"unit": "hours",
"validFrom": "2026-01-01T00:00:00.000Z",
"validTo": null,
"createdAt": "2026-01-01T00:00:00.000Z"
}
]

Карточка норматива расхода ГСМ по id

Возвращает одну запись норматива расхода ГСМ по UUID.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID норматива расхода ГСМ

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetClassCode": "DRILL",
"norm": "engine-oil-500h",
"value": 500,
"unit": "hours",
"validFrom": "2026-01-01T00:00:00.000Z",
"validTo": null,
"createdAt": "2026-01-01T00:00:00.000Z"
}

EAM / refs / maintenance-norms

Нормы ТО по типам активов

Preview bulk-import: eam/maintenance-norms

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: eam/maintenance-norms

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: eam/maintenance-norms

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO, Mechanic.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Список нормативов ТО

По умолчанию — активные «сейчас». Передай asOf (ISO datetime) для point-in-time, includeHistory=true для всех версий.

Authorizations:

bearer

query Parameters

assetClassCode	string non-empty Example: assetClassCode=DRILL Фильтр по коду класса актива
norm	string non-empty Example: norm=engine-oil-500h Фильтр по коду норматива
asOf	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: asOf=2026-05-18T08:00:00.000Z Точка во времени для temporal-выборки
includeHistory	boolean Example: includeHistory=false Включить исторические (неактивные) записи

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"assetClassCode": "DRILL",
"norm": "engine-oil-500h",
"value": 500,
"unit": "hours",
"validFrom": "2026-01-01T00:00:00.000Z",
"validTo": null,
"createdAt": "2026-01-01T00:00:00.000Z"
}
]

Карточка норматива ТО по id

Возвращает одну запись норматива ТО по UUID.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID норматива ТО

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetClassCode": "DRILL",
"norm": "engine-oil-500h",
"value": 500,
"unit": "hours",
"validFrom": "2026-01-01T00:00:00.000Z",
"validTo": null,
"createdAt": "2026-01-01T00:00:00.000Z"
}

Core / refs / production-objects

Справочник production objects

Список справочника production-objects

Возвращает записи справочника production objects. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "BORLY",
"name": "Участок Борлы",
"region": "Караганда",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи production-objects по id

Возвращает одну запись справочника production objects по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника production-objects

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "BORLY",
"name": "Участок Борлы",
"region": "Караганда",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись production-objects

Частичное обновление записи справочника production objects. Роли: Admin, CEO. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника production-objects

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "BORLY",
"name": "Участок Борлы",
"region": "Караганда",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: core/production-objects

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: core/production-objects

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: core/production-objects

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Core / refs / tmc-categories

Категории ТМЦ

Список справочника tmc-categories

Возвращает записи справочника tmc categories. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "FUEL",
"name": "ГСМ",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи tmc-categories по id

Возвращает одну запись справочника tmc categories по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника tmc-categories

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "FUEL",
"name": "ГСМ",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись tmc-categories

Частичное обновление записи справочника tmc categories. Роли: Admin, CEO, Supply. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника tmc-categories

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "FUEL",
"name": "ГСМ",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: core/tmc-categories

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO, Supply.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: core/tmc-categories

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO, Supply.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: core/tmc-categories

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO, Supply.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Core / refs / downtime-categories

Категории простоев

Список справочника downtime-categories

Возвращает записи справочника downtime categories. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "PLAN-TO",
"name": "Плановое ТО",
"group": "planned",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи downtime-categories по id

Возвращает одну запись справочника downtime categories по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника downtime-categories

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "PLAN-TO",
"name": "Плановое ТО",
"group": "planned",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись downtime-categories

Частичное обновление записи справочника downtime categories. Роли: Admin, CEO. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника downtime-categories

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "PLAN-TO",
"name": "Плановое ТО",
"group": "planned",
"parentId": null,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: core/downtime-categories

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: core/downtime-categories

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: core/downtime-categories

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Core / refs / hse-incident-classifiers

Классификаторы HSE-инцидентов

Список справочника hse-incident-classifiers

Возвращает записи справочника hse incident classifiers. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "NEAR-MISS",
"group": "safety",
"severity": "low",
"name": "Почти инцидент",
"createdAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи hse-incident-classifiers по id

Возвращает одну запись справочника hse incident classifiers по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника hse-incident-classifiers

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "NEAR-MISS",
"group": "safety",
"severity": "low",
"name": "Почти инцидент",
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись hse-incident-classifiers

Частичное обновление записи справочника hse incident classifiers. Роли: Admin, CEO, OtibSpecialist. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника hse-incident-classifiers

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "NEAR-MISS",
"group": "safety",
"severity": "low",
"name": "Почти инцидент",
"createdAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: core/hse-incident-classifiers

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO, OtibSpecialist.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: core/hse-incident-classifiers

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO, OtibSpecialist.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: core/hse-incident-classifiers

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO, OtibSpecialist.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

HR / refs / positions

Справочник должностей

Список справочника positions

Возвращает записи справочника positions. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "MECH",
"name": "Механик",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи positions по id

Возвращает одну запись справочника positions по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника positions

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "MECH",
"name": "Механик",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись positions

Частичное обновление записи справочника positions. Роли: Admin, CEO. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника positions

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "MECH",
"name": "Механик",
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Preview bulk-import: hr/positions

Валидирует строки импорта и возвращает diff (создание/обновление/деактивация) без записи в БД. Роли: Admin, CEO.

Authorizations:

bearer

Request Body schema: application/json
required

required	Array of objects <= 10000 items Строки импорта (поля зависят от справочника)
mode	string Enum: "merge" "full_replace" Режим импорта: merge — upsert по бизнес-ключу; full_replace — деактивация отсутствующих строк

Responses

Request samples

Payload

Content type

application/json

{"rows": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"mode": "merge"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"module": "hr",
"entity": "positions",
"mode": "merge",
"totalRows": 1,
"diff": {"willCreate": [{"code": "MECH",
"name": "Механик",
"active": true
}
],
"willUpdate": [{"current": {"code": "MECH",
"name": "Механик (старое)",
"active": true
},
"next": {"code": "MECH",
"name": "Механик",
"active": true
}
}
],
"willDeactivate": [{"code": "LEGACY",
"name": "Устаревшая должность",
"active": false
}
],
"errors": [{"rowNumber": 3,
"field": "code",
"message": "Дубликат кода MECH"
}
]
},
"expiresAt": "2026-05-18T08:00:00.000Z"
}

Commit bulk-import: hr/positions

Применяет ранее провалидированный batch из preview. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

batchId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

UUID batch'а, полученный из ответа preview

Responses

Request samples

Payload

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

Commit bulk-import по batchId в URL: hr/positions

Альтернатива commit с batchId в path вместо body. Требует Idempotency-Key. Роли: Admin, CEO.

Authorizations:

bearer

path Parameters

batchId

required

string <uuid>

UUID batch'а, полученный из preview

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"batchId": "22222222-2222-4222-8222-222222222222",
"status": "committed",
"applied": {"created": 1,
"updated": 0,
"deactivated": 0
},
"eventId": "evt-import-001"
}

HR / refs / system-roles

Системные роли (canonical PascalCase)

Список справочника system-roles

Возвращает записи справочника system roles. Параметр activeOnly=true исключает неактивные записи. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

activeOnly

boolean

Передай true чтобы получить только активные записи (без soft-deleted/expired)

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"code": "Mechanic",
"name": "Механик",
"description": "Обслуживание и ремонт техники на объекте",
"permissions": [{"action": "read",
"subject": "Asset"
}
],
"scopeByObject": true,
"version": 1,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}
]

Карточка записи system-roles по id

Возвращает одну запись справочника system roles по UUID. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника system-roles

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "Mechanic",
"name": "Механик",
"description": "Обслуживание и ремонт техники на объекте",
"permissions": [{"action": "read",
"subject": "Asset"
}
],
"scopeByObject": true,
"version": 1,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Обновить запись system-roles

Частичное обновление записи справочника system roles. Роли: Admin. Допустимые поля задаёт updateSchema модуля-владельца.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи справочника system-roles

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"name": "Новое наименование",
"active": true
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"code": "Mechanic",
"name": "Механик",
"description": "Обслуживание и ремонт техники на объекте",
"permissions": [{"action": "read",
"subject": "Asset"
}
],
"scopeByObject": true,
"version": 1,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

SCM / Fuel

Резервуары ДТ, поставки, списания

Резервуары ДТ — список

Курсорная пагинация. Для Foreman / Mechanic — только свой production object (или укажите objectId)

Authorizations:

bearer

query Parameters

objectId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: objectId=11111111-1111-4111-8111-111111111111 UUID v4
status	string Enum: "normal" "attention" "critical"
cursor	string
limit	integer ( 0 .. 200 ]
active	string Enum: "true" "false"

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "11111111-1111-4111-8111-111111111111",
"code": "string",
"capacityLiters": 0,
"minLevelLiters": 0,
"currentBalanceLiters": 0,
"active": true,
"statusDerived": "normal",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Создать резервуар

По умолчанию — роль Admin (корпоративный справочник объекта)

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

objectId required	string <uuid> (CreateFuelTankDtoUuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID v4
code required	string [ 1 .. 64 ] characters Уникальный код резервуара в рамках организации
capacityLiters required	integer ( 0 .. 9007199254740991 ]
minLevelLiters required	integer [ 0 .. 9007199254740991 ]
initialBalanceLiters	number >= 0

Responses

Request samples

Payload

Content type

application/json

{"objectId": "11111111-1111-4111-8111-111111111111",
"code": "string",
"capacityLiters": 9007199254740991,
"minLevelLiters": 9007199254740991,
"initialBalanceLiters": 0
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "11111111-1111-4111-8111-111111111111",
"code": "string",
"capacityLiters": 0,
"minLevelLiters": 0,
"currentBalanceLiters": 0,
"active": true,
"statusDerived": "normal",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Резервуар по id

Возвращает карточку резервуара. Доступ ограничен ролью и object scope по production object.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "11111111-1111-4111-8111-111111111111",
"code": "string",
"capacityLiters": 0,
"minLevelLiters": 0,
"currentBalanceLiters": 0,
"active": true,
"statusDerived": "normal",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Обновить minLevel резервуара

Меняет пороговое значение minLevel, на котором поднимается алерт «low stock». Аудит + idempotency обязательны.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

minLevelLiters

number >= 0

Новый нижний порог контроля, л — не может превышать ёмкость

Responses

Request samples

Payload

Content type

application/json

{"minLevelLiters": 0
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "11111111-1111-4111-8111-111111111111",
"code": "string",
"capacityLiters": 0,
"minLevelLiters": 0,
"currentBalanceLiters": 0,
"active": true,
"statusDerived": "normal",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Заявки на пополнение — список

Курсорная пагинация заявок на пополнение ДТ. Фильтрация по статусу и production object.

Authorizations:

bearer

query Parameters

tankId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: tankId=11111111-1111-4111-8111-111111111111 UUID v4
status	any
cursor	string
limit	integer ( 0 .. 200 ]

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Создать заявку на пополнение

Создаёт заявку в статусе draft. Передача в согласование — отдельный submit.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

tankId required	string <uuid> (CreateFuelSupplyRequestDtoUuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID v4
requestedVolumeLiters required	number > 0
desiredDeliveryDate required	string^\d{4}-\d{2}-\d{2}$
justification required	string [ 1 .. 2000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "string",
"justification": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Заявка по id

Карточка заявки на пополнение со связанными поставками. Доступ ограничен object scope.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Обновить заявку на пополнение

Правка полей заявки в статусе draft. После submit редактирование запрещено.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

requestedVolumeLiters	number > 0
desiredDeliveryDate	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...
justification	string [ 1 .. 2000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Отправить заявку на согласование

Переводит заявку draft → submitted. Триггерит уведомление утверждающим.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Согласовать заявку

submitted → approved. Поставщик получает разрешение на отгрузку.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

string <= 1000 characters

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Отклонить заявку

submitted → rejected с причиной отказа. Терминальный статус.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 10 .. 1000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"reason": "stringstri"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Вернуть заявку на доработку

submitted → draft с комментарием. Автор правит и повторно отправляет на submit.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

required

string >= 10 characters

Комментарий руководителю до доработки заявки (минимум 10 символов)

Responses

Request samples

Payload

Content type

application/json

{"comment": "stringstri"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Привязать поставку к заявке

Связывает фактически зарегистрированную поставку с approved-заявкой для закрытия плана.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

supplyId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID зарегистрированной поставки ДТ
fulfilledQuantityLiters	number > 0 Фактически принятый объём, л (по умолчанию = requestedVolume заявки)

Responses

Request samples

Payload

Content type

application/json

{"supplyId": "11111111-1111-4111-8111-111111111111",
"fulfilledQuantityLiters": 0
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"requestedVolumeLiters": 0,
"desiredDeliveryDate": "2019-08-24",
"justification": "string",
"status": "draft",
"initiatorId": "11111111-1111-4111-8111-111111111111",
"submittedAt": "2026-05-18T08:00:00.000Z",
"approvedById": "e14877de-475e-46ee-a353-ff17542c6dab",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectedById": "6c20ebb9-9a39-46e5-82e0-45b38ea7cfd3",
"rejectedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"fulfilledSupplyId": "bb48ac53-1b89-440a-8a91-66ca9626dfe6",
"fulfilledAt": "2026-05-18T08:00:00.000Z",
"lastReturnComment": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

История поставок ДТ

Курсорная пагинация фактически зарегистрированных поставок ДТ по объекту.

Authorizations:

bearer

query Parameters

tankId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: tankId=11111111-1111-4111-8111-111111111111 UUID v4
supplierId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: supplierId=11111111-1111-4111-8111-111111111111 UUID v4
cursor	string
limit	integer ( 0 .. 200 ]

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"quantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"supplyRequestId": "11111111-1111-4111-8111-111111111111",
"sagaId": "11111111-1111-4111-8111-111111111111",
"actorId": "11111111-1111-4111-8111-111111111111"
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Регистрация поставки (приёмка)

Создаёт запись приёмки топлива в резервуар; обновляет баланс и аудит.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

tankId required	string <uuid> (RecordFuelSupplyDtoUuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID v4
supplierId required	string <uuid> (RecordFuelSupplyDtoUuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID v4
quantityLiters required	number > 0
	RecordFuelSupplyDtoUuid (string) or null
	RecordFuelSupplyDtoUuid (string) or null
occurredAt	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...

Responses

Request samples

Payload

Content type

application/json

{"tankId": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"quantityLiters": 0,
"supplyRequestId": "11111111-1111-4111-8111-111111111111",
"sagaId": "11111111-1111-4111-8111-111111111111",
"occurredAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"quantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"supplyRequestId": "11111111-1111-4111-8111-111111111111",
"sagaId": "11111111-1111-4111-8111-111111111111",
"actorId": "11111111-1111-4111-8111-111111111111"
}

Сторно поставки (counter-entry)

Создаёт обратную транзакцию по поставке: оригинал не удаляется, баланс компенсируется.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason required	string [ 3 .. 500 ] characters
comment required	string [ 10 .. 2000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"reason": "string",
"comment": "stringstri"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"kind": "supply",
"signedQuantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"actorId": "11111111-1111-4111-8111-111111111111",
"sagaId": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"supplyRequestId": "11111111-1111-4111-8111-111111111111",
"fuelEntryId": "11111111-1111-4111-8111-111111111111",
"manualPurpose": "string",
"reversesEntryId": "11111111-1111-4111-8111-111111111111",
"reason": "string",
"comment": "string"
}

История списаний ДТ

Курсорная пагинация списаний топлива (как PRD-автоматических, так и ручных).

Authorizations:

bearer

query Parameters

tankId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: tankId=11111111-1111-4111-8111-111111111111 UUID v4
kinds	string CSV: consumption_auto,consumption_manual
shiftReportId	string <uuid> (Uuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... Example: shiftReportId=11111111-1111-4111-8111-111111111111 UUID v4
cursor	string
limit	integer ( 0 .. 200 ]

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"kind": "consumption_auto",
"quantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"fuelEntryId": "11111111-1111-4111-8111-111111111111",
"manualPurpose": "string",
"sagaId": "11111111-1111-4111-8111-111111111111",
"actorId": "11111111-1111-4111-8111-111111111111"
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Ручное списание ДТ

Регистрирует списание топлива вручную (вне PRD shift-report). Снижает баланс резервуара.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

tankId required	string <uuid> (RecordManualConsumptionDtoUuid) ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA... UUID v4
quantityLiters required	number > 0
manualPurpose required	string [ 3 .. 500 ] characters
	RecordManualConsumptionDtoUuid (string) or null
occurredAt	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...

Responses

Request samples

Payload

Content type

application/json

{"tankId": "11111111-1111-4111-8111-111111111111",
"quantityLiters": 0,
"manualPurpose": "string",
"sagaId": "11111111-1111-4111-8111-111111111111",
"occurredAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"kind": "consumption_auto",
"quantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"fuelEntryId": "11111111-1111-4111-8111-111111111111",
"manualPurpose": "string",
"sagaId": "11111111-1111-4111-8111-111111111111",
"actorId": "11111111-1111-4111-8111-111111111111"
}

Сторно списания (counter-entry)

Создаёт обратную транзакцию по списанию: оригинал сохраняется, баланс восстанавливается.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason required	string [ 3 .. 500 ] characters
comment required	string [ 10 .. 2000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"reason": "string",
"comment": "stringstri"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"tankId": "11111111-1111-4111-8111-111111111111",
"organizationId": "11111111-1111-4111-8111-111111111111",
"kind": "supply",
"signedQuantityLiters": 0,
"occurredAt": "2026-05-18T08:00:00.000Z",
"actorId": "11111111-1111-4111-8111-111111111111",
"sagaId": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"supplyRequestId": "11111111-1111-4111-8111-111111111111",
"fuelEntryId": "11111111-1111-4111-8111-111111111111",
"manualPurpose": "string",
"reversesEntryId": "11111111-1111-4111-8111-111111111111",
"reason": "string",
"comment": "string"
}

SCM / Suppliers

Справочник поставщиков

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

По умолчанию — только active. Фильтры: status[], category, q (legalName/shortName/bin/iin). Поставщики — компанийный справочник, без object-scope.

Authorizations:

bearer

query Parameters

status	Array of arrays Example: status=active Фильтр по статусу FSM (можно несколько). По умолчанию — только active
category	string Enum: "tmc" "fuel" "service" "equipment" Example: category=tmc Фильтр по категории поставщика
q	string <= 100 characters Example: q=БурТех Поиск по legalName / shortName / bin / iin
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}
],
"nextCursor": null
}

Создать поставщика (статус draft)

Доступно ролям: Supply, Admin. Затем — POST /:id/submit для отправки на проверку.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

	string or null БИН юр. лица (12 цифр). Заполняется ЛИБО bin, ЛИБО iin (XOR, SCM-SUP-INV-02)
	string or null ИИН индивидуального предпринимателя (12 цифр)
legalName required	string [ 2 .. 500 ] characters Полное юридическое наименование
shortName required	string [ 2 .. 100 ] characters Краткое наименование для UI
legalAddress required	string [ 5 .. 500 ] characters Юридический адрес
countryCode	string = 2 characters Default: "KZ" ISO 3166-1 alpha-2 (по умолчанию KZ)
	string or null КПФ (41 ТОО, 42 АО, 17 ИП). Опционально — выводится из bin/iin
categories required	Array of strings non-empty Items Enum: "tmc" "fuel" "service" "equipment" Категории поставщика (одна или несколько). Q2 — финальный список с PO

Responses

Request samples

Payload

Content type

application/json

{"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"countryCode": "KZ",
"categories": ["tmc"
]
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Получить поставщика по id

Возвращает карточку. Контакты/счета — отдельный endpoint (TODO scm/suppliers).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Отправить поставщика на проверку (draft → under_review)

Требует ≥1 primary contact + ≥1 primary bank с валидным IBAN (SCM-SUP-INV-05). Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

string <= 500 characters

Опциональный комментарий финдиректору при отправке на проверку

Responses

Request samples

Payload

Content type

application/json

{"comment": "Реквизиты заполнены, прошу проверить"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Утвердить поставщика (under_review → active)

Split of duty: approvedBy ≠ submittedBy (SCM-SUP-INV-13). Доступно ceo/admin. Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

string <= 500 characters

Опциональный комментарий при approve (финдиректор/CEO)

Responses

Request samples

Payload

Content type

application/json

{"comment": "Реквизиты проверены, согласовано"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Вернуть в draft с комментарием (under_review → draft)

Доступно ceo/admin. comment обязателен (≥10 символов).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

required

string [ 10 .. 1000 ] characters

Что исправить (минимум 10 символов) — будет видно snabжению

Responses

Request samples

Payload

Content type

application/json

{"comment": "Уточнить юридический адрес — указан фактический"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Заблокировать поставщика (active → suspended)

Reason обязателен. После события scm.supplier.suspended соседние модули отменяют draft закупки (SCM-SUP-INV-03c).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

suspendedReason required	string Enum: "payment_delay" "tax_issue" "quality_complaint" "sanction" "other" Категория причины блокировки
suspendedReasonText required	string [ 10 .. 1000 ] characters Свободный текст причины (минимум 10 символов)

Responses

Request samples

Payload

Content type

application/json

{"suspendedReason": "payment_delay",
"suspendedReasonText": "Просрочка оплаты по счёту № 12345 от 2026-04-01"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Разблокировать поставщика (suspended → active)

Reason обязателен (минимум 10 символов).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 10 .. 1000 ] characters

Обоснование снятия блокировки (минимум 10 символов)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Задолженность погашена согласно платёжному поручению № 67890"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Архивировать поставщика (* → archived, terminal)

Двойное согласование для active/suspended (Q5): coApprovedBy обязателен, ≠ actorId. Cross-aggregate sync guards (SCM-SUP-INV-11/-11c) — TODO до wiring scm/tmc + eam.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID поставщика

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

archivedReason required	string [ 10 .. 1000 ] characters Причина архивации (минимум 10 символов)
	string or null

Responses

Request samples

Payload

Content type

application/json

{"archivedReason": "Контракт расторгнут по соглашению сторон",
"coApprovedBy": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"bin": "190140012345",
"iin": null,
"legalName": "Товарищество с ограниченной ответственностью \"БурТехСервис\"",
"shortName": "ТОО БурТехСервис",
"legalAddress": "г. Алматы, ул. Тестовая 1",
"legalFormCode": "41",
"countryCode": "KZ",
"status": "draft",
"categories": ["tmc"
],
"suspendedReason": null,
"archivedReason": null,
"submittedAt": null,
"submittedBy": null,
"activatedAt": null,
"activatedBy": null,
"suspendedAt": null,
"archivedAt": null,
"archivedCoApprovedBy": null
}

Назначить primary-контакт у поставщика

SCM-SUP-INV-07: два UPDATE в транзакции (сброс текущего primary + установка нового). Partial UNIQUE страхует от гонок (ADR-0028). Idempotent.

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID поставщика
contactId required	string <uuid> UUID контакта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

Назначить primary-счёт у поставщика

SCM-SUP-INV-07 для bank accounts. Аналогично контактам — два UPDATE в транзакции. Idempotent.

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID поставщика
bankId required	string <uuid> UUID банковского счёта

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

Изменить реквизиты банковского счёта поставщика

SCM-SUP-INV-10: смена IBAN валидируется через mod-97 + reason ≥ 10 символов. Каждое изменённое поле пишется в supplier_audit_log; публикуется событие scm.supplier.updated (ADR-0028).

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID поставщика
bankId required	string <uuid> UUID банковского счёта

Request Body schema: application/json
required

iban	string^KZ[A-Z0-9]{18}$ KZ IBAN (20 символов, mod-97)
bankName	string [ 1 .. 200 ] characters Название банка
	string or null БИК (8 символов) или null
	string or null КБе или null
currency	string = 3 characters ISO 4217 валюта счёта
reason required	string [ 10 .. 1000 ] characters Причина изменения реквизитов (≥10 символов) — попадает в supplier_audit_log

Responses

Request samples

Payload

Content type

application/json

{"iban": "string",
"bankName": "string",
"bik": "stringst",
"bk": "st",
"currency": "str",
"reason": "stringstri"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"supplierId": "11111111-1111-4111-8111-111111111111",
"bankName": "string",
"bik": "string",
"iban": "string",
"bk": "string",
"currency": "string",
"isPrimary": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

SCM / TMC

Товарно-материальные ценности (склад, инвентаризация)

Список позиций номенклатуры ТМЦ

Authorizations:

bearer

query Parameters

category	string Enum: "drill_tool" "spare" "consumable" "other"
active	boolean
q	string <= 200 characters
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...
limit	integer [ 1 .. 200 ] Default: 50

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"nomenclatureCode": "string",
"name": "string",
"category": "drill_tool",
"unit": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"lastPurchasePrice": 0,
"weightedAvgPrice": 0,
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": "string"
}

Создать позицию ТМЦ

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

nomenclatureCode required	string [ 1 .. 64 ] characters Уникальный код номенклатуры в рамках организации
name required	string [ 2 .. 500 ] characters Полное наименование позиции
category required	string Enum: "drill_tool" "spare" "consumable" "other" Классификатор позиции (TmcCategory)
unit required	string Enum: "шт" "кг" "л" "м" "компл" Единица измерения
	string or null
initialPrice	number >= 0 Начальная цена (если есть остаток на старте)

Responses

Request samples

Payload

Content type

application/json

{"nomenclatureCode": "DRL-BIT-152",
"name": "Долото буровое 152мм",
"category": "drill_tool",
"unit": "шт",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"initialPrice": 0
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"nomenclatureCode": "string",
"name": "string",
"category": "drill_tool",
"unit": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"lastPurchasePrice": 0,
"weightedAvgPrice": 0,
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Получить позицию по id

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"nomenclatureCode": "string",
"name": "string",
"category": "drill_tool",
"unit": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"lastPurchasePrice": 0,
"weightedAvgPrice": 0,
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Обновить карточку позиции

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

name	string [ 2 .. 500 ] characters
	string or null

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"nomenclatureCode": "string",
"name": "string",
"category": "drill_tool",
"unit": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"lastPurchasePrice": 0,
"weightedAvgPrice": 0,
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Снять позицию с учёта (TMC-INV-14)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"nomenclatureCode": "string",
"name": "string",
"category": "drill_tool",
"unit": "string",
"assetClassId": "11111111-1111-4111-8111-111111111111",
"lastPurchasePrice": 0,
"weightedAvgPrice": 0,
"active": true,
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z"
}

Зарегистрировать поступление ТМЦ

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

warehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Склад-получатель
source required	string Enum: "supplier" "transfer" "return"
	string or null
inboundDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата поступления (ISO date)
documentNumber required	string [ 1 .. 100 ] characters Номер документа-основания (TMC-INV-07 — обязательно)
	string or null
	string or null
receivedById required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID получателя из hr/personnel
required	Array of objects non-empty

Responses

Request samples

Payload

Content type

application/json

{"warehouseId": "11111111-1111-4111-8111-111111111111",
"source": "supplier",
"supplierId": "11111111-1111-4111-8111-111111111111",
"inboundDate": "2019-08-24",
"documentNumber": "string",
"documentReference": "http://example.com",
"requestId": "11111111-1111-4111-8111-111111111111",
"receivedById": "11111111-1111-4111-8111-111111111111",
"lines": [{"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"pricePerUnit": 0
}
]
}

Response samples

Content type

application/json

{"inboundId": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"totalAmount": 0,
"lineCount": 9007199254740991
}

Ручной акт списания

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

warehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Склад-источник
	string or null
targetObjectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID ProductionObject — куда списано
reason required	string Enum: "planned_to" "repair" "production" "loss" Основание списания (для manual_act обязательно)
	string or null
occurredAt required	string <date-time> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Когда произошло списание (ISO datetime)
required	Array of objects non-empty

Responses

Request samples

Payload

Content type

application/json

{"warehouseId": "11111111-1111-4111-8111-111111111111",
"assetId": "11111111-1111-4111-8111-111111111111",
"targetObjectId": "11111111-1111-4111-8111-111111111111",
"reason": "planned_to",
"documentReference": "http://example.com",
"occurredAt": "2019-08-24T14:15:22Z",
"lines": [{"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Response samples

Content type

application/json

{"consumptionId": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"lineCount": 9007199254740991
}

Список перемещений

Authorizations:

bearer

query Parameters

status required	string
warehouseId required	string
cursor required	string
limit required	number

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"fromWarehouseId": "11111111-1111-4111-8111-111111111111",
"toWarehouseId": "11111111-1111-4111-8111-111111111111",
"status": "issued",
"transferDate": "string",
"documentNumber": "string",
"issuedById": "11111111-1111-4111-8111-111111111111",
"confirmedById": "11111111-1111-4111-8111-111111111111",
"issuedAt": "2026-05-18T08:00:00.000Z",
"confirmedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}
],
"nextCursor": "string"
}

Issue: создать перемещение (issued)

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

fromWarehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Склад-источник
toWarehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Склад-получатель
transferDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...
documentNumber required	string [ 1 .. 100 ] characters
required	Array of objects non-empty

Responses

Request samples

Payload

Content type

application/json

{"fromWarehouseId": "11111111-1111-4111-8111-111111111111",
"toWarehouseId": "11111111-1111-4111-8111-111111111111",
"transferDate": "2019-08-24",
"documentNumber": "string",
"lines": [{"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fromWarehouseId": "11111111-1111-4111-8111-111111111111",
"toWarehouseId": "11111111-1111-4111-8111-111111111111",
"status": "issued",
"transferDate": "string",
"documentNumber": "string",
"issuedById": "11111111-1111-4111-8111-111111111111",
"confirmedById": "11111111-1111-4111-8111-111111111111",
"issuedAt": "2026-05-18T08:00:00.000Z",
"confirmedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Получить перемещение по id

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fromWarehouseId": "11111111-1111-4111-8111-111111111111",
"toWarehouseId": "11111111-1111-4111-8111-111111111111",
"status": "issued",
"transferDate": "string",
"documentNumber": "string",
"issuedById": "11111111-1111-4111-8111-111111111111",
"confirmedById": "11111111-1111-4111-8111-111111111111",
"issuedAt": "2026-05-18T08:00:00.000Z",
"confirmedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Confirm: подтвердить прибытие (issued → confirmed)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

note	string <= 500 characters

Responses

Request samples

Payload

Content type

application/json

{"note": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fromWarehouseId": "11111111-1111-4111-8111-111111111111",
"toWarehouseId": "11111111-1111-4111-8111-111111111111",
"status": "issued",
"transferDate": "string",
"documentNumber": "string",
"issuedById": "11111111-1111-4111-8111-111111111111",
"confirmedById": "11111111-1111-4111-8111-111111111111",
"issuedAt": "2026-05-18T08:00:00.000Z",
"confirmedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Список заявок на пополнение

Authorizations:

bearer

query Parameters

status required	string
warehouseId required	string
cursor required	string
limit required	number

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}
],
"nextCursor": "string"
}

Создать заявку (draft)

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

warehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Целевой склад
justification required	string [ 3 .. 2000 ] characters
required	Array of objects non-empty

Responses

Request samples

Payload

Content type

application/json

{"warehouseId": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"lines": [{"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0
}
]
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Получить заявку по id

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Отправить заявку (draft → sent)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

object (SubmitTmcRequestDto)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Согласовать заявку (sent → approved). Только Engineer/Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

object (ApproveTmcRequestDto)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Отклонить заявку (sent → rejected)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 3 .. 500 ] characters

Responses

Request samples

Payload

Content type

application/json

{"reason": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Вернуть на доработку (sent → draft)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

comment

required

string [ 3 .. 500 ] characters

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Взять в работу (approved → in_progress)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

object (StartTmcRequestDto)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Закрыть (in_progress → fulfilled)

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

linkedInboundIds

required

Array of strings <uuid> [ items <uuid >^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... ]

Responses

Request samples

Payload

Content type

application/json

{"linkedInboundIds": ["11111111-1111-4111-8111-111111111111"
]
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"createdById": "11111111-1111-4111-8111-111111111111",
"justification": "string",
"status": "draft",
"approvedById": "11111111-1111-4111-8111-111111111111",
"approvedAt": "2026-05-18T08:00:00.000Z",
"rejectReason": "string",
"createdAt": "2026-05-18T08:00:00.000Z",
"updatedAt": "2026-05-18T08:00:00.000Z",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"fulfilledQuantity": 0
}
]
}

Список инвентаризаций

Authorizations:

bearer

query Parameters

status required	string
warehouseId required	string
cursor required	string
limit required	number

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"inventoryDate": "string",
"responsibleId": "11111111-1111-4111-8111-111111111111",
"status": "in_progress",
"completedAt": "2026-05-18T08:00:00.000Z",
"documentReference": "string",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"bookQuantity": 0,
"actualQuantity": 0,
"variance": 0,
"adjustmentReason": "string"
}
]
}
],
"nextCursor": "string"
}

Стартовать инвентаризацию (snapshot TmcBalance)

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

warehouseId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Склад
inventoryDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...
	string or null

Responses

Request samples

Payload

Content type

application/json

{"warehouseId": "11111111-1111-4111-8111-111111111111",
"inventoryDate": "2019-08-24",
"documentReference": "http://example.com"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"inventoryDate": "string",
"responsibleId": "11111111-1111-4111-8111-111111111111",
"status": "in_progress",
"completedAt": "2026-05-18T08:00:00.000Z",
"documentReference": "string",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"bookQuantity": 0,
"actualQuantity": 0,
"variance": 0,
"adjustmentReason": "string"
}
]
}

Получить инвентаризацию по id

Authorizations:

bearer

path Parameters

id

required

string <uuid>

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"inventoryDate": "string",
"responsibleId": "11111111-1111-4111-8111-111111111111",
"status": "in_progress",
"completedAt": "2026-05-18T08:00:00.000Z",
"documentReference": "string",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"bookQuantity": 0,
"actualQuantity": 0,
"variance": 0,
"adjustmentReason": "string"
}
]
}

Завершить инвентаризацию (in_progress → completed). Создаёт TmcMovement(inventory_adjustment) для variance != 0.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

required

Array of objects non-empty

Array (non-empty)

lineId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID строки
actualQuantity required	number >= 0
	string or null

Responses

Request samples

Payload

Content type

application/json

{"lines": [{"lineId": "11111111-1111-4111-8111-111111111111",
"actualQuantity": 0,
"adjustmentReason": "string"
}
]
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"inventoryDate": "string",
"responsibleId": "11111111-1111-4111-8111-111111111111",
"status": "in_progress",
"completedAt": "2026-05-18T08:00:00.000Z",
"documentReference": "string",
"lines": [{"id": "11111111-1111-4111-8111-111111111111",
"itemId": "11111111-1111-4111-8111-111111111111",
"bookQuantity": 0,
"actualQuantity": 0,
"variance": 0,
"adjustmentReason": "string"
}
]
}

Остатки ТМЦ

Фильтры: warehouseId, itemId, onlyLowStock. Object-scope для foreman/mechanic — фильтрация по warehouseId (TODO интеграция с @RequiresObjectScope после регистрации Warehouse в Refs-Kit).

Authorizations:

bearer

query Parameters

warehouseId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: warehouseId=11111111-1111-4111-8111-111111111111 UUID склада
itemId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: itemId=11111111-1111-4111-8111-111111111111 UUID позиции
onlyLowStock	boolean
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...
limit	integer [ 1 .. 500 ] Default: 100

Responses

Response samples

Content type

application/json

{"items": [{"itemId": "11111111-1111-4111-8111-111111111111",
"warehouseId": "11111111-1111-4111-8111-111111111111",
"quantity": 0,
"minStock": 0,
"isLowStock": true,
"updatedAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": "string"
}

HR / Personnel

Кадровый учёт персонала

Список сотрудников с фильтрами

Курсорная пагинация. Фильтрация по objectId, status и positionId. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Supply, Admin.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=11111111-1111-4111-8111-111111111111 Фильтр по производственному объекту
status	string Enum: "active" "onWatch" "onVacation" "terminated" Example: status=active Фильтр по статусу FSM
positionId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: positionId=11111111-1111-4111-8111-111111111111 Фильтр по должности
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}
],
"nextCursor": null
}

Создать (hire) нового сотрудника

Приём сотрудника на работу (HR 1.1). Idempotent. Роли: Admin.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

fullName required	string [ 1 .. 200 ] characters ФИО сотрудника
tabNumber required	string [ 1 .. 50 ] characters Табельный номер (уникальный бизнес-ключ)
birthDate	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата рождения (ISO 8601, YYYY-MM-DD; диапазон 1900-01-01 … today)
positionId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID должности из справочника
objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID производственного объекта
phone	string <= 50 characters Контактный телефон
email	string <email> ^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z... Рабочий email
hiredAt required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата приёма на работу (ISO 8601, YYYY-MM-DD; диапазон 1990-01-01 … today)

Responses

Request samples

Payload

Content type

application/json

{"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Карточка сотрудника

Возвращает карточку сотрудника. Object scope по id.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Перевести сотрудника на другой объект

Перевод между производственными объектами (HR 1.4). Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

toObjectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID целевого производственного объекта
effectiveFrom	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата начала действия перевода (ISO 8601, YYYY-MM-DD); по умолчанию — сегодня
reason required	string [ 1 .. 1000 ] characters Обоснование перевода (1–1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"toObjectId": "33333333-3333-4333-8333-333333333333",
"effectiveFrom": "2026-05-18",
"reason": "Перевод на участок Борлы"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Заезд на вахту

FSM: active → onWatch. Idempotent. Роли: Engineer, Foreman, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

arrivalDate

string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

Дата заезда на вахту (ISO 8601, YYYY-MM-DD); по умолчанию — сегодня

Responses

Request samples

Payload

Content type

application/json

{"arrivalDate": "2026-05-18"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Отъезд с вахты

FSM: onWatch → active. Idempotent. Роли: Engineer, Foreman, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Уход в отпуск

FSM: active → onVacation. Idempotent. Роли: Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

expectedReturnDate

string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

Ожидаемая дата возвращения с отпуска (ISO 8601, YYYY-MM-DD)

Responses

Request samples

Payload

Content type

application/json

{"expectedReturnDate": "2026-06-15"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Возврат из отпуска

FSM: onVacation → active. Idempotent. Роли: Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

Уволить сотрудника (HR 1.6)

FSM → terminated. Idempotent. Роли: Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID сотрудника

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason required	string [ 1 .. 500 ] characters Причина увольнения
terminatedAt	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата увольнения (ISO 8601, YYYY-MM-DD); по умолчанию — сегодня
force	boolean Пропустить проверку открытых assignments (HR-INV-05)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Увольнение по собственному желанию",
"terminatedAt": "2026-05-18",
"force": false
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"fullName": "Иванов Иван Иванович",
"tabNumber": "TAB-001",
"birthDate": "2026-05-18",
"positionId": "22222222-2222-4222-8222-222222222222",
"status": "active",
"objectId": "33333333-3333-4333-8333-333333333333",
"phone": "+7-700-000-0001",
"email": "ivanov@example.com",
"hiredAt": "2026-05-18",
"terminatedAt": null
}

HR / Brigades

Бригады и состав

Список бригад с фильтрами

Курсорная пагинация. Фильтры: objectId, workType, isActive. Cross-object — CEO/Engineer/Admin/OtibSpecialist; иначе scope по productionObjectIds.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=33333333-3333-4333-8333-333333333333 Фильтр по производственному объекту
workType	string Enum: "drilling" "blasting" "auxiliary" Example: workType=drilling Фильтр по типу работ
isActive	boolean Example: isActive=true Фильтр по активности (по умолчанию true)
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}
],
"nextCursor": null
}

Создать бригаду

Создание производственной бригады (HR 1.2). Idempotent. Роли: Engineer, Foreman, Admin.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

name required	string [ 1 .. 200 ] characters Название бригады
objectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID производственного объекта
workType required	string Enum: "drilling" "blasting" "auxiliary" Тип работ бригады
	string or null

Responses

Request samples

Payload

Content type

application/json

{"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Карточка бригады

Возвращает карточку бригады. Object scope по id.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Обновить бригаду

Изменение имени, типа работ или бригадира (HR 1.2). Роли: Engineer, Foreman, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

name	string [ 1 .. 200 ] characters Новое название бригады
workType	string Enum: "drilling" "blasting" "auxiliary" Новый тип работ
	string or null

Responses

Request samples

Payload

Content type

application/json

{"name": "Бригада-Борлы-1",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Активный состав бригады

Список текущих memberships (toDate IS NULL).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

Responses

Response samples

Content type

application/json

[{"id": "11111111-1111-4111-8111-111111111111",
"brigadeId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": null
}
]

Добавить сотрудника в бригаду

Добавление в состав бригады (HR 1.2). Если у сотрудника есть активная membership в другой бригаде — она закрывается в той же транзакции (HR-BRG-INV-01). Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

personnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID сотрудника
fromDate	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата начала членства (ISO 8601, YYYY-MM-DD); по умолчанию — сегодня

Responses

Request samples

Payload

Content type

application/json

{"personnelId": "22222222-2222-4222-8222-222222222222",
"fromDate": "2026-05-18"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"brigadeId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": null
}

Расформировать бригаду

Деактивация бригады с закрытием всех активных membership (HR-BRG-INV-05). Idempotent.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

string <= 1000 characters

Комментарий к операции (до 1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Окончание буровых работ на участке"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Восстановить бригаду

Восстановление расформированной бригады. Состав не восстанавливается.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID бригады

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

string <= 1000 characters

Комментарий к операции (до 1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Возобновление работ на участке"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"name": "Бригада-Борлы-1",
"objectId": "33333333-3333-4333-8333-333333333333",
"workType": "drilling",
"brigadierId": "22222222-2222-4222-8222-222222222222",
"isActive": true,
"createdAt": "2026-05-18T08:00:00.000Z"
}

Исключить сотрудника из бригады

Закрывает активную membership через toDate. Запись остаётся в БД (audit trail).

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID бригады
personnelId required	string <uuid> UUID сотрудника

Request Body schema: application/json
required

toDate

string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

Дата окончания членства (ISO 8601, YYYY-MM-DD); по умолчанию — сегодня

Responses

Request samples

Payload

Content type

application/json

{"toDate": "2026-05-18"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"brigadeId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": null
}

HR / Watches

Вахты и смены

Список вахт с фильтрами

Курсорная пагинация. Фильтрация по objectId, dateFrom, dateTo. Foreman/Mechanic — только свои объекты.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=33333333-3333-4333-8333-333333333333 Фильтр по производственному объекту
dateFrom	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateFrom=2026-06-01 Левая граница диапазона (по startDate), ISO 8601 YYYY-MM-DD
dateTo	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateTo=2026-06-30 Правая граница диапазона (по startDate), ISO 8601 YYYY-MM-DD
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"startDate": "2026-05-18T08:00:00.000Z",
"endDate": "2026-05-18T08:00:00.000Z",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}
],
"nextCursor": null
}

Создать вахту (HR 1.3, HR 6.1.1)

Создание 15-дневной вахты. HR-WCH-INV-02 (HR-INV-08): startDate ≥ now+3d, иначе 409.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

objectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID производственного объекта
startDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата начала вахты (ISO 8601, YYYY-MM-DD)
endDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата окончания вахты (ISO 8601, YYYY-MM-DD)
force	boolean admin override 3-дневного планирования (Q-WCH-1)

Responses

Request samples

Payload

Content type

application/json

{"objectId": "33333333-3333-4333-8333-333333333333",
"startDate": "2026-06-01",
"endDate": "2026-06-15",
"force": false
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"startDate": "2026-05-18T08:00:00.000Z",
"endDate": "2026-05-18T08:00:00.000Z",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Карточка вахты

Возвращает карточку вахтового цикла.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID вахты

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"startDate": "2026-05-18T08:00:00.000Z",
"endDate": "2026-05-18T08:00:00.000Z",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Включить сотрудника в вахту (FSM → scheduled)

HR-WCH-INV-01: departureDate ≥ arrivalDate, иначе 422.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID вахты

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

personnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID сотрудника
arrivalDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Плановая дата заезда (ISO 8601, YYYY-MM-DD)
departureDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Плановая дата отъезда (ISO 8601, YYYY-MM-DD)

Responses

Request samples

Payload

Content type

application/json

{"personnelId": "22222222-2222-4222-8222-222222222222",
"arrivalDate": "2026-06-01",
"departureDate": "2026-06-15"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"arrivalDate": "2026-05-18T08:00:00.000Z",
"departureDate": "2026-05-18T08:00:00.000Z",
"status": "scheduled",
"cancelledAt": null,
"cancelReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Заезд: FSM scheduled → active

Side-effect — Personnel → on_watch (через hr/personnel handler).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID назначения

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"arrivalDate": "2026-05-18T08:00:00.000Z",
"departureDate": "2026-05-18T08:00:00.000Z",
"status": "scheduled",
"cancelledAt": null,
"cancelReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Отъезд: FSM active → completed

Side-effect — Personnel → active (через hr/personnel handler).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID назначения

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

departureDate

string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

Фактическая дата отъезда (ISO 8601, YYYY-MM-DD); по умолчанию — плановая departureDate

Responses

Request samples

Payload

Content type

application/json

{"departureDate": "2026-06-15"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"arrivalDate": "2026-05-18T08:00:00.000Z",
"departureDate": "2026-05-18T08:00:00.000Z",
"status": "scheduled",
"cancelledAt": null,
"cancelReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Отмена назначения: FSM scheduled → cancelled

HR-WCH-INV-07: после active отменить нельзя — использовать /depart.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID назначения

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

string <= 1000 characters

Комментарий к операции (до 1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Сотрудник заболел до заезда"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"arrivalDate": "2026-05-18T08:00:00.000Z",
"departureDate": "2026-05-18T08:00:00.000Z",
"status": "scheduled",
"cancelledAt": null,
"cancelReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Список смен с фильтрами

Курсорная пагинация. Фильтрация по objectId, shiftDate, shiftType, watchId.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=33333333-3333-4333-8333-333333333333 Фильтр по производственному объекту
shiftDate	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: shiftDate=2026-06-01 Фильтр по дате смены (ISO 8601, YYYY-MM-DD)
shiftType	string Enum: "day" "night" Example: shiftType=day Фильтр по типу смены
watchId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: watchId=11111111-1111-4111-8111-111111111111 Фильтр по родительской вахте
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-05-18T08:00:00.000Z",
"shiftType": "day",
"durationHours": 11,
"foremanId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111",
"substitutions": [ ]
}
],
"nextCursor": null
}

Создать 11-часовую смену

HR-WCH-INV-04: UNIQUE(objectId, shiftDate, shiftType). HR-WCH-INV-06: durationHours=11.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

watchId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID родительской вахты (опционально)
objectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID производственного объекта
shiftDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата смены (ISO 8601, YYYY-MM-DD)
shiftType required	string Enum: "day" "night" Тип смены (day / night)
foremanId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID мастера смены (опционально)

Responses

Request samples

Payload

Content type

application/json

{"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-06-01",
"shiftType": "day",
"foremanId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-05-18T08:00:00.000Z",
"shiftType": "day",
"durationHours": 11,
"foremanId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111",
"substitutions": [ ]
}

Карточка смены

Возвращает карточку 11-часовой смены.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID смены

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-05-18T08:00:00.000Z",
"shiftType": "day",
"durationHours": 11,
"foremanId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111",
"substitutions": [ ]
}

Назначить мастера смены

HR-WCH-INV-05 (HR-INV-06): foreman должен быть active/onWatch. Событие hr.shift.foreman-assigned слушает PRD 1.0.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID смены

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

foremanId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...

UUID нового мастера смены

Responses

Request samples

Payload

Content type

application/json

{"foremanId": "22222222-2222-4222-8222-222222222222"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-05-18T08:00:00.000Z",
"shiftType": "day",
"durationHours": 11,
"foremanId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111",
"substitutions": [ ]
}

Регистрация замены/подмены в смене (HR 1.3)

Foreman регистрирует подмену; не меняет foremanId.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID смены

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

replacedPersonnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID заменяемого сотрудника
substitutePersonnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID подменяющего сотрудника
reason	string <= 1000 characters Комментарий к операции (до 1000 символов)

Responses

Request samples

Payload

Content type

application/json

{"replacedPersonnelId": "22222222-2222-4222-8222-222222222222",
"substitutePersonnelId": "22222222-2222-4222-8222-222222222222",
"reason": "Заболел в день смены"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"watchId": "11111111-1111-4111-8111-111111111111",
"objectId": "33333333-3333-4333-8333-333333333333",
"shiftDate": "2026-05-18T08:00:00.000Z",
"shiftType": "day",
"durationHours": 11,
"foremanId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111",
"substitutions": [ ]
}

HR / Timesheet

Табельный учёт рабочего времени

Табель за период

Курсорная пагинация. Foreman видит только свои objects (productionObjectIds). dateFrom/dateTo — inclusive.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=33333333-3333-4333-8333-333333333333 Фильтр по производственному объекту
personnelId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: personnelId=22222222-2222-4222-8222-222222222222 Фильтр по сотруднику
shiftId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: shiftId=11111111-1111-4111-8111-111111111111 Фильтр по смене
shiftReportId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: shiftReportId=11111111-1111-4111-8111-111111111111 Фильтр по сменному отчёту
status	string Enum: "draft" "confirmed" "adjusted" "reverted" Example: status=confirmed Фильтр по статусу записи
dateFrom required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateFrom=2026-05-18 Нижняя граница периода (ISO 8601, YYYY-MM-DD) — включительно
dateTo required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateTo=2026-05-18 Верхняя граница периода (ISO 8601, YYYY-MM-DD) — включительно
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"shiftId": "22222222-2222-4222-8222-222222222222",
"personnelId": "33333333-3333-4333-8333-333333333333",
"hoursWorked": 10,
"downtimeHours": 1,
"status": "confirmed",
"confirmedFromShiftReport": true,
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"adjustmentReason": null,
"adjustedBy": null,
"adjustedAt": null
}
],
"nextCursor": null
}

Экспорт табеля за период (HR 5.1)

XLSX-выгрузка табеля. Foreman видит только свои objects. Пока возвращает JSON-массив; формат XLSX — TODO до prod (см. open Q-TS-1).

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=33333333-3333-4333-8333-333333333333 Фильтр по производственному объекту
dateFrom required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateFrom=2026-05-18 Нижняя граница периода (ISO 8601, YYYY-MM-DD) — включительно
dateTo required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Example: dateTo=2026-05-18 Верхняя граница периода (ISO 8601, YYYY-MM-DD) — включительно

Responses

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

Карточка записи табеля

Возвращает одну запись табеля. Object scope по shift.objectId записи.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи табеля

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"shiftId": "22222222-2222-4222-8222-222222222222",
"personnelId": "33333333-3333-4333-8333-333333333333",
"hoursWorked": 10,
"downtimeHours": 1,
"status": "confirmed",
"confirmedFromShiftReport": true,
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"adjustmentReason": null,
"adjustedBy": null,
"adjustedAt": null
}

Ручная корректировка часов записи табеля (HR 6.2.5)

Idempotent. Поле reason обязательно (HR-TS-INV-02). Сумма hoursWorked + downtimeHours ≤ 11 (HR-TS-INV-01) — иначе 422 hours_exceed_shift_duration. Роли: Engineer, Admin.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи табеля

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

hoursWorked required	number [ 0 .. 11 ] Отработанные часы после корректировки (0–11)
downtimeHours required	number [ 0 .. 11 ] Часы простоя после корректировки (0–11)
reason required	string [ 1 .. 500 ] characters Причина корректировки — обязательное поле (HR-TS-INV-02)

Responses

Request samples

Payload

Content type

application/json

{"hoursWorked": 9,
"downtimeHours": 1,
"reason": "Сотрудник ушёл раньше по согласованию инженера"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"shiftId": "22222222-2222-4222-8222-222222222222",
"personnelId": "33333333-3333-4333-8333-333333333333",
"hoursWorked": 10,
"downtimeHours": 1,
"status": "confirmed",
"confirmedFromShiftReport": true,
"shiftReportId": "11111111-1111-4111-8111-111111111111",
"adjustmentReason": null,
"adjustedBy": null,
"adjustedAt": null
}

HR / Asset Assignments

Закрепление активов за персоналом

Текущие закрепления (по умолчанию active=true)

Курсорная пагинация. Фильтрация по objectId / assetId / personnelId / role / active. Роли: CEO, Engineer, Foreman, Mechanic, OtibSpecialist, Admin.

Authorizations:

bearer

query Parameters

objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=11111111-1111-4111-8111-111111111111 Фильтр по производственному объекту
assetId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: assetId=11111111-1111-4111-8111-111111111111 Фильтр по UUID актива
personnelId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: personnelId=11111111-1111-4111-8111-111111111111 Фильтр по UUID сотрудника
role	string Enum: "primary_operator" "shift_operator" "mechanic" Example: role=primary_operator Фильтр по роли закрепления
active	any Example: active=true true — только active (toDate IS NULL), false — все, включая закрытые
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"role": "primary_operator",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": "2026-05-18T08:00:00.000Z",
"assignedBy": "11111111-1111-4111-8111-111111111111",
"reason": "Плановая ротация смены",
"closedBy": "11111111-1111-4111-8111-111111111111",
"closeReason": null,
"closeCause": null,
"isActive": true
}
],
"nextCursor": null
}

Закрепить сотрудника на технику (HR 1.4)

Для primary_operator/mechanic предыдущее активное закрепление на той же паре (asset, role) закрывается автоматически. Idempotent. Роли: Engineer, Foreman, Mechanic, Admin.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

assetId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID актива (техники)
personnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID сотрудника
role required	string Enum: "primary_operator" "shift_operator" "mechanic" Роль закрепления
fromDate required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата начала закрепления (ISO 8601, YYYY-MM-DD)
reason	string [ 1 .. 500 ] characters Основание закрепления (опционально)

Responses

Request samples

Payload

Content type

application/json

{"assetId": "11111111-1111-4111-8111-111111111111",
"personnelId": "22222222-2222-4222-8222-222222222222",
"role": "primary_operator",
"fromDate": "2026-05-18",
"reason": "Плановая ротация смены"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"role": "primary_operator",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": "2026-05-18T08:00:00.000Z",
"assignedBy": "11111111-1111-4111-8111-111111111111",
"reason": "Плановая ротация смены",
"closedBy": "11111111-1111-4111-8111-111111111111",
"closeReason": null,
"closeCause": null,
"isActive": true
}

Карточка закрепления

Возвращает закрепление по id. Object scope по связанному активу.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID закрепления

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"assetId": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"role": "primary_operator",
"fromDate": "2026-05-18T08:00:00.000Z",
"toDate": "2026-05-18T08:00:00.000Z",
"assignedBy": "11111111-1111-4111-8111-111111111111",
"reason": "Плановая ротация смены",
"closedBy": "11111111-1111-4111-8111-111111111111",
"closeReason": null,
"closeCause": null,
"isActive": true
}

Закрыть закрепление (to_date=now, cause=manual)

Idempotent. Роли: Engineer, Foreman, Mechanic, Admin. Object scope по связанному активу.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID закрепления

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

toDate	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[... Дата закрытия закрепления (ISO 8601); по умолчанию — сегодня
reason	string [ 1 .. 500 ] characters Основание закрытия (опционально)

Responses

Request samples

Payload

Content type

application/json

{"toDate": "2026-05-18",
"reason": "Перевод на другой объект"
}

Response samples

Content type

application/json

{"type": "https://mineflow.dev/errors/409",
"title": "Asset already decommissioned",
"status": 409,
"code": "ASSET_ALREADY_DECOMMISSIONED",
"instance": "/api/v1/eam/assets/11111111-1111-4111-8111-111111111111"
}

HR / User Accounts

Учётные записи (Keycloak ↔ Personnel)

Список учётных записей (admin only)

Курсорная пагинация. Фильтры status / systemRoleCode / search.

Authorizations:

bearer

query Parameters

status	string Enum: "active" "locked" "deactivated" Example: status=active Фильтр по статусу FSM
systemRoleCode	string Example: systemRoleCode=foreman Фильтр по коду роли (например, "foreman"). Возвращает учётки, чей systemRoleIds содержит роль с этим code.
objectId	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: objectId=11111111-1111-4111-8111-111111111111 Фильтр по производственному объекту (через Personnel.object_id)
search	string <= 200 characters Example: search=ivan Поиск по login, ФИО, табельному номеру
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... Example: cursor=11111111-1111-4111-8111-111111111111 UUID последнего элемента предыдущей страницы
limit	integer ( 0 .. 200 ] Default: 50 Example: limit=50 Максимум элементов на странице (1–200)

Responses

Response samples

Content type

application/json

{"items": [{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}
],
"nextCursor": null
}

Создать учётную запись (HR 1.6)

Создаёт UserAccount для существующего Personnel. Проверки: HR-UA-INV-01 (login unique), HR-UA-INV-03 (one active per personnel), HR-UA-INV-15 (валидная комбинация ролей). Публикует hr.user-account.created.

Authorizations:

bearer

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

personnelId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... UUID Personnel из hr/personnel
login required	string [ 3 .. 50 ] characters ^[a-z][a-z0-9._-]*$ Уникальный login (= keycloak username)
systemRoleIds required	Array of strings <uuid> non-empty [ items <uuid >^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... ] Начальный набор ролей. Обычно одна (Position.system_role_id); для совмещения — несколько (HR 6.1.2; HR-UA-INV-15).
	string or null Если не задан/null — генерируется Keycloak и отправляется через password-reset flow. Минимум 12 символов, lower + upper + digit (когда задан). Сейчас не wired в use-case (R11-DTO-F1) — оставлено для будущей Keycloak Admin API интеграции.

Responses

Request samples

Payload

Content type

application/json

{"personnelId": "11111111-1111-4111-8111-111111111111",
"login": "ivanov",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"initialPassword": null
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Моя учётка (self-service)

Возвращает UserAccount, связанный с keycloak_subject текущего JWT. Доступно любой аутентифицированной роли. Если Keycloak provision ещё не завершился, делает fallback по personnelId.

Authorizations:

bearer

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Карточка учётки (admin only; self-service через /me)

Возвращает полную карточку UserAccount по id. Доступно только Admin. Для self-service использовать GET /hr/user-accounts/me.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Изменить роли пользователя (атомарно, без двойного согласования; Q2 PO)

Полная замена массива systemRoleIds одним PATCH. Защита: HR-UA-INV-04 (нельзя убрать admin у последнего admin), HR-UA-INV-08 (admin не меняет свои роли), HR-UA-INV-15 (валидная комбинация). Публикует hr.user-account.roles-changed.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

systemRoleIds required	Array of strings <uuid> non-empty [ items <uuid >^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{... ] Новый полный набор ролей (replace, не patch). Должен быть валидной комбинацией (HR-UA-INV-15).
reason required	string [ 1 .. 500 ] characters Обязательная причина — попадает в security_audit_log (HR 1.6)

Responses

Request samples

Payload

Content type

application/json

{"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"reason": "Повышение после аттестации"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Деактивировать учётку (terminal)

active|locked → deactivated. Защита HR-UA-INV-04: нельзя деактивировать последнего активного admin в организации.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason

required

string [ 1 .. 500 ] characters

Обязательно — попадает в security_audit_log (HR 1.6, HR-UA-INV-05)

Responses

Request samples

Payload

Content type

application/json

{"reason": "Увольнение"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Принудительная блокировка (admin manual)

active → locked. Публикует hr.user-account.locked.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Request Body schema: application/json
required

reason required	string [ 1 .. 500 ] characters Причина блокировки — попадает в security_audit_log
	string or null

Responses

Request samples

Payload

Content type

application/json

{"reason": "Расследование инцидента безопасности",
"lockedUntil": "2026-05-18T08:00:00.000Z"
}

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Разблокировать учётку

locked → active, failed_login_count = 0.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"id": "11111111-1111-4111-8111-111111111111",
"personnelId": "11111111-1111-4111-8111-111111111111",
"systemRoleIds": ["11111111-1111-4111-8111-111111111111"
],
"login": "ivanov",
"keycloakSubject": null,
"status": "active",
"lastLoginAt": "2026-05-18T08:00:00.000Z",
"failedLoginCount": 0,
"lockedUntil": "2026-05-18T08:00:00.000Z",
"deactivatedAt": "2026-05-18T08:00:00.000Z",
"deactivationReason": null,
"createdAt": "2026-05-18T08:00:00.000Z",
"createdBy": "11111111-1111-4111-8111-111111111111"
}

Сбросить пароль (HR 1.6)

Выпускает one-time password через Keycloak Admin API. Публикует hr.user-account.password-reset-issued. Реальный Keycloak adapter подключается через KEYCLOAK_PASSWORD_RESET_ADAPTER provider override в apps/api/src/modules/iam — по умолчанию используется stub-адаптер.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID учётки

header Parameters

Idempotency-Key

required

string <uuid>

Example: 55555555-5555-4555-8555-555555555555

UUID v4 — повтор с тем же ключом возвращает сохранённый ответ (TTL 24ч)

Responses

Response samples

Content type

application/json

{"resetToken": "kc-reset-xyz",
"expiresAt": "2026-05-18T08:00:00.000Z",
"deliveryChannel": "admin_display"
}

Admin / Outbox

Список outbox-событий + сводная статистика

По умолчанию возвращает pending+dead (нездоровое состояние). Используйте status=published для аудита успешно отправленных.

Authorizations:

bearer

query Parameters

status	string Enum: "pending" "published" "dead" "skipped" Example: status=pending Фильтр по статусу. По умолчанию — pending+dead (нездоровое состояние).
olderThanSeconds	integer ( 0 .. 2592000 ] Example: olderThanSeconds=300 Возвращает только события, у которых createdAt старше N секунд. Удобно для поиска stuck-events (типичные пороги: 300, 900, 3600).
limit	integer [ 1 .. 500 ] Default: 50 Example: limit=50 Максимум записей (1..500, default 50).

Responses

Response samples

Content type

application/json

{"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
"eventType": "string",
"eventVersion": "string",
"status": "pending",
"attempts": 9007199254740991,
"lastError": "string",
"nextAttemptAt": "2019-08-24T14:15:22Z",
"publishedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"partitionKey": "db0d97a8-9e58-4a44-b19b-97f930f840f9"
}
],
"hasMore": true,
"stats": {"pendingCount": 9007199254740991,
"deadCount": 9007199254740991,
"duePendingCount": 9007199254740991,
"oldestDuePendingAt": "2019-08-24T14:15:22Z"
}
}

Сбросить событие на повторную публикацию

Статус → pending, attempts → 0, lastError → null, nextAttemptAt → now(). Используется когда downstream восстановлен и dead-event нужно "дотолкать".

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи event_outbox

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "pending",
"attempts": 9007199254740991
}

Явно пометить событие как пропущенное

Статус → skipped. Используется когда оператор подтвердил, что событие неактуально (данные починены вручную, downstream уже консистентен). Событие НЕ будет опубликовано.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID записи event_outbox

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "skipped"
}

Admin / Queues

Список всех очередей со счётчиками waiting/active/delayed/failed

Возвращает stats по mineflow-saga-steps, mineflow-saga-compensate, mineflow-audit-log. Поле backlogWarning=true означает waiting+delayed превысил порог (default 1000, override через env BULLMQ_BACKLOG_WARN_THRESHOLD).

Authorizations:

bearer

Responses

Response samples

Content type

application/json

{"items": [{"name": "mineflow-saga-steps",
"waiting": 9007199254740991,
"active": 9007199254740991,
"delayed": 9007199254740991,
"failed": 9007199254740991,
"completed": 9007199254740991,
"paused": 9007199254740991,
"backlogWarning": true
}
],
"backlogThreshold": 9007199254740991
}

Детальная статистика одной очереди + sample failed jobs

Возвращает stats + до 10 последних failed jobs (id, reason, attempts).

Authorizations:

bearer

path Parameters

name

required

string

Enum: "mineflow-saga-steps" "mineflow-saga-compensate" "mineflow-audit-log"

Имя очереди

Responses

Response samples

Content type

application/json

{"name": "mineflow-saga-steps",
"waiting": 9007199254740991,
"active": 9007199254740991,
"delayed": 9007199254740991,
"failed": 9007199254740991,
"completed": 9007199254740991,
"paused": 9007199254740991,
"backlogWarning": true,
"recentFailed": [{"jobId": "string",
"failedReason": "string",
"attemptsMade": 9007199254740991,
"finishedOn": "2019-08-24T14:15:22Z"
}
]
}

PRD / Production Plans

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

Курсорная пагинация. Foreman/Mechanic — scoped по своим объектам. Engineer/CEO/Admin — all.

Authorizations:

bearer

query Parameters

horizon	string Enum: "year" "month"
year	integer [ 2020 .. 2100 ]
month	integer [ 1 .. 12 ]
status	string Enum: "draft" "approved" "superseded"
cursor	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...
limit	integer [ 1 .. 200 ] Default: 50

Responses

Response samples

200

Content type

application/json

{"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"horizon": "year",
"year": -9007199254740991,
"month": 1,
"status": "draft",
"currentVersionId": "7d3c5b66-ff6d-477a-9982-96f00519947f",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"versions": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": 1,
"previousVersionId": "de7aac6a-ef9d-4693-9e70-ffd12c3baa44",
"reason": "string",
"requiresCeoApproval": true,
"status": "pending-ceo",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "2019-08-24T14:15:22Z",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}
],
"nextCursor": "53a4a333-2825-45a4-80d2-5f430d088f36"
}

Создать draft план (на год или месяц)

PRD-PLAN-INV-01: один активный план на (org, horizon, year, month).

Authorizations:

bearer

Request Body schema: application/json
required

horizon required	string Enum: "year" "month"
year required	integer [ 2020 .. 2100 ]
	integer or null Default: null

Responses

Request samples

Payload

Content type

application/json

{"horizon": "year",
"year": 2020,
"month": null
}

Response samples

201

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"horizon": "year",
"year": -9007199254740991,
"month": 1,
"status": "draft",
"currentVersionId": "7d3c5b66-ff6d-477a-9982-96f00519947f",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"versions": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": 1,
"previousVersionId": "de7aac6a-ef9d-4693-9e70-ffd12c3baa44",
"reason": "string",
"requiresCeoApproval": true,
"status": "pending-ceo",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "2019-08-24T14:15:22Z",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

Получить план по id (с историей версий)

Возвращает план производства по UUID вместе с историей версий (snapshot активной + предыдущие ревизии).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID плана

Responses

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"horizon": "year",
"year": -9007199254740991,
"month": 1,
"status": "draft",
"currentVersionId": "7d3c5b66-ff6d-477a-9982-96f00519947f",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"versions": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": 1,
"previousVersionId": "de7aac6a-ef9d-4693-9e70-ffd12c3baa44",
"reason": "string",
"requiresCeoApproval": true,
"status": "pending-ceo",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "2019-08-24T14:15:22Z",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

Утвердить draft план (создаёт ProductionPlanVersion v1)

FSM: draft → approved. Активирует расчёт PlanEntry.factValue через подписку на prd.shift-report.approved.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID плана

Request Body schema: application/json
required

required

Array of objects non-empty

Array (non-empty)

objectId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...
drillingTargetM required	number >= 0
blastingTargetM3 required	number >= 0
required	object or null

Responses

Request samples

Payload

Content type

application/json

{"objectPlans": [{"objectId": "e39ea5f2-2188-47f8-add0-f1976630af5e",
"drillingTargetM": 0,
"blastingTargetM3": 0,
"monthlyBreakdown": {"property1": {"drilling": 0,
"blasting": 0
},
"property2": {"drilling": 0,
"blasting": 0
}
}
}
]
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"horizon": "year",
"year": -9007199254740991,
"month": 1,
"status": "draft",
"currentVersionId": "7d3c5b66-ff6d-477a-9982-96f00519947f",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"versions": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": 1,
"previousVersionId": "de7aac6a-ef9d-4693-9e70-ffd12c3baa44",
"reason": "string",
"requiresCeoApproval": true,
"status": "pending-ceo",
"approvedBy": "c91bd49a-5920-43a3-b792-1660455e23bf",
"approvedAt": "2019-08-24T14:15:22Z",
"rejectedBy": "5cb42f49-c6a2-45fc-805c-4333469e59d0",
"rejectedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

Корректировка утверждённого плана (создаёт v{n+1})

Если delta > 20% и инициатор — не CEO: версия в pending_ceo, требуется approveVersion от CEO. Reason обязателен (PRD-PLAN-INV-06).

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID плана

Request Body schema: application/json
required

reason required	string [ 5 .. 1000 ] characters
required	Array of objects non-empty

Responses

Request samples

Payload

Content type

application/json

{"reason": "string",
"objectPlans": [{"objectId": "e39ea5f2-2188-47f8-add0-f1976630af5e",
"drillingTargetM": 0,
"blastingTargetM3": 0,
"monthlyBreakdown": {"property1": {"drilling": 0,
"blasting": 0
},
"property2": {"drilling": 0,
"blasting": 0
}
}
}
]
}

CEO утверждает значительную (>20%) корректировку

pending_ceo → approved_version; current_version_id плана обновляется.

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID плана
versionId required	string <uuid> UUID версии (pending_ceo)

Responses

CEO отклоняет значительную (>20%) корректировку

pending_ceo → rejected_version; current_version_id плана не меняется.

Authorizations:

bearer

path Parameters

id required	string <uuid> UUID плана
versionId required	string <uuid> UUID версии (pending_ceo)

Request Body schema: application/json
required

reason

required

string [ 5 .. 1000 ] characters

Responses

Request samples

Payload

Content type

application/json

{"reason": "string"
}

Заместить план новым (старый → superseded)

FSM: approved → superseded. Новый план должен уже существовать.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID плана

Request Body schema: application/json
required

replacedByPlanId

required

string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

Responses

Request samples

Payload

Content type

application/json

{"replacedByPlanId": "d46a27c3-b175-4b02-98de-0a698c9ce0e4"
}

Создать/скорректировать суточный норматив (DailyNorm)

Foreman ±15% — гард в use-case (PRD-PLAN-INV-13). Engineer/CEO/Admin — без ограничения; >15% за рамки лимита Foreman, требуется amend плана.

Authorizations:

bearer

path Parameters

id

required

string <uuid>

UUID плана

Request Body schema: application/json
required

objectPlanId required	string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...
	string or null Default: null
targetMPerShift required	number > 0
baseTargetM required	number > 0
effectiveFrom required	string <date> ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[...
	string or null Default: null

Responses

Request samples

Payload

Content type

application/json

{"objectPlanId": "99943a2e-9d71-47a9-bea2-c7c58f207eee",
"assetId": null,
"targetMPerShift": 0,
"baseTargetM": 0,
"effectiveFrom": "2019-08-24",
"effectiveTo": null
}

sim

Список sim-прогонов

Возвращает доступные прогоны симулятора (read-only, читаются с диска var/sim).

Authorizations:

bearer

Responses

Реплей событий прогона

Лента событий прогона с пагинацией по тику (afterTick, limit).

Authorizations:

bearer

path Parameters

runId

required

string

query Parameters

afterTick required	string
limit required	string

Responses

Координационные сообщения прогона

Лента coordination-сообщений персон с пагинацией по seq (afterSeq, limit).

Authorizations:

bearer

path Parameters

runId

required

string

query Parameters

afterSeq required	string
limit required	string

Responses

Снимок мира на тике

Состояние мира прогона на конкретном тике (query-параметр tick обязателен).

Authorizations:

bearer

path Parameters

runId

required

string

query Parameters

tick

required

string

Responses

Тики со снимками мира

Список тиков прогона, для которых доступен снимок состояния мира.

Authorizations:

bearer

path Parameters

runId

required

string

Responses

Сводка прогона

Итоговая сводка прогона симулятора (персоны, тики, нарушения инвариантов).

Authorizations:

bearer

path Parameters

runId

required

string

MineFlow Core API (0.1.0)

Health

Liveness probe (процесс жив)

Authorizations:

Responses

Response samples

Liveness probe (alias)

Authorizations:

Responses

Response samples

Readiness probe (Postgres + Redis + Keycloak + MinIO)

Authorizations:

Responses

Response samples

Deep dependencies check (alias readiness)

Authorizations:

Responses

Response samples

Observability

Prometheus scrape endpoint

Authorizations:

Responses

Response samples

Refs / registry

Реестр зарегистрированных справочников

Authorizations:

Responses

Response samples

Admin / Organizations

Создать новую организацию (super-admin)

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Список всех организаций (super-admin)

Authorizations:

Responses

Response samples

Карточка организации

Authorizations:

path Parameters

Responses

Response samples

Обновить организацию (super-admin)

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Деактивировать организацию (super-admin)

Authorizations:

path Parameters

Responses

Response samples

Реактивировать организацию (super-admin)

Authorizations:

path Parameters

Responses

Response samples

Admin / Sagas DLQ

Список failed jobs в DLQ саг

Authorizations:

query Parameters

Responses

Response samples

Счётчики job-ов по статусам

Authorizations:

Responses

Response samples

Перезапустить failed job из DLQ

Authorizations:

path Parameters

Responses

Response samples

Удалить failed job из DLQ

Authorizations:

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required