API

[ПР] Три группы: входящий FHIR от вендоров СМП, внутренний REST для собственных клиентов, исходящий к МИС и серверам координат.

Базовый префикс внутреннего API — /api/v1. Аутентификация клиентов — сессия/JWT + RBAC; для интеграций — mTLS + сервисная учётная запись.

Входящий: приём от СМП

Метод	Путь	Аутентификация	Ответ
POST	/fhir/$process-message	mTLS + IP allowlist	202 / синхронный Bundle для transport_request
POST	/api/v1/smp/transport-request	mTLS	200 + Bundle с решением
POST	/api/v1/smp/transport-notification	mTLS	202
POST	/api/v1/smp/transport-health-status	mTLS	202
POST	/api/v1/smp/transport-cancel	mTLS	202
POST	/api/v1/smp/transport-complete	mTLS	202
GET	/fhir/metadata	публично	CapabilityStatement

Подробности контрактов и обработки ошибок — в «Входящих сообщениях».

Центральный пульт и направления

Метод	Путь	Роль	Назначение
GET	/api/v1/transports	operator	Список направлений; фильтры по статусу, цвету, времени
GET	/api/v1/transports/{id}	operator	Карточка: пациент, состояние, динамика, координаты
GET	/api/v1/transports/{id}/vitals	operator	История витальных показателей
GET	/api/v1/transports/{id}/locations	operator	Трек машины
POST	/api/v1/transports/{id}/handoff-to-mis	operator	Ручная передача в МИС для сбора бригады (FR-T-11)
POST	/api/v1/transports/{id}/accept	triage_nurse	Подтверждение приёма пациента (accepted_at)
GET	/api/v1/bed-requests	operator	Журнал запросов мест
POST	/api/v1/bed-requests/{id}/decide	operator	Решение по запросу госпитализации
WS	/api/v1/ws/pult	operator	Поток обновлений пульта

POST /api/v1/transports/{id}/handoff-to-mis

{
  "reason": "Подозрение на ОИМ, требуется кардиореанимационная бригада",
  "requested_specialties": ["cardiology", "intensive_care"],
  "eta_minutes": 8
}

Действие фиксирует, кто и почему передал

initiated_by и reason обязательны. Это не бюрократия: расхождения между рекомендацией правил и решением оператора — основной материал для последующей настройки правил сортировки.

Обращения и сортировка

Метод	Путь	Роль	Назначение
POST	/api/v1/appeals/self	публично (терминал)	Кнопка «ЗАРЕГИСТРИРОВАТЬ ОБРАЩЕНИЕ В ПРИЕМНЫЙ ПОКОЙ»
GET	/api/v1/appeals	triage_nurse, registrar	Список обращений
GET	/api/v1/appeals/{id}	triage_nurse, registrar	Карточка обращения
POST	/api/v1/appeals/{id}/assess	triage_nurse	Сортировка: расчёт правилами или ручное присвоение цвета
POST	/api/v1/appeals/{id}/reassess	triage_nurse	Пересортировка при ухудшении
POST	/api/v1/appeals/{id}/register	registrar	Оформление: паспортная часть + ЭЦП → МИС
POST	/api/v1/appeals/{id}/close	registrar	Выбытие из приёмного отделения (FR-T-24)
GET	/api/v1/appeals/{id}/ticket	triage_nurse	Данные талона для печати

POST /api/v1/appeals/{id}/assess — сортировка по правилам

{
  "mode": "rules",
  "inputs": [
    { "param": "respiratory_rate", "loinc": "9279-1", "value": 26, "unit": "/min" },
    { "param": "spo2",             "loinc": "2708-6", "value": 91, "unit": "%" },
    { "param": "temperature",      "loinc": "8310-5", "value": 38.4, "unit": "Cel" },
    { "param": "gender",  "value_text": "male" },
    { "param": "weight",  "value": 82, "unit": "kg" }
  ]
}

Ответ

{
  "assessment_id": 10432,
  "color": "yellow",
  "ticket_code": "В34-017",
  "rule": { "code": "R-YEL-RESP", "version": 3 },
  "explanation": "ЧД 26 ≥ 22 и SpO₂ 91 % < 94 % — правило R-YEL-RESP v3",
  "sla_deadline": "2026-07-14T11:05:00+03:00"
}

POST /api/v1/appeals/{id}/assess — быстрая ручная сортировка

{
  "mode": "manual",
  "color": "red",
  "reason": "Визуальная оценка: нарушение сознания"
}

Ответ всегда содержит обоснование

explanation — не украшение интерфейса. Медсестра должна видеть, почему система предложила цвет, чтобы осознанно согласиться или переопределить. Система, выдающая цвет без объяснения, не будет использоваться по назначению — персонал начнёт ставить цвета вручную, и заявленная инновация исчезнет.

Очередь

Метод	Путь	Роль	Назначение
GET	/api/v1/queue	registrar	Очередь в порядке приоритета
POST	/api/v1/queue/call-next	registrar	Вызвать следующего (красные → жёлтые → зелёные)
POST	/api/v1/queue/{id}/call	registrar	Вызвать конкретный талон
GET	/api/v1/queue/board	публично (табло)	Данные для ТВ-табло
GET	/api/v1/queue/sla-breaches	admin	Нарушения норматива выбытия

Правила сортировки

Метод	Путь	Роль	Назначение
GET	/api/v1/triage-rules	admin	Список правил
POST	/api/v1/triage-rules	admin	Создать правило
POST	/api/v1/triage-rules/{id}/versions	admin	Новая версия (черновик)
POST	/api/v1/triage-rules/{id}/versions/{v}/approve	admin	Утверждение версии + ЭЦП
POST	/api/v1/triage-rules/{id}/versions/{v}/activate	admin	Ввод в действие
POST	/api/v1/triage-rules/simulate	admin	Прогон набора значений без сохранения

simulate — обязательная защита от ошибки в правилах

Правило сортировки, введённое с опечаткой в пороге, может неверно классифицировать пациентов до того, как это заметят. Возможность прогнать новую версию на исторических данных до активации — не удобство, а мера безопасности. Реализуется до первого редактирования правил в промышленной эксплуатации.

Администрирование и отчётность

Метод	Путь	Роль	Назначение
GET	/api/v1/providers	admin	Провайдеры по трём осям
POST	/api/v1/providers	admin	Подключить провайдера
GET	/api/v1/providers/{id}/health	admin	Доступность источника
GET	/api/v1/devices	admin	Полевые устройства и шлюзы
GET	/api/v1/reports/kpi/waiting-time	admin	КПЭ: среднее время ожидания
GET	/api/v1/reports/kpi/throughput	admin	КПЭ: пациентов в час
GET	/api/v1/reports/calls	admin	Статистика вызовов из палат
GET	/api/v1/audit	security	Журнал аудита
GET	/api/v1/security-events	security	События информационной безопасности

Исходящие вызовы

Направление	Операция	Описание
→ МИС	push_appeal	Создание обращения в приёмный покой
→ МИС	request_team	Запрос сбора бригады встречи
→ МИС	cancel_notice	Уведомление об отмене транспортировки

| → Сервер координат | fetch_positions | Опрос положения карет | | → Сервер координат | health | Проверка доступности |

Контракты адаптеров — в «Адаптерах».

Общие соглашения

Аспект	Правило
Формат	JSON; FHIR-эндпоинты — application/fhir+json
Время	ISO 8601 со смещением, всегда
Ошибки	{ "error": { "code", "message", "details" } }; FHIR-эндпоинты — OperationOutcome
Пагинация	?limit=&cursor=; курсорная, не offset
Идемпотентность	Заголовок Idempotency-Key для всех POST, меняющих состояние
Версионирование	Префикс /api/v1; несовместимые изменения — новый префикс
Аудит	Каждый вызов, читающий или меняющий ПДн, → audit_log
Ограничение частоты	На сервисную учётную запись; 429 + Retry-After