#Launch Pull: запуск из МИС, результат забираете вы

Launch Pull — это сценарий Launch при доставке pull.

Врач по-прежнему нажимает «smartica.ai» в карточке конкретного приёма. ID приёма в вашей МИС известен сразу. Готовый протокол smartica.ai вам не присылает: ваш бэкенд забирает его сам и подтверждает получение.

В этом режиме у вас нет входящих endpoint. smartica.ai не вызывает ваш GET и не вызывает ваш PUT. Все запросы идут от вашего бэкенда к smartica.ai.

Если результат должен прийти к вам входящим PUT, вам нужен Launch Push — он описан в статье Launch: запуск из МИС. Если запись начинается вне МИС, с телефона, вам нужен Import.

#Что подготовить до кода

• Подключение с доставкой pull. Режим задаётся один раз при подключении и общий для Launch и Import.
• platform — идентификатор клиники, который выдаёт smartica.ai.
• API-ключ клиники. Им подписываются все запросы ниже. Ключ живёт только на бэкенде.
• Бланк текущего приёма: название (template) и непустой список полей (fields с id и label).

Адреса контуров — в статье Тестовая площадка.

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

Один и тот же encounter_id вашей МИС проходит через шаги 2, 5 и 7. В адресе stop стоит он. В адресе забора протокола и ack стоит уже smartica_encounter_id — UUID, который вернёт smartica.ai.

#Шаг 1. Кнопка в карточке приёма

Кнопка не ведёт на smartica.ai напрямую. Браузер передаёт бэкенду только ID текущего приёма. Email врача, ФИО и platform бэкенд берёт сам.

Полные правила кнопки — в разделе «Что должна сделать кнопка» статьи Launch. Они одинаковы для Launch Push и Launch Pull.

#Шаг 2. Запросить ссылку и передать бланк

POST /api/v1/integrations/{platform}/sso/token
Authorization: Bearer <API-ключ клиники>
Content-Type: application/json
Accept: application/json

{
  "user_email": "doctor@clinic.ru",
  "user_full_name": "Иванов Иван Иванович",
  "encounter_id": "12345",
  "template": "Терапия",
  "fields": [
    { "id": "complaints", "label": "Жалобы" },
    { "id": "anamnesis", "label": "Анамнез" }
  ]
}

encounter_id — строка из цифр или UUID. Число без кавычек и строки вроде "enc-123" вернут 422.

user_full_name передавайте всегда. При первом входе врача без ФИО аккаунт не создаётся.

template и fields в Launch Pull обязательны оба. В этом режиме smartica.ai не ходит в вашу МИС за бланком. Если не передать название или передать пустой список полей, подготовка приёма завершится ошибкой, и врач не сможет начать запись.

fields[].id — стабильный код поля в вашей МИС. fields[].label — человекочитаемое название: по нему smartica.ai понимает, что класть в поле. Названия вроде "field_3" или "Данные" дают пустой протокол.

Ответ 200:

{
  "launch_url": "https://app.smartica.ai/launch?platform=your-clinic&encounter_id=12345&t=...",
  "expires_in": 60
}

Откройте launch_url как есть, один раз. Не разбирайте ссылку, не сохраняйте параметр t и не открывайте её повторно: токен одноразовый и живёт около минуты.

Остальные коды ошибок SSO — в статье Launch URL и SSO.

#Шаг 3. Врач записывает приём

После открытия ссылки врач попадает в smartica.ai уже авторизованным, в приём с вашим encounter_id. Бланк уже закреплён за этим приёмом — отдельный GET с вашей стороны не нужен и не будет вызван.

Врач включает микрофон, говорит с пациентом и останавливает запись кнопкой в smartica.ai. Если он уже вернулся в МИС, остановку делает шаг 4.

Повторное открытие того же encounter_id — это тот же приём, а не новый. Новая запись объединяется с предыдущей стенограммой.

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

Этот запрос один и тот же для Launch Push и Launch Pull. Доставка на него не влияет: и при push, и при pull кнопка в МИС останавливает открытую вкладку с записью.

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

Тело пустое. В адресе — encounter_id приёма в вашей МИС, тот же, что уходил в SSO. Это не smartica_encounter_id.

Ответ приходит сразу и не содержит протокол. Если запись короче 15 секунд, вкладка завершит её, как только этот минимум наберётся; отдельной ошибки из-за этого нет.

Дальше пути расходятся:

• Launch Push. Когда протокол готов, smartica.ai вызывает ваш PUT. Контракт — в статье PUT: запись протокола.
• Launch Pull. PUT не будет. Заберите протокол сами, шаги 5–7.

#Шаг 5. Найти приём в smartica.ai

Список фильтруется по статусу и по врачу. Найдите элемент, у которого encounter_id совпадает с ID приёма в вашей МИС, и запомните smartica_encounter_id.

Пока идёт расшифровка:

GET /api/v1/integrations/{platform}/encounters?user_email=doctor@clinic.ru&user_full_name=Иванов%20Иван%20Иванович&status=processing
Authorization: Bearer <API-ключ клиники>
Accept: application/json

Когда протокол готов, тот же запрос со status=ready:

{
  "encounters": [
    {
      "smartica_encounter_id": "7f3a9c2e-4b1e-4a8d-9c3f-2e1a8b4d6f0c",
      "encounter_id": "12345",
      "status": "ready",
      "revision": 1
    }
  ],
  "next_cursor": null
}

Пока вашего encounter_id нет в ready, подождите и повторите. Не чаще, чем позволяют лимиты. Если next_cursor не null, обойдите следующие страницы параметром cursor.

#Шаг 6. Забрать протокол

GET /api/v1/integrations/{platform}/encounters/{smartica_encounter_id}
Authorization: Bearer <API-ключ клиники>
Accept: application/json

В адресе — UUID из шага 5, не ID вашей МИС.

Пока status не равен ready, массив fields пуст. При ready сохраните fields, transcript и revision. Полей, которых нет в fields, в протоколе не очищайте.

Полный пример ответа и правило пустых полей — в разделе «Режим pull: забрать протокол».

#Шаг 7. Подтвердить получение

Подтверждайте только после того, как протокол реально сохранён в МИС.

POST /api/v1/integrations/{platform}/encounters/{smartica_encounter_id}/ack
Authorization: Bearer <API-ключ клиники>
Content-Type: application/json

{
  "revision": 1
}

revision — номер из ответа шага 6, не единица «на всякий случай».

Ответ 200: "status": "accepted" и тот же revision. Повтор той же ревизии безопасен.

Если пока вы сохраняли протокол врач дописал приём, придёт 409 revision_mismatch и актуальный revision. Заберите протокол заново, обновите сохранённые данные и подтвердите новый номер.

Подробности — в разделе «Режим pull: подтвердить получение».

#Чего не делать

• Не поднимать GET и PUT «на будущее»: в Launch Pull smartica.ai их не вызывает.
• Не класть API-ключ клиники в браузер.
• Не вызывать stop с smartica_encounter_id в адресе.
• Не подтверждать ack, пока протокол не сохранён у вас.
• Не передавать в SSO только encounter_id без бланка.

#Чеклист

• Кнопка в карточке приёма ходит на ваш бэкенд, а не сразу на smartica.ai
• В SSO всегда уходят user_email, user_full_name, encounter_id, template и непустой fields
• launch_url открывается один раз и без изменений
• «Завершить запись» вызывает POST …/encounters/{encounter_id}/stop с вашим ID приёма
• Тот же stop используется и в Launch Push, и в Launch Pull
• После остановки Launch Pull забирает протокол через GET и подтверждает ack с актуальным revision
• Поля, которых нет в fields, в карте не очищаются

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

• Launch: запуск из МИС — общий поток и Launch Push
• Launch URL и SSO — ошибки запроса ссылки
• Import: импорт из smartica.ai — тот же забор протокола и ack
• Глоссарий — чем encounter_id отличается от smartica_encounter_id