VK
Youtube
Telegram
+7(812) 670-45-63

Сервис Терминологии

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

Назначение сервиса

Сервис Терминологии предназначен для автоматизации процессов консолидации, первичной обработки и ведения нормативно-справочной информации. Данный компонент предоставляет собой механизм управления процессом ведения нормативно-справочной информации и обеспечивает функции ее интеграции между различными учетными и информационными системами, являясь единым источником непротиворечивой информации о справочниках.
Сценарии работы сервиса
Обмен данными между внешними системами и сервисом Терминологии осуществляется в рамках следующих сценариев:
  1. Поиск справочника.
  2. Сервис Терминологии возвращает найденный справочник и метаинформацию по нему.
  3. Запрос версий справочника.
  4. Сервис Терминологии возвращает список версий справочника по идентификатору.
  5. Запрос значений справочника.
  6. Сервис Терминологии возвращает код и значение из справочника. Если в запросе указана версия справочника, то сервис возвращает значения этой версии справочника. Если версия не указана, то сервис возвращает значения из актуальной версии.
  7. Запрос дополнительной информации о значении (поиск значения).
  8. Сервис Терминологии возвращает дополнительную информацию о значении из справочника. Если в запросе указана версия справочника, то сервис возвращает значения этой версии справочника. Если версия не указана, то сервис возвращает значения из актуальной версии.
  9. Валидация значения в справочнике.
  10. Сервис Терминологии возвращает информацию о вхождении запрошенного значения в указанный справочник. Если в запросе указана версия справочника, то сервис возвращает значения этой версии справочника. Если версия не указана, то сервис возвращает значения из актуальной версии.
Базовая схема информационного взаимодействия приведена на [Рисунок 1].

Описание протокола взаимодействия

Общая информация

Информационный обмен осуществляется в соответствии со стандартом FHIR® (Fast Healthcare Interoperability Resources), разработанным организацией HL7. Подробное описание стандарта доступно по следующим ссылкам:
В качестве протокола взаимодействия используется REST (использование REST-протокола в FHIR® – см. http://fhir-ru.github.io/http.html).
Авторизация в сервисе и формат обмена

Для обращения к сервису Терминологии необходимо указать в заголовке сообщения авторизационный ключ в формате:
Authorization: N3[пробел][GUID передающей системы]
Авторизационный ключ системе-клиенту сервиса выдается администратором интеграционной платформы.
В качестве формата обмена требуется указать:
Content-Type: application/json
Формат обмена

В запросах к сервису НСИ возможно задать необходимый формат результата одним из способов:
  1. В секции HEADERS, например:
Content-Type: application/json
или
Content-Type: application/xml
2. В URL, например:
_format=json
или
_format=xml
Если формат не задан явным образом, то по умолчанию сервис формирует ответы в формате xml.
Важно! Сервис НСИ первоначально вычисляет и формирует результат в формате json. Затем, если в запросе явно задан формат xml, производится преобразование типа json в xml. Поэтому в запросах к сервису НСИ рекомендуется использовать формат json.
Версия API
При обращении к сервису Терминологии возможно указать в параметре секции HEADERS сообщения версию API:
api_version: [номер версии]
Параметр необязателен к указанию. Если параметр не заполнен, то используется дефолтная версия интерфейса взаимодействия.

Номер версии API в определенных сценариях определяет пара метры ответа. Различия в параметрах ответа при использовании конкретной версии интерфейса взаимодействия указаны при описании конкретных операций сервиса.
Операции со справочниками
Сервис Терминологии поддерживает следующие операции:
  1. Получение данных паспорта справочника
  2. Получение версий справочника ($versions)
  3. Запрос значений справочника ($expand)
  4. Получение информации о значении (записи справочника) ($lookup)
  5. Валидация значения в справочнике ($validate-code)
Более подробно об операциях со справочниками можно ознакомиться по адресу: http://fhir-ru.github.io/valueset-operations.html

Описание операций сервиса

Получение данных паспорта справочника

Получение информации о справочнике осуществляется с помощью GET-запроса. В качестве адреса должен быть указан URL в формате [base]/ValueSet?_format=json&url=urn:oid:[OID справочника].
Например:
[base]/ValueSet?_format=json&url=urn:oid:1.2.643.5.1.13.2.1.1.181
Метод возвращает детальную информацию о справочнике. Параметры ответа, которые используются в дальнейшей работе с сервисом приведены в [Таблица 1].
Пример запроса приведен в разделе примеры запросов.
Получение версий справочника ($versions)
Получение информации о списке версий справочника осуществляется с помощью GET-запроса. В качестве адреса должен быть указан URL в формате [base]/term/ValueSet/[идентификатор справочника в сервисе Терминологии] /$versions?_format=json.

Например:
[base]/term/ValueSet/1.2.643.5.1.13.2.1.1.181/$versions?_format=json
Метод возвращает массив с информацией по каждой версии справочника. Параметры ответа, которые используются в дальнейшей работе с сервисом приведены в [Таблица 2].
Пример запроса приведен в разделе примеры запросов.
Запрос значений справочника ($expand)
Получение значений заданного справочника осуществляется с помощью POST-запроса по URL в формате
[base]/term/ValueSet/$expand?_format=[формат]
Параметры запроса приведены ниже.

Описание параметров
Перечень параметров для получения значений справочника приведен в [Таблица 3].
Пример запроса

При запросе значений справочника в качестве адреса указывается URL в формате [base]/ValueSet/$expand?_format=json. В ответе сервис возвращает json с общей информацией о справочнике и массивом значений справочника в соответствии со значением кодовой системы.
Пример POST-запроса приведен в разделе примеры запросов.

Параметры ответа
Метод возвращает метаинформацию о справочнике и пары код-значение. Параметры ответа, которые используются в дальнейшей работе с сервисом приведены в [Таблица 2].
Получение информации о значении (записи справочника) ($lookup)
Метод предназначен для получения дополнительной информации о значении справочника по коду этого значения. Поиск заданного значения в справочнике осуществляется с помощью POST-запроса по URL в формате [base]/ValueSet/$lookup. Параметры запроса приведены ниже.

Описание параметров
Перечень параметров для получения дополнительной информации о значении справочника приведен в [Таблица 5].
Пример запроса
При поиске данных о значении в справочнике в качестве адреса указывается URL в формате [base]/ValueSet/$lookup?_format=json. В ответе сервис возвращает json с детализированной информацией о значении, которое соответствует коду значения из запроса.
Пример запроса приведен в разделе примеры запросов.

Параметры ответа
Метод возвращает массив дополнительных параметров значения справочника, соответствующего коду. Параметры ответа приведены в [Таблица 6].
Зависимость кода статуса HTTP и структуры ответа от указания заголовка «api-version»
Валидация значения в справочнике ($validate-code)
Метод предназначен для проверки: принадлежит ли код значения из запроса указанному справочнику. Валидация значения в справочнике осуществляется с помощью POST-запроса по URL в формате [base]/ValueSet/$validate-code. Параметры запроса приведены ниже.
Описание параметров
Перечень параметров для валидации кода значения в справочнике приведен в [Таблица 7].
Пример запроса
При валидации значений справочника в качестве адреса указывается URL в формате [base]/ValueSet/$validate-code?_format=json. В ответе сервис возвращает json с указанием, найден ли код из запроса в соответствующем справочнике.
Пример POST-запроса приведен в разделе примеры запросов.

Параметры ответа
Метод возвращает результат проверки значения справочника. Параметры ответа приведены в [Таблица 8].
Получение соответствий кодовых значений заданных справочников
Для перекодирования кодовых значений одного справочника в кодовые значения, соответствующие другому справочнику, возможно использования метода вычисления соответствия кодовых значений. Получение соответствий кодовых значений заданных справочников происходит с помощью POST-запроса по URL в формате:
[base]/term/ConceptMap/translate?_format=[формат]
Перечень параметров для получения соответствия кодовых значений заданных справочников приведен в таблице 12.
* Примечание: в общем случае в системе имеется однозначное соответствие кодовых значений пары справочников. Однако могут быть ситуации, когда в целях систем-потребителей составляется несколько справочников соответствия кодовых значений одной и той же пары справочников. В данном случае возможно управлять получением соответствия указанием публичного идентификатора справочника соответствия (OID справочника), по которому необходимо вычислить соответствие.

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

Параметры ответа приведены в таблице 10 и таблице 11.
Пакетное выполнение операций
Для выполнения нескольких операций в одном запросе предусмотрен запрос пакетного выполнения операций. Запросы, поддерживающие пакетное выполнение:
  • получение информации о значении (lookup);
  • проверка наличия значения в справочнике (validate-code);
  • получение соответствий кодовых значений двух заданных справочников (translate).
Пакетное выполнение операций выполняется POST-запросом по URL в формате:
[base]/term/batch?_format=[формат]
Параметры ответа приведены в таблице 13.
Поиск значения в справочнике
Поиск значений в справочнике осуществляется с помощью GET-запроса по URL в формате:
[base]/term/ValueSet/oid/version/_search?attribute:operation=value&attribute:operation =value..&_format=[формат]
либо с помощью POST-запроса в формате:
[base]/term/ValueSet/_search?_format=[формат]
Параметры запросов представлены в таблице 14.
* Введенное поисковое значение разбивается на массив букв и цифр. В результате выводится все записи, которые одновременно содержат все элементы полученного массива.

** При перечислении элементов поиска необходимо учитывать экранирование. Если в искомом значении присутствует запятая, то она экранируется двумя обратными слешами. Если в искомом значении присутствует обратный слеш, то он экранируется тремя обратными слешами.

Параметры ответа представлены в таблице 15.
Получение истории изменений справочника
Получение изменений справочника (дельты данных) двух заданных версий справочника происходит с помощью GET-запроса по URL в формате:
[base]/term/ValueSet/oid/_versions_history/?low_version=[младшая версия]&low_version_datetime=[дата:время]&high_version=[старшая версия]&high_version_datetime&count=[кол-во элементов]&page=[номер страниц]&_format=[формат]
либо с помощью POST-запроса по URL в формате:
[base]/term/ValueSet/_versions_history?_format=[формат]
Общие принципы работы метода:
  1. В результате вычисления дельты справочных данных выводятся все записи, которые были подвержены каким-либо изменениям относительно переданных версий.
  2. Для созданных записей в результате запроса передаются все пары код_атрибута:значение, которые заданы для записи.
  3. Для измененных записей в результате запроса передаются код записи и пары код_атрибута:значение измененных атрибутов.
  4. Для удаленных записей в результате запроса передаются все пары код_атрибута:значение, которые были заданы для записи.
Параметры запросов представлены в таблице 16.
Параметры ответа представлены в таблице 17.
Проверка доступности сервиса
Проверка доступности сервиса происходит с помощью GET-запроса по URL в формате:
[base]/version
При успешном выполнении метода пользователю возвращается JSON, содержащий номер версии сервиса.
Параметры ответа приведены в таблице 18.

Доступные справочники

Федеральные справочники
Региональные справочники