#Запуск из МИС, протокол присылаем мы (Launch)

Launch — кнопка «smartica.ai» в карточке приёма. Врач нажимает кнопку, попадает в smartica.ai уже авторизованным и записывает разговор. Заполненный протокол возвращается в тот же приём.

Если запись начинается вне МИС, откройте Запись вне МИС (Import).

#Что должна сделать кнопка

Кнопка не ведёт на smartica.ai напрямую. Она обращается к вашему бэкенду, а бэкенд запрашивает ссылку у smartica.ai.

Для ссылки нужен ключ клиники. Храните ключ только на бэкенде. В JavaScript ключ увидит любой, кто откроет исходный код страницы. Текущего врача и доступ врача к приёму определяет только бэкенд.

Сделайте так:

  1. Фронтенд передаёт бэкенду только внутренний ID приёма.
  2. Бэкенд проверяет, что текущий врач имеет доступ к этому приёму.
  3. Бэкенд берёт user_email и user_full_name из своей базы.
  4. Бэкенд запрашивает у smartica.ai одноразовую ссылку. В запрос бэкенд ставит ключ клиники.
  5. Бэкенд отвечает браузеру редиректом 302 на эту ссылку или отдаёт ссылку для новой вкладки.

Не делайте так:

  • Не принимайте email врача или platform из браузера без проверки на бэкенде.
  • Не помещайте ключ клиники в JavaScript, в конфиг фронтенда или в параметры страницы.
  • Не собирайте ссылку для входа сами.
  • Не сохраняйте ссылку. Не открывайте ссылку повторно.

#Последовательность запросов

Шаг Кто → кому Что происходит
1 Врач → МИС Нажимает «smartica.ai» в карточке приёма
2 Бэкенд МИС → smartica.ai Запрашивает одноразовую ссылку
3 Браузер → smartica.ai Открывает ссылку без изменений
4 smartica.ai → МИС Запрашивает контекст приёма через GET
5 Врач → smartica.ai Записывает разговор. Останавливает запись в smartica.ai или кнопкой в МИС
6 smartica.ai Расшифровывает и заполняет поля
7 smartica.ai → МИС Асинхронно отправляет PUT с результатом

Один и тот же encounter_id проходит через шаги 2, 4 и 7 и через кнопку «Завершить запись». Именно он связывает всё вместе.

Врач и браузеркарточка приёма в МИС
Бэкенд МИСкнопка, GET и PUT
smartica.aiзапись, расшифровка, протокол
Вход
1
Врач нажимает «smartica.ai» в карточке приёма
Браузер → бэкенд МИС
ID текущего приёма
email и ФИО бэкенд берёт сам
2
Бэкенд МИС → smartica.ai
Запросить ссылку для входа
POST …/sso/token
user_email · user_full_name · encounter_id
smartica.ai → бэкенд МИС
launch_url
Бэкенд МИС → браузер
launch_url
редирект 302 или новая вкладка
3
Браузер → smartica.ai
Открыть ссылку один раз, без изменений
Бланкесли бланк не передан в запросе ссылки
4
smartica.ai → бэкенд МИС
Какой бланк у этого приёма?
GET /…/encounters/{encounter_id}
Бэкенд МИС → smartica.ai
template · fields
"template": "Кардиолог",
"fields": [
  { "id": "complaints", "label": "Жалобы" },
  …
]
Передали template и fields в запросе ссылки — шага 4 не будет.
Запись
5
Врач записывает разговор
Бэкенд МИС → smartica.ai
Завершить запись, по желанию
POST …/encounters/{encounter_id}/stop
6
Расшифровка и заполнение полей
Доставкаpush: протокол приходит к вам сам
7
smartica.ai → бэкенд МИС
Заполненный протокол
PUT /…/encounters/{encounter_id}
encounter_id · fields · transcript
Приём 12345 в МИС
complaintsЖалобы на давящую боль…
transcriptзаменить целиком
поля, которых нет в fieldsне трогать
Обновляйте тот же приём. Повторный PUT с тем же encounter_id не должен создавать второй протокол.
Бэкенд МИС → smartica.ai
200 и JSON: протокол сохранён

Передайте template и fields в запросе ссылки на шаге 2. Тогда smartica.ai возьмёт бланк из запроса и не вызовет ваш GET. Шага 4 не будет. Смотрите раздел Inline-поля вместо GET.

В этих полях можно указать type. Описание типов лежит в статье Типы полей бланка. Ошибка в типе даёт ответ 422 и массив warnings. Приём при этом не создаётся.

Шаг 7 есть только при доставке push. При pull входящего PUT нет. Передайте бланк в запросе ссылки. Готовый протокол заберите сами. Шаги описаны в статье Запуск из МИС, протокол забираете вы (Launch Pull).

#Завершить запись из МИС

Врач останавливает запись кнопкой в smartica.ai. Если врач уже вернулся в МИС, остановку делает ваш бэкенд. Запрос один и для Launch Push, и для Launch Pull. Доставка на запрос не влияет.

POST /api/v1/integrations/{platform}/encounters/{encounter_id}/stop
Authorization: Bearer <ключ клиники>

Тело запроса пустое. В адресе стоит encounter_id приёма в вашей МИС. Этот encounter_id уходил в запрос ссылки. encounter_id не является UUID записи в smartica.ai.

Ответ Что значит
200 и "status": "stopping" Запись ещё идёт. Вкладка врача завершит запись в ближайшие секунды. Повторный запрос даёт тот же ответ.
200 и "status": "finished" Запись уже остановлена.
409 not_recording Врач ещё не начал запись.
404 encounter_not_found Такого приёма нет.

Кнопка не ждёт готовый протокол. После остановки при push результат приходит входящим PUT. При pull результат забираете вы.

#Что происходит при первом открытии приёма

  1. smartica.ai авторизует врача по одноразовому токену. smartica.ai находит существующий аккаунт или создаёт новый по email и ФИО.
  2. smartica.ai убирает токен из адресной строки редиректом на чистый адрес. Токен не остаётся в истории браузера.
  3. smartica.ai создаёт для приёма связанную запись.
  4. Если поля не переданы заранее, smartica.ai запрашивает контекст приёма. Контракт описан в статье Бланк приёма.
  5. smartica.ai закрепляет полученные template и fields за этим приёмом.

Если GET недоступен или вернул невалидный JSON, подготовка завершается ошибкой. Врач не сможет начать запись. Исправьте endpoint. Попросите врача открыть приём заново.

#Что происходит при повторном запуске

Тот же encounter_id означает тот же приём.

  • Врач возвращается в существующий приём в smartica.ai.
  • Открытие и закрытие без записи не создаёт новый PUT.
  • Новая запись разговора объединяется с предыдущей стенограммой. Новая запись не заменяет стенограмму.
  • После обработки smartica.ai отправляет PUT снова, уже с обновлёнными данными.
  • Не привязывайте тот же encounter_id к другому приёму. Не используйте тот же encounter_id для новой карточки.

PUT обновляет существующий протокол. PUT не создаёт второй протокол. Подробности смотрите в разделе Идемпотентность.

Врач может дописать приём после перерыва. Врач возвращается по кнопке и записывает продолжение. В МИС приходит объединённый результат.

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

После остановки записи расшифровка и заполнение идут не в запросе браузера. Врач может закрыть вкладку или выключить компьютер. Обработка продолжится на стороне smartica.ai.

Врач видит статус отправки в интерфейсе smartica.ai. Если отправка не удалась, в том же интерфейсе есть кнопка повтора.

Контракт не гарантирует автоматический повтор на каждую ошибку. Поэтому:

  • Отвечайте на PUT в пределах согласованного timeout. Сейчас timeout равен 30 секундам.
  • Сделайте PUT идемпотентным.
  • Не рассчитывайте, что запрос придёт ровно один раз.

Подробности смотрите в статье Авторизация и ошибки.

#Тестовое и рабочее окружения

Формат запросов в обоих окружениях одинаковый. Меняются только хосты, секреты, сетевые правила и тестовые данные.

Чтобы тестовый прогон не записал данные в боевую карту, используйте разные ключи для тестового и рабочего окружений.

Адреса обоих контуров и порядок перехода на рабочий описаны в статье Тестовая площадка.

Открывайте адрес запуска без токена только при локальной отладке, когда врач уже вошёл в smartica.ai вручную. На общем тестовом стенде и в рабочем окружении проверяйте поток, который пойдёт в продакшн.

#Сводка контрактов

Направление Метод Кто пишет код Назначение
МИС → smartica.ai POST на выданный SSO endpoint smartica.ai Получить одноразовую ссылку
МИС → smartica.ai POST …/encounters/{encounter_id}/stop smartica.ai Завершить идущую запись
Браузер → smartica.ai GET на полученную ссылку smartica.ai Авторизовать врача и открыть приём
smartica.ai → МИС GET /…/encounters/{id} Вы Отдать бланк и поля
smartica.ai → МИС PUT /…/encounters/{id} Вы Принять поля и стенограмму

Адреса на вашей стороне выбираете вы. Согласуйте эти адреса при подключении. platform и точный SSO endpoint выдаёт smartica.ai после регистрации подключения.

#Связанные статьи

← Все статьи: Интеграция с МИС Поиск по базе знаний