#Обзор интеграции

Эта статья — точка входа для разработчиков МИС. Прочитайте её целиком до того, как писать код: дальше будет намного понятнее.

#Что делает Smartica

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

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

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

Если API-интеграция не нужна, врач может скопировать результат в МИС вручную — код писать не придётся.

#Главное, что нужно понять: запросы идут в обе стороны

Это самая частая точка непонимания. В интеграции два разных API и два разных секрета.

            [1] МИС просит ссылку для входа врача
        ┌──────────────────────────────────────────────┐
        │                                              ▼
   ┌────┴─────┐                                  ┌───────────┐
   │   Ваша   │                                  │  Smartica │
   │   МИС    │                                  │           │
   └────▲─────┘                                  └─────┬─────┘
        │                                              │
        └──────────────────────────────────────────────┘
            [2] Smartica спрашивает поля бланка (GET)
            [3] Smartica отдаёт заполненный протокол (PUT)

	Кто пишет код	Кто хранит секрет	Что это
API Smartica	Smartica (готово)	Вы	Мы даём вам endpoint'ы. Вы их вызываете
API вашей МИС	Вы	Smartica	Вы делаете endpoint'ы. Мы их вызываем

Значит, вам нужно и вызывать наш API, и реализовать свой. Ключ, которым вы обращаетесь к нам, и логин-пароль, которым мы обращаемся к вам, — это два разных секрета. Не путайте их: подробности в статье Авторизация, ошибки и повторная доставка.

#Два сценария: Launch и Import

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

#Launch — врач стартует из МИС

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

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

#Import — врач стартует из Smartica

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

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

#Сравнение

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

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

#Два способа доставки результата: push и pull

Сценарий отвечает на вопрос «как приём начался». Доставка отвечает на другой вопрос — как готовый протокол попадёт в МИС. Это независимые настройки.

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

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

Вам нужен endpoint, доступный для наших серверов из интернета.
Реакция мгновенная: врачу не надо ничего нажимать.
Это режим по умолчанию.

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

Smartica никуда не ходит. Ваша МИС периодически (или по действию врача) спрашивает у нас: «протокол готов?» — и, если готов, забирает его. После сохранения у себя МИС отправляет нам подтверждение (ack).

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

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

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

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

Сценарий	Доставка	Что реализует ваша команда
Launch	push	Кнопка в карточке приёма → серверный SSO-запрос → `GET` контекста → приём входящего `PUT`
Launch	pull	Кнопка в карточке приёма → серверный SSO-запрос → `GET` контекста → опрос Smartica + `ack`
Import	push	Форма выбора записи → запрос списка → запрос на привязку → приём входящего `PUT`
Import	pull	Форма выбора записи → запрос списка → запрос на привязку → опрос Smartica + `ack`

Пояснения:

GET контекста можно не делать даже в Launch: если вы передадите название бланка и его поля прямо в SSO-запросе, Smartica не будет ходить к вам за ними. Как это сделать — в Launch URL и SSO.
PUT — единственный endpoint, который обязателен при push. Его контракт описан в PUT: запись протокола.
В Import список полей бланка передаётся всегда прямо в запросе на привязку, поэтому GET там не нужен никогда.

Самая простая конфигурация для старта — Launch + push с полями в SSO-запросе: тогда у вас на стороне МИС только один входящий endpoint (PUT) и один исходящий вызов (SSO).

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

#Launch

Врач открывает карточку приёма в МИС и нажимает «Smartica».
Браузер сообщает бэкенду МИС только ID текущего приёма.
Бэкенд МИС проверяет права врача, берёт его email и ФИО из своей базы и запрашивает у Smartica одноразовую ссылку для входа.
Браузер врача открывает полученную ссылку — врач попадает в Smartica уже авторизованным.
Smartica узнаёт, какие поля надо заполнить: либо запрашивает их у вас через GET, либо берёт из SSO-запроса.
Врач записывает разговор с пациентом и останавливает запись.
Smartica расшифровывает аудио и раскладывает текст по полям.
Результат попадает в МИС — через PUT при push или через ваш запрос и ack при pull.

#Import

Врач записывает приём в Smartica, не открывая МИС.
Позже врач открывает в МИС форму «Импорт из Smartica».
Бэкенд МИС запрашивает у Smartica список записей, ожидающих привязки.
Врач выбирает нужную запись и указывает, к какому приёму в МИС её привязать.
МИС отправляет запрос на привязку и вместе с ним передаёт название бланка и его поля.
Smartica заполняет протокол.
Результат попадает в МИС — так же, через PUT или через ваш запрос и ack.

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

МИС получает от Smartica:

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

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

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

#Подключение не является self-service

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

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

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

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

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

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

Как это происходит по шагам — в статье Онбординг партнёра.

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

Ниже — все запросы, которые существуют в контракте. На практике вам понадобится подмножество: смотрите таблицу «Что именно мне нужно реализовать».

#Вы вызываете Smartica

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

#Smartica вызывает вас

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

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

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

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

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

Путь вручную — прозрачнее. Быстрый старт проведёт по шагам с готовым примером кода.

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

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

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

#Как начать

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