Взаимодействие со шлюзом в рамках ЦПГ HTTP API (неактуально)
Настоящий раздел содержит описание HTTP API для взаимодействия с цифровым профилем гражданина (ЦПГ). Данное API постепенно выводится из эксплуатации, в связи с чем не рекомендуется к использованию новым клиентам. Раздел сохранён исключительно в справочных целях для клиентов, уже использующих ЦПГ HTTP API в своих информационных системах. Новым клиентам необходимо использовать коммерческое ЦПГ HTTP API, а действующим клиентам следует осуществить переход на него в ближайшее время.
В данном разделе приводится пошаговое взаимодействие клиентской системы и шлюза, доступного по адресу https://gate.esia.pro/. В качестве клиентской ИС рассматривается система с идентификатором a4fb804bfdf54df4f4da7faae24375e6, секретом 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 и путем возврата https://ya.ru.
Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и ЦПГ
ЕСИА Шлюз не хранит персональные данные пользователей в базе данных. Передача персональных данных пользователя происходит через защищённый по HTTPS канал связи.
ЕСИА Шлюз хранит только транспортную информацию (scopes, redirect_uri, время запроса, авторизационный код ЕСИА) и SHA-512 от ФИО и СНИЛСа пользователя. Эти данные необходимы для обработки внештатных ситуаций, таких как составление заявки в службу поддержки ЕСИА и реагирование на запросы правоохранительных органов, и не являются персональными данными.
Авторизация (Получение авторизационного кода)
/auth/authorize
Параметры:
- client_id — идентификатор клиентской системы на стороне шлюза;
- response_type — тип ответа (допустимое значение
code); - provider — наименование провайдера данных (допустимое значение
cpg_oauth); - scope — набор областей доступа (допустимое значение
openid); - redirect_uri — путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь после авторизации со стороны ЕСИА (должен полностью совпадать с URL возврата, указанным в настройках системы на стороне шлюза);
- state — набор случайных символов, имеющий вид 128-битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения CSRF-атак;
- nonce — набор случайных символов, имеющий вид 128-битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения подделки токена идентификации;
- person_filter — необязательный параметр, позволяющий производить авторизацию только для определённых групп лиц. Значение необходимо передавать в обычном виде, без кодирования в Base64:
- для авторизации только подтверждённых учётных записей в параметре необходимо передать
conf_acc; - для авторизации только учётных записей детей в параметре необходимо передать
acc_kid; - для авторизации всех учётных записей, кроме учётных записей детей, в параметре необходимо передать
acc_not_kid; - для авторизации только подтверждённых учётных записей или учётных записей детей в параметре необходимо передать комбинацию из
conf_accиacc_kid(т. е.person_filter=conf_acc%20acc_kid).
- для авторизации только подтверждённых учётных записей в параметре необходимо передать
- следующие параметры указываются в запросе только в случае наличия значения cpg_oauth для параметра provider:
- permissions — перечень scope, запрашиваемых в рамках типов согласий;
- purposes — мнемоники целей. Список допустимых значений указан в таблице 2 “Реестр целей” в Сценарии использования инфраструктуры Цифрового профиля;
- sysname — мнемоника типа согласия. Список допустимых значений указан в таблице 1 “Реестр типов согласий” в Сценарии использования инфраструктуры Цифрового профиля;
- actions — мнемоника действия. Список допустимых значений указан в таблице 3 “Реестр действий” в Сценарии использования инфраструктуры Цифрового профиля;
- responsible_object — определяет лицо или организацию, от чьего имени осуществляется обработка данных (строка с ФИО или другой информацией — на усмотрение организации, запрашивающей согласие). Необязательный параметр;
- expire — срок, на который будет выдано согласие после утверждения (в минутах);
- raw_documents — перечень scope, для которых будет выполняться запрос документов в исходном виде. Перечень типов документов, которые можно запрашивать в исходном виде, указан в п. 5.1.8 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- xml_documents — перечень scope, для которых будет выполняться запрос документов в виде XML-файлов. Перечень типов документов, которые можно запрашивать в виде XML-файлов, указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- pdf_documents — перечень scope, для которых будет выполняться запрос документов в виде PDF-файлов. Перечень типов документов, которые можно запрашивать в виде PDF-файлов, указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- file_documents — перечень scope, для которых будет выполняться запрос документов в виде ZIP-архива. Перечень типов документов, которые можно запрашивать в виде ZIP-архива, указан в п. 5.1.13 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- ext_documents — перечень scope, для которых будет выполняться запрос перечня ссылок на файлы, полученные от ведомства, детализирующие документы определённого типа. Перечень типов документов, для которых можно запрашивать перечень ссылок, указан в п. 5.1.10 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- permission_types — при запросе нескольких типов согласий, вышеуказанные cpg_oauth параметры отправляются в списке объектов. Необязательный параметр.
Тестирование
Для каждого scope в permissions, raw_documents, xml_documents, pdf_documents, file_documents, ext_documents при использовании тестовой ЕСИА можно задать вариант возвращаемого ответа. Список допустимых вариантов можно посмотреть в п. 5.3 в Методических рекомендациях по интеграции Цифрового профиля.
Чтобы указать, какой вариант тестового ответа нужен для конкретного scope, добавьте после имени scope двоеточие и номер ответа:
https://gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6&response_type=code&scope=openid&redirect_uri=https://ya.ru&provider=cpg_oauth&permissions=ils_doc%3A3+reg_realestate%3A2&file_documents=reg_realestate%3A2&xml_documents=pension_reference%3A2&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
ils_doc%3A3 — для ils_doc будет выбран тип ответа №3 (%3A — URL-кодировка двоеточия).
Примеры
Для инициации процесса получения доступа к цифровому профилю гражданина и платформе согласий необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. При этом в запросе необходимо:
- значение параметра provider установить в
cpg_oauth; - в параметре scope указать
openid; - указать обязательные параметры
permissions,purposes(например, CREDIT из Сценариев использования инфраструктуры Цифрового профиля),sysname(CREDIT из Сценариев использования инфраструктуры Цифрового профиля),actions(ALL_ACTIONS_TO_DATA),expire(3); - при необходимости, указать опциональный параметр
responsible_object(Иванов Иван Иванович).
Для клиентской системы с вышеуказанными параметрами авторизационный запрос будет иметь следующий вид:
https://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://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://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 — путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь. Должен совпадать с URL возврата, указанным при получении авторизационного кода;
- client_id — идентификатор клиентской системы на стороне шлюза;
- code — авторизационный код;
- client_secret — секрет клиентской системы на стороне шлюза.
На предыдущем шаге после успешной авторизации в ЕСИА был получен авторизационный код, который следует обменять на токен доступа (access_token) для его последующего использования при получении пользовательских данных. Один код можно обменять только на один токен. Для этого отправляется POST-запрос на URL:
https://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://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://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://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://gate.esia.pro/auth/userinfo
со следующими заголовками запроса:
- Authorization: Bearer [access_token]
Пример запроса на получение данных:
curl -X POST https://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, необходимо в Таблице 8 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть, какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметр permissions авторизационного запроса, формирование которого описано выше.
Например, необходимо получить паспорт гражданина РФ и свидетельство о рождении. Для этого необходимо в Таблице 8 документа Сценарии использования инфраструктуры Цифрового профиля по мнемонике типа документа (RF_PASSPORT и FID_BRTH_CERT соответственно) или названию типа документа (Паспорт гражданина РФ и Свидетельство о рождении – другая страна) определить перечень необходимых scope. В данном случае такими scope являются id_doc, birth_cert_doc. Их и нужно добавить в параметр permissions авторизационного запроса. В результате будет получен следующий запрос:
https://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, необходимо в Таблице 8 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть, какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметр raw_documents.
ВАЖНО! При запросе документа ответ может поступить не сразу, а в течение некоторого времени. Это происходит, если сведение запрошено в ведомстве, а ответ от ведомства ещё не поступил. В этом случае возвращается идентификатор этого запроса и идентификатор пользователя (oid), как в приведённом выше примере. С помощью идентификатора запроса осуществляется процесс обработки персональных данных. Для возможности получения сведения о документах необходимо обновить запрос, то есть послать исходный запрос на получение документов ещё раз.
Например, необходимо получить выписку о транспортном средстве по владельцу в исходном виде. Для этого в авторизационный запрос необходимо добавить параметр raw_documents, в котором указать scope, соответствующий указанному типу документа. В результате будет получен авторизационный запрос следующего вида:
https://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, необходимо в Таблице 8 документа Сценарии использования инфраструктуры Цифрового профиля, содержащей типы документов пользователя, найти нужную мнемонику типа документа и в столбце Требуемая область доступа (scope) для получения данных документа посмотреть, какой(ие) скоуп(ы) нужны для получения этого документа. Эти scope и нужно добавить в параметры pdf_documents, file_documents или xml_documents.
ВАЖНО! При запросе документа ответ может поступить не сразу, а в течение некоторого времени. Это происходит, если сведение запрошено в ведомстве, а ответ от ведомства ещё не поступил. В этом случае возвращается идентификатор этого запроса и идентификатор пользователя (oid), как в приведённом выше примере. С помощью идентификатора запроса осуществляется процесс обработки персональных данных. Для возможности получения сведения о документах необходимо обновить запрос, то есть послать исходный запрос на получение документов ещё раз.
Например, необходимо получить справку о доходах и суммах налога ФЛ (форма 2-НДФЛ) и справку о назначенных пенсиях и социальных выплатах в виде PDF- и XML-документов. Для этого в авторизационный запрос необходимо добавить параметры pdf_documents и xml_documents, в которых указать scope, соответствующие указанным типам документов. В результате будет получен авторизационный запрос следующего вида:
https://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-файлов. Перечень типов документов, которые можно запрашивать в виде XML-файлов, указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- pdf_documents — перечень scope, для которых будет выполняться запрос документов в виде PDF-файлов. Перечень типов документов, которые можно запрашивать в виде PDF-файлов, указан в п. 5.1.7 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- file_documents — перечень scope, для которых будет выполняться запрос документов в виде ZIP-архива. Перечень типов документов, которые можно запрашивать в виде ZIP-архива, указан в п. 5.1.13 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- ext_documents — перечень scope, для которых будет выполняться запрос перечня ссылок на файлы, полученные от ведомства, детализирующие документы определённого типа. Перечень типов документов, для которых можно запрашивать перечень ссылок, указан в п. 5.1.10 в Методических рекомендациях по интеграции Цифрового профиля. Необязательный параметр;
- permission_types — при запросе нескольких типов согласий, вышеуказанные cpg_oauth параметры отправляются в списке объектов. Необязательный параметр.
Пример POST-запроса на получение части данных:
curl -X POST https://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://gate.esia.pro/auth/user_permissions
со следующими заголовками запроса:
- Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ
Пример запроса на получение данных:
curl -X GET https://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://gate.esia.pro/auth/logout?client_id=a4fb804bfdf54df4f4da7faae24375e6&redirect_uri=https://ya.ru
После завершения сессии в системе ЕСИА пользователь будет перенаправлен на адрес, указанный в параметре redirect_uri.
ВАЖНО! Путь возврата пользователя обязательно должен быть указан в соответствующей КИС.
Также на технологическом портале тестовой/промышленной ЕСИА, в настройках ИС, необходимо добавить URL, соответствующий точке возврата в шлюз после логаута на стороне ЕСИА.
Такой URL в данном случае будет иметь следующий вид:
https://gate.esia.pro/auth/esia_oauth/logout_callback