Взаимодействие со шлюзом в рамках ЦПГ HTTP API
В данном разделе приводится пошаговое взаимодействие клиентской системы и шлюза, доступного по адресу https://demo.gate.esia.pro/. В качестве клиентской ИС рассматривается система с идентификатором a4fb804bfdf54df4f4da7faae24375e6, секретом 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 и путем возврата https://ya.ru
Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и ЦПГ
ЕСИА Шлюз не хранит персональные данные пользователей в базе данных. Передача персональных данных пользователя происходит через защищенный по https канал связи.
ЕСИА Шлюз хранит только транспортную информацию (scopes, redirect_uri, время запроса, авторизационный код ЕСИА) и SHA-512 от ФИО и СНИЛСа пользователя. Эти данные необходимы для обработки внештатных ситуаций, таких как составление заявки в службу поддержки ЕСИА и реагирование на запросы правоохранительных органов и не являются персональными данными.
Авторизация (Получение авторизационного кода)
/auth/authorize
Параметры:
- client_id - идентификатор клиентской системы на стороне шлюза;
- response_type - тип ответа (допустимое значение
code); - provider - наименование провайдера данных (допустимые значния
esia_oauth,ebs_oauth,cpg_oauth); - scope - набор областей доступа:
- для provider=esia_oauth перечень скоупов можно найти в https://digital.gov.ru/ru/documents/6186/;
- для provider=ebs_oauth допустимое значение
openid bio; - для provider=cpg_oauth допустимое значение
openid;
- redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь после авторизации со стороны ЕСИА (должен полностью совпадать с URL возврата, указанным в настройках системы на стороне шлюза);
- state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения CSRF атак;
- nonce - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения подделки токена идентификации;
- следующие параметры указываются в запросе только в случае наличия значения cpg_oauth для параметра provider:
- permissions - перечень scope запрашиваемых в рамках типов согласий;
- purposes - мнемоники целей. Список допустимых значений указан в таблице 2 “Реестр целей” в Сценарии использования инфраструктуры Цифрового профиля;
- sysname - мнемоника типа согласия. Список допустимых значений указан в таблице 1 “Реестр типов согласий” в Сценарии использования инфраструктуры Цифрового профиля;
- actions - мнемоника действия. Список допустимых значений указан в таблице 3 “Реестр действий” в Сценарии использования инфраструктуры Цифрового профиля;
- responsible_object - определяет лицо или организацию, от чьего имени осуществляется обработка данных (строка ФИО или другой информацией - на усмотрение организации запрашивающей согласие). Необязательный параметр;
- expire - срок, на который будет выдано согласие после утверждения (в минутах);
- raw_documents - перечень scope, для которых будет выполняться запрос документов в исходном виде. Перечень типов документов, которые можно запрашивать в исходном виде указан в п. 5.1.8 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- xml_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в xml виде указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- pdf_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в pdf виде указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- file_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в zip виде указан в п. 5.1.13 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр.
- ext_documents - перечень scope, для которых будет выполняться запрос перечня ссылок на файлы, полученные от ведомства, детализирующие документы определённого типа. Перечень типов документов, для которых можно запрашивать перечень ссылок указан в п. 5.1.10 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр.
- permission_types - при запросе нескольких типов согласий, вышеуказанные cpg_oauth параметры отправляются в списке объектов. Необязательный параметр.
Примеры:
Для инициации процесса получения доступа к цифровому профилю гражданина и платформе согласий необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. При этом в запросе необходимо:
- значение параметра provider установить в
cpg_oauth; - в параметре scope указать
openid; - указать обязательные параметры
permissions,purposes(например, CREDIT из методических рекомендаций),sysname(CREDIT из методических рекомендаций),actions(ALL_ACTIONS_TO_DATA),expire(60); - при необходимости, указать опциональный параметр
responsible_object(Иванов Иван Иванович).
Для клиентской системы с вышеуказанными параметрами авторизационный запрос будет иметь следующий вид:
https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permissions=fullname&purposes=CREDIT&sysname=CREDIT&actions=ALL_ACTIONS_TO_DATA&expire=3&responsible_object=Иванов Иван Иванович&state=1a73f168-4485-11ed-b878-0242ac120002&nonce=5f32db1a-85cc-4fb1-bad6-1751cc225d49
Для запроса нескольких целей согласия нужно указать их в запросе в параметре purposes. Должна получиться ссылка следующего вида:
https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&redirect_uri=https://ya.ru&scope=openid&provider=cpg_oauth&permissions=fullname&sysname=CREDIT&purposes=CREDIT+REG_QUESTIONNAIRE+UPD_CUSTOMER_INF&actions=ALL_ACTIONS_TO_DATA&expire=5&state=1a73f168-4485-11ed-b878-0242ac120002
Для запроса нескольких типов согласий нужно перечислить все необходимые параметры в списке объектов permission_types. Должна получиться ссылка следующего вида:
https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permission_types[][permissions]=fullname%20gender%20snils&permission_types[][purposes]=CREDIT&permission_types[][sysname]=CREDIT&permission_types[][actions]=ALL_ACTIONS_TO_DATA&permission_types[][expire]=60&permission_types[][permissions]=fullname%20gender%20birthplace%20addresses&permission_types[][purposes]=CREDIT_CARD&permission_types[][sysname]=CREDIT_CARD&permission_types[][actions]=ALL_ACTIONS_TO_DATA&permission_types[][expire]=60&state=1a73f168-4485-11ed-b878-0242ac120002
В случае успешной авторизации произойдет редирект на url следующего вида:
https://ya.ru/?code=ef8b0177d144b628c177260bd4aa4f444f14a1091a02189d6e691f441e0a85e5&state=1a73f168-4485-11ed-b878-0242ac120002
где, в параметре code передается авторизационный код.
В случае возникновения ошибки будет редирект на url возврата с указанием ошибки:
https://ya.ru/?error=bad_request&error_description=Нет+ни+одного+поддерживаемого+скоупа&state=1a73f168-4485-11ed-b878-0242ac120002
где, в параметрах error и error_description хранится информация об ошибке.
Получение токена доступа (Обмен авторизационного кода на токен доступа)
/auth/token
Параметры:
- grant_type - тип разрешения (допустимое значение
authorization_code); - redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
- client_id – идентификатор клиентской системы на стороне шлюза;
- code - авторизационный код;
- client_secret - секрет клиентской системы на стороне шлюза.
На предыдущем шаге после успешной авторизации в ЕСИА был получен авторизационный код, который следует обменять на токен доступа (access_token) для его последующего использования при получении пользовательских данных. Один код можно обменять только на один токен. Для этого отправляем POST запрос на url
https://demo.gate.esia.pro/auth/token
со следующими параметрами запроса:
- grant_type=authorization_code;
- redirect_uri=https://ya.ru – путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
- client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиентской системы на стороне шлюза;
- code - авторизационный код;
- client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 - секрет клиентской системы на стороне шлюза.
Пример запроса получения access_token:
curl -X POST https://demo.gate.esia.pro/auth/token -d "grant_type=authorization_code&client_id=a4fb804bfdf54df4f4da7faae24375e6&code=df09baaf1cd797565471eb519caead41ea23174acb5f18615f87c479330dc3d6&client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28&redirect_uri=https://ya.ru"
Будет получен следующий ответ:
{
"access_token": "eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw",
"token_type": "Bearer",
"expires_in": 3588,
"refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
"scope": "openid fullname",
"created_at": 1644242600,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}
В поле access_token находится токен доступа необходимый для получения данных. А в refresh_token находится токен обновления необходимый для перевыпуска токена доступа. Значение refresh_token присутствует в ответе только для провайдеров данных esia_oauth и cpg_oauth.
Перевыпуск токена доступа (Обмен токена обновления на токен доступа)
/auth/token
Параметры:
- grant_type - тип разрешения (допустимое значение
refresh_token); - redirect_uri - путь возврата индивидуален для конкретного клиента;
- client_id – идентификатор клиента;
- refresh_token - токен обновления;
- client_secret - секрет клиента.
На предыдущем шаге были получены токены доступа и обновления. Токен обновления можно обменять на новый токен доступа (access_token) и, вместе с ним, токен обновления (refresh_token) для последующего использования при получении пользовательских данных. После перевыпуска токенов предыдущие токены доступа и обновления перестают работать. Для этого отправляем POST запрос на url:
https://demo.gate.esia.pro/auth/token
со следующими параметрами запроса:
- grant_type=refresh_token;
- redirect_uri=https://ya.ru – путь возврата индивидуален для конкретного клиента;
- client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиента;
- refresh_token=GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM - токен обновления;
- client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 - секрет клиента.
Пример запроса на перевыпуск токена доступа:
curl -X POST https://demo.gate.esia.pro/auth/token -d "grant_type=refresh_token&client_id=a4fb804bfdf54df4f4da7faae24375e6&refresh_token=GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM&client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28&redirect_uri=https://ya.ru"
Будет получен следующий ответ:
{
"access_token": "eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw",
"token_type": "Bearer",
"expires_in": 3596,
"refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
"scope": "openid fullname",
"created_at": 1678856341,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}
Получение данных цифрового профиля
Получение персональных данных пользователя
/auth/userinfo
Заголовки:
- Authorization - заголовок включающий в себя данные для проверки подлинности.
Для получения данных отправляется POST запрос на url:
https://demo.gate.esia.pro/auth/userinfo
со следующими заголовками запроса:
- Authorization: Bearer [access_token]
Пример запроса на получение данных:
curl -X POST https://demo.gate.esia.pro/auth/userinfo -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw"
На основе полученного токена доступа шлюз предоставляет клиентским системам доступ к областям данных из защищённого хранилища ЕСИА.
Пример ответа в случае запроса fullname, birthdate, birthplace, gender, snils, inn, addresses, mobile и email:
{
"sub": "4",
"info": {
"uid": "1000482766",
"oid": "1000482766",
"firstName": "Александр",
"middleName": "Викторович",
"lastName": "Наличников",
"snils": "159-756-279 05",
"inn": "330077654542",
"gender": "M",
"birthDate": "04.10.1995",
"birthPlace": "Дом",
"email": "wsdlfkj@yandex.ru",
"mobilePhone": "+7(999)5675677",
"registrationAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"homeAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"trusted": true,
"documents": [],
"scope": [
"birthplace",
"gender",
"mobile",
"email",
"openid",
"fullname",
"addresses",
"inn",
"snils",
"birthdate"
]
}
}
ВАЖНО! В соответствии с законодательством перечень скоупов доступных для клиентских систем шлюза может быть ограничен. Поэтому, прежде чем указывать перечень скоупов в запросе к шлюзу, необходимо сверить этот перечень с перечнем скоупов указанных в заявке на подключение к тестовой/промышленной ЕСИА.
Полный перечень скоупов и соответствующих им данных, которые могут быть запрошены из защищённого хранилища ЕСИА можно найти в методических рекомендациях по использованию ЕСИА.
Получение документов пользователя
Запрос документов происходит так же, как и запрос других данных - путем указания нужного scope. Чтобы выбрать подходящий scope необходимо в Таблице 7 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметр permissions авторизационного запроса, формирование которого описанно выше.
Например, необходимо получить паспорт гражданина РФ и свидетельство о рождении. Для этого необходимо в Таблице 7 документа Сценарии использования инфраструктуры Цифрового профиля по мнемонике типа документа (RF_PASSPORT и FID_BRTH_CERT соответственно) или названию типа документа (Паспорт гражданина РФ и Свидетельство о рождении – другая страна) определить перечень необходимых scope. В данном случае такими scope являются id_doc, birth_cert_doc. Их и нужно добавить в параметр permissions авторизационного запроса. В резулльтате будет получен следующий запрос:
https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permissions=fullname+birthdate+birthplace+gender+snils+inn+addresses+mobile+email+id_doc+birth_cert_doc&purposes=CREDIT&sysname=CREDIT&actions=ALL_ACTIONS_TO_DATA&expire=3&responsible_object=Иванов Иван Иванович&state=1a73f168-4485-11ed-b878-0242ac120002
В случае успешной авторизации произойдет редирект на url следующего вида:
https://ya.ru/?code=hFGdtqdBuiGcKRQ7EHnh7aeCdkY7ZBmi3aqXo7Tw71Q&state=1a73f168-4485-11ed-b878-0242ac120002
После этого необходимо обменять авторизационный код на токен доступа access_token и запросить данные.
Пример ответа в случае запроса персональных данных пользователя и документов(паспорт гражданина РФ и свидетельства о рождении):
{
"sub": "4",
"info": {
"uid": "1000482766",
"oid": "1000482766",
"firstName": "Александр",
"middleName": "Викторович",
"lastName": "Наличников",
"snils": "159-382-279 05",
"inn": "330073041542",
"gender": "M",
"birthDate": "04.10.1995",
"birthPlace": "Дом",
"citizenship": "RUS",
"email": "wsdlfkj@yandex.ru",
"mobilePhone": "+7(999)5675677",
"registrationAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"homeAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"trusted": true,
"documents": [
{
"oid": "1000482766",
"id": "156516",
"receiptDocDate": 1680099387000,
"validateDateDoc": 1680099387000,
"relevance": "actual",
"status": "verified_by_validate",
"lastName": "Наличников",
"firstName": "Александр",
"middleName": "Викторович",
"birthPlace": "Дом",
"gender": "M",
"birthDate": "04.10.1995",
"departmentDoc": "Главное управление по вопросам миграции МВД России",
"series": "5465",
"number": "456456",
"issueId": "545555",
"issuedBy": "Фловыралорыв",
"issueDate": "02.11.2011",
"type": "RF_PASSPORT"
},
{
"oid": "1000482766",
"id": "210614",
"receiptDocDate": 1651064300538,
"relevance": "actual",
"status": "unverified",
"lastName": "Наличников",
"firstName": "Александр",
"middleName": "Викторович",
"birthPlace": "Дом",
"gender": "M",
"birthDate": "04.10.1995",
"departmentDoc": "Орган записи актов гражданского состояния",
"series": "12321332",
"number": "32332323",
"issuedBy": "Фывыв",
"issueDate": "07.04.2022",
"type": "FID_BRTH_CERT"
}
],
"scope": [
"birth_cert_doc",
"birthplace",
"gender",
"mobile",
"id_doc",
"email",
"openid",
"fullname",
"addresses",
"inn",
"snils",
"birthdate"
]
}
}
Перечень параметров, которые возвращаются по каждому типу документа (type), приведены в разделе 5.2 методических рекомендаций.
ВАЖНО: При запросе документа ответ может поступить не сразу, а в течении некоторого времени. Это происходит, если сведение запрошено в ведомстве, а ответ от ведомства ещё не поступил. В этом случае возвращается идентификатор этого запроса и идентификатор пользователя (oid).
Пример такого ответа приведён ниже:
{
"sub" : 3,
"info": {
"uid" : "1000698657",
"oid" : "1000698657",
"firstName" : "Инокентий",
"middleName" : "Васильевич",
"lastName" : "Растопов",
"snils" : "076-732-132 01",
"inn" : "923453423423",
"gender" : "M",
"birthDate" : "08.06.1982",
"trusted" : 1,
"documents" : [
{
"oid" : "1000698657",
"id" : "ef367ef2-76d6-416e-a098-b2adc6362507",
"version" : "1",
"createdOn" : 1685447570367,
"updatedOn" : 1685447570367,
"receiptDocDate" : 1685447570367,
"validateDateDoc" : 1685447570360,
"relevance" : "actual",
"status" : "verified_by_request",
"departmentDoc" : "Федеральная налоговая служба",
"error" : "ndflNotFound",
"year" : "2020",
"type" : "INCOME_REFERENCE",
},
{
"oid" : "1000698657",
"id" : "8e8be1de-75e2-42fe-9cf6-7cf20e814d5a",
"version" : "1",
"createdOn" : 1685447572343,
"updatedOn" : 1685447572343,
"receiptDocDate" : 1685447572343,
"validateDateDoc" : 1685447572334,
"relevance" : "actual",
"status" : "verified_by_request",
"departmentDoc" : "Федеральная налоговая служба",
"error" : "ndflNotFound",
"year" : "2022",
"type" : "INCOME_REFERENCE",
},
{
"oid" : "1000698657",
"id" : "2df5d300-0547-41a6-a526-e7cd5b169b69",
"version" : "1",
"createdOn" : 1685447572724,
"updatedOn" : 1685447572724,
"receiptDocDate" : 1685447572724,
"validateDateDoc" : 1685447572713,
"relevance" : "actual",
"status" : "verified_by_request",
"departmentDoc" : "Федеральная налоговая служба",
"error" : "ndflNotFound",
"year" : "2021",
"type" : "INCOME_REFERENCE",
},
{
"oid" : 1000698657,
"requestId" : 4864167,
}
],
"scope" : [
"ils_doc",
"openid",
"gender",
"fullname",
"snils",
"ndfl_person",
"birthdate",
"inn",
]
}
}
}
С помощью идентификатора запроса осуществляется процесс обработки персональных данных. Для возможности получения сведения о документах необходимо обновить запрос, то есть послать исходный запрос на получение документов ещё раз.
Для типа документа INCOME_REFERENCE (Справка о доходах и суммах налога физического лица (форма 2-НДФЛ)) дополнительно указывается параметр year – год, за который успешно получена справка 2-НДФЛ в ведомстве.
Например:
[
{
"id": "91899952b06c4cc89746d38b2c8c72f3",
"relevance": "actual",
"year": "2017",
"type": "INCOME_REFERENCE"
},
{
"id": "3a340bafae204f7e84ae71af2f8c0743",
"relevance": "actual",
"year": "2019",
"type": "INCOME_REFERENCE"
}
]
ВАЖНО: в случае, если у пользователя нет информации по следющим сведениям: FID_BRTH_CERT, OLD_BRTH_CERT, RF_BRTH_CERT, MARRIED_CERT, DIVORCE_CERT, NAME_CHANGE_CERT и FATHERHOOD_CERT, то в ответе на запрос вернется ошибка 404.
Получение данных о документах в исходном виде
Для получения данных о документах в исходном виде необходимо в специальном параметре указать scope, соответствующие требуемым типам документов. Таким специальными парметром является raw_documents.
Сервис доступен для ограниченного набора типов документов. К таким документам относятся следующие:
- DIGITAL_EDUC_DOC (данные цифровых документов об образовании версии 1.0.1);
- DIGITAL_EDUC_DOC_V2 (данные цифровых документов об образовании версии 2.0.6);
- DISABLED_PERSON (сведения об инвалидности);
- ILS_PFR (сведения о состоянии индивидуального страхового счета застрахованного лица);
- PAYOUT_INCOME (сведения о доходах физического лица и о выплатах страховых взносов, произведенных в пользу физического лица);
- SELF_EMPLOYED (сведения о статусе самозанятого);
- VEHICLE_INFO (выписка о транспортном средстве по владельцу);
- GIBDD_DRIVER_LICENSE (сведения о водительском удостоверении, полученнном из ГИБДД).
Чтобы выбрать подходящий scope необходимо в Таблице 7 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметр raw_documents.
ВАЖНО: При запросе документа ответ может поступить не сразу, а в течении некоторого времени. Это происходит, если сведение запрошено в ведомстве, а ответ от ведомства ещё не поступил. В этом случае возвращается идентификатор этого запроса и идентификатор пользователя (oid), как в выше приведённом примере. С помощью идентификатора запроса осуществляется процесс обработки персональных данных. Для возможности получения сведения о документах необходимо обновить запрос, то есть послать исходный запрос на получение документов ещё раз.
Например, необходимо получить выписку о транспортном средстве по владельцу в исходном виде. Для этого в авторизационный запрос необходимо добавить параметр raw_documents, в котором указать scope, соответствующий указанному типу документа. В результате будет получен авторизационный запрос следующего вида:
https://demo.gate.esia.pro/auth/authorize?state=1692192660637&purposes=CREDIT&actions=ALL_ACTIONS_TO_DATA&permissions=fullname addresses birthdate drivers_licence_doc&expire=3&sysname=CREDIT&responsible_object=2&client_id=ZCgPIeDnlLv6PQVrCrIeagnHcviGq47iuTv_LmnQcyE&redirect_uri=https://ya.ru&provider=cpg_oauth&response_type=code&scope=openid&raw_documents=vehicle_reg_cert_doc
В случае успешной авторизации произойдет редирект на url следующего вида:
https://ya.ru/?code=hFGdtqdBuiGcKRQ7EHnh7aeCdkY7ZBmi3aqXo7Tw71Q&state=1692192660637
После этого необходимо обменять авторизационный код на токен доступа access_token и запросить данные.
Пример ответа в случае запроса выписки о транспортном средстве по владельцу в исходном виде:
{
"sub": "4",
"info": {
"uid": "1000482766",
"oid": "1000482766",
"firstName": "Александр",
"middleName": "Викторович",
"lastName": "Наличников",
"birthDate": "04.10.1995",
"registrationAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"homeAddress": {
"addressStr": "г Ростов-на-Дону, ул Ткацкая",
"region": "Ростовская",
"countryId": "RUS",
"house": "3",
"zipCode": "344016",
"city": "Ростов-на-Дону",
"street": "Ткацкая",
"fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
},
"trusted": true,
"documents": [
{
"oid": "1000482766",
"id": "210575",
"receiptDocDate": 1651047027853,
"relevance": "actual",
"status": "unverified",
"lastName": "Наличников",
"firstName": "Александр",
"middleName": "Викторович",
"birthDate": "04.10.1995",
"departmentDoc": "Управление ГИБДД ГУ МВД России",
"series": "2323",
"number": "232323",
"issueDate": "16.03.2022",
"expiryDate": "16.03.2032",
"type": "RF_DRIVING_LICENSE"
},
{
"oid": "1077130925",
"id": "744b21b1-5a4c-40f6-8aa2-5beb94451556",
"version": 1,
"createdOn": 1618556541315,
"updatedOn": 1618556541315,
"receiptDocDate": 1618556541315,
"validateDateDoc": 1618556541095,
"relevance": "actual",
"status": "verified_by_request",
"departmentDoc": "Управление ГИБДД ГУ МВД России",
"nameDoc": "Выписка о ТС по владельцу",
"content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjwhLS1T.....uZXJEYXRhPg0KPC9uczE6UmVzcG9uc2VCeU93bmVycz4NCg==",
"type": "VEHICLE_INFO"
}
],
"scope": [
"addresses",
"birthdate",
"drivers_licence_doc",
"vehicle_reg_cert_doc",
"fullname",
"openid"
]
}
}
Получение данных в виде PDF-, XML- документов и в виде ZIP-архива
Для получения данных о документах в виде PDF-, XML- документов и в виде ZIP-архива необходимо в специальных параметрах указать scope, соответствующие требуемым типам документов. Такими специальными парметрами являются следующие:
- pdf_documents - получение документов в виде PDF-файлов;
- file_documents - получение документов в виде ZIP-архива;
- xml_documents - получение документов в виде XML-файлов.
Сервис доступен для ограниченного набора типов документов. Перечень типов документов, которые можно запрашивать в виде PDF-, XML- документов указан в п.5.1.7, а перечень типов документов, которые можно запрашивать в виде zip-фрхива указан в п. 5.1.13 Методических рекомендаций по интеграции Цифрового профиля
Чтобы выбрать подходящий scope необходимо в Таблице 7 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметры pdf_documents, file_documents или xml_documents.
ВАЖНО: При запросе документа ответ может поступить не сразу, а в течении некоторого времени. Это происходит, если сведение запрошено в ведомстве, а ответ от ведомства ещё не поступил. В этом случае возвращается идентификатор этого запроса и идентификатор пользователя (oid), как в выше приведённом примере. С помощью идентификатора запроса осуществляется процесс обработки персональных данных. Для возможности получения сведения о документах необходимо обновить запрос, то есть послать исходный запрос на получение документов ещё раз.
Например, необходимо получить справку о доходах и суммах налога ФЛ (форма 2-НДФЛ) и справку о назначенных пенсиях и социальных выплатах в виде PDF-, XML- документов. Для этого в авторизационный запрос необходимо добавить параметры pdf_documents и xml_documents, в которых указать scope, соответствующие указанным типам документов. В результате будет получен авторизационный запрос следующего вида:
https://demo.gate.esia.pro/auth/authorize?state=1a73f168-4485-11ed-b878-0242ac120002&purposes=CREDIT&actions=ALL_ACTIONS_TO_DATA&permissions=fullname addresses birthdate drivers_licence_doc&expire=3&sysname=CREDIT&responsible_object=2&client_id=ZCgPIeDnlLv6PQVrCrIeagnHcviGq47iuTv_LmnQcyE&redirect_uri=https://ya.ru&provider=cpg_oauth&response_type=code&scope=openid&pdf_documents=ndfl_person pension_reference&xml_documents=ndfl_person pension_reference
В случае успешной авторизации произойдет редирект на url следующего вида:
https://ya.ru/?code=hFGdtqdBuiGcKRQ7EHnh7aeCdkY7ZBmi3aqXo7Tw71Q&state=1a73f168-4485-11ed-b878-0242ac120002
После этого необходимо обменять авторизационный код на токен доступа access_token и запросить данные.
Пример ответа в случае запроса справки о доходах и суммах налога ФЛ (форма 2-НДФЛ) и справки о назначенных пенсиях и социальных выплатах в виде PDF-, XML- документов:
"documents": [
{
"oid": "1077115523",
"id": "69b29ec3-38f6-4132-b1e4-ba5dfd00e1d4",
"version": 1,
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"receiptDocDate": 1590473174594,
"validateDateDoc": 1590473174578,
"relevance": "actual",
"status": "verified_by_request",
"departmentDoc": "ФНС России",
"year": "2019",
"data": [
{
"orgInfo": {
"fullName": "РОМАШКА",
"inn": "7777021812",
"kpp": "777701001"
},
"rate": "13",
"income": "639489.06",
"tax": "83134",
"files": [
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8_2.xml",
"metadata": "application/xml",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
},
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8_2.pdf",
"metadata": "application/pdf",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
}
]
},
{
"personInfo": {
"firstName": "ИГОРЬ",
"lastName": "СИДОРОВ",
"middleName": "ПЕТРОВИЧ",
"inn": "728066734016"
},
"rate": "13",
"income": "304712.30",
"tax": "39613",
"files": [
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8.xml",
"metadata": "application/xml",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
},
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8.pdf",
"metadata": "application/pdf",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
}
]
}
],
"type": "INCOME_REFERENCE"
},
{
"oid": "1078121672",
"id": "8fa4e7ef-d55b-4ee5-86a1-f8f04a177b78",
"version": 3,
"createdOn": 1628771255428,
"updatedOn": 1628771381532,
"receiptDocDate": 1628771381502,
"validateDateDoc": 1628771381502,
"relevance": "actual",
"status": "verified_by_request",
"legalForce": true,
"lastName": "Сидорова",
"firstName": "Анна",
"middleName": "Алексеевна",
"birthPlace": "Самара",
"gender": "M",
"birthDate": "04.08.1993",
"departmentDoc": "Пенсионный фонд России",
"files": [
{
"file": "JVBERi0.....DAwMCBu",
"name": "PFR_101000_SPSV_20200514_8ec61bb5_b96e_4885_ad34_5ca24dbdfd74.pdf",
"metadata": "application/pdf"
},
{
"file": "JVBERi0.....DAwMCBu",
"name": "PFR_101000_SPSV_20200514_8ec61bb5_b96e_4885_ad34_5ca24dbdfd74.xml",
"metadata": "application/xml"
},
{
"file": "JVBERi0.....DAwMCBu",
"name": "1.xml",
"metadata": "application/xml"
}
],
"divName": "МИЦ ПФР",
"docDetails": {
"dateDocDetails": "14.05.2020",
"numDocDetails": "22-05-20-0000941620"
},
"infoDate": "14.05.2020",
"insPension": {
"typePension": 1,
"periodPension": {
"fromPeriodPension": "23.12.2018",
"toPeriodPension": "бессрочно"
},
"basicPension": {
"sumBasPen": 10343.55,
"strBasPen": [
{
"typeStrBasPen": 1,
"sumStrBasPen": 362.24
},
{
"typeStrBasPen": 2,
"sumStrBasPen": 0
}
]
},
"wrkPension": {
"sumWrkPen": 9063.4,
"strWrkPen": [
{
"typeStrWrkPen": 1,
"sumStrWrkPen": 317.4
},
{
"typeStrWrkPen": 2,
"sumStrWrkPen": 0
}
]
}
},
"fixToPension": {
"fixToBasPen": {
"typeFixToBasPen": 1,
"sumFixToBasPen": 5686.25
},
"fixToWrkPen": {
"typeFixToWrkPen": 1,
"sumFixToWrkPen": 4982.9
}
},
"wrkExperience": {
"insExperience": {
"totalInsExp": {
"yearsInsExperience": 35,
"monthsInsExperience": 2,
"daysInsExperience": 13
},
"farNorth": {}
}
},
"docName": 1,
"type": "PENSION_REFERENCE"
},
{
"oid": "1077115523",
"id": "69b29ec3-38f6-4132-b1e4-ba5dfd00e1d4",
"version": 1,
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"receiptDocDate": 1590473174594,
"validateDateDoc": 1590473174578,
"relevance": "actual",
"status": "verified_by_request",
"departmentDoc": "ФНС России",
"year": "2019",
"data": [
{
"orgInfo": {
"fullName": "РОМАШКА",
"inn": "7777021812",
"kpp": "777701001"
},
"rate": "13",
"income": "639489.06",
"tax": "83134",
"files": [
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8_2.xml",
"metadata": "application/xml",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
},
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8_2.pdf",
"metadata": "application/pdf",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
}
]
},
{
"personInfo": {
"firstName": "ИГОРЬ",
"lastName": "СИДОРОВ",
"middleName": "ПЕТРОВИЧ",
"inn": "728066734016"
},
"rate": "13",
"income": "304712.30",
"tax": "39613",
"files": [
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8.xml",
"metadata": "application/xml",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
},
{
"createdOn": 1590473174594,
"updatedOn": 1590473174594,
"file": "JVBERi0.....DAwMCBu",
"name": "epgu_2ndfl_20200428_a70844e3-892a-11ea-9715-001a4a1662e8.pdf",
"metadata": "application/pdf",
"sign": "MIIK/AYJKo.....ZPRkBAVQ="
}
]
}
],
"type": "INCOME_REFERENCE"
},
{
"oid": "1078121672",
"id": "8fa4e7ef-d55b-4ee5-86a1-f8f04a177b78",
"version": 3,
"createdOn": 1628771255428,
"updatedOn": 1628771381532,
"receiptDocDate": 1628771381502,
"validateDateDoc": 1628771381502,
"relevance": "actual",
"status": "verified_by_request",
"legalForce": true,
"lastName": "Сидорова",
"firstName": "Анна",
"middleName": "Алексеевна",
"birthPlace": "Самара",
"gender": "M",
"birthDate": "04.08.1993",
"departmentDoc": "Пенсионный фонд России",
"files": [
{
"file": "JVBERi0.....DAwMCBu",
"name": "PFR_101000_SPSV_20200514_8ec61bb5_b96e_4885_ad34_5ca24dbdfd74.pdf",
"metadata": "application/pdf"
},
{
"file": "JVBERi0.....DAwMCBu",
"name": "PFR_101000_SPSV_20200514_8ec61bb5_b96e_4885_ad34_5ca24dbdfd74.xml",
"metadata": "application/xml"
}
],
"divName": "МИЦ ПФР",
"docDetails": {
"dateDocDetails": "14.05.2020",
"numDocDetails": "22-05-20-0000941620"
},
"infoDate": "14.05.2020",
"insPension": {
"typePension": 1,
"periodPension": {
"fromPeriodPension": "23.12.2018",
"toPeriodPension": "бессрочно"
},
"basicPension": {
"sumBasPen": 10343.55,
"strBasPen": [
{
"typeStrBasPen": 1,
"sumStrBasPen": 362.24
},
{
"typeStrBasPen": 2,
"sumStrBasPen": 0
}
]
},
"wrkPension": {
"sumWrkPen": 9063.4,
"strWrkPen": [
{
"typeStrWrkPen": 1,
"sumStrWrkPen": 317.4
},
{
"typeStrWrkPen": 2,
"sumStrWrkPen": 0
}
]
}
},
"fixToPension": {
"fixToBasPen": {
"typeFixToBasPen": 1,
"sumFixToBasPen": 5686.25
},
"fixToWrkPen": {
"typeFixToWrkPen": 1,
"sumFixToWrkPen": 4982.9
}
},
"wrkExperience": {
"insExperience": {
"totalInsExp": {
"yearsInsExperience": 35,
"monthsInsExperience": 2,
"daysInsExperience": 13
},
"farNorth": {}
}
},
"docName": 1,
"type": "PENSION_REFERENCE"
}
]
Получение данных только по части скоупов
ЕСИА Шлюз позволяет запросить данные гражданина только по части скоупов. Для этого во время запроса данных необходимо перечислить скоупы, доступ к которым был ранее получен на этапе авторизации.
/auth/userinfo
Заголовки:
- Authorization - заголовок включающий в себя данные для проверки подлинности.
Параметры:
- permissions - перечень scope запрашиваемых в рамках типов согласий;
- raw_documents - перечень scope, для которых будет выполняться запрос документов в исходном виде. Перечень типов документов, которые можно запрашивать в исходном виде указан в п. 5.1.8 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- xml_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в xml виде указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- pdf_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в pdf виде указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- file_documents - перечень scope, для которых будет выполняться запрос документов в виде файлов. Перечень типов документов, которые можно запрашивать в zip виде указан в п. 5.1.13 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр/
- ext_documents - перечень scope, для которых будет выполняться запрос перечня ссылок на файлы, полученные от ведомства, детализирующие документы определённого типа. Перечень типов документов, для которых можно запрашивать перечень ссылок указан в п. 5.1.10 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр.
- permission_types - при запросе нескольких типов согласий, вышеуказанные cpg_oauth параметры отправляются в списке объектов. Необязательный параметр.
Пример POST запроса на получение части данных:
curl -X POST https://demo.gate.esia.pro/auth/userinfo --data "permissions=fullname" -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw"
На основе полученного токена доступа шлюз предоставляет клиентским системам доступ к областям данных из защищённого хранилища ЕСИА.
Пример ответа в случае запроса fullname из защищённого хранилища ЕСИА:
{
"sub": "4",
"info": {
"uid": "1000482766",
"oid": "1000482766",
"firstName": "Александр",
"middleName": "Викторович",
"lastName": "Наличников",
"snils": "159-756-279 05",
"inn": "330077654542",
"gender": "M",
"birthDate": "04.10.1995",
"birthPlace": "Дом",
"email": "wsdlfkj@yandex.ru",
"mobilePhone": "+7(999)5675677",
"trusted": true,
"documents": [],
"scope": [
"birthplace",
"gender",
"mobile",
"email",
"openid",
"fullname",
"addresses",
"inn",
"snils",
"birthdate"
]
}
}
Получение согласий пользователя из Цифрового профиля
/auth/user_permissions
Заголовки:
- Authorization - заголовок включающий в себя данные для проверки подлинности.
Для получения данных отправляется GET или POST запрос на url:
https://demo.gate.esia.pro/auth/user_permissions
со следующими заголовками запроса:
- Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ
Пример запроса на получение данных:
curl -X GET https://demo.gate.esia.pro/auth/user_permissions -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ"
На основе полученного токена доступа шлюз предоставляет список всех согласий пользователя, выданных клиентской системе.
Пример ответа в случае запроса списка выданных согласий при взаимодействии с REST API платформы согласий:
{
"elements": [
{
"stateFacts": [
"Identifiable"
],
"id": 74273,
"personId": 7597001,
"orgId": 7413897,
"permissionId": 1,
"sysname": "CREDIT",
"name": "Предоставление кредита (займа)",
"description": "Предоставление кредита (займа), в том числе кредита с лимитом кредитования и (или) овердрафта, выпуск и обслуживание банковской карты для обслуживания кредита (займа)",
"orgShortName": "ОРГАНИЗАЦИЯ 1181280564",
"ogrn": "2000000000002",
"orgAddress": "127434, Город Москва,Улица Дубки",
"issuedOn": 1691763799,
"expiredOn": 1691764699,
"status": "A",
"createdOn": 1691763799,
"updatedOn": 1691763799,
"signatureId": "78efb45b-21a8-48c2-af48-bbada3eebff1",
"signatureStatus": "ISSUED",
"scopes": {
"stateFacts": [
"hasSize"
],
"size": 9,
"elements": [
{
"stateFacts": [
"ReadOnly"
],
"sysname": "fullname",
"name": "Просмотр вашей фамилии, имени и отчества",
"description": "Фамилия, имя и отчество, указанные в документе, удостоверяющем личность",
"orgGroup": "Министерство внутренних дел Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "birthdate",
"name": "Просмотр даты вашего рождения",
"description": "Дата рождения, указанная в документе, удостоверяющем личность",
"orgGroup": "Министерство внутренних дел Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "birthplace",
"name": "Просмотр вашего места рождения",
"description": "Место рождения, указанное в документе, удостоверяющем личность",
"orgGroup": "Министерство внутренних дел Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "gender",
"name": "Просмотр вашего пола",
"description": "Пол гражданина",
"orgGroup": "Министерство внутренних дел Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "snils",
"name": "Просмотр вашего СНИЛС",
"description": "Страховой номер индивидуального лицевого счета (СНИЛС) застрахованного лица",
"orgGroup": "Пенсионный фонд Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "inn",
"name": "Просмотр вашего ИНН",
"description": "Идентификационный номер налогоплательщика (физического лица)",
"orgGroup": "Федеральная налоговая служба Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "addresses",
"name": "Проосмотр ваших ваших адреса регистрации и адреса проживания",
"description": "Сведения о регистрации гражданина по месту жительства или месту пребывания (снятии с регистрационного учета)",
"orgGroup": "Министерство внутренних дел Российской Федерации"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "mobile",
"name": "Просмотр номера вашего мобильного телефона",
"description": "Номер мобильного телефона (физического лица)"
},
{
"stateFacts": [
"ReadOnly"
],
"sysname": "email",
"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": "Обработка персональных данных, включая сбор, запись, систематизацию, накопление, хранение, уточнение, извлечение, использование, передачу, обезличивание, блокирование, удаление, уничтожение персональных данных"
}
]
}
}
]
}
Выход из системы ЕСИА
/auth/logout
Параметры:
- client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиентской системы на стороне шлюза;
- redirect_uri=https://ya.ru – путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь;
- state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Должен отличаться от набора, использованного для получения авторизационного кода. Необходим для предотвращения CSRF атак.
Для инициации процесса выхода из системы ЕСИА необходимо сформировать запрос и передать его на соответствующий URL шлюза. Для клиентской системы с вышеуказанными параметрами запрос будет иметь следующий вид:
curl https://demo.gate.esia.pro/auth/logout?client_id=a4fb804bfdf54df4f4da7faae24375e6&redirect_uri=https://ya.ru
После завершения сессии в системе ЕСИА пользователь будет перенаправлен на адрес, указанный в параметре redirect_uri.
ВАЖНО! Путь возврата пользователя обязательно должен быть указан в соответствующей КИС
Также, на технологическом портале тестовой/промышленной ЕСИА, в настройках ИС, необходимо добавить url, соответствующий точке возврата в шлюз после логаута на стороне ЕСИА.
Такой URL в данном случае будет иметь следующий вид:
https://demo.gate.esia.pro/auth/esia_oauth/logout_callback