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

Сервис обогащения предназначен для получения и валидации СНИЛС в ПФР через ЕГИСЗ.

Информационный обмен осуществляется в соответствии со стандартом FHIR® (Fast Healthcare Interoperability Resources), разработанным организацией HL7. Подробное описание стандарта доступно по следующим ссылкам:

http://hl7.org/fhir/summary.html
https://fhir-ru.github.io/core/ (перевод)
https://hl7.org/fhir/terminology-module.html (описание Терминологических сервисов).

В качестве протокола взаимодействия используется REST (использование REST-протокола в FHIR® – см. https://hl7.org/fhir/http.html).

1. Авторизация в сервисе и формат обмена

Для обращения к сервису Обогащения СНИЛС, ЕНП необходимо указать в заголовке сообщения авторизационный ключ в формате:
Authorization: N3[пробел][GUID]

Этот токен выдаётся вместе с промышленными доступами, он не совпадает ни с каким GUID других сервисов (ИЭМК, ОДЛИ, ОДИИ и т.д.).

В качестве формата обмена требуется указать:
Content-Type: application/json

На текущий момент единственным ограничением запросов в промышленной среде сервиса обогащения является ограничение в 500 запросов в минуту (это ограничение федеральное и распространяется на всех операторов России одновременно).

2.1 Заказ на получение СНИЛС гражданина по набору данных гражданина и данным документа, удостоверяющего личность

Элемент	Кратность	Описание
patient	1..1	Блок персональной информации пациента
familyName	1..1	Фамилия. Строка — не более 100 символов
firstName	1..1	Имя. Строка — не более 100 символов
patronymic	0..1	Отчество. Обязательно при наличии. Строка — не более 100 символов
birthDate	1..1	Дата рождения. В формате: YYYY-MM-DD
gender	1..1	Пол. Строка: [1, 2]. Справочник 1.2.643.5.1.13.13.11.1040
patientPersDocs	1..1	Блок информации о документе пациента.
type	1..1	Тип документа. Справочник: 1.2.643.5.1.13.13.99.2.48 Разрешённые значения [1, 6, 7, 9, 11, 20, 42] 1 — Паспорт гражданина Российской Федерации 6 — Свидетельство о рождении 7 — Паспорт моряка (удостоверение личности моряка) 9 — Военный билет (у лиц, проходящих военную службу) 11 — Вид на жительство 20 — Паспорт гражданина СССР 42 — Заграничный паспорт гражданина Российской Федерации
series	0..1	Серия документа. Строка — не более 10 символов, не должно быть пробелов
number	1..1	Номер документа. Строка — не более 20 символов, не должно быть пробелов
issueDate	1..1	Дата выдачи. В формате: YYYY-MM-DD
issuer	1..1	Кем выдан (не обязан соответствовать на 100% как в паспорте)

Метод

POST

Входные данные

Конечная точка:
[baseURL]/snils
Тело запроса:
В теле запроса информация о пациенте в формате JSON. Описание структуры ресурса приведено выше

Выходные данные

Элемент	Описание
Resource-URI	Путь до ресурса

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

2.1.1 Пример заказа на получение СНИЛС гражданина по реквизитам

POST /snils HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Content-Type: application/json;charset=UTF-8
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39
{
«patient»: {
«familyName»: «Иванов»,
«firstName»: «Иван»,
«patronymic»: «Иванович»,
«birthDate»: «1992-10-31»,
«gender»: «1»
},
«patientPersDocs»: {
«type»: «1»,
«series»: «4890»,
«number»: «627790»,
«issueDate»: «2007-01-01»,
«issuer»: «ОВД»
}
}

2.1.2 Пример ответа

HTTP/2 200/202
Content-Encoding: text/plain; charset=utf-8
Content-Length: 43

Выходные данные
/snils/{id}

HTTP/2 40X/50X
Content-Encoding: application/problem+json; charset=utf-8
Если запрос содержит ошибки по структуре
{
«type»: «тип_ошибки»,
«title»: «заголовок_ошибки»,
«status»: код_ошибки,
«errors»: {описание_ошибки},
«traceId»: «идентификатор_ошибки»
}

Если запрос содержит ошибки по данным
{
«code»: «код_ошибки»,
«description»: «текст_ошибки»
}

2.2 Запрос статуса заказа

Между данными запросами оканчивающиеся на /{id} должна быть пауза в 10 секунд!

Метод

GET

Входные данные

Конечная точка:
[baseURL]/snils/id

Выходные данные

Элемент	Обязательность	Описание
status	Да	Статус выполнения запроса Принимаемые значение: «Выполнено» «В процессе» «Ошибка»
snils	Нет	СНИЛС
error_code	Нет	Код ошибки
error_text	Нет	Текстовое описание ошибки

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

2.2.1 Пример запроса

GET /snils/cf2c0205-e0cb-4dfd-ad02-80959c091344 HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39

2.2.2 Пример ответа

HTTP/2 200/202
Content-Type: text/plain;charset=utf-8
Content-Encoding: UTF-8

{

«patient»: {

«status»: «Выполнено»,

«snils»: «номер_СНИЛС»

}

3.1 Запрос на проверку соответствия фамильно-именной группы, даты рождения, пола и СНИЛС

Элемент	Кратность	Описание
patient	1..1	Блок персональной информации пациента
familyName	1..1	Фамилия. Строка — не более 100 символов
firstName	1..1	Имя. Строка — не более 100 символов
patronymic	0..1	Отчество. Обязательно при наличии. Строка — не более 100 символов
snils	1..1	СНИЛС. Строка — 11 цифр, без тире и пробелов
birthDate	1..1	Дата рождения. В формате: YYYY-MM-DD
gender	1..1	Пол. Число: [1, 2]. Справочник 1.2.643.5.1.13.13.11.1040

Метод

POST

Входные данные

Конечная точка:
[baseURL]/snils-validate
Тело запроса:
В теле запроса информация о пациенте в формате JSON. Описание структуры ресурса приведено выше

Выходные данные

Элемент	Описание
Resource-URI	Путь до ресурса

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

3.1.1 Пример запроса

POST /snils-validate HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Content-Type: application/json;charset=UTF-8
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39
{
«patient»: {
«familyname»: «Иванов»,
«firstname»: «Иван»,
«patronymic»: «Иванович»,
«snils»: «12312312312»,
«birthDate»: «1966-09-12»,
«gender»: «1»
}
}

3.1.2 Пример ответа

HTTP/2 200/202
Content-Encoding: text/plain; charset=utf-8
Content-Length: 52

Выходные данные
/snils-validate/{id}

HTTP/2 40X/50X
Content-Encoding: application/problem+json; charset=utf-8

Если запрос содержит ошибки по структуре
{
«type»: «тип_ошибки»,
«title»: «заголовок_ошибки»,
«status»: код_ошибки,
«errors»: {описание_ошибки},
«traceId»: «идентификатор_ошибки»
}

Если запрос содержит ошибки по данным
{
«code»: «код_ошибки»,
«description»: «текст_ошибки»
}

3.2 Запрос статуса

Между данными запросами оканчивающиеся на /{id} должна быть пауза в 10 секунд!

Метод

GET

Входные данные

Конечная точка:
[baseURL]/snils-validate/id

Выходные данные

Элемент	Обязательность	Описание
status	Да	Статус выполнения запроса Принимаемые значение: «Выполнено» «В процессе» «Ошибка»
result	Нет	Булево значение
error_code	Нет	Код ошибки
error_text	Нет	Текстовое описание ошибки

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

3.2.1 Пример запроса

GET /snils-validate/cf2c0205-e0cb-4dfd-ad02-80959c091344 HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39

3.2.2 Пример ответа

HTTP/2 200/202
Content-Type: text/plain;charset=utf-8

{

«patient»: {

«result»: true,

«status»: «Выполнено»

}

4.1 Запрос на получение ОМС (ЕНП — единый номер полиса) по персональным данным пациента

Элемент	Кратность	Описание
patient	1..1	Блок персональной информации пациента
familyName	1..1	Фамилия. Строка — не более 40 символов
firstName	1..1	Имя. Строка — не более 40 символов
patronymic	0..1	Отчество. Обязательно при наличии. Строка — не более 40 символов
birthDate	1..1	Дата рождения. В формате: YYYY-MM-DD
patientPersDocs	1..1	Блок информации о документе пациента.
type	1..1	Тип документа. Справочник: 1.2.643.5.1.13.13.99.2.48 Разрешённые значения [1, 6, 7, 9, 11, 20, 42]
series	0..1	Серия документа. Строка — не более 10 символов
number	1..1	Номер документа. Строка — не более 20 символов

Метод

POST

Входные данные

Конечная точка:
[baseURL]/united-policy-number
Тело запроса:
В теле запроса информация о пациенте в формате JSON. Описание структуры ресурса приведено выше

Выходные данные

Элемент	Описание
Resource-URI	Путь до ресурса

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

4.1.1 Пример запроса

POST /united-policy-number HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Content-Type: application/json;charset=UTF-8
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39
{
«patient»: {
«familyName»: «Иванов»,
«firstName»: «Иван»,
«patronymic»: «Иванович»,
«birthDate»: «1992-10-31»
},
«patientPersDocs»: {
«type»: «1»,
«series»: «4890»,
«number»: «627790»
}
}

4.1.2 Пример ответа

HTTP/2 200/202
Content-Encoding: text/plain; charset=utf-8
Content-Length: 58

Выходные данные
/united-policy-number/{id}

HTTP/2 40X/50X
Content-Encoding: application/problem+json; charset=utf-8

Если запрос содержит ошибки по данным
{
«code»: «код_ошибки»,
«description»: «текст_ошибки»
}

4.2 Запрос статуса

Между данными запросами оканчивающиеся на /{id} должна быть пауза в 10 секунд!

Метод

GET

Входные данные

Конечная точка:
[baseURL]/united-policy-number/id

Выходные данные

Элемент	Обязательность	Описание
unitedPolicyNumber	Нет	Единый номер полиса ОМС (ЕНП). Строка из 16 цифр
region	Нет	Код субъекта РФ по ОКАТО, где зарегистрирована СМО в качестве участника ОМС
insuranceOrganization	Нет	Наименование страховой медицинской организации
startDate	Нет	Дата начала страхования
endDate	Нет	Дата окончания страхования
status	Да	Статус выполнения запроса Принимаемые значение: «Выполнено» «В процессе» «Ошибка»
error_code	Нет	Код ошибки
error_text	Нет	Текстовое описание ошибки

HTTP-код ответа

200/202	Успешное выполнение запроса
405	Использование метода запрещено
500	Иные ошибки

4.2.1 Пример запроса

GET /united-policy-number/cf2c0205-e0cb-4dfd-ad02-80959c091344 HTTP/2
HOST: https://b2b.n3health.ru/mpisnils/Proxy/
Accept: */*
Authorization: N3 7496f7bf-0bb0-4e4e-a946-17475f08ad39

4.2.2 Пример ответа

HTTP/2 200/202
Content-Type: text/plain;charset=utf-8
Content-Encoding: UTF-8

{

«patient»: {

«unitedPolicyNumber»: «1234567891234567»,

«region»: «40000»,

«insuranceOrganization»: «АДМИНИСТРАТИВНОЕ СТРУКТУРНОЕ ПОДРАЗДЕЛЕНИЕ ООО \»КАПИТАЛ МС\» — ФИЛИАЛ В Г. САНКТ-ПЕТЕРБУРГЕ И ЛЕНИНГРАДСКОЙ ОБЛАСТИ»,

«startDate»: «2020-01-09»,

«status»: «Выполнено»

}