#Запуск из МИС, протокол забираете вы (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.

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

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

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

Фоновое задание берёт врачей только из связки, сохранённой на шаге 2. Список приёмов запрашивается по одному врачу. Без связки готовый протокол останется в smartica.ai, пока его не запросят вручную.

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

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

Правила кнопки одинаковы для 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. Число без кавычек вернёт 422. Строка вроде "enc-123" вернёт 422.

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

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

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 перечислены в статье Ссылка для входа врача.

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

После открытия ссылки врач попадает в smartica.ai уже авторизованным, в приём с вашим encounter_id. Бланк уже закреплён за этим приёмом. Отдельный GET с вашей стороны не нужен. smartica.ai этот 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 приёма в вашей МИС. Этот encounter_id уходил в SSO. Не подставляйте в адрес smartica_encounter_id.

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

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

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

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

Список фильтруется по статусу и по врачу. user_email обязателен. Общего списка по клинике нет. На шаге 2, вместе с запросом ссылки, сохраните связку. В связке храните ID приёма, email врача и пустой smartica_encounter_id. Фоновое задание по расписанию берёт врачей из связок, которые ждут протокол. Задание запрашивает список по каждому врачу.

Найдите в ответе элемент, у которого encounter_id совпадает с ID приёма в вашей МИС. Допишите в связку smartica_encounter_id и revision. До этого момента 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 вашей МИС.

Тело ответа 200 и правило пустых полей описаны в статье Готовый протокол. При ready сохраните fields, transcript и revision.

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

Подтверждайте ack только после сохранения протокола в МИС.

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: подтвердить получение.

Если врач потом поправит протокол в карте, пришлите сохранённый текст по статье Протокол после правки врача. В base_revision передайте номер из шага 6.

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

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

#Чеклист

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

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

• Статья Запуск из МИС, протокол присылаем мы (Launch) описывает общий поток и Launch Push.
• В статье Ссылка для входа врача перечислены ошибки запроса ссылки.
• Статья Готовый протокол содержит ответ GET и правило пустых полей.
• Статья Запись вне МИС (Import) описывает тот же ack для записи вне МИС.
• Статья Глоссарий объясняет, чем encounter_id отличается от smartica_encounter_id.
• Протокол после правки врача