#Обзор

Прочитайте статью до кода. Она объясняет, зачем в интеграции два API и два секрета.

#Что делает smartica.ai

smartica.ai записывает разговор врача с пациентом через микрофон и расшифровывает разговор в текст. Затем smartica.ai раскладывает текст по полям протокола приёма.

Задача интеграции — положить заполненный протокол в карту пациента в вашей МИС. Врач не копирует текст руками.

smartica.ai не является медицинской информационной системой. Карту пациента храните вы. Мы возвращаем текст в вашу систему.

Если API не нужен, врач переносит результат по статье Копирование в МИС. Код для этого не нужен.

#Запросы идут в обе стороны

В интеграции два API и два секрета. Эти API и секреты часто путают.

Браузер врачакарточка приёма в МИС
Бэкенд МИСваш сервер
smartica.aiзапись, расшифровка, протокол
Вы → намAPI smartica.ai, запросы подписаны API-ключом клиники
Бэкенд МИС → smartica.ai
Ссылка для входа врача
POST …/sso/token · Launch
Бэкенд МИС → smartica.ai
Завершить запись
POST …/encounters/{encounter_id}/stop · Launch
Бэкенд МИС → smartica.ai
Список записей и привязка
GET …/encounters · POST …/import · Import
Бэкенд МИС → smartica.ai
Забрать протокол и подтвердить
GET …/encounters/{id} · POST …/ack · pull
Мы → вамAPI вашей МИС, запросы подписаны вашими учётными данными
smartica.ai → бэкенд МИС
Поля бланка
GET /…/encounters/{id} · Launch без бланка в SSO
smartica.ai → бэкенд МИС
Заполненный протокол
PUT /…/encounters/{id} · push
Браузерсекретов не знает
Браузер → бэкенд МИС
ID текущего приёма
email, ФИО и ключ берёт бэкенд
Браузер → smartica.ai
Открыть готовую ссылку для входа
launch_url от бэкенда, один раз
Где секреты
Ничего не хранит
API-ключ клиникивыдаём мы, им подписываете запросы к нам
Учётные данные вашего APIвыдаёте вы, ими мы подписываем GET и PUT
Кто пишет код Кто хранит секрет Роль
API smartica.ai smartica.ai (готово) Вы Мы даём вам endpoint'ы. Вы вызываете эти endpoint'ы
API вашей МИС Вы smartica.ai Вы делаете endpoint'ы. Мы вызываем эти endpoint'ы

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

#Сценарии Launch и Import

Сценарий задаёт, с чего начинается приём.

#Launch — врач начинает приём в МИС

Врач открывает карточку приёма в вашей МИС и нажимает кнопку «smartica.ai». ID приёма известен сразу.

Launch подходит, когда врач работает за компьютером и МИС открыта.

#Import — врач начинает приём в smartica.ai

Врач записывает приём в smartica.ai отдельно. Например, с телефона на выезде или в кабинете без компьютера. МИС в этот момент не участвует. Позже врач открывает в МИС форму «Импорт из smartica.ai», выбирает запись из списка и привязывает запись к приёму.

Import подходит для выездов и обходов, когда компьютера рядом нет.

#Сравнение

Launch Import
Что нажимает врач сначала Кнопку в карточке приёма МИС Кнопку записи в smartica.ai
Когда становится известен ID приёма МИС Сразу, на первом шаге Позже, в момент привязки
Откуда smartica.ai берёт список полей бланка Запрашивает у вас через GET или получает сразу в SSO-запросе Только из тела запроса на привязку
Нужен ли вам публичный API для входящих запросов Да, если smartica.ai возвращает результат сама Не обязательно. Вы забираете результат сами
Подробная статья Запуск из МИС, протокол присылаем мы (Launch) Запись вне МИС (Import)

Сценарии не исключают друг друга. Можно включить оба. Оба сценария используют один platform и один ключ.

#Доставка push и pull

Сценарий задаёт, как приём начался. Доставка задаёт, как готовый протокол попадает в МИС. Сценарий и доставка настраиваются отдельно.

#push — smartica.ai сама приносит результат

Когда протокол готов, smartica.ai вызывает PUT на вашем сервере.

  • Вам нужен endpoint, доступный для наших серверов из интернета.
  • Врач ничего не нажимает.
  • push — режим по умолчанию.

#pull — МИС сама забирает результат

smartica.ai не вызывает ваш сервер. Ваша МИС спрашивает, готов ли протокол. Спрашивать можно по расписанию или по действию врача. Если протокол готов, МИС забирает протокол. После сохранения МИС отправляет подтверждение (ack).

  • Публичный входящий endpoint не нужен. Все соединения начинает ваша МИС.
  • pull подходит, когда МИС стоит в закрытом контуре и снаружи недоступна.
  • Задержка равна интервалу вашего опроса.

Режим фиксируется один раз при подключении. Режим действует на Launch и на Import.

#Что вам нужно реализовать

Найдите свою строку. Слева ваша комбинация. Справа список работ.

Сценарий Доставка Что реализует ваша команда
Launch push Кнопка в карточке приёма → серверный SSO-запрос → GET контекста → приём входящего PUT
Launch pull Кнопка в карточке приёма → SSO с template и fields → по желанию stop → опрос smartica.ai + ack. Пошагово в статье Запуск из МИС, протокол забираете вы (Launch Pull)
Import push Форма выбора записи → запрос списка → запрос на привязку → приём входящего PUT
Import pull Форма выбора записи → запрос списка → запрос на привязку → опрос smartica.ai + ack

Пояснения:

  • GET контекста можно не делать даже в Launch. Передайте название бланка и поля бланка в SSO-запросе. Тогда smartica.ai не запрашивает бланк у вас. Как передать бланк в SSO, описано в статье Ссылка для входа врача.
  • При push обязателен один входящий endpoint, PUT. Контракт описан в статье Запись протокола в карту.
  • В Import список полей бланка всегда передаётся в запросе на привязку. GET в Import не нужен.

Для старта берите Launch и push с полями в SSO-запросе. Тогда на стороне МИС один входящий endpoint (PUT) и один исходящий вызов (SSO).

#Как выглядит поток целиком

#Launch

  1. Врач открывает карточку приёма в МИС и нажимает «smartica.ai».
  2. Браузер сообщает бэкенду МИС только ID текущего приёма.
  3. Бэкенд МИС проверяет права врача. Бэкенд берёт email и ФИО врача из своей базы. Бэкенд запрашивает у smartica.ai одноразовую ссылку для входа.
  4. Браузер врача открывает полученную ссылку. Врач попадает в smartica.ai уже авторизованным.
  5. smartica.ai узнаёт, какие поля заполнять. smartica.ai запрашивает поля у вас через GET или берёт поля из SSO-запроса.
  6. Врач записывает разговор с пациентом и останавливает запись.
  7. smartica.ai расшифровывает аудио и раскладывает текст по полям.
  8. Результат попадает в МИС. При push smartica.ai вызывает PUT. При pull вы забираете протокол и отправляете ack.

#Import

  1. Врач записывает приём в smartica.ai и не открывает МИС.
  2. Позже врач открывает в МИС форму «Импорт из smartica.ai».
  3. Бэкенд МИС запрашивает у smartica.ai список записей, ожидающих привязки.
  4. Врач выбирает запись и указывает приём в МИС для привязки.
  5. МИС отправляет запрос на привязку. В том же запросе МИС передаёт название бланка и поля бланка.
  6. smartica.ai заполняет протокол.
  7. Результат попадает в МИС. При push smartica.ai вызывает PUT. При pull вы забираете протокол и отправляете ack.

#Какие данные передаются

МИС получает от smartica.ai:

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

Персональные данные пациента передавать не нужно. Не передавайте ни ФИО, ни номер карты, ни телефон, ни дату рождения. smartica.ai работает с содержанием разговора. Пациента вы связываете через свой ID приёма.

Не добавляйте эти поля в запросы по своей инициативе. Поля протокола и стенограмма уже содержат медицинские сведения. Не расширяйте этот набор без необходимости. Подробности в статье Защита данных.

#Регистрация подключения

{platform} в примерах нельзя придумать. {platform} — зарегистрированный идентификатор вашей клиники в smartica.ai. Идентификатор выдаём мы при подключении.

Пока подключение не создано и не активировано на нашей стороне, любой запрос возвращает 404, включая верный URL.

Одна клиника — одно подключение. Филиалы получают отдельный идентификатор и отдельный ключ.

До начала разработки запросите у нас:

  • зарегистрированный platform.
  • точный адрес SSO endpoint и базовый URL нужного окружения.
  • API-ключ клиники.
  • какие сценарии включаем: Launch, Import или оба.
  • какой способ доставки: push или pull.
  • при push согласованные адреса ваших GET и PUT и схему авторизации.

Разработку начинайте по статье Тестовая площадка. Там отдельный адрес и отдельный ключ. На рабочий контур переходите после приёмочного прогона. Меняются только адрес и секреты.

Шаги подключения описаны в статье Подключение.

#Сводка вызовов

Ниже все запросы контракта. На практике нужно подмножество. Смотрите таблицу «Что вам нужно реализовать».

#Вы вызываете smartica.ai

Вызов Когда нужен Назначение
POST …/sso/token Launch Получить одноразовую ссылку для входа врача
POST …/encounters/{encounter_id}/stop Launch Завершить идущую запись из МИС
GET …/encounters?status=awaiting_import Import Список записей, ожидающих привязки
POST …/encounters/{id}/import Import Привязать запись к приёму в МИС
GET …/encounters/{id} pull Забрать готовый протокол
POST …/encounters/{id}/ack pull Подтвердить, что вы сохранили протокол у себя
POST …/encounters/{id}/versions push и pull Прислать протокол после правки врача в МИС. Необязательно
POST …/fields/validate каждое новое поле, до приёма Увидеть ошибку схемы. Позже она не вернётся
GET …/value-sets, GET и PUT …/value-sets/{id} если есть длинные списки Посмотреть справочники, загрузить один и сверить его

#smartica.ai вызывает вас

Вызов Когда нужен Назначение
GET /…/encounters/{id} Launch без полей в SSO Отдать название бланка и список полей
PUT /…/encounters/{id} push Принять заполненный протокол

Вы выбираете адреса на своей стороне. Адреса согласовываете при подключении. В документации пример такой: /api/for-smartica/encounters/{id}.

#В каком порядке читать дальше

Дальше есть два пути. Оба приводят к одному результату. Выбирайте по обстоятельствам.

Путь с ИИ-агентом. Если у вас есть Cursor, Claude Code или похожий инструмент с доступом к репозиторию, инструмент напишет большую часть кода. Откройте статью Промпты для ИИ-агента. Там готовые промпты, пошаговый план и разбор ошибок, которые ИИ допускает в этой задаче. Отдельный опыт работы с ИИ не нужен. Статья подходит и тем, кто пробует впервые.

Путь вручную. Статья Первый приём ведёт по шагам и даёт пример кода.

В обоих случаях держите под рукой статью Глоссарий. Параметры подключения запросите по статье Подключение.

Дальше читайте по своей комбинации сценария и доставки:

К справочным статьям возвращайтесь, когда они понадобятся:

#Как начать

Напишите на support@smartica.ai или откройте статью Поддержка. Укажите название МИС, клинику, окружения и контакт разработчика.

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