Методические рекомендации по интеграции с REST API Цифрового профиля (Версия 1.25)

ТАБЛИЦА ИЗМЕНЕНИЙ

СПИСОК СОКРАЩЕНИЙ

ВВЕДЕНИЕ

КАК ПОДКЛЮЧИТЬСЯ К REST API ЦИФРОВОГО ПРОФИЛЯ

4.1 Подключение к ЦП посредством использования существующего защищенного

канала СМЭВ

СРЕДЫ ДЛЯ ИНТЕГРАЦИОННОГО ТЕСТИРОВАНИЯ

ONLINE-РЕЖИМ ЗАПРОСА СОГЛАСИЙ

6.1 Сервисы REST-API ЕСИА для взаимодействия с платформой согласий

6.1.1

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

6.1.2

Получение конкретного типа согласия

6.1.3

Получение всех согласий пользователя, выданных организации, по

идентификатору пользователя (oid)

6.1.4

Получение согласия пользователя, выданного организации, по

идентификатору согласия:

6.2 Уведомление потребителей платформы согласий

ПОЛУЧЕНИЕ ДАННЫХ ЦИФРОВОГО ПРОФИЛЯ ПОЛЬЗОВАТЕЛЯ

7.1 Сервисы REST API для получения сведений пользователя

7.1.1

Основные сведения о гражданине

7.1.2

Коллекция ссылок на документы

7.1.3

Данные документа

7.1.4

Данные всех документов, указанного типа

7.1.5

Выписка с данными в исходном виде

7.2 Данные документов

7.2.1

Паспорт гражданина РФ

7.2.2

История выданных паспортов

7.2.3

Документ иностранного гражданина, удостоверяющий личность на

территории РФ

7.2.4

Водительское удостоверение

7.2.5

Заграничный паспорт

7.2.6

Свидетельство о рождении - другая страна

7.2.7

Свидетельство о рождении - СССР

7.2.8

Свидетельство о рождении - Россия

7.2.9

Свидетельство о заключении брака

7.2.10

Свидетельство о расторжении брака

101

7.2.11

Свидетельство о перемене имени

133

7.2.12

Свидетельство об установлении отцовства

136

7.2.13

Сведения о транспортном средстве

139

7.2.14

Сведения о состоянии индивидуального страхового счета застрахованного

лица

142

7.2.15

Справка о доходах и суммах налога физического лица

177

7.2.16

Справка о назначенных пенсиях и социальных выплатах на дату

185

7.2.17

Сведения о трудовой деятельности застрахованного лица в системе

обязательного пенсионного страхования

197

7.2.18 Сведения о назначенных и реализованных мерах социальной защиты

(поддержки)

205

7.2.19 Сведения об инвалидности гражданина

216

7.2.20 Сведения о выписке из регистра сертификатов материнского (семейного)

капитала

221

7.2.21 Сведения об отнесении гражданина к категории граждан предпенсионного

возраста 224

7.2.22 Сведения о полисе ОМС и прикреплении к медицинской организации

230

7.2.23 Выписка о транспортном средстве по владельцу

234

7.3 Тестирование REST API Цифрового профиля

238

СПЕЦИФИКАЦИЯ СЕРВИСОВ REST-API ЦИФРОВОГО ПРОФИЛЯ И

ПЛАФОРМЫ СОГЛАСИЙ

242

8.1 Инструментальное средство описания и документирования REST сервисов

(Swagger)

242

8.2 Спецификация сервисов REST API Цифрового профиля и Платформы согласий.242

1 ТАБЛИЦА ИЗМЕНЕНИЙ

Версия

Дата

Автор

Изменение

1.0

13.04.2020

Петраков С.В.

Создание документа

Цирихов А.М.

Жукова Д.А.

1.1

24.04.2020

Жукова Д.А.

 Удаление информации о методе

/api/public/v1/prns/{oid}/claimed/permissions

 Обновление спецификации (раздел 8.2).

1.2

06.05.2020

Цирихов А.М.

 Подраздел 5.1 - исключение scope

death_cert_doc из реестра типов согласий и

таблицы с перечнем предоставляемыех

ЕСИА наборов данных о пользователе

(scope);

 Раздел 6 - исключение типа документа

DEATH_CERT и scope death_cert_doc из

видов доументов пользователя в ЦП.

 Исключение подраздела 6.2.13 с описанием

типа документа «Свидетельство о смерти» из

подраздела 6.2.

 Обновление спецификации (раздел 8.2).

1.3

14.05.2020

Цирихов А.М.

Подраздел 5.5 - добавлено описание требований

к учётной записи уполномоченного сотрудника

организации-потребителя платформы согласий,

выполняющего настройку механизмов рассылки

уведомлений о событиях платформы согласий в

«Технологическом портале ЕСИА»

1.4

18.05.2020

Цирихов А.М.

Подраздел 5.5 - добавлены требования к

сертификату SSL для ИС организации-

потребителя, для корректного приёма по HTTPS-

протоколу REST-сервисом ИС организации-

потребителя уведомлений о событиях

платформы согласий

1.5

25.05.2020

Петраков С.В.

 Скорректированы неточности в подразделе

7.2.14 «Сведения о состоянии

индивидуального страхового счета

застрахованного лица»:

o удален параметр gender;

o у параметра version исправлен тип со

«строка» на «целое число»;

o в параметрах ipk, otherPeriodPensFactor,

PensFactor, currentYearPensFactor,

pensFactorBefore2015 удалено

округление до трех знаков;

o у параметров ipkBefore2015,

ipkCurrentYear, pensRightsTill2002,

pensRights20022014 исправлен тип с

«массив» на «объект»;

o у параметра quarter (из блока

detailPeriods) указан его тип - массив;

o исправлено название параметра

detailsPeriod на detailPeriods.



Раздел 7 - обновлена Ошибка! Источник

ссылки не найден.: добавлен новый вид

документа INCOME_REFERENCE (Справка

о доходах и суммах налога физического лица

(форма 2-НДФЛ))



В подразделы 7.1.3 и 7.1.4 добавлено

описание сервисов, позволяющих получить

данные по справке о доходах и суммах

налога физического лица только в одном

формате (XML или PDF)



Добавлен подраздел с данными документа

«Справка о доходах и суммах налога

физического лица»



Обновление спецификации (раздел 8.2).

1.6

02.06.2020

Цирихов А.М.



Исключён подраздел «Offline-режим запроса

Жукова Д.А.

согласий»;



Исключён подраздел «Сервисы REST API

ЕСИА для взаимодействия с платформой

соласий»;



Корректировки текста в разделе 5, в

подразделах 5.2 («Online-режим запроса

согласий») и 8.2 («Спецификация сервисов

REST API Цифрового профиля и Платформы

согласий»);



Обновление спецификации (подраздел 8.2).

 Добавлен п. 4.1 с описанием требования

подключения к защищенному каналу СМЭВ

для направления REST-запросов к ЦП.

1.7

21.07.2020

Онацкая Т.В.

 Добавлен раздел 6.2.16 Справка о

18.09.2020

Жукова Д.А.

назначенных пенсиях и социальных

выплатах на дату;

 Добавлен раздел 6.2.17 Сведения о трудовой

деятельности застрахованного лица в

системе обязательного пенсионного

страхования;

 В разделе 7.1.4 добавлена информация о

получении в ответе идентификаторов запроса

и пользователя;

 Обновлено вложение zip-архив.

1.8

23.09.2020

Жукова Д.А.

Добавление раздела о тестировании REST API

ЦП - п. 0

1.9

30.09.2020

Жукова Д.А.

Добавление раздела с информацией об

интеграционных средах (п.5).

1.10

30.10.2020

Тихонова М.А.

В пункте 7.2.1 в таблице 6 - Паспорт

гражданина РФ, пункте 7.2.3 в таблице 8 -

Документ иностранного гражданина,

удостоверяющий личность на территории РФ и

в пункте 7.2.5 в таблице 10 - Заграничный

паспорт изменено требование к обязательности

атрибутов «birthplace» и «issiedBy» на «не

обязательно».

1.11

28.12.2020

Петраков С.В.

Скорректирована информация о Справке о

доходах и суммах налога физического лица в п.

7.1.1, 7.1.2, 7.1.3, 7.2.15

Добавлен новый тип согласий и новая цель -

MFO_AGREEMENT.

1.12

16.02.2021

Цветкова Г.А.

 В разделах 0, 0, 7.2.17 заменены строки с

Жукова Д.А.

полным кодом файлов в BASE64 на

сокращенный вариант и указание папки, где

хранятся полные примеры

 Изменено описание примеров ответа на

запрос сведений



В разделе 7.1.3 обновлено описание пути

/digital/api/public/{version}/pso/{oid}/docs/{do

c_type}/{id}/{fileType}



В разделе 7.2.17 скорректировано описание

параметра dismissalBasis и добавлен

вложенный параметр type;



Добавлен раздел 7.2.18 Сведения о

назначенных и реализованных мерах

социальной защиты (поддержки)



Добавлен раздел 7.2.19 Сведения об

инвалидности гражданина



Добавлен раздел 7.2.20 Сведения о выписке

из регистра сертификатов материнского

(семейного) капитала



Добавлен раздел 7.2.21 Сведения об

отнесении гражданина к категории граждан

предпенсионного возраста



Добавлен раздел 7.2.22 Сведения о полисе

ОМС и прикреплении к медицинской

организации



Добавлен раздел Основные сведения о

гражданине7.1.1 Основные сведения о

гражданине



Вложение zip-архив в разделе 8.2 заменено

вынесено из документа в отдельный архив



Разделы с реестрами платформы согласий

(типы согласий, цели, действия, scope) и

реестр доступных сведений ЦП перенесены в

документ «Сценарии использования

инфраструктуры Цифрового профиля»



Добавлен раздел «Сервисы REST-API ЕСИА

для взаимодействия с платформой согласий»

1.13

05.03.2021

Петраков С.В.

 Удален ошибочно указанный параметр

eventGroup в таблице 22 (Сведения о

трудовой деятельности застрахованного

лица в системе обязательного

пенсионного страхования)

 Добавлены параметры error и

errorUpdatedOn в таблицу 14, которые

будут возвращаться во второй версии

сервисов REST API для получения

сведений пользователя (пп. 7.1.3 и 7.1.4)

для получения документа «Сведения о

состоянии индивидуального страхового

счета застрахованного лица»

1.14

24.03.2021

Губанов В.Ю.



Добавлен метод REST API: GET

/digital/api/public/{version}/pso/{oid}/doc/

{doc_type}/raw (Получение выписки в

исходном виде у пользователя с

идентификатором oid) (пп. 7.1.5)



Добавлен раздел 7.2.23 Выписка о

транспортном средстве по владельцу



В разделе 7.1.1 добавлено уточнение по

скоупу addresses

1.15

13.04.2021

Петраков С.В.



В п. 7.1.4 добавлен признак расширенной

модели данных (может быть указан

только в отношении свидетельств о браке

и разводе).



В п. 7.2.9 добавлено описание

параметров и пример расширенной

модели данных для свидетельства о

браке



В п. 7.2.10 добавлено описание

параметров и пример расширенной

модели данных для свидетельства о

разводе



В п. 7.3 добавлены новые види сведений:

MDCL_PLCY - 1 заглушка

PRE_RETIREMENT_AGE - 2 заглушки

FAMILY_ASSETS - 3 заглушки

DISABLED_PERSON - 2 заглушки

PAYMENTS_EGISSO - 1 заглушка

1.16

28.04.2021

Губанов В.Ю.

 В п. 7.2.16 добавлены параметры ответа и

их описание. Обновлен пример ответа на

запрос справки о назначенных пенсиях и

социальных выплатах

1.17

04.05.2021

Тихонова М.А.

 В п. 7.1.4 и 7.1.5 добавлено описание

реализации идентификатора запроса при

ответе от вызов метода REST API ЕСИА.

1.18

28.06.2021

Михайлюк К.А.

 В п. 7.2.2 добавлены параметры ответа и

их описание. Добавлены дополнительные

примеры ответов.

1.19

13.07.2021

Тихонова М.А.

Скорректирована информация

по использованию сертификатов по ГОСТ-2012.

1.20

20.07.2021

Тихонова М.А.

В п.6.1.3 и 6.1.4 скорректированы ответы от

вызовов метода REST API ЕСИА - изменен тип

действия (ALL_ACTIONS_TO_DATA)

1.21

26.07.2021

Губанов В.Ю.



В п. 7.3 добавлено описание метода

REST API для тестирования:

/digital/api/public/{version}/pso/{oid}/doc/

{doc_type}/raw



В п. 7.3 добавлено описание типа

документа для тестирования при

использовании метода REST API

/digital/api/public/{version}/pso/{oid}/doc/

{doc_type}/raw:

VEHICLE_INFO - 1 заглушка

1.22

30.07.2021

Маркелова М.Н.



В п. 7.1.4 добавлена информация об

ответе на запрос по документам

FID_BRTH_CERT, OLD_BRTH_CERT,

RF_BRTH_CERT, MARRIED_CERT,

DIVORCE_CERT,

NAME_CHANGE_CERT и

FATHERHOOD_CERT



В п.7.2.18 и п. 7.2.23 добавлены

параметры error и errorUpdatedOn,

изменены требования обязательности по

некоторым параметрам, а также

добавлены новые таблицы с описанием

возможных ошибок и примеры ответов с

ошибкой

 Поправлен пример в п. 7.2.21

1.23

02.08.2021

Тихонова М.А.

В разделе 7.2.18 скорректировано требование к

заполнению поля «comment»

1.24

18.08.2021

Тихонова Е.Н.

В разделах 7.2.14, 7.2.18, 7.2.21 и 7.2.23:

1. Добавлено описание параметров

“errorUpdatedOn” и “error”;

2. Добавлены пример ответа при отправке

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

примеры ответа при получении ошибки в

процессе запроса/обновления сведений

1.25

23.08.2021

Космачева М.А.

В раздел 7.2.15 добавлен код ошибки ESIA-

020131

2 СПИСОК СОКРАЩЕНИЙ

АРМ

Автоматизированное рабочее место

ГИС

Государственная информационная система

ЕСИА

Федеральная государственная информационная система

«Единая система идентификации и аутентификации в

инфраструктуре,

обеспечивающей

информационно-

технологическое взаимодействие информационных систем,

используемых для предоставления государственных и

муниципальных услуг в электронной форме»

ИС

Информационная система

ИЭП

Инфраструктура электронного правительства

КЭП

Усиленная квалифицированная электронная подпись

ЦП

Цифровой профиль гражданина в учётной записи ЕСИА

ФЛ

Физическое лицо

ЮЛ

Юридическое лицо

API

Application Programming Interface (программный интерфейс

приложения, интерфейс прикладного программирования) -

набор готовых классов, процедур, функций, структур и

констант, предоставляемых приложением (библиотекой,

сервисом) или операционной системой для использования во

внешних программных продуктах

OAuth2.0

Открытый протокол авторизации, который позволяет

предоставить третьей стороне ограниченный доступ к

защищённым ресурсам пользователя без необходимости

передавать данной третьей стороне логин и пароль

OID

Object Identifier (идентификатор объекта)

- строка или

последовательность

десятичных

цифр,

однозначно

идентифицирующая объект

PUSH

Способ распространения информации (контента) в Интернете,

когда данные поступают от поставщика к пользователю на

основе установленных параметров. Пользователь же, в свою

очередь, либо отвергает, либо принимает данные

PUSH-уведомление

PUSH-уведомления

(PUSH-сообщения)

краткие

всплывающие сообщения, отображаемые на экране

персонального компьютера или мобильного устройства

(смартфона и т.п.). Предназначены для информирования

(уведомления) пользователя, для запроса на выполнение или

побуждения пользователя к совершению определённых

действий и др. PUSH-уведомления могут появляться на экране

любого устройства, где есть область оповещений или

возможность вывода на экран данных, принятых из сети

Интернет. В ЕПГУ PUSH-уведомления инициируются

сервером ЕПГУ

REST

Representational

State

Transfer

(передача состояния

представления)

- архитектурный стиль взаимодействия

компонентов распределённого приложения в сети. REST

представляет собой согласованный набор ограничений,

учитываемых

при

проектировании

распределённой

гипермедиа-системы. То есть REST - это набор принципов и

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

интернет, использующий существующие стандарты (протокол

HTTP, стандарт построения URL, форматы данных JSON и

XML) в ходе взаимодействия

Scope

Область доступа (тип данных, к которым система-клиент

намерена получить доступ). Например, если система-клиент

запрашивает доступ к сведениям о сотрудниках организации,

то область доступа (scope) должна иметь значение

http://esia.gosuslugi.ru/org_emps

(с

необходимыми

параметрами). Перечень актуальных и устаревших областей

доступа приведен в документе "Методические рекомендации

по использованию Единой системы идентификации и

аутентификации"

SQL

Structured Query Language (язык структурированных запросов)

- декларативный язык программирования, применяемый для

создания, модификации и управления данными в реляционной

базе данных, управляемой соответствующей системой

управления базами данных

XML

eXtensible Markup Language (расширяемый язык разметки) -

язык для создания структурированных машиночитаемых

документов

3 ВВЕДЕНИЕ

Настоящий документ разработан в целях реализации и во исполнение Постановления

Правительства РФ от 3 июня 2019 г. № 710 “О проведении эксперимента по повышению

качества и связанности данных, содержащихся в государственных информационных

ресурсах”.

Данные методические рекомендации:

1. Описывают базовые сценарии использования REST API Цифрового профиля:

 идентификация и аутентификация пользователей посредством ЕСИА (п.6);

 запрос согласий пользователей для доступа к его сведениям (п.6);

 получения информационными системами участников эксперимента данных из

регистров, хранимых в Цифровом профиле (п.7).

2. Предоставляет методические рекомендации по интеграции информационных систем

с REST API Цифрового профиля.

4 КАК ПОДКЛЮЧИТЬСЯ К REST API ЦИФРОВОГО

ПРОФИЛЯ

В ЕСИА создан механизм аутентификации пользователей, основанный на

спецификациях OAuth 2.0 и расширении OpenID Connect 1.0.

Чтобы предоставить пользователям вашей системы возможность входить через ЕСИА и

предоставлять доступ к сведениям своего Цифрового профиля со стороны

подключающейся системы необходимо:



Зарегистрировать свою организацию в ЕСИА.

Для регистрации организации в ЕСИА потребуется подтвержденная учетная запись

и квалифицированная электронная подпись (КЭП) руководителя. Процесс

регистрации ЮЛ в ЕСИА описан в Руководстве пользователя ЕСИА (доступно по

ссылке https://digital.gov.ru/ru/documents/6182/ );



Зарегистрировать ИС в регистре информационных систем ЕСИА (в соответствии с

Регламентом¹).

Ответственному сотруднику необходимо предоставить доступ к Технологическому

порталу ЕСИА: руководитель или администратор профиля организации должен

включить его в специальную группу доступа «Технологический портал».

Ответственному сотруднику необходимо зарегистрировать свою ИС через

технологический портал, доступный по ссылке http://esia.gosuslugi.ru/console/tech

Руководство пользователя технологического портала доступно по ссылке:

https://digital.gov.ru/ru/documents/6190/. В результате регистрации информационная

система заносится в регистр ИС, взаимодействующих с ЕСИА;



Сгенерировать для ИС криптографические ключи и выпустить на них сертификат

ключа квалифицированной электронной подписи для подключаемой

информационной системы (должен быть выпущен УЦ и содержать ОГРН ЮЛ).

Загрузить сертификат для зарегистрированной ИС в Технологический портал.

Сертификат, используемый для проверки подписи, должен быть предварительно

зарегистрирован в ЕСИА и привязан к учетной записи системы-клиента в ЕСИА.

ЕСИА использует сертификаты в формате X.509 и взаимодействует с алгоритмами

формирования электронной подписи ГОСТ Р 34.10-2012 и криптографического

хэширования ГОСТ Р 34.11-2012.

Согласовать подключение и регистрацию системы с целью идентификации и

аутентификации и получения сведений пользователей в тестовой среде в

соответствии с Регламентом². Для этого необходимо отправить форму заявки на

адрес sd@sc.minsvyaz.ru/ (актуальная форма заявки приведена в приложении Е

Регламента). В заявке указываются перечень scopes - областей данных пользователя,

¹ Регламент размещен по ссылке: https://digital.gov.ru/ru/documents/4244/

Раздел 6 Регламента.

² Раздел 9 Регламента.

которые хочет получать потребитель. Исполнение этого процесса предоставляет

возможность потребителю производить взаимодействие с ЕСИА в тестовой среде.

В результате подключения будет предоставлена инструкция по созданию учетных

записей пользователей в тестовой среде.



Реализовать интерфейсы подключения, доработать дизайн и провести тестирование.

Сертификаты тестовой и продуктивной сред ЕСИА, используемые для

формирования электронных подписей ответов как поставщика, доступны по ссылке

http://esia.gosuslugi.ru/public/esia.zip.



Реализовать интерфейсы системы-клиента REST-сервисов ЕСИА и модели контроля

доступа, основанной на OAuth

2.0. Детальная информация содержится в

приложениях Приложении Б и Приложении В «Методических рекомендаций по

использованию Единой системы идентификации и аутентификации» по ссылке

https://digital.gov.ru/ru/documents/6186/.

Недопустимо отображать страницу

аутентификации ЕСИА во фрейме сайта.



Обеспечить в соответствии с требованиями законодательства комплекс мер,

необходимых для обеспечения информационной безопасности и защиты

персональных данных пользователей, получаемых информационной системой в

процессе ее взаимодействия с инфраструктурой ЦП, в соответствии с Федеральным

законом от 27 июля 2006 г. N 152-ФЗ "О персональных данных";



Подключиться к защищенному каналу СМЭВ для направления запросов REST-API

к Цифровому профилю (п. 4.1);



Синхронизировать системное время сервера со значением точного времени.

Расхождение более чем в минуту может приводить к возникновению ошибок при

взаимодействии потребителя с поставщиком идентификации ЕСИА.



Подключить продуктивную версию интегрируемой системы к продуктивной среде

ЕСИА и инфраструктуре Цифрового профиля в соответствии с Регламентом³. Для

этого необходимо отправить форму заявки на адрес sd@sc.minsvyaz.ru/ (актуальная

форма заявки приведена в приложении Е Регламента). При подключении к

продуктивной среде оператором эксплуатации будет проверена работоспособность

интеграции в тестовой среде.



После подключения ИС к промышленной ЕСИА проверить работу промышленной

версии ЕСИА с промышленной версией вашей системы.

³ Раздел 10 Регламента.

4.1 Подключение к ЦП посредством использования

существующего защищенного канала СМЭВ

В целях исполнения постановления Правительства Российской Федерации от 3 июня

2019 г. № 710 «О проведении эксперимента по повышению качества и связанности данных,

содержащихся в государственных информационных ресурсах» Минкомсвязью России

совместно с ПАО «Ростелеком» была разработана принципиальная схема

информационного взаимодействия на период проведения эксперимента.

Главная идея текущей схемы заключается в разделении запросов на аутентификацию

(https://esia.gosuslugi.ru/aas/oauth2/*) и запросов к REST API цифрового профиля

(https://esia.gosuslugi.ru/digital/api/*) на стороне участников эксперимента. Запросы на

аутентификацию должны обрабатываться стандартным образом в соответствии с

«Методическими рекомендациями по использованию Единой системы идентификации и

аутентификации» (доступны по ссылке https://digital.gov.ru/ru/documents/6186/) с

использованием каналов связи общего пользования. Запросы же к Цифровому профилю

должны перенаправляться посредством прокси сервера на стороне участников

эксперимента в защищённую сеть системы межведомственного электронного

взаимодействия (далее - СМЭВ) на IP-адрес баллансировщика в защищаемой сети

инфраструктуры электронного правительства: 172.16.104.200 8443.

В случае организации вышеуказанного информационного взаимодействия из подсети

(подсетей), уже указанных в настройках криптографического маршрутизатора на стороне

участника эксперимента, доступ к REST API Цифрового профиля будет предоставлен в

рамках уже существующего защищённого канала до СМЭВ и соответствующего договора

на эксплуатацию этого канала.

По вопросам подключения, работы и решению проблем, связанных с

криптоканалами, необходимо обращаться по адресу kriptokanal@rt.ru

5 СРЕДЫ ДЛЯ ИНТЕГРАЦИОННОГО ТЕСТИРОВАНИЯ

https://esia-portal1.test.gosuslugi.ru/ - интеграционная среда ЕСИА и ЦП (необходимо

использовать для тестирования аутентификации, REST API платформы согласий и ЦП).

https://svcdev-betalk.test.gosuslugi.ru/?new-lk=1 - интеграционная среда ЕПГУ (необходимо

использовать для просмотра и изменения данных пользователя и управления согласиями через

интерфейс Личного кабинета Госуслуг). Интегрирована с тестовой средой ЕСИА и ЦП

(https://esia-portal1.test.gosuslugi.ru/ ) в части атуентификации и данных пользователей.

6 ONLINE-РЕЖИМ ЗАПРОСА СОГЛАСИЙ

При запросе согласия пользователя в online-режиме системе-клиенту необходимо

реализовать стандартный механизм взаимодействия с ЕСИА для получения маркера доступа при

аутентификации пользователя с некоторыми особенностями. Актуальная версия стандартных

сервисов ЕСИА, основанных на протоколе OAuth 2.0 и OpenID Connect 1.0, представлена в

спецификации сервисов и REST API платформы согласий и ЦП в разделе 8 настоящего

документа и в «Методических рекомендациях по использованию Единой системы

идентификации и аутентификации» по ссылке: https://digital.gov.ru/ru/documents/6186/

(Приложение В).

В рамках эксперимента для запроса согласия пользователя в качестве значения

параметра scope необходимо использовать значение openid (scope, дающий право запросить

проведение аутентификации пользователя и получения маркера идентификации). Использование

других значений scope в рамках сценария запрещено. Запрос согласий возможен только у

граждан, имеющих подтверждённую учётную запись в ЕСИА. В противном случае будет

выполнена аутентификация с выдачей маркера доступа со scope «openid», но без запроса и

выдачи согласий.

В запросе к OAuth2.0 ЕСИА метода /aas/oauth2/ac (Приложение В.2.2 «Методических

рекомендаций по использованию Единой системы идентификации и аутентификации») должен

быть указан дополнительный параметр

- «permissions»

- JSON-объект со списком

запрашиваемых согласий, закодированный в формате base64 url safe. Для каждого

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

параметра «permissions» - перечень мнемоник запрашиваемых типов согласий и с перечнем для

каждого типа согласия:

 срок действия запрашиваемого типа согласия;

 необязательный атрибут

- лицо (сотрудник организации) или организация,

осуществляющее обработку данных (строка с ФИО или другой информацией);

 мнемоники и признаки обязательности scope;

 мнемоники целей;

 мнемоники действий.

Мнемоники типа согласия, цели и действия должны быть указаны строго из реестров

платформы согласий. Реестр платформы согласий указан в документе «Сценарии использования

инфраструктуры Цифрового профиля».

Запрашиваемый срок действия согласия не может превышать максимальный срок

действия, определённый для данного типа согласия.

Структура JSON-объекта параметра «permissions»:

{

"type": "array",

"items": {

"properties": {

"sysname": {

"type": "string",

"description": "Мнемоника типа согласия"

"responsibleObject": {

"type": "string",

"description": "Лицо (сотрудник организации) или организация, осуществляющее обработку

данных<br> (строка с ФИО или другой информацией, переданная в запросе<br> согласия - на усмотрение

организации, запрашивающей согласие)\n"

"expire": {

"type": "integer",

"description": "Срок, на который будет выдано согласие после утверждения (в минутах)"

"purposes": {

"type": "array",

"description": "Перечень мнемоник целей",

"items": {

"properties": {

"sysname": {

"type": "string",

"description": "Мемоника цели"

}

"required": [

"sysname"

]

}

"actions": {

"type": "array",

"description": "Перечень мнемоник действий",

"items": {

"properties": {

"sysname": {

"type": "string",

"description": "Мнемоника действия"

}

"required": [

"sysname"

]

}

"scopes": {

"type": "array",

"description": "Перечень мнемоник scope",

"items": {

[

{

"scopes": [

{"sysname": "fullname"},

{"sysname": "mobile"},

{"sysname": "email"}

"sysname": "CREDIT",

"purposes": [{"sysname":"CREDIT"}],

"actions": [{"sysname":"ALL_ACTIONS_TO_DATA"}],

"responsibleObject": "Иванов Иван Иванович",

"expire": 262800

{

"scopes": [

{"sysname": "fullname"},

{"sysname": "mobile"},

{"sysname": "id_doc"},

{"sysname": "snils"}

"sysname": "CREDIT_CARD",

"purposes": [{"sysname":"CREDIT_CARD"}],

"actions": [{"sysname":"ALL_ACTIONS_TO_DATA"}],

"responsibleObject": "Петров Петр Петрович",

"expire": 162800

}

]

После аутентификации пользователю отображается страница предоставления согласий

интерфейсе ЕСИА. У пользователя есть возможность с помощью визуальных элементов

управления выбрать только часть запрошенных согласий, а также часть scope (доступов к

данным) в рамках согласия (в случае, если эти scope для указанного типа согласия необязательны,

но желательны).

Если пользователь ранее предоставлял согласие на запрошенный тип согласия с данной

мнемоникой и такой же список целей, действий и scope, и срок действия его не истёк, то такое

согласие не отображается на странице запроса согласий, и данный шаг пропускается.

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

авторизационного кода. Запрос к методу /aas/oauth2/te следует выполнять без дополнительного

параметра «permissions», а в параметре «scope» также указать только одно значение - «openid».

После успешной обработки запроса произойдет выдача маркера доступа на все запрошенные и

утвержденные scope, привязанные к запрошенным типам согласий. Также в маркер доступа

включается endpoint метода REST-API ЕСИА, по которому ИС сможет получить все согласия,

которые пользователь выдал организации-владельцу ИС - параметр «permissions_url» (п. 8

настоящих Методических рекомендаций).

В ответе на запрос метода /aas/oauth2/te возвращается маркер доступа (access_token) с

включенными в него scope в соответствии с запрошенными и выданными пользователем

согласиями. Маркер обновления (refresh_token) в этом случае в ответе не возвращается.

В случае истечения срока действия выданного маркера доступа (access_token) необходимо

выполнить запрос метода /aas/oauth2/te с указанием в параметре scope значения

prm_chg?oid={oid}, где {oid} - OID учётной записи пользователя. OID учётной записи

пользователя может быть получен либо из ранее выданного маркера доступа, либо из события

уведомления о выдаче согласия. В ответе на запрос будет возвращён новый действующий

пользовательский маркер доступа (access_token).

Пример получаемого маркера доступа при запросе согласий:

eyJ2ZXIiOjEsInR5cCI6IkpXVCIsInNidCI6ImFjY2VzcyIsImFsZyI6IkdPU1QzNDEwXzIwMTJfMjU2In0.eyJuYmYiOjE1ODIxNDI

wMDcsInBlcm1pc3Npb25zIjoiQ1JFRElUIiwic2NvcGUiOiJvcGVuaWQgZW1haWw_bW9kZT13Jm9pZD0xMDc3MDk5NjAwIGZ1bGxuYW

1lP21vZGU9dyZvaWQ9MTA3NzA5OTYwMCBtb2JpbGU_bW9kZT13Jm9pZD0xMDc3MDk5NjAwIiwiaXNzIjoiaHR0cDpcL1wvZXNpYS5nb

3N1c2x1Z2kucnVcLyIsInVybjplc2lhOnNpZCI6IjZCNTkwNDQ1NTI5OEM0NUQyN0NGNzQwMkYzMDM2OTc4IiwidXJuOmVzaWE6c2Jq

X2lkIjoxMDc3MDk5NjAwLCJleHAiOjE1ODIxNDM4MDcsImlhdCI6MTU4MjE0MjAwNywiY2xpZW50X2lkIjoiVEVTVF9TWVMiLCJwZXJ

taXNzaW9uc191cmwiOiJodHRwczpcL1wvZXNpYS1kZXYudGVzdC5nb3N1c2x1Z2kucnVcL2VzaWEtcnNcL2FwaVwvcHVibGljXC92MV

wvcHJuc1wvMTA3NzA5OTYwMFwvaXNzdWVkXC9wZXJtaXNzaW9ucyJ9.-EHrq3WQxfOKbguf-

hd52biJlcP6Z1Cprgzuo70XYKOgOBxbwR4cm5094BJTfBYBY9-7PUMa8Z5mQEXAp9gvmg

6.1 Сервисы REST-API ЕСИА для взаимодействия с платформой

согласий

Актуальные механизмы интеграции с сервисами ЕСИА на базе подхода REST описаны

в «Методических рекомендациях по использованию Единой системы идентификации и

аутентификации» по ссылке: https://digital.gov.ru/ru/documents/6186/ (Приложение Б). Полная

спецификация сервисов REST API Цифрового профиля и платформы согласий приведена в

разделе 8.

Системе-клиенту доступны методы REST API для взаимодействия с платформой

согласий.

6.1.1 Получение всех доступных типов согласий из реестра согласий

Path: /esia-rs/api/public/v1/permissions

Тип запроса: GET

Параметры запроса:

pageIndex

pageSize

{

"stateFacts": [

"Paginated",

"hasSize",

"EntityRoot",

"FirstPage"

"size": 2,

"pageSize": 2,

"pageIndex": 1,

"totalSize": 11,

"elements": [

{

"stateFacts": [

"Identifiable"

"id": 32,

"itSystemId": 7508541,

"sysname": "PERM_8",

"name": "Согласие 8",

"description": "Согласие 8",

"revokedOn": 1572004313,

"scopeMode": "LIMITED",

"createdOn": 1572001102,

"updatedOn": 1572004313,

"scopes": {

"stateFacts": [

"hasSize"

"size": 2,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи",

"required": true

{

"stateFacts": [

"ReadOnly"

"sysname": "email",

"name": "Просмотр вашего адреса электронной почты",

"description": "Адрес электронной почты, указанный в вашей учетной записи",

"required": false

}

]

}

{

"stateFacts": [

"Identifiable"

"id": 31,

"itSystemId": 7508541,

"sysname": "PERM_7",

"name": "Согласие 7",

"description": "Согласие 7",

"scopeMode": "LIMITED",

"createdOn": 1571999547,

"updatedOn": 1571999547,

"scopes": {

"stateFacts": [

"hasSize"

"size": 2,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи",

"required": false

{

"stateFacts": [

"ReadOnly"

"sysname": "email",

"name": "Просмотр вашего адреса электронной почты",

"description": "Адрес электронной почты, указанный в вашей учетной записи",

"required": false

}

]

}

]

}

Возможные коды ошибок:

Код HTTP 404:

ESIA-039870=Выбранная информационная система не найдена

6.1.2 Получение конкретного типа согласия

Path: /esia-rs/api/public/v1/permissions/{id}

Тип запроса: GET

Требуемый scope: usr_prm

Авторизация: указать в заголовке запроса поле "Authorization", с полученным

системным маркером доступа.

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

{

"stateFacts": [

"EntityRoot",

"Identifiable"

"id": 32,

"itSystemId": 7508541,

"sysname": "PERM_8",

"name": "Согласие 8",

"description": "Согласие 8",

"revokedOn": 1572004313,

"scopeMode": "LIMITED",

"createdOn": 1572001102,

"updatedOn": 1572004313,

"scopes": {

"stateFacts": [

"hasSize"

"size": 2,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи",

"required": true

{

"stateFacts": [

"ReadOnly"

"sysname": "email",

"name": "Просмотр вашего адреса электронной почты",

"description": "Адрес электронной почты, указанный в вашей учетной записи",

"required": false

}

]

}

Возможные коды ошибок:

Код HTTP 404:

{

"stateFacts": [

"EntityRoot",

"hasSize"

"size": 3,

"elements": [

{

"stateFacts": [

"Identifiable"

"id": 30,

"personId": 7435533,

"orgId": 7413781,

"permissionId": 1,

"sysname": "PERS_DATA",

"name": "Согласие на доступ к персональным данным",

"description": "Согласие на доступ к персональным данным",

"orgShortName": "ОРГАНИЗАЦИЯ -783988581",

"ogrn": "1047702026701",

"orgAddress": "127434, Город Москва,Улица Дубки, д. 1, стр. 1",

"issuedOn": 1572020850,

"expiredOn": 1572042750,

"status": "A",

"createdOn": 1572020850,

"updatedOn": 1572020850,

"scopes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи"

}

]

"purposes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "CREDIT",

"name": "Выдачи кредита"

}

]

"actions": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "ALL_ACTIONS_TO_DATA",

"name": "Обработка и изменение персональных данных"

}

]

}

{

"stateFacts": [

"Identifiable"

"id": 27,

"personId": 7435533,

"orgId": 7413781,

"permissionId": 33,

"sysname": "PERM_9",

"name": "Согласие 9",

"description": "Согласие 9",

"orgShortName": "ОРГАНИЗАЦИЯ -783988581",

"ogrn": "1047702026701",

"orgAddress": "127434, Город Москва,Улица Дубки, д. 1, стр. 1",

"responsibleObject": "Петров Петр Петрович",

"issuedOn": 1572020850,

"expiredOn": 1603555445,

"sessionId": "9979b075-43dd-41c2-bec4-0db0452243ba",

"status": "A",

"createdOn": 1572015602,

"updatedOn": 1572019445,

"scopes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи"

}

]

"purposes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "CREDIT",

"name": "Выдачи кредита"

}

]

"actions": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "ALL_ACTIONS_TO_DATA",

"name": "Обработка и изменение персональных данных"

}

]

}

{

"stateFacts": [

"Identifiable"

"id": 24,

"personId": 7435533,

"orgId": 7413781,

"permissionId": 35,

"sysname": "PERM_11",

"name": "Согласие 11",

"description": "Согласие 11",

"orgShortName": "ОРГАНИЗАЦИЯ -783988581",

"ogrn": "1047702026701",

"orgAddress": "127434, Город Москва,Улица Дубки, д. 1, стр. 1",

"status": "W",

{

"stateFacts": [

"EntityRoot",

"Identifiable"

"id": 30,

"personId": 7435533,

"orgId": 7413781,

"permissionId": 1,

"sysname": "PERS_DATA",

"name": "Согласие на доступ к персональным данным",

"description": "Согласие на доступ к персональным данным",

"orgShortName": "ОРГАНИЗАЦИЯ -783988581",

"ogrn": "1047702026701",

"orgAddress": "127434, Город Москва,Улица Дубки, д. 1, стр. 1",

"issuedOn": 1572020850,

"expiredOn": 1572042750,

"status": "A",

"createdOn": 1572020850,

"updatedOn": 1572020850,

"scopes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "fullname",

"name": "Просмотр вашей фамилии, имени и отчества",

"description": "Фамилия, имя и отчество, указанные в вашей учетной записи"

}

]

"purposes": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "CREDIT",

"name": "Выдачи кредита"

}

]

"actions": {

"stateFacts": [

"hasSize"

"size": 1,

"elements": [

{

"stateFacts": [

"ReadOnly"

"sysname": "ALL_ACTIONS_TO_DATA",

"name": "Обработка и изменение персональных данных"

}

]

}

Возможные коды ошибок:

Код HTTP 404:

ESIA-035000=Пользователь не найден

ESIA-039870=Выбранная информационная система не найдена

ESIA-036710=Согласие не найдено

6.2 Уведомление потребителей платформы согласий

Реализован механизм и соответствующая модель данных для отправки уведомлений о

событиях платформы согласий в ИС организаций - потребителей платформы (организаций,

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

передачи в ИС атрибутов события платформы согласий, в том числе - идентификатора согласия

и связанного с согласием идентификатора гражданина - пользователя ЕСИА.

В платформе согласий предусмотрена возможность отправки запросов на REST-сервисы

(методы) ИС организаций-потребителей платформы согласий в соответствии с моделью данных,

описывающей атрибутивный состав события платформы согласий:

 тип события платформы согласий ЕСИА, в виде символьной мнемоники-кода

события, возможные значения:

 PermissionOperationEnum.claimPermission - запрос согласия;

 PermissionOperationEnum.issuePermission - выдача гражданином согласия;

 PermissionOperationEnum.refusePermission

- отказ гражданина от выдачи

согласия;

 PermissionOperationEnum.revokePermission - отзыв гражданином согласия;

 идентификатор (OID) учётной записи гражданина - пользователя ЕСИА, которому

был направлен запрос согласия/которым было выдано согласие/которым было

отказано в выдаче согласия/который отозвал согласие;

 идентификатор сессии (необязательный атрибут события)

- идентификатор,

предназначенный для хранения служебной информации о запрошенном/выданном

согласии;

 идентификатор согласия в реестре согласий.

Представленный атрибутивный состав события платформы согласий определят

структуру тела (JSON) запроса на REST-сервис информационной системы организации:

 eventType : string - источник события, для платформы согласий всегда равен

permissionsEvent;

 opType : string - тип события платформы согласий (см. описание выше);

 oid : string - идентификатор (OID) учётной записи пользователя ЕСИА (см. описание

выше);

 sessionId : string - идентификатор сессии, необязательный атрибут события;

 issPrmId : integer - идентификатор согласия в реестре согласий (см. описание выше).

Пример JSON тела запроса:

{

"eventType": "permissionsEvent",

"opType": "PermissionOperationEnum.issuePermission",

"oid": "1000031415",

"sessionId": "9979b075-43dd-41c2-bec4-0db0452243ba",

"issPrmId": 27

}

Для получения уведомлений в описанном выше формате в ИС организации-потребителя

платформы согласий необходимо реализовать REST-метод, удовлетворяющий условиям:

 публичный доступ, т.е., метод доступен для запроса со стороны внешний ИС

(например, доступен для использования извне со стороны внешнего

балансировщика ИС);

 тип HTTP запроса - POST;

 URL метода - произвольный, на усмотрение владельца ИС организации, например,

https://yoursysdomain/permissions/notify

 приём в теле запроса JSON в соответствии с описанным выше форматом;

 ответ на запрос метода: с HTTP кодом 200 OK.

Взаимодействие между платформой согласий и REST-сервисом ИС организации-

потребителя осуществляется по протоколу HTTPS, в ИС организации-потребителя должен быть

установлен SSL-сертификат, удовлетворяющий следующим требованиям:

 сертификат выпущен одним из доверенных Центров Сертификации на рынке SSL-

сертификатов, использование самовыпущенных SSL-сертификатов не допускается;

 алгоритм шифрования: RSA.

В Технологическом портале ЕСИА (далее - Техпортал) уполномоченный сотрудник

организации-потребителя платформы согласий должен указать URL-адрес REST-сервиса

(метода) информационной системы организации для приёма уведомлений от платформы

согласий.

Указанные действия в Техпортале может выполнять уполномоченный сотрудник

организации-потребителя платформы согласий, учётная запись в ЕСИА которого удовлетворяет

следующим требованиям:

 сотрудник является руководителем организации или администратором профиля

организации в ЕСИА;

 сотрудник включен в группу доступа «Технологический портал» Единой системы

идентификации и аутентификации.

Примечание: данные настройки выполняются в профиле организации в ЕСИА -

руководитель организации может назначить администратором профиля своей

организации и включить в группу доступа «Технологический портал» ЕСИА любого

сотрудника - участника организации.

Раздел Техпортала «Оповещения» предназначен для настройки механизмов рассылки

уведомлений о событиях некоторых сервисов ЕСИА, используемых зарегистрированными ИС

организаций. Доступ к указанным настройкам осуществляется на вкладке «Оповещения»

страницы «Управление сервисами» раздела Техпортала «Сервисы» (Рисунок 1).

Рисунок 1 - Настройка механизмов рассылки уведомлений сервисов ЕСИА

В группе настроек «Адрес сервиса для приёма уведомлений от платформы согласий»

предоставляется возможность указания или редактирование ранее указанного URL-адреса REST-

сервиса (метода), реализованного в ИС организации, на который будут направляться запросы с

передачей в теле запроса атрибутов событий платформы согласий. Ввод и последующее

редактирование URL-адреса REST-сервиса (метода) ИС для приёма уведомлений платформы

согласий осуществляется на форме «Данные для оповещения» (рисунок 2), отображаемой при

нажатии соответствующей кнопки «+ Добавить адрес» (рисунок 1).

Рисунок 2 - Ввод или редактирование URL-адреса REST-сервиса ИС организации для приёма

уведомлений о событиях платформы согласий ЕСИА

7 ПОЛУЧЕНИЕ ДАННЫХ ЦИФРОВОГО ПРОФИЛЯ

ПОЛЬЗОВАТЕЛЯ

В рамках эксперимента потребителям предоставляется доступ к данным пользователя

при наличии действующего согласия посредством REST API. Актуальные механизмы

интеграции с сервисами ЕСИА на базе подхода REST описаны в «Методических рекомендациях

по использованию Единой системы идентификации и аутентификации» по ссылке:

https://digital.gov.ru/ru/documents/6186/ (Приложение Б). Механизмы получения согласия

пользователей подробно описаны в п.5. Полная спецификация сервисов REST API Цифрового

профиля и платформы согласий приведена в разделе 8.

7.1 Сервисы REST API для получения сведений пользователя

Актуальные механизмы интеграции с сервисами ЕСИА на базе подхода REST описаны

в «Методических рекомендациях по использованию Единой системы идентификации и

аутентификации» по ссылке: https://digital.gov.ru/ru/documents/6186/ (Приложение Б). Полная

спецификация сервисов REST API Цифрового профиля и платформы согласий приведена в

разделе 8.

Системе-клиенту доступны методы REST API для получения сведений пользователя.

7.1.1 Основные сведения о гражданине

Path: /digital/api/public/{version}/pso/{oid}

Тип запроса: GET

Назначение: получение основной информации о гражданине с идентификатором oid.

Параметры запроса:

 version - версия API. Текущая версия: v1.

 oid - уникальный идентификатор пользователя.

Требуемый scope: в зависимости от запрашиваемого типа информации, информация

предоставляется со следующими скоупами:

- fullname

- birthdate

- birthplace

- gender

- snils

- inn

- addresses (получение адреса временной регистрации возможно только с версией

метода v2);

- mobile

- email

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель со всеми параметрами в случае успеха:

{

"oid": "1077131562",

"firstName": "Дмитрий",

"middleName": "Андреевич",

"lastName": "Лаптев",

"snils": "204-585-302 46",

"inn": "403956183997",

"gender": "M",

"birthDate": "21.11.1985",

"birthPlace": "Бишкенк",

"mobilePhone": "+7(905)6578090",

"homeAddress":{

"addressStr": "Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа",

"region": "23",

"flat": "пом.419",

"countryId": "RUS",

"house": "43Ke",

"frame": "2Lk",

"zipCode": "394000",

"building": "2f",

"street": "Советская Улица",

"fiasCode": "720b25da-f43e-4204-9013-3cb06be3e9e4"

"trusted": true

}

7.1.2 Коллекция ссылок на документы

Path: /digital/api/public/{version}/pso/{oid}/docs/{doc_type}

Тип запроса: GET

Назначение: получение коллекции имеющихся документов типа doc_type у

пользователя с идентификатором oid.

Параметры запроса:

 version - версия API. Текущая версия: v1.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (все типы документов приведены в таблице Ошибка!

Источник ссылки не найден.).

Требуемый scope: в зависимости от запрашиваемого типа документа (см.

таблицу Ошибка! Источник ссылки не найден.).

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель со всеми параметрами в случае успеха:

[

{

"id": "91899952b06c4cc89746d38b2c8c72f3",

"relevance": "actual",

"type": "MARRIED_CERT"

{

"id": "3a340bafae204f7e84ae71af2f8c0743",

"relevance": "actual",

"type": "MARRIED_CERT"

}

]

Для типа документа INCOME_REFERENCE (Справка о доходах и суммах налога

физического лица (форма 2-НДФЛ)) дополнительно указывается параметр year - год, за

который успешно получена справка 2-НДФЛ в ведомстве:

[

{

"id": "91899952b06c4cc89746d38b2c8c72f3",

"relevance": "actual",

"year": "2017",

"type": "INCOME_REFERENCE"

{

"id": "3a340bafae204f7e84ae71af2f8c0743",

"relevance": "actual",

"year": "2019",

"type": "INCOME_REFERENCE"

}

]

7.1.3 Данные документа

Path: /digital/api/public/{version}/pso/{oid}/docs/{doc_type}/{id}

Тип запроса: GET

Назначение: получение данных документа типа doc_type и идентификатором id у

пользователя с идентификатором oid

Параметры запроса:

 version - версия API. Текущая версия: v1. Для документа «Сведения о состоянии

индивидуального страхового счета застрахованного лица» (ILS_PFR) доступна

вторая версия (v2) API.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (все типы документов приведены в таблице Ошибка!

Источник ссылки не найден.).

 id - уникальный идентификатор документа.

Требуемый scope: в зависимости от запрашиваемого типа документа (см.

таблицу Ошибка! Источник ссылки не найден.).

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель со всеми параметрами в случае успеха.

Перечень параметров, которые возвращаются по каждому типу документа (doc_type),

приведены в разделе 7.2.

Path: /digital/api/public/{version}/pso/{oid}/docs/{doc_type}/{id}/{fileType}

Тип запроса: GET

Назначение: получение данных документа в формате только xml или только pdf. Сервис

доступен для типов документов INCOME_REFERENCE (Справка о доходах и суммах

налога физического лица (форма

2-НДФЛ)), PENSION_REFERENCE (Справка о

назначенных пенсиях и социальных выплатах на дату), ELECTRONIC_WORKBOOK

(Сведения о трудовой деятельности застрахованного лица в системе обязательного

пенсионного страхования), FAMILY_ASSETS (сведения о выписке из регистра

сертификатов материнского капитала).

Параметры запроса:

 version - версия API. Текущая версия: v1.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (все типы документов приведены в таблице Ошибка!

Источник ссылки не найден.).

 id - уникальный идентификатор документа.

 fileType - тип файла (XML или PDF)

Требуемый scope: ndfl_person

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель, у которой в массиве files будет приведены

только файлы указанного в запросе типа и файл подписи к нему в случае успеха.

7.1.4 Данные всех документов, указанного типа

Path: /digital/api/public/{version}/pso/{oid}/doc/{doc_type}

Тип запроса: GET

Назначение: получение данных всех документов типа doc_type у пользователя с

идентификатором oid. Для типа документов VEHICLE_INFO (Выписка о транспортном

средстве по владельцу) реализован сервис описаный в п. 7.1.5

Параметры запроса:

 version - версия API. Текущая версия: v1. Для документа «Сведения о состоянии

индивидуального страхового счета застрахованного лица» (ILS_PFR) доступна

вторая версия (v2) API.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (все типы документов приведены в таблице Ошибка!

Источник ссылки не найден.).

 extended - признак расширенной модели данных (может быть указан только в

отношении свидетельств о браке и разводе). Если указан extended=true, то тогда в

ответе вернется информация о соответствующей записи акта гражданского

состояния (при наличии).

[

{

"oid": "1000376121",

"id": "9717eee3-47fa-42de-a1c7-1f52e08a2387",

"version": 1,

"createdOn": 1582187411649,

"updatedOn": 1582187411649,

"receiptDocDate": 1582187411649,

"relevance": "actual",

"status": "unverified",

"lastName": "Петров",

"firstName": "Иван",

"middleName": "Сергеевич",

"gender": "M",

"birthDate": "23.06.1989",

"departmentDoc": "Орган записи актов гражданского состояния",

"series": "CXI-ОРТТ",

"number": "545454",

"issuedBy": "загс",

"issueDate": "01.01.2010",

"actNo": "999",

"actDate": "01.01.2010",

"type": "MARRIED_CERT"

{

"oid": "1000376121",

"id": "92528138-f675-4fb0-9c84-28a4ee864cea",

"version": 1,

"createdOn": 1582192223736,

"updatedOn": 1582192223736,

"receiptDocDate": 1582192223736,

"relevance": "actual",

"status": "unverified",

"lastName": "Петров",

"firstName": "Иван",

"middleName": "Сергеевич",

"gender": "M",

"birthDate": "23.06.1989",

"departmentDoc": "Орган записи актов гражданского состояния",

"series": "CXI-ОРТТ",

"number": "911999",

"issuedBy": "загс",

"issueDate": "01.01.2015",

"actNo": "999",

"actDate": "01.01.2015",

"type": "MARRIED_CERT"

{

"oid": "1000376121",

"id": "47a882fc-1f91-4503-8539-9f37a4f1b3f3",

"version": 1,

"createdOn": 1582192270471,

"updatedOn": 1582192270471,

"receiptDocDate": 1582192270471,

"relevance": "actual",

"status": "unverified",

"lastName": "Петров",

"firstName": "Иван",

"middleName": "Сергеевич",

"gender": "M",

"birthDate": "23.06.1989",

"departmentDoc": "Орган записи актов гражданского состояния",

"series": "CXI-ОРТТ",

"number": "921999",

"issuedBy": "загс",

"issueDate": "01.01.2018",

"actNo": "999",

"actDate": "01.01.2018",

"type": "MARRIED_CERT"

}

]

В случае, если сведение запрошено в ведомстве и ответ еще не поступил, возвращается

идентификатор этого запроса и идентификатор пользователя (oid). С помощью идентификатора

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

сведения о документах необходимо обновить запрос. Для типа документа

INCOME_REFERENCE (Справка о доходах и суммах налога физического лица (форма 2-НДФЛ))

дополнительно указывается параметр year - год, за который успешно получена справка 2-НДФЛ

в ведомстве.

В случае, если у пользователя нет информации по следющим сведениям:

FID_BRTH_CERT, OLD_BRTH_CERT, RF_BRTH_CERT, MARRIED_CERT, DIVORCE_CERT,

NAME_CHANGE_CERT и FATHERHOOD_CERT, то в ответе на запрос вернется ошибка 404.

Перечень параметров, которые возвращаются по каждому типу документа (doc_type),

приведены в разделе 7.2.

Path: /digital/api/public/{version}/pso/{oid}/doc/{doc_type}/{fileType}

Тип запроса: GET

Назначение: получение данных всех документов в формате только xml или только pdf.

Сервис доступен для типов документов INCOME_REFERENCE (Справка о доходах и

суммах налога физического лица (форма 2-НДФЛ)), PENSION_REFERENCE (Справка о

назначенных пенсиях и социальных выплатах на дату).

Параметры запроса:

 version - версия API. Текущая версия: v1.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (все типы документов приведены в таблице Ошибка!

Источник ссылки не найден.).

 fileType - тип файла (XML или PDF).

Требуемый scope: в зависимости от запрашиваемого типа документа

(см. таблицу Ошибка! Источник ссылки не найден.).

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель со всеми параметрами в случае успеха, при

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

и файл подписи к нему (при наличии).

7.1.5 Выписка с данными в исходном виде

Path: /digital/api/public/{version}/pso/{oid}/doc/{doc_type}/raw

Тип запроса: GET

Назначение: получение выписки с данными в исходном виде у пользователя с

идентификатором oid. Сервис доступен для типа документов VEHICLE_INFO (Выписка

о транспортном средстве по владельцу).

Параметры запроса:

 version - версия API. Текущая версия: v1.

 oid - уникальный идентификатор пользователя.

 doc_type - тип документа (VEHICLE_INFOОшибка! Источник ссылки не

найден.).

Требуемый scope: в зависимости от запрашиваемого типа документа

(см. таблицу Ошибка! Источник ссылки не найден.).

Авторизация: указать в заголовке запроса поле "Authorization", с полученным маркером

доступа, содержащем информацию о действующим согласии.

Ответ: возвращается ошибка или модель со всеми параметрами в случае успеха

(приведен пример для документа «Выписка о ТС по владельцу»):

{

"oid": "1077130925",

"id": "1ab0a427-48e9-47f7-ad10-6b58ff3d75e0",

"version": 1,

"createdOn": 1616081460770,

"updatedOn": 1616081460770,

"receiptDocDate": 1616081460770,

"validateDateDoc": 1616081460601,

"relevance": "actual",

"status": "verified_by_request",

"departmentDoc": "Управление ГИБДД ГУ МВД России",

"nameDoc": "Выписка о ТС по владельцу",

"content": "PD94b…..JzPg==",

"type": "VEHICLE_INFO"

}

В случае, если сведение запрошено в ведомстве и ответ еще не поступил, возвращается

идентификатор этого запроса и идентификатор пользователя (oid). С помощью идентификатора

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

сведения о выписки транспортого средства по владельцу необходимо обновить запрос.Перечень

параметров, которые возвращаются по каждому типу документа (doc_type), приведены в разделе

7.2.

7.2 Данные документов

7.2.1 Паспорт гражданина РФ

Модель документа «Паспорт гражданина РФ» приведена в следующей таблице:

Таблица 1 - Паспорт гражданина РФ

Требования к

№

Код поля

Описание поля

Комментарий

заполнению

oid

Идентификатор

обязательно

Строка

пользователя

Уникальный

обязательно

Строка

идентификатор

документа

status

Статус достоверности

обязательно

Принимает значения:

verified_by_validate

verified_by_request

verified_by_push

unverified

relevance

Релевантность

обязательно

Принимает значения:

документа

actual

expired

invalid

series

Серия документа

обязательно

Строка

number

Номер документа

обязательно

Строка

issueDate

Дата выдачи документа

обязательно

Дата

формате:

ДД.ММ.ГГГГ

type

Тип документа

обязательно

Для

паспорта

РФ

принимает

значение

RF_PASSPORT

departmentDoc

Ведомство, к которому

не обязательно

Строка

относится документ

10.

receiptDocDate

Дата и время получения

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

11.

validateDateDoc

Дата и время валидации

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

12.

lastName

Фамилия пользователя

обязательно

Строка

Требования к

№

Код поля

Описание поля

Комментарий

заполнению

13.

firstName

Имя пользователя

обязательно

Строка

14.

middleName

Отчество пользователя

не обязательно

Строка

15.

gender

Половая

обязательно

Принимает значения:

принадлежность

M - мужской пол

F - женский пол

16.

birthDate

Дата рождения

обязательно

Дата

формате:

ДД.ММ.ГГГГ

17.

birthplace

Место рождения

не обязательно

Строка

18.

issuedBy

Кем выдан паспорт

не обязательно

Строка

19.

issueId

Код подразделения

обязательно

Строка

Пример ответа на запрос паспорта гражданина РФ:

{

"oid": "1000376121",

"id": "67664",

"receiptDocDate": 1576835468000,

"validateDateDoc": 1576835468000,

"relevance": "actual",

"status": "verified_by_validate",

"lastName": "Петров",

"firstName": "Иван",

"middleName": "Сергеевич",

"birthPlace": "Курская область",

"gender": "M",

"birthDate": "23.06.1989",

"departmentDoc": "Главное управление №1 по вопросам миграции МВД России",

"series": "0001",

"number": "393393",

"issueId": "145854",

"issuedBy": "РОВД 89",

"issueDate": "17.07.2009",

"type": "RF_PASSPORT"

}

7.2.2 История выданных паспортов

Модель документа «История выданных паспортов» приведена в следующей таблице:

Таблица 2 - История выданных паспортов

№

Код поля

Описание поля

Требования

Комментарий

заполнению

oid

Идентификатор

обязательно

Строка

пользователя

Уникальный

обязательно

Строка

идентификатор

документа

status

Статус достоверности

обязательно

Принимает значения:

verified_by_validate

verified_by_request

verified_by_push

unverified

relevance

Релевантность

обязательно

Принимает значения:

документа

actual

expired

invalid

departmentDoc

Ведомство, к которому

не обязательно

Строка

относится документ

receiptDocDate

Дата и время получения

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

validateDateDoc

Дата и время валидации

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

version

Версия документа

обязательно

Строка

createdOn

Дата и время создания

обязательно

Задается как количество

документа

миллисекунд,

прошедших с

00:00:00

UTC 1 января 1970 года

10.

updatedOn

Дата

время

обязательно

Задается как количество

обновления документа

миллисекунд,

прошедших с

00:00:00

UTC 1 января 1970 года

11.

lastName

Фамилия пользователя

обязательно

Строка

№

Код поля

Описание поля

Требования

Комментарий

заполнению

12.

firstName

Имя пользователя

обязательно

Строка

13.

middleName

Отчество пользователя

не обязательно

Строка

14.

birthDate

Дата рождения

обязательно

Дата

формате:

ДД.ММ.ГГГГ

15.

error

Мнемоника ошибки

не обязательно

Строка.

Возвращается вместо

истории паспортов в

случае возникновения

ошибок.

16.

errorUpdateOn

Дата и время получения

не обязательно

Задается как количество

ошибки

миллисекунд,

прошедших с

00:00:00

UTC 1 января 1970 года.

Возвращается вместо

истории паспортов в

случае возникновения

ошибок.

По каждому выданному паспорту возвращаются следующие данные (пп. 17 - 24)

17.

series

Серия документа

не обязательно

Строка

18.

number

Номер документа

обязательно

Строка

19.

issueDate

Дата выдачи документа

обязательно

Дата

формате:

ДД.ММ.ГГГГ

20.

issuedBy

Кем выдан паспорт

не обязательно

Строка

21.

issueId

Код подразделения

не обязательно

Строка

22.

passportType

Тип паспорта

обязательно

Принимает значения:

RF_PASSPORT

(паспорт

гражданина

РФ)

FRGN_PASS

(заграничный паспорт)

USSR_PASSPORT

(паспорт СССР)

23.

passportStatus

Статус паспорта

обязательно

Принимает значения:

valid (Действителен)

invalid

(Не

действителен)

noInformation

(Сведениями

по

№

Код поля

Описание поля

Требования

Комментарий

заполнению

заданным реквизитам не

располагаем)

24.

invalidityReason

Причина

не обязательно

Принимает значения:

недействительности

expired (истек срок

действия)

replaced (заменен на

новый)

withViolation (выдан с

нарушением)

inSearch (в розыске)

destroyed

(изъят,

уничтожен)

ownerDeath (в связи со

смертью владельца)

technicalDefect

(технический брак)

lost (утрачен)

При выполнении отправки запроса в МВД для получения/обновления истории выданных паспортов возвращаются

следующие данные (пп. 25-26)

25.

oid

Идентификатор

обязательно

Строка

пользователя

26.

requestId

Номер

запроса,

обязательно

Строка

отправленного в МВД

для

получения/обновления

истории

выданных

паспортов

Пример ответа на запрос истории паспортов:

{

"oid": "10031415",

"id": "91899952b06c4cc89746d38b2c8c72f3",

"status": "verified_by_validate",

"departmentDoc": "ГУВМ МВД России",

"receiptDocDate": "1574237502",

"validateDateDoc": "1574237613",

"version": 1,

"createdOn": 1582187411649,

"updatedOn": 1582187411649,

"firstName": "Мария",

"middleName": "Петровна",

"lastName": "Менделеева",

"birthDate": "02.09.2000",

"history": [

{

"passportType": "RF_PASSPORT",

"series": "65 02",

"number": "650230",

"issueDate": "02.09.2000",

"issuedBy": "Гагаринским отделением милиции №5 по г. Москве МВД России",

"issueId": "503-078",

"passportStatus": "invalid",

"invalidityReason": "replaced"

{

"passportType": "FRGN_PASS",

"series": "12",

"number": "3444444",

"issueDate": "09.02.2018",

"issuedBy": "ФМС 404",

"passportStatus": "valid"

}

]

}

Пример ответа при отправке запроса в МВД для получения/обновления истории паспортов:

{

"oid": "10031415",

"requestId": "2325834"

}

Пример ответа с ошибкой при попытке актуализации ранее полученной истории паспортов:

{

"oid": "10031415",

"id": "91899952b06c4cc89746d38b2c8c72f3",

"status": "verified_by_validate",

"departmentDoc": "ГУВМ МВД России",

"receiptDocDate": "1574237502",

"validateDateDoc": "1574237613",

"version": 1,

"createdOn": 1582187411649,

"updatedOn": 1582187411649,

"firstName": "Мария",

"middleName": "Петровна",

"lastName": "Менделеева",

"birthDate": "02.09.2000",

"error": "DocHistoryError",

"errorUpdatedOn": 1624373989862,

"history": [

{

"passportType": "RF_PASSPORT",

"series": "65 02",

"number": "650230",

"issueDate": "02.09.2000",

"issuedBy": "Гагаринским отделением милиции №5 по г. Москве МВД России",

"issueId": "503-078",

"passportStatus": "invalid",

"invalidityReason": "replaced"

{

"passportType": "FRGN_PASS",

"series": "12",

"number": "3444444",

"issueDate": "09.02.2018",

"issuedBy": "ФМС 404",

"passportStatus": "valid"

}

]

}

7.2.3 Документ иностранного гражданина, удостоверяющий

личность на территории РФ

Модель документа «Документ иностранного гражданина, удостоверяющий личность на

территории РФ» приведена в следующей таблице:

Таблица 3 - Документ иностранного гражданина, удостоверяющий личность на территории РФ

№

Код поля

Описание поля

Требования

Комментарий

заполнению

oid

Идентификатор

обязательно

Строка

пользователя

Уникальный

обязательно

Строка

идентификатор

документа

status

Статус достоверности

обязательно

Принимает значения:

verified_by_validate

verified_by_request

verified_by_push

unverified

relevance

Релевантность

обязательно

Принимает значения:

документа

actual

expired

invalid

type

Тип документа

обязательно

Для

документа

иностранного

гражданина принимает

значение FID_DOC

departmentDoc

Ведомство, к которому

не обязательно

Строка

относится документ

receiptDocDate

Дата и время получения

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

validateDateDoc

Дата и время валидации

не обязательно

Задается как количество

документа в формате

миллисекунд,

timestamp

прошедших с

00:00:00

UTC 1 января 1970 года

lastName

Фамилия пользователя

обязательно

Строка

10.

firstName

Имя пользователя

обязательно

Строка

11.

middleName

Отчество пользователя

не обязательно

Строка

№

Код поля

Описание поля

Требования

Комментарий

заполнению

12.

gender

Половая

обязательно

Принимает значения:

принадлежность

M - мужской пол

F - женский пол

13.

birthDate

Дата рождения

обязательно

Дата

формате:

ДД.ММ.ГГГГ

14.

birthplace

Место рождения

не обязательно

Строка

15.

series

Серия документа

не обязательно

Строка

16.

number

Номер документа

обязательно

Строка

17.

issueDate

Дата выдачи документа

обязательно

Дата

формате:

ДД.ММ.ГГГГ

Пример ответа на запрос документа иностранного гражданина, удостоверяющего личность на

территории РФ:

{

"oid": "1077096702",

"id": "100941",

"receiptDocDate": 1576591537000,

"validateDateDoc": 1576591537000,

"relevance": "actual",

"status": "verified_by_validate",

"lastName": "Кинэн",

"firstName": "Мэйнард",

"middleName": "Джеймс",

"birthPlace": "врн",

"gender": "M",

"birthDate": "01.01.1990",

"departmentDoc": "Главное управление №1 по вопросам миграции МВД России",

"series": "01236541",

"number": "12332131",

"issueDate": "01.01.2010",

"type": "FID_DOC"

}

7.2.4 Водительское удостоверение

Модель документа «Водительское удостоверение» приведена в следующей таблице:

Таблица 4 - Водительское удостоверение

№

Код поля

Описание поля

Требования

Комментарий

заполнению

oid

Идентификатор

обязательно

Строка

пользователя

Уникальный

обязательно

Строка

идентификатор

документа

status

Статус достоверности

обязательно

Принимает значения:

verified_by_validate

verified_by_request

verified_by_push

unverified

relevance

Релевантность

обязательно

Принимает значения:

документа

actual

expired

invalid

series

Серия документа

обязательно

Строка

number

Номер документа

обязательно

Строка

issueDate

Дата выдачи документа

обязательно

Дата

формате:

ДД.ММ.ГГГГ

type

Тип документа

обязательно

Для

водительского

удостоверения

принимает

значение

RF_DRIVING_LICENS

departmentDoc

Ведомство, к которому

не обязательно

Строка

относится документ

10.

receiptDocDate

Дата и время получения

не обязательно

Задается

как

документа в формате

количество

timestamp

миллисекунд,

прошедших с 00:00:00

UTC 1 января 1970 года

11.

validateDateDoc

Дата и время валидации

не обязательно

Задается

как

документа в формате

количество

timestamp

миллисекунд,

№

Код поля

Описание поля

Требования

Комментарий

заполнению

прошедших с 00:00:00

UTC 1 января 1970 года

12.

lastName

Фамилия пользователя

обязательно

Строка

13.

firstName

Имя пользователя

обязательно

Строка

14.

middleName

Отчество пользователя

не обязательно

Строка

15.

birthDate

Дата рождения

обязательно

Дата

формате:

ДД.ММ.ГГГГ

16.

birthplace

Место рождения

обязательно

Строка

17.

countryName

Страна выдачи ВУ

не обязательно

Строка

18.

issuedBy

Кем

выдано

обязательно

Строка

удостоверение

19.

expiryDate

Действителен до

обязательно

Дата

формате:

ДД.ММ.ГГГГ

20.

experience

Водительский стаж (год

не обязательно

Год в формате: xxxx

выдачи первых прав)

(где x

- символы

десятичных цифр 0…9)

21.

Методические рекомендации по интеграции с REST API Цифрового профиля (Версия 1.25) - часть 1