Группы, с которыми чаще всего работают пользователи и интеграторы.
Точные схемы — в Scalar (/scalar).
/api/v0.1/clashes| Метод | Путь | Назначение | Кто |
|---|---|---|---|
GET |
/clashes |
Список | UI, BI, боты |
GET |
/clashes/list |
Постраничный облегчённый список | Веб-таблица, интеграции |
POST |
/clashes/list/query |
Чтение списка с фильтрами и сортировкой в JSON | Веб-таблица, интеграции |
GET/PUT |
/clashes/table-preferences |
Колонки и их порядок для текущего пользователя | Веб-таблица |
GET |
/clashes/{id} |
Одна коллизия | UI, интеграции |
PATCH |
/clashes/{id}/review-status |
Статус ревью | UI, автоматизация |
POST |
/clashes/claim |
Забрать одну или группу коллизий текущим пользователем | Инженер, главный инженер |
POST |
/clashes/take-in-work |
Устарело: прежнее принятие в работу для старых плагинов | Установленные старые плагины |
GET |
/clashes/attention |
Персональный список коллизий, требующих внимания | Пилот уведомлений |
GET |
/clashes/attention/summary |
Количество коллизий, требующих внимания | Пилот уведомлений |
GET |
/clashes/{id}/attention |
Личные комментарии и состояние последнего возврата | Проектировщик, координатор |
POST |
/clashes/{id}/attention/seen |
Карточка показана: снять свои уведомления о возврате и проверке | Клиенты при открытии карточки |
POST |
/clashes/attention/{eventId}/confirm |
Устарело: подтвердить возврат для старых плагинов | Установленные старые плагины |
PATCH |
/clashes/{id}/severity |
Приоритет | UI |
GET/POST |
/clashes/{id}/image |
Картинка (MinIO) | UI, экспорт |
POST |
/clashes/images/batch |
До 250 картинок одним multipart-запросом | Новый экспортёр |
POST |
/clashes/import/snapshots |
Начать полный импорт NWF | Worker / плагин экспорта |
PUT |
/clashes/import/snapshots/{snapshotId} |
Принять полный снимок NWF | Worker / плагин экспорта |
PUT |
/clashes/import/batch |
Прежний импорт при выключенных снимках | Прежние экспортёры |
Новый экспортёр сначала отправляет полный снимок без PNG. Данные доступны
сразу, пока картинки ещё создаются и загружаются по 250. Автоматическая job
остаётся Running до подтверждения последней пачки; её progress содержит
плановое и выгруженное число батчей. Существующий callback завершения отчёта
совместим с прежними плагинами; новые /clash-detection/results и
/clash-detection/images-completed разделяют приём данных и завершение job.
Схемы запросов и коды ошибок — в Scalar.
Список для веба, плагинов и интеграций включает коллизии со статусами Navisworks
New, Active, Reviewed. Коллизии с Approved и Resolved остаются в БД,
но не возвращаются в GET /clashes; GET /clashes/{id} для них отвечает 404.
После следующей выгрузки из Navisworks коллизия снова появится, если её
исходный статус станет видимым. Рабочий статус ClashFlow на это не влияет.
Для /clashes/list правила поиска, совместной работы фильтров, счётчиков и
пагинации, схемы ответа и примеры ошибок описаны в Scalar (/scalar).
Первая страница — 0, размер по умолчанию — 30, максимум — 100.
Например, /clashes/list?reviewStatus=active возвращает активные коллизии;
totalCount относится к ним, а statusCounts сохраняет количества по всем
рабочим статусам с учётом остальных фильтров. Некорректный reviewStatus
возвращает 400 с кодом invalid_review_status и указанием поля.
Полную карточку с элементами получают через /clashes/{id}.
Перевод свободной коллизии из «Активная» в «В работе» через
PATCH /clashes/{id}/review-status назначает исполнителем вызывающего, если
его основная роль — Engineer или Chief-engineer. Чужое назначение сменой
статуса не перехватывается.
POST /clashes/claim принимает requestId (UUID команды) и clashIds
(1..100 уникальных GUID коллизий) и закрепляет коллизии за текущей учётной
записью, в том числе у другого исполнителя, не меняя статус. Доступен только
инженеру и главному инженеру (иначе 403 forbidden_claim).
Ответ содержит результат по каждой коллизии: claimed (с прежним исполнителем),
alreadyYours или notFound. При сетевом повторе сохраняйте
тот же requestId и набор ID: вернётся прежний результат. Новый набор с тем же
ключом даёт 409; для нового осознанного действия нужен новый ключ.
После ответа обновите карточку/список: сохранённый результат команды может
предшествовать более поздней смене статуса.
Назначение возвращается в status.assignee карточки и облегчённого списка:
имя, устойчивый идентификатор пользователя и дата. Старые записи без исполнителя
имеют null. Фильтр assignedToMe=true для GET /clashes/list и тела POST
/clashes/list/query применяется сервером до пагинации и счётчиков; он
не меняет область NWF и правила видимости. Точные схемы и ошибки — в Scalar.
Для назначенных коллизий обычная смена статуса сохраняет исполнителя.
/clashes/attention возвращает коллизии текущего пользователя с новыми чужими
комментариями, возвратом проектировщику (pendingReturn) или ожидающей
проверкой его ролью (pendingStatusReview: «На согласование» — главным
инженерам, «На проверку фиктивности» — BIM-инженерам). Сводка считает
коллизии: несколько причин одной коллизии увеличивают общую сумму на один.
Состояние хранится на сервере и сохраняется при закрытии приложения.
Комментарий снимается после фактического просмотра через read-state
Discussions. Возврат и проверка снимаются вызовом
POST /clashes/{id}/attention/seen, когда пользователь открыл карточку;
прочтение чата их не снимает. Уход коллизии из статуса отменяет ожидающие
возврат и проверку для всех и сохраняет историю отмены.
Скрытые или отсутствующие коллизии временно исключаются из активного списка
без обработки причин. После настоящего удаления новая карточка с тем же
GUID не наследует прежнее внимание.
Событие clash-attention-changed в /hubs/discussions сообщает перечитать
HTTP-список и сводку. После входа/reconnect клиент тоже выполняет сверку.
Старый POST /clashes/{id}/comments возвращает 410 legacy_comments_disabled;
отправляйте новые сообщения через Discussions с clientMessageId.
Наличие этих методов не подтверждает готовность кнопок и списка в установленном
вебе/Revit. Core и оба клиента пилота обновляются согласованно одним окном;
проверяйте состав установленной сборки.
Веб-таблица использует POST /clashes/list/query: запрос только читает данные,
а JSON позволяет передать несколько выбранных значений без ограничения длины
URL. Значения одного поля объединяются через «ИЛИ», фильтры разных полей —
через «И». Сортировка применяется к одному полю по всей выборке до пагинации.
Прежний GET /clashes/list сохраняется. Доступные поля, операции и ограничения
описаны в Scalar.
Запрос с facetField возвращает варианты значений этого поля с поиском и
пагинацией в facet; строки и общие счётчики списка в таком ответе пустые.
facet.totalCount — число разных значений, facet.counts — количество
уникальных коллизий для каждого значения до пагинации. Варианты учитывают
текущую сборку и остальные фильтры, кроме фильтра самого поля. Через POST
можно дополнительно запросить количества не более 100 выбранных ключей
в facetValues. Для верхнего выбора сборки используется facetField=nwf
с ограниченным списком nwfOptions; недоступные количества возвращаются
в facet.countErrors, а не как ложный ноль. Параметры описаны в Scalar.
Облегчённый список содержит дополнительные поля расположения и массив items
с именами моделей, ID элементов, семействами и типами.
/clashes/table-preferences принимает и возвращает { "columns": [...] }.
Порядок массива задаёт порядок колонок. Настройки принадлежат текущему
авторизованному пользователю и доступны с правом чтения коллизий; фильтры и
сортировка в этом профиле не сохраняются.
Полезные поля полного ответа (упрощённо):
| Поле | Смысл |
|---|---|
info.id |
GUID коллизии |
info.tradeClash |
Номер / обозначение из Clash Detective |
info.testName |
Имя теста |
info.groupName |
Группа результатов Clash Detective внутри теста (вложенные — через « / »); пустая строка, если коллизия не в группе |
info.levelName, info.gridsIntersection, info.distance |
Локация / глубина |
status.reviewStatus |
Active, InWork, … |
status.clashSeverity |
Low … Critical |
status.checkDate |
Дата проверки |
items |
Элементы, участвующие в коллизии |
items[].sourceFileName, items[].sourceFilePath |
Имя и полный адрес оригинальной модели после полного импорта |
items[].nwcFilePath |
Отдельный технический адрес NWC; nullable у прежних элементов |
Navis передаёт адрес NWC; Core определяет оригинал по Model Inventory.
Временный путь конвертации не используется как источник. Для обновления
прежних записей повторите полную выгрузку NWF с теми же GUID. Новый экспортёр
требует включённого протокола снимков; администратор обновляет Core раньше
плагинов. Если соответствие NWC и оригинала неизвестно, весь пакет отклоняется.
/api/v0.1/configuration| Метод | Путь | Назначение |
|---|---|---|
GET/PUT |
/server-settings |
Серверы и пути |
GET/PUT |
/export-settings |
Правила выгрузки NWC |
GET/PUT |
/schedule-timezone |
Общий часовой пояс расписания задач (Administrator) |
Обычно только веб и админы.
GET /configuration/schedule-timezone возвращает сохранённый
configuredTimeZoneId, эффективный effectiveTimeZone, реальный
serverTimeZone и доступные availableTimeZones. PUT принимает
{"timeZoneId":"Asia/Yekaterinburg"}; {"timeZoneId":null} возвращает
автоматический режим (пояс сервера). Неизвестный пояс даёт 400.
Настройка меняет только будущие расчёты расписания, не отображение дат веба.
GET /actualization-policies/schedule-timezone сохраняет прежние поля
описания эффективного пояса и дополнительно показывает serverTimeZone.
/api/v0.1/model-inventoryОтдельный сервис на Worker-контуре (проксируется для UI). Основные:
| Метод | Путь | Назначение |
|---|---|---|
GET |
/solution-tree |
Дерево моделей |
POST |
/solution-tree/refresh |
Обновить дерево |
GET |
/model-artifact-states |
Состояния артефактов |
GET |
/clash-matrices |
Матрицы коллизий |
POST |
/files/delete-local-copies |
Удалить локальные выгрузки в папке |
POST |
/files/delete-nwc |
Удалить *.nwc в папке |
/api/v0.1/nwc-export-queue| Метод | Путь | Назначение | Кто |
|---|---|---|---|
GET |
/nwc-export-queue |
Active Pending/Running + завершённые за N часов | UI (TaskManager) |
POST |
/nwc-export-queue/tasks/{taskId}/cancel |
Остановить партию: Worker снимает Navisworks, строки → Failed | UI (TaskManager) |
/api/v0.1/navis-report| Метод | Путь | Назначение |
|---|---|---|
POST |
/queue |
Поставить генерацию отчёта в очередь |
Внутренний контур агентов (claim / heartbeat / complete). Для Power BI и
Telegram обычно не нужен; используйте список коллизий и статусы.
Наблюдаемость job для UI — отдельные read-эндпоинты (см. Scalar).
Чтение/запись коллизий и админ-операции завязаны на политики авторизации
и роли Keycloak. Анонимно в MVP остаются отдельные worker-callback’и —
их не используйте из внешних интеграций.