#Глоссарий и правила идентификаторов

#Стороны интеграции

Термин Что означает
МИС Медицинская информационная система партнёра
Бэкенд МИС Доверенный сервер партнёра, который хранит секреты и вызывает SSO API Smartica
Браузер врача Открывает только выданный launch_url; не должен знать SSO_KEY
Smartica Вызывает API МИС, записывает разговор, заполняет протокол и отправляет результат

#Поля контракта

Поле Смысл
encounter_id Идентификатор приёма в МИС. Связывает SSO, GET, PUT и повторный запуск
platform Зарегистрированный slug адаптера МИС в Smartica
user_email Email врача. Используется для SSO и проверки владельца приёма
user_full_name ФИО врача. Нужно для автоматического создания или восстановления аккаунта при первом SSO-входе
template Стабильное человекочитаемое имя бланка или специальности
fields[].id Стабильный уникальный ключ поля внутри протокола
fields[].label Однозначное название поля, по которому Smartica понимает его смысл
fields[].value Сформированный текст поля, возвращаемый в PUT
transcript Полная объединённая стенограмма приёма, возвращаемая в PUT
launch_url Готовая одноразовая ссылка для входа врача и открытия приёма

#encounter_id

Передавайте encounter_id JSON-строкой, даже если в вашей базе это число:

{ "encounter_id": "12345" }

Поддерживаются два формата:

  • только цифры: "12345";
  • UUID в канонической форме 8-4-4-4-12: "a1b2c3d4-e5f6-7890-abcd-ef1234567890".

Не поддерживаются "enc-123", "TEST-1", пробелы и другие произвольные строки. SSO API вернёт 422.

#Правила жизненного цикла

  1. ID должен однозначно определять приём внутри подключённой организации.
  2. Один и тот же ID используйте при SSO, в URL GET и PUT, а также в JSON-теле.
  3. Повторный запуск того же ID означает продолжение того же приёма.
  4. Не переиспользуйте ID для другого пациента, врача или новой карточки.
  5. После запуска ID нельзя привязать к другой заметке Smartica.

#platform

Формат:

^[a-z0-9]+(?:-[a-z0-9]+)*$

Допустимы строчные латинские буквы, цифры и одиночные дефисы между сегментами.

platform выдаёт Smartica после регистрации адаптера. Это не self-service slug: произвольное корректное по формату значение не создаёт маршрут и не включает интеграцию.

#template

Передавайте название, которое однозначно описывает бланк или специальность:

  • "Кардиолог";
  • "ЛОР";
  • "Первичный приём педиатра";
  • "УЗИ органов брюшной полости".

Для одного типа бланка всегда используйте одно написание. Не чередуйте "ЛОР", "lor" и "Отоларинголог": это ухудшает стабильность заполнения.

#fields[].id и fields[].label

id может быть техническим, но должен быть непустым, уникальным и неизменным:

{ "id": "objective_status", "label": "Объективный статус (status praesens)" }

Качество label напрямую влияет на результат:

Хорошо Плохо
"Жалобы" "field_3"
"Диагноз (основной)" "Диагноз" при наличии нескольких видов диагноза
"Объективный статус (status praesens)" "Статус"
"Рекомендации по лечению" "Данные"

#Стиль endpoint МИС

  • используйте HTTPS;
  • ресурс называйте существительным во множественном числе;
  • помещайте encounter_id в path;
  • используйте один и тот же ресурс для чтения контекста и записи результата.

Рекомендуемый вариант:

GET /api/smartica/encounters/{encounter_id}
PUT /api/smartica/encounters/{encounter_id}

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

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