# Протокол информационного взаимодействия МИС со шлюзом интеграции Opera

**Редакция:** 0.1 (черновик) · **Дата:** 2026-11-03 · **Приложение А:** [openapi.yaml](openapi.yaml)

## 1. Общие положения

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

**Участники**

| Участник | Роль в обмене |
| --- | --- |
| МИС | Передаёт план операций, сведения о пациенте и бригаде; забирает итоги анестезии |
| Шлюз интеграции Opera | Единственная точка обмена: принимает и проверяет данные, сопоставляет идентификаторы, выдаёт итоги |
| Служба каталогов ОЗ (Active Directory) | Единый идентификатор работника для обеих сторон |
| ЦИСЗ | Получает данные от МИС; в обмене по протоколу не участвует |

**Термины**

- **Операция** — назначенное в МИС хирургическое вмешательство с идентификатором `misOperationId`.
- **Итоги анестезии** — сведения об анестезиологическом пособии, которые Opera
  передаёт МИС после завершения операции (раздел 6).
- **Ревизия** — номер версии записи у отправителя. Он только растёт (раздел 9).
- **Справочник ЦИСЗ** — справочник подсистемы НСИ ЦИСЗ, опубликованный на
  [fhir.by](https://fhir.by/) (раздел 7).

## 2. Границы и владение данными

МИС владеет планом, Opera — фактом. Всё назначенное задаёт МИС, всё, что произошло
в операционной, фиксирует Opera. Каждая сторона хранит свои данные сама и не пишет
в хранилище другой.

| Данные | Владелец | Правило |
| --- | --- | --- |
| Операционные залы и их соответствие залам МИС | Opera | Соответствие ведёт администратор в «Учётной системе» Opera; МИС передаёт свой код зала |
| План операций: время, зал, вмешательство, плановая бригада | МИС | Новая ревизия от МИС целиком замещает прежнюю |
| Пациент: идентификация, демография, антропометрия, краткая карточка | МИС | Opera хранит снимок на момент операции |
| Ссылки на карту в МИС и исследования в PACS | МИС | Opera показывает ссылку как есть, только на разрешённые хосты |
| Факт операции: время начала и окончания, зал, фактическая бригада | Opera | Если операция уже начата, план из МИС не переписывает факт |
| Итоги анестезии | Opera | Выдаются МИС в составе, указанном в разделе 6 |
| Архив операций | Opera | Отмена или удаление в МИС не удаляет из архива операцию, которая уже состоялась |

**Принцип минимума.** Стороны передают только поля, перечисленные в разделах 5 и 6.
Для каждого поля указано, зачем оно нужно. Состав итогов анестезии определён полями
профиля ЦИСЗ [SurgicalProcedure](https://fhir.by/StructureDefinition-SurgicalProcedure.html),
которые МИС заполняет по данным Opera. Расширить состав можно только новой редакцией
протокола (раздел 10).

**Вне протокола:**
- показатели мониторинга и данные медицинских приборов;
- промежуточные записи хода анестезии;
- видеозаписи и снимки;
- электронные документы Opera.

Планирование операций и предоперационный осмотр анестезиолога ведутся в МИС.

## 3. Транспорт и безопасность

Обмен идёт по REST поверх HTTPS (TLS 1.2 и выше). Тела запросов и ответов — JSON
в UTF-8, базовый путь — `/integration/v1`. Все вызовы инициирует МИС: она передаёт
план и сама забирает итоги. Шлюз сам к МИС не обращается.

- **Аутентификация** — OAuth 2.0 Client Credentials. МИС получает токен доступа по
  `client_id` и `client_secret` на `/integration/v1/oauth/token` и передаёт его
  в заголовке `Authorization: Bearer`. Токен действует 15 минут.
- **Взаимная аутентификация TLS** — если её требует ОЗ. Клиентский сертификат МИС
  выпускает УЦ ОЗ либо МИС передаёт его при подключении.
- **Области доступа** — `plan.write` (передача плана) и `results.read` (итоги
  анестезии). Одна учётная запись клиента — одна МИС в одной ОЗ.
- **Сетевой доступ** — шлюз принимает запросы только с адресов серверов МИС,
  согласованных при подключении.
- **Ограничение частоты** — не более 20 запросов в секунду на клиента. При
  превышении шлюз отвечает `429` с заголовком `Retry-After`.
- **Журнал** — шлюз записывает каждый вызов: время, клиент, метод, идентификатор
  записи, результат. В каждом ответе есть `X-Request-Id`. При разборе инцидентов
  МИС ссылается на него.
- **Персональные данные** обрабатываются по Закону № 99-З в целях оказания
  медицинской помощи. Шлюз размещается в контуре ОЗ и не передаёт данные за его пределы.

## 4. Идентификаторы и сопоставление

Все идентификаторы МИС — непрозрачные строки до 64 символов: шлюз их не разбирает
и не вкладывает в них смысла. Идентификатор обозначает один объект всё время его
существования и повторно не используется. Работников идентифицирует
Active Directory ОЗ.

| Идентификатор | Что обозначает | Как используется |
| --- | --- | --- |
| `misOperationId` | Назначение на операцию в МИС | Ключ операции. Не меняется при переносе на другое время или в другой зал |
| `misEncounterId` | Госпитализация в МИС | Связывает операцию со случаем; возвращается в итогах |
| `misPatientId` | Пациент в МИС | Ключ пациента |
| `cardNumber` | Номер медицинской карты стационарного пациента | Для показа и поиска; ключом не является |
| `ldapId` | Работник в Active Directory ОЗ: атрибут `objectGUID` | **Основной ключ работника.** По нему же работник входит в Opera |
| `misEmployeeId` | Работник в МИС | Возвращается в итогах, чтобы МИС не сопоставляла работника сама |
| `positionId` | Ставка (должность) работника в МИС | Хранится как есть и возвращается в итогах. У работника может быть несколько ставок |
| `misRoomKey` | Операционный зал в МИС | Сопоставляется с залом Opera на стороне Opera (см. ниже) |

**Работник: `ldapId`.** Используется атрибут AD `objectGUID`. Он назначается учётной
записи при создании и не меняется при смене фамилии, логина или подразделения.
Передаётся строкой GUID в каноническом виде, как его показывают средства
администрирования AD (`Get-ADUser … | Select ObjectGUID`):
`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, сравнение без учёта регистра. Не используются
`sAMAccountName` и `userPrincipalName` (меняются при смене фамилии) и `objectSid`
(меняется при переносе учётной записи между доменами).

**Сопоставление зала.** Соответствие «зал МИС → зал Opera» хранится в Opera: у зала
в «Учётной системе» указывается код зала МИС. Если код ещё не указан, шлюз ищет зал
по названию без учёта регистра и пробелов и при совпадении запоминает код. Если зал
не найден, операция принимается без зала с предупреждением `ROOM_NOT_MAPPED`, и зал
назначает оперблок. МИС никаких таблиц соответствия не ведёт.

**Сопоставление работника.** Шлюз ищет работника по `ldapId`. Если `ldapId` не передан
или его нет в AD, шлюз принимает участника бригады по `misEmployeeId` и ФИО
и возвращает предупреждение `EMPLOYEE_NOT_IN_DIRECTORY`. Операция всё равно
принимается: из-за расхождения в справочнике работников её нельзя снимать с плана.

## 5. Данные от МИС

МИС передаёт операцию одним запросом `PUT /operations/{misOperationId}`. Запрос
содержит план, пациента, бригаду, ссылки и краткую карточку. Повторная передача той же
ревизии безопасна (раздел 9). Пациента между операциями можно обновить запросом
`PUT /patients/{misPatientId}`, например после нового взвешивания.

### 5.1 Операция

| Поле | Обяз. | Содержание | Зачем |
| --- | --- | --- | --- |
| `revision` | да | Ревизия записи в МИС | Порядок изменений (раздел 9) |
| `status` | да | `PLANNED` или `CANCELLED` | Постановка в план и снятие с плана |
| `misEncounterId` | да | Госпитализация | Профиль SurgicalProcedure требует ссылку на случай |
| `scheduledStart` | нет | Плановое начало, ISO 8601 с часовым поясом. Если не передано, операция в листе ожидания | Расписание зала |
| `plannedDurationMin` | нет | Плановая длительность, минуты | Расписание зала |
| `urgency` | да | Срочность, код справочника ЦИСЗ | Расписание; поле профиля |
| `room` | нет | `misRoomKey` и название зала. Несопоставленный зал не отклоняет операцию (раздел 4) | Расписание зала |
| `department` | нет | Код и название отделения, направившего пациента | Показ на пульте |
| `procedure` | да | Вмешательство: код справочника ЦИСЗ «Хирургические вмешательства» и текст | Показ на пульте, архив |
| `diagnosis` | да | Диагноз до операции: код МКБ-10 и текст | Показ на пульте, архив |
| `team` | да | Плановая бригада (5.3) | Доступ к операции, показ на пульте |
| `links` | нет | Ссылки (5.4) | Переход в МИС и PACS с пульта |
| `card` | нет | Краткая карточка (5.5) | Показ на пульте |
| `patient` | да | Пациент (5.2) | — |

### 5.2 Пациент

| Поле | Обяз. | Содержание | Зачем |
| --- | --- | --- | --- |
| `misPatientId` | да | Ключ пациента | Сопоставление |
| `cardNumber` | да | Номер медицинской карты | Показ, поиск в архиве |
| `lastName`, `firstName`, `middleName` | да / да / нет | ФИО | Идентификация пациента в операционной |
| `birthDate` | да | Дата рождения | Идентификация, возраст для расчётов |
| `sex` | да | `male` или `female` — обязательный реквизит медицинской карты (ф. 003/у-07) | Расчёты анестезиолога |
| `anthropometry` | нет | `heightCm`, `weightKg`, `measuredAt` | Расчёт доз и скоростей введения |
| `allergies` | нет | `state` (`PRESENT`, `NONE`, `UNKNOWN`) и `text` | Безопасность назначений |
| `bloodGroup` | нет | `abo` (`O`, `A`, `B`, `AB`) и `rh` (`POS`, `NEG`) | Готовность к трансфузии |

Антропометрия передаётся с датой измерения (`measuredAt`). Если её нет, анестезиолог
вводит рост и вес сам, и для итогов используется его значение. Если аллергоанамнез
не передан, Opera считает его несобранным (`UNKNOWN`), а не отрицательным.

### 5.3 Участник бригады

| Поле | Обяз. | Содержание |
| --- | --- | --- |
| `ldapId` | да* | `objectGUID` работника в AD ОЗ |
| `misEmployeeId` | да | Ключ работника в МИС |
| `positionId` | нет | Ставка, на которой работник участвует в операции |
| `lastName`, `firstName`, `middleName` | да / да / нет | ФИО (для показа и для случая, когда работника нет в AD) |
| `role` | да | Роль в бригаде, код справочника ЦИСЗ «Состав оперирующей бригады» |

\* Без `ldapId` шлюз принимает участника с предупреждением (раздел 4).

### 5.4 Ссылки

`links` — список `{rel, href, title}`. Адрес полностью формирует МИС. Opera показывает
ссылку на пульте и открывает её без изменений.

| `rel` | Куда ведёт |
| --- | --- |
| `mis-patient` | Карта пациента в МИС |
| `mis-operation` | Назначение на операцию в МИС |
| `pacs-study` | Исследование в PACS; ссылок может быть несколько |

Шлюз принимает ссылки только на хосты из списка разрешённых. Список ведёт администратор
ОЗ в настройках шлюза: схема (`https` или `http`), имя хоста и порт отдельно для МИС
и для PACS. Ссылку на хост не из списка шлюз отклоняет с кодом `LINK_HOST_NOT_ALLOWED`,
а в поле `field` указывает, какая это ссылка.

### 5.5 Краткая карточка

`card.sections` — до 8 разделов `{title, fields}`. В разделе до 20 полей
`{label, value, alert}`. Opera показывает карточку на пульте как есть; `alert: true`
подсвечивает поле. Состав и порядок разделов определяет МИС.

## 6. Данные для МИС: итоги анестезии

После завершения операции Opera публикует итоги анестезии. По ним МИС заполняет поля
профиля ЦИСЗ SurgicalProcedure, относящиеся к анестезии и бригаде. МИС забирает итоги
сама из ленты `GET /anesthesia-results?after={cursor}` (раздел 8). Текущие итоги
одной операции можно получить по `GET /anesthesia-results/{misOperationId}`.

| Поле | Содержание | Поле SurgicalProcedure |
| --- | --- | --- |
| `misOperationId`, `misEncounterId`, `misPatientId` | Ключи МИС | `basedOn`, `encounter`, `subject` |
| `revision` | Ревизия итогов в Opera | — |
| `status` | `FINAL` — итоги подписаны; `AMENDED` — исправлены; `ENTERED_IN_ERROR` — отозваны | `status` |
| `operationPeriod` | Фактические начало и окончание операции | `occurrence[x]` |
| `misRoomKey` | Фактический зал, код МИС | `location` |
| `anesthesia.type` | Вид анестезии, код справочника ЦИСЗ «Виды анестезии» | `extension:anesthesia` |
| `anesthesia.period` | Начало и окончание анестезии | — (для журнала МИС) |
| `team` | Фактическая бригада: `ldapId`, `misEmployeeId`, `positionId`, `role` | `performer` |
| `medications` | Введённые препараты (6.1) | `used` |
| `signedAt` | Когда итоги подписал анестезиолог | — |

### 6.1 Введённые препараты

По каждому препарату, введённому за время анестезиологического пособия, передаётся
одна строка. Состав строки совпадает с полем `used` профиля SurgicalProcedure: в нём
допустима только ссылка на запись справочника ЦИСЗ `MedicationBy` и наименование.

| Поле | Содержание | Поле SurgicalProcedure |
| --- | --- | --- |
| `medication.coding` | Код записи справочника `MedicationBy`: торговое наименование, лекарственная форма, упаковка | `used.reference` = `Medication/<код>` |
| `medication.text` | Наименование препарата | `used.display` |
| `uncoded` | `true`, если препарата нет в `MedicationBy`; тогда передаётся только наименование | — |

Дозы, пути, время и скорость введения не передаются: в профиле операции ЦИСЗ таких
полей нет. Профиль принимает до 10 препаратов на операцию. Opera передаёт все,
порядок строк — по времени первого введения.

## 7. Справочники

Обе стороны кодируют данные справочниками НСИ ЦИСЗ, а не собственными. Поэтому
таблицы перекодировки между МИС и Opera не нужны, а коды из итогов анестезии
переходят в пакет для ЦИСЗ без изменений.

| Справочник ЦИСЗ | Id | Где используется | Записей* | Примеры кодов |
| --- | --- | --- | --- | --- |
| Виды анестезии | `AnesthesiaType` | `anesthesia.type` (6) | 20, иерархический | `general`, `endotracheal`, `spinal`, `epidural`, `no-anesthesia` |
| Состав оперирующей бригады | `OperatingTeam` | `team[].role` (5.3, 6) | 14 | `operator`, `assistant`, `anesthetist`, `anesthetist-sister`, `surgical-sister` |
| Справочник ЛС | `MedicationBy` | `medications[].medication` (6.1) | 9434 | запись = торговое наименование + форма + упаковка |
| Срочность вмешательства | `ProcedureUrgency` | `urgency` (5.1) | 3 | `planned`, `urgent`, `emergency` |
| Хирургические вмешательства (NCSP-B, приказ № 1578) | `SurgicalInterventions` | `procedure` (5.1) | 8740 | `JESA00`, `JESA10` |
| МКБ-10 | `InternClassificDiseases10` | `diagnosis.icd10` (5.1) | 17730 | `K80.1` |

\* По `$expand` на тестовом сервере ЦИСЗ, ноябрь 2026.

**Кодирование.** Код передаётся объектом `{system, version, code, display}`.
`system` имеет вид `https://fhir.by/ValueSet/<Id>`, как в примерах руководства
[fhir.by](https://fhir.by/terminology.html). `version` — версия справочника, по которой
выбран код. Шлюз проверяет коды от МИС по актуальной версии справочника; неизвестный
код отклоняется с ошибкой `UNKNOWN_CODE`.

**Источник.** Справочники загружаются из терминологического сервиса НСИ ЦИСЗ
(`ValueSet/$expand`, `ValueSet/$validate-code`; раздел 6 Протокола информационного
взаимодействия МИС ОЗ с ЦИСЗ, [описание](https://fhir.by/nsiTerminologyService.html)).
Шлюз хранит версионированную копию и обновляет её ежедневно. Если НСИ недоступна,
он работает по последней загруженной версии.

## 8. Сценарии обмена

1. **Постановка в план.** МИС передаёт `PUT /operations/{misOperationId}` со
   `status: PLANNED`. Шлюз отвечает `200` и `result: ACCEPTED`. Операция появляется
   в расписании зала и на пульте.
2. **Изменение и перенос.** МИС передаёт ту же операцию целиком с бо́льшей ревизией.
   Если операция ещё не начата, план замещается. Если начата, шлюз принимает ревизию,
   но факт (время, зал, статус) не меняется, а в ответе приходит предупреждение
   `PLAN_DIFFERS_FROM_FACT`.
3. **Отмена.** МИС передаёт `status: CANCELLED`. Не начатая операция снимается
   с плана. Начатую или завершённую отменить нельзя: шлюз отвечает `409`
   `OPERATION_ALREADY_STARTED`, и оперблок разбирает расхождение.
4. **Обновление пациента.** `PUT /patients/{misPatientId}` — для пациента, уже переданного в операции, — обновляет антропометрию,
   аллергоанамнез, группу крови и карточку во всех ещё не завершённых операциях
   пациента.
5. **Получение итогов.** МИС периодически, рекомендуется раз в минуту, вызывает
   `GET /anesthesia-results?after={cursor}`. В ответе — записи в порядке публикации
   и `nextCursor`. МИС сохраняет курсор только после того, как обработала записи.
   Первый вызов — без `after`.
6. **Исправление итогов.** Если анестезиолог исправил итоги, в ленте появляется новая
   ревизия той же операции со `status: AMENDED`. Если итоги отозваны —
   `ENTERED_IN_ERROR`. МИС замещает ранее полученные данные.

## 9. Ошибки, повторы, ревизии

**Ревизии.** Шлюз хранит последнюю принятую ревизию каждой операции и каждого пациента.

- Ревизия **больше** сохранённой — принимается.
- Ревизия **равна** сохранённой — ответ `200` с `result: UNCHANGED`. Это повтор после сбоя связи.
- Ревизия **меньше** сохранённой — ответ `200` с `result: STALE`, запись не меняется.

Сообщения, пришедшие не по порядку, не откатывают данные назад.

**Повторы.** `PUT` идемпотентен, повтор безопасен. При сетевой ошибке, `429` или
`5xx` МИС повторяет запрос с нарастающей паузой: 1, 2, 4, 8 секунд и далее до 5 минут.
При остальных `4xx` повтор не поможет: нужно исправить данные.

**Тело ошибки:** `{code, message, field, requestId}`. Поле `message` написано для
человека: МИС может показать его в своём журнале как есть.

| HTTP | `code` | Когда |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | Нет обязательного поля, неверный формат; `field` указывает поле |
| 400 | `UNKNOWN_CODE` | Кода нет в справочнике ЦИСЗ актуальной версии |
| 400 | `LINK_HOST_NOT_ALLOWED` | Ссылка на хост, не согласованный при подключении |
| 401 | `UNAUTHORIZED` | Нет токена или срок токена истёк |
| 403 | `FORBIDDEN` | У клиента нет нужной области доступа |
| 404 | `NOT_FOUND` | Итогов по операции нет; пациент в `PUT /patients` шлюзу ещё не известен |
| 409 | `OPERATION_ALREADY_STARTED` | Отмена операции, которая уже начата |
| 429 | `RATE_LIMITED` | Превышена частота запросов |
| 503 | `UNAVAILABLE` | Шлюз временно недоступен; повторить позже |

**Предупреждения** (`warnings` в ответе `200`) не мешают приёму:
`EMPLOYEE_NOT_IN_DIRECTORY`, `ROOM_NOT_MAPPED`, `PLAN_DIFFERS_FROM_FACT`.

## 10. Версии и песочница

**Версии контракта.** Версия входит в путь: `/integration/v1`.
- Обратно совместимые изменения — новое необязательное поле или новое значение
  предупреждения — выходят в той же версии. МИС должна игнорировать незнакомые поля.
- Несовместимые изменения выходят в `/v2`. Прежняя версия работает параллельно
  не менее 6 месяцев.
- Состав передаваемых данных меняется только новой редакцией протокола, которую
  согласовали обе стороны.

**Песочница.** На демонстрационном стенде разворачивается отдельный экземпляр шлюза
со своей учётной записью клиента и синтетическими данными. Песочница принимает все
вызовы раздела 5 и отвечает так же, как рабочий шлюз. После планового окончания
операции песочница публикует синтетические итоги анестезии. Данные песочницы
сбрасываются ежедневно. Доступ к ней выдаётся по заявке, на период разработки
и испытаний.

## 11. Открытые вопросы

- [ ] Вид `system` в кодах: `https://fhir.by/ValueSet/<Id>` (примеры руководства)
  или `urn:oid:<Id>` (терминологический сервер) — какой принимает валидатор ЦИСЗ.
- [ ] Ресурс `Medication` для `used`: МИС включает его в пакет или ссылается на
  уже существующий в ЦИСЗ — уточняется у РНПЦ МТ.
- [ ] Если препаратов больше 10, какие из них МИС передаёт в ЦИСЗ.
- [ ] Нужна ли взаимная аутентификация TLS в контуре ОЗ.
- [ ] Передавать ли беременность и срок гестации отдельным полем пациента.
- [ ] Версия Протокола ЦИСЗ, на которую опирается раздел 6: 1.3 (приказ МЗ № 603
  от 20.05.2026) или 1.4.