#Направления и услуги

После приёма в протоколе уже есть назначения: анализ, исследование, консультация другого врача. Врач ищет эти назначения в справочнике направлений и услуг клиники. Справочник большой. Одна и та же услуга называется по-разному.

smartica.ai читает готовый протокол и показывает короткие совпадения из справочника вашей клиники. Врач отмечает нужные пункты. Направления создаёт ваша МИС.

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

Возможность подключается отдельно для каждой интеграции. Пока мы не включили возможность, методы из этой статьи отвечают 404 service_requests_disabled. Чтобы включить возможность, напишите нам.

#Зачем направления и услуги врачу и МИС

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

Пока список готовится, в окне видно, что идёт разбор. Разбор обычно занимает меньше полуминуты. Затем появляется блок «Нашли в протоколе».

Под каждым пунктом стоит цитата из протокола. Пункт опирается на эту цитату. Врач сверяет пункт с цитатой и ставит галочку.

Если нужной услуги нет в списке, врач ищет услугу в том же окне по названию, сокращению или коду из вашего справочника. Отметки сохраняются сразу. Окно можно закрыть и открыть снова.

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

Программа рассчитывает список. Программа может предложить лишнее или пропустить нужное. Поэтому заранее ничего не отмечено. Последний выбор остаётся за врачом.

#Пример

Фрагмент протокола:

Пациентка жалуется на боли в эпигастрии после еды. Направлена к неврологу. Назначены общий анализ крови и ЭГДС.

Окно может показать три пункта. Названия и коды берутся из справочника клиники. Общий классификатор здесь не используется.

МРТ, биохимию «на всякий случай» и остальные пункты чекапа окно не добавляет. В протоколе этих назначений нет. Если фраза слишком общая и в справочнике несколько похожих услуг, в списке будут ближайшие услуги. Врач оставит одну. Если услуги нет в справочнике клиники, в списке её тоже не будет. Врач найдёт замену поиском или не назначит ничего.

Так же работает поиск, когда врач дописывает назначение сам. Врач вводит ОАК, невролог или B03.016.003. Затем врач отмечает строку из вашего справочника. Эта строка попадает в ответ вместе со строками, которые нашлись по протоколу.

#Какие строки бывают

Справочник клиники устроен по-разному. Окно учитывает состав справочника.

• Направление и услуга. Анализ внутри группы, например «Клинические анализы крови», и внутри группы «Общий анализ крови развёрнутый». Врач отмечает услугу. В ответе приходят оба ID.
• Только направление. Консультация без отдельной услуги в справочнике. Врач отмечает направление целиком. Услуга в ответе пустая.
• Только услуга. Справочник без групп направлений. Врач отмечает услугу. Направление в ответе пустое.

Повторный забор без новых галочек возвращает тот же набор. Если врач отметил ещё пункт и вы забрали выбор снова, придёт новый полный набор. Создайте в МИС только строки, которых в ней ещё нет.

#Как окно выглядит для врача

1. Врач записывает приём через smartica.ai. Протокол попадает в МИС.
2. В карточке приёма врач открывает окно «Направления и услуги». МИС запрашивает у нас ссылку. МИС показывает страницу во встроенном браузере.
3. Пока smartica.ai разбирает протокол, в окне видно, что идёт анализ. Разбор обычно занимает меньше полуминуты.
4. Появляется список «Нашли в протоколе». Под каждым пунктом стоит цитата из протокола. Пункт опирается на эту цитату. Ничего не отмечено заранее. Врач ставит галочки сам.
5. Чего нет в списке, врач находит в справочнике клиники поиском в том же окне: по названию, сокращению или коду из справочника.
6. Врач нажимает кнопку в МИС. МИС забирает отмеченное и создаёт направления.

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

Окно для врачей описано в статье Направления и услуги из протокола.

#Что делает МИС

Общая часть адреса: /api/v1/integrations/{platform}. service-requests означает направления и услуги, которые врач назначает пациенту. Авторизация как у остальных методов партнёра: Authorization: Bearer <API-ключ клиники>.

encounter_id в этих вызовах содержит ID приёма в вашей МИС. Вы передаёте тот же ID в SSO. Окно работает только для приёма, который прошёл через smartica.ai.

#Справочник

PUT /api/v1/integrations/{platform}/service-requests/catalog
Authorization: Bearer <API-ключ клиники>
Content-Type: application/json

{
  "items": [
    {
      "direction_id": "501",
      "direction_code": "LAB-01",
      "direction_name": "Клинические анализы крови",
      "service_id": "7001",
      "service_code": "B03.016.003",
      "service_name": "Общий анализ крови развёрнутый"
    },
    {
      "direction_id": "502",
      "direction_code": null,
      "direction_name": "Консультация невролога",
      "service_id": null,
      "service_code": null,
      "service_name": null
    },
    {
      "direction_id": null,
      "direction_code": null,
      "direction_name": null,
      "service_id": "800",
      "service_code": "ECG",
      "service_name": "ЭКГ"
    }
  ]
}

Один список строк. Каждая строка содержит направление с услугой, только направление или только услугу. Каждый раз присылайте справочник целиком, без сокращения до одних изменений.

ID и коды можно передавать строкой или числом.

• Строка без услуги описывает направление целиком, например консультацию. Врач выбирает это направление само по себе.
• Строка без направления описывает услугу. Так вы присылаете справочник, в котором направлений нет.
• Если одна услуга входит в несколько направлений, пришлите несколько строк с одним service_id. В окне врач видит услугу один раз.
• У одного direction_id название и код во всех строках одинаковые. У одного service_id название и код во всех строках тоже одинаковые. Не присылайте направление и само по себе, и с услугами. Не присылайте услугу и саму по себе, и внутри направления.
• Если строки нет в новом справочнике, мы перестаём её предлагать. Строки, которые МИС уже забрала через commit, не меняются.

Большой справочник можно сжать. Поставьте заголовок Content-Encoding: gzip. В теле передайте сжатый JSON. В items до 20 000 строк. Тело до 8 МБ.

Ответ 200 содержит число записей, которые мы приняли. services считает разные услуги, а не строки. Одна услуга в двух направлениях даёт "services": 1.

{ "directions": 2, "services": 2 }

Справочник не записывается. Прежний справочник остаётся, если:

• Тело пустое, оборвано или не читается.
• Нет списка items или список пуст.
• В строке нет ни направления, ни услуги, либо название не сходится с id.
• У одного id в разных строках разные названия или коды.
• Направление указано и само по себе, и с услугами, либо услуга указана и сама по себе, и внутри направления.
• У нас уже больше 100 направлений, а новый справочник меньше половины текущего. Поэтому обрезанная выгрузка не сотрёт справочник.

Во всех этих случаях ответ 422 validation_failed. Описание лежит в message.

#Что мы храним

GET /api/v1/integrations/{platform}/service-requests/catalog
Authorization: Bearer <API-ключ клиники>

Тело не нужно. Ответ 200 содержит тот же список items, который мы приняли, те же числа, что в ответе PUT, и synced_at. Поле synced_at показывает, когда справочник последний раз успешно принят. Время в формате ISO 8601. directions и services считают разные записи, а не строки. Одна услуга в двух направлениях даёт две строки в items и "services": 1.

{
  "directions": 2,
  "services": 2,
  "synced_at": "2026-10-31T11:47:00+05:00",
  "items": [
    {
      "direction_id": "501",
      "direction_code": "LAB-01",
      "direction_name": "Клинические анализы крови",
      "service_id": "7001",
      "service_code": "B03.016.003",
      "service_name": "Общий анализ крови развёрнутый"
    }
  ]
}

Порядок строк может отличаться от присланного. Строки, которых нет в последнем принятом справочнике, в ответ не попадают. Если вы ещё не присылали справочник, в ответе будут "directions": 0, "services": 0, "synced_at": null и "items": []. Тот же synced_at есть в ответе PUT.

#Коды

Код необязателен. В окне код виден рядом с названием. По коду работает поиск. Передавайте код так, как он записан в справочнике.

Чаще всего в справочнике стоит код из номенклатуры медицинских услуг Минздрава (приказ от 13.10.2017 № 804н), например B03.016.003, общий анализ крови развёрнутый. Клиника может добавить к коду свой хвост, например B03.016.003.002. Свои внутренние коды без связи с номенклатурой тоже подходят.

Буквы A и B в кодах номенклатуры латинские. Если в вашем справочнике эти буквы набраны кириллицей, замените их при выгрузке. Врач набирает код латиницей. Кириллический код не находится.

Поиск в окне находит пункт по названию и по коду. Код можно ввести с точками и без, целиком или частью от четырёх символов. Запросы B03.016.003, 016.003 и 016003 находят одну и ту же услугу.

#Ссылка на окно

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

Тело не нужно. Ответ 200:

{
  "embed_url": "https://app.smartica.ai/embed/service-requests/open/9f1c…",
  "expires_in": 60
}

Ссылка одноразовая. Ссылка живёт expires_in секунд. Запрашивайте новую ссылку при каждом показе окна. Сохранять одну ссылку на смену врача нельзя. Второй раз ссылка не откроется. Открытое окно работает 30 минут. Затем окно просит открыть его заново из МИС. Отмеченное при этом сохраняется.

С этим же вызовом мы начинаем разбирать протокол. Отдельно запускать разбор не нужно.

#Как встроить окно

Откройте embed_url во встроенном браузере вашей программы (WebView, CEF и аналоги) или в <iframe> веб-страницы карточки приёма. Окно тянется по ширине. Окно работает при ширине от 280 px. По высоте рекомендуем не меньше 400 px. Список и поиск прокручиваются внутри окна.

Во встроенном браузере открывайте ссылку напрямую. Дополнительная настройка не нужна. Внутри <iframe> браузер показывает окно только на страницах, которые мы разрешили. При подключении сообщите origin такой страницы. Origin включает схему и хост, например https://mis.clinic.ru. Если у <iframe> есть атрибут sandbox, в атрибуте нужны allow-scripts и allow-same-origin.

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

#Что отметил врач

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

Вызывайте этот метод по кнопке в МИС. Окно читать не нужно. Всё, что врач отметил, приходит в ответе. Тело не нужно. Ответ 200:

{
  "service_requests": [
    {
      "direction_id": "501",
      "direction_code": "LAB-01",
      "direction_name": "Клинические анализы крови",
      "service_id": "7001",
      "service_code": "B03.016.003",
      "service_name": "Общий анализ крови развёрнутый"
    },
    {
      "direction_id": "502",
      "direction_code": null,
      "direction_name": "Консультация невролога",
      "service_id": null,
      "service_code": null,
      "service_name": null
    }
  ]
}

direction_id и service_id совпадают с вашими ID из справочника. service_id равен null, если врач выбрал направление без услуги. direction_id равен null, если услуга в справочнике без направления.

Повторный вызов без новых отметок возвращает тот же набор. Врач может нажать кнопку дважды. Если врач потом отметил ещё пункт, следующий вызов вернёт новый полный набор. Создайте в МИС только строки, которых в ней ещё нет. Если врач ничего не отметил, ответ 200 содержит "service_requests": [].

#Если врач поправил протокол в МИС

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

#Ошибки

Если ссылка истекла или ссылку уже открывали, в окне будет «Ссылка устарела». Запросите новую ссылку.

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

• Протокол после правки врача
• Запуск из МИС, протокол присылаем мы (Launch)
• Авторизация и ошибки
• Лимиты