--- name: smartica-mis-integration description: >- Реализация и поддержка интеграции медицинской информационной системы (МИС) со Smartica: кнопка запуска приёма, SSO-ссылка для входа врача, GET контекста приёма, PUT записи протокола, сценарий Import и режимы доставки push/pull. Активируется при работе с кодом интеграции Smartica, при упоминании encounter_id, smartica_encounter_id, launch_url, платформы Smartica, а также при разборе ошибок этой интеграции. license: MIT metadata: author: Smartica docs: https://smartica.ai/help/integrations/overview --- # Интеграция МИС со Smartica Smartica записывает разговор врача с пациентом, расшифровывает его и возвращает заполненные поля протокола в МИС. Этот скилл содержит инварианты контракта и типичные ошибки. **Он не заменяет документацию** — за деталями всегда обращайся к источнику ниже. ## Источник правды Перед реализацией загрузи актуальную документацию. Не полагайся на память: контракт мог измениться. - Индекс: `https://smartica.ai/llms.txt` - Любая статья доступна как Markdown — добавь `.md` к адресу. | Тема | URL | |---|---| | Обзор и модель взаимодействия | `https://smartica.ai/help/integrations/overview.md` | | Термины и идентификаторы | `https://smartica.ai/help/integrations/glossary.md` | | Тестовая площадка и адреса контуров | `https://smartica.ai/help/integrations/test-environment.md` | | Launch: запуск из МИС | `https://smartica.ai/help/integrations/launch.md` | | SSO и ссылка для входа | `https://smartica.ai/help/integrations/launch-and-sso.md` | | GET контекста приёма | `https://smartica.ai/help/integrations/mis-api-get-encounter.md` | | PUT записи протокола | `https://smartica.ai/help/integrations/mis-api-export-encounter.md` | | Import: запись вне МИС | `https://smartica.ai/help/integrations/import.md` | | Авторизация и ошибки | `https://smartica.ai/help/integrations/authentication-and-errors.md` | | Лимиты | `https://smartica.ai/help/integrations/limits.md` | | Диагностика по симптомам | `https://smartica.ai/help/integrations/troubleshooting.md` | Загружай `.md`-версии, а не HTML-страницы `/help`. ## Модель взаимодействия Запросы идут **в обе стороны**, и это два разных API с двумя разными секретами: - **МИС → Smartica**: `Authorization: Bearer `. Так запрашивается ссылка для входа врача и, в режиме `pull`, забираются готовые протоколы. - **Smartica → МИС**: одна из трёх схем поверх HTTPS — HMAC-подпись (заголовки `Smartica-Signature` и `Smartica-Timestamp`, максимальная защита), `Authorization: Bearer <токен>` (по умолчанию) или HTTP Basic (совместимость). Схема фиксируется при подключении. Так вызываются `GET` контекста и `PUT` результата. Если выбрана HMAC-подпись: подписываемая строка — `"{timestamp}.{МЕТОД}.{путь}.{тело}"`, алгоритм HMAC-SHA256 в hex. Проверяй свежесть метки времени (допуск 5 минут), бери **сырое тело** до разбора JSON и сравнивай подпись за постоянное время. Точный контракт — в статье об авторизации. Не путай эти секреты и не используй один вместо другого. ## Остановись и спроси, если неизвестно Эти значения **выдаёт Smartica при подключении**. Их нельзя подобрать или вывести из документации: - точный адрес SSO endpoint; - зарегистрированный `platform` (идентификатор клиники); - режим доставки результата: `push` или `pull`. Базовый адрес Smartica всегда бери из конфигурации проекта, а не из примеров в документации: разработка идёт на тестовой площадке, а примеры написаны для рабочего адреса. Ключ и адрес должны относиться к одному контуру, иначе будет `401` или `404`. Если их нет — остановись и запроси у пользователя. Придуманный `platform` даёт `404` на любом запросе, и это выглядит как ошибка кода, хотя проблема в конфигурации. ## Инварианты, которые нельзя нарушать ### Идентификаторы - `encounter_id` передаётся **строкой**, даже если в базе это число: `"12345"`, не `12345`. - Допустимы только цифры либо UUID вида 8-4-4-4-12. Значения `"enc-123"`, `"TEST-1"`, строки с пробелами дают `422`. - Один `encounter_id` = один приём навсегда. Не переиспользуй его. - В сценарии Import: `smartica_encounter_id` идёт **в адресе**, `encounter_id` — **в теле**. Это разные значения. ### SSO и вход врача - Запрос за ссылкой делает **только бэкенд**. Ключ клиники не должен попадать во frontend, логи, аналитику и тексты ошибок. - Email и ФИО врача берутся из доверенной сессии МИС, **не из тела запроса браузера**. - `user_full_name` передавай всегда: без него первый вход нового врача вернёт `422`. - Полученный `launch_url` отдавай браузеру **без изменений**. Не собирай его вручную, не сохраняй параметр `t`, не логируй целиком. - Ссылка одноразовая, живёт секунды из поля `expires_in`. Не зашивай `60` в код и не кэшируй ссылку. ### PUT записи протокола - Обработка обязана быть **идемпотентной по `encounter_id`**. Повторный одинаковый запрос обновляет существующий приём и не создаёт дубликат. - Поля, отсутствующие в массиве `fields`, **не очищай**. Приходят только те поля, для которых нашлось содержание. - Пустой массив `fields` — валидный запрос. Стенограмму всё равно сохрани. - `transcript` заменяет предыдущую версию целиком. - Отвечай `200` и JSON-объектом. `204`, пустое тело и HTML считаются ошибкой интеграции. - Значения могут содержать переводы строк и UTF-8. Сохраняй без потерь; экранируй при выводе в HTML на своей стороне. ### GET контекста приёма - Возвращай `200`, `Content-Type: application/json`, объект с `encounter_id`, `user_email`, `template`, `fields[{id,label}]`. - `fields[].id` — уникальные, стабильные, не меняются после запуска. - `fields[].label` — человекочитаемые названия: **по ним Smartica определяет смысл поля**. `"field_3"` или `"Данные"` приведут к плохому заполнению. - Для одного бланка всегда возвращай одно и то же значение `template`. ### Режим pull - Забери протокол, сохрани у себя, затем подтверди приёмку с тем `revision`, который пришёл в ответе. - Ошибка `409 revision_mismatch` означает, что протокол перезаполнили: забери заново, **обнови сохранённые данные** и подтверди актуальную ревизию. - Подтверждай только после реального сохранения. ### Безопасность и данные - Секреты только в переменных окружения. В `.env.example` — плейсхолдеры. - Персональные данные пациента в контракте не передаются. Не добавляй ФИО, номер карты, телефон и дату рождения. - В текстах ошибок не должно быть стектрейсов, SQL, внутренних путей и секретов: они сохраняются для диагностики и могут показываться пользователю. - Не логируй стенограммы целиком. ## Лимиты | Что | Значение | |---|---| | `fields` | до 80 элементов | | `fields[].id` | до 128 символов | | `fields[].label`, `template`, `user_email`, `user_full_name` | до 255 символов | | Запрос ссылки для входа | 30 в минуту | | Список записей | 60 в минуту | | Чтение, привязка, подтверждение | 120 в минуту | | Timeout запросов Smartica к МИС | 30 секунд | При `429` учитывай `Retry-After`. Не повторяй автоматически `401` и `403`: неудачные попытки авторизации ограничены отдельно. ## Типичные ошибки Всё перечисленное компилируется без проблем и не ловится тестами, написанными по неверно понятому требованию. - Придуман адрес SSO вместо выданного при подключении. - Ключ клиники оказался в клиентском бандле. - Email врача принят из тела запроса браузера. - `PUT` создаёт новую запись вместо обновления существующей. - Очищаются поля, которых нет в `fields`. - Падение на `"fields": []`. - `encounter_id` отправлен числом. - `launch_url` собран конкатенацией строк. - Ответ `204` или пустое тело вместо `200` с JSON. - Сохранён параметр `t` из ссылки для входа. - Стенограмма попала в логи целиком. ## Проверка перед завершением Не ограничивайся зелёными тестами: если требование понято неверно, тест закрепит неверное поведение. - [ ] Секреты читаются из окружения, в коде и бандле их нет - [ ] Email и ФИО врача берутся из сессии МИС - [ ] Доступ врача к приёму реально проверяется - [ ] `encounter_id` передаётся строкой - [ ] Повторный `PUT` не создаёт дубликат — проверено запросом, а не только тестом - [ ] `PUT` с частичным набором полей не затирает остальные - [ ] `PUT` с пустым `fields` сохраняет стенограмму - [ ] Успешные ответы — `200` с JSON - [ ] Тексты ошибок безопасны При расхождении между этим скиллом и документацией по ссылкам выше — **верна документация**. Сообщи о расхождении пользователю.