Взаимодействие со шлюзом в рамках СМЭВ HTTP API

В данном разделе приводится пошаговое взаимодействие клиентской системы и шлюза, по адресу https://demo.gate.esia.pro/. В качестве клиентской ИС рассматривается система с идентификатором a4fb804bfdf54df4f4da7faae24375e6, секретом 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 и путями возврата (https://ya.ru, https://ya.ru/userinfo/callback

Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и СМЭВ

Схема процесса взаимодействия

ЕСИА Шлюз хранит так же транспортную информацию (scopes, redirect_uri, время запроса, авторизационный код ЕСИА) и SHA-512 от ФИО и СНИЛСа пользователя. Эти данные необходимы для обработки внештатных ситуаций, таких как составление заявки в службу поддержки ЕСИА и реагирование на запросы правоохранительных органов и не являются персональными данными.

Авторизация (Получение авторизационного кода)

/auth/authorize

Параметры:

  • client_id - идентификатор клиентской системы на стороне шлюза;
  • response_type - тип ответа (допустимое значение code);
  • provider - наименование провайдера данных (в рамках взаимодействия со СМЭВ нужно указать smev_oauth);
  • scope - набор областей доступа:
    • для provider=smev_oauth допустимое значение openid;
  • redirect_uri - путь возврата индивидуален для конкретного клиента, на который будет перенаправлен пользователь после авторизации со стороны ЕСИА (должен полностью совпадать с URL возврата, указанным в настройках системы на стороне шлюза);
  • state - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения CSRF атак;
  • nonce - набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Необходим для предотвращения подделки токена идентификации;
  • person_filter - необязательный параметр, позволяющий производить авторизацию только для определенных групп лиц, перечень значений можно найти в https://adm.digital.gov.ru/app/uploads. Значение передавать в обычном виде, без кодирования в Base64;
  • следующие параметры указываются в запросе только в случае наличия значения smev_oauth для параметра provider:

Параметры raw_documents, xml_documents, pdf_documents, file_documents, ext_documents оставлены для совместимости с запросом в ЦПГ. На данный момент они не влияют на формат ответа из СМЭВ. Работа с ними может быть пересмотрена.

Примеры

Для инициации процесса получения доступа к цифровому профилю гражданина и платформе согласий необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. При этом в запросе необходимо:

  • значение параметра provider установить в smev_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=smev_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=smev_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=smev_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://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": 600,
  "refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
  "scope": "openid",
  "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 и smev_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": 600,
  "refresh_token": "GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM",
  "scope": "openid",
  "created_at": 1678856341,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkpzcTc4bnhUR01OSFZFc1YwVEdYOEFaSlA0V1lQSEFWUE9URmt4bnk1aTgifQ.eyJpc3MiOiJsb2NhbGhvc3Q6MzAwMCIsInN1YiI6IjMiLCJhdWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwiZXhwIjoxNjQ0MjQyNzIwLCJpYXQiOjE2NDQyNDI2MDB9.asAZd5wwjvh0NIP7FPRUWLV0Ivh-_-wXJ4skS3eYH7TOfPgTO5sUN5jp234QI2D5Zbt0kB0zADgAl1TWigT-6NTNaZQSeVhUlofOH49dONWKzUL5NXlhuOOn938tk54RMXFK66Bw8tPEIdM8smo7VwRLTQhF5cfrLYyv7xDRYXa-KtKNC72mh8PtDwoIEE5Apj8O98fxAvh0n2SBDJlfYiwJBAi3tXahiyH_-ElB0agI_6TrqQafyjJHVL9iz6GgghEPvU-0616CRbqgbMo3RxbCATEnnOFup6DCs1448Ll_9Uh-xWQiQvZ2uho_ICjQqspPb3ZakmjoZgFZ3GVgDg"
}

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

/auth/userinfo

Заголовки:

  • Authorization - заголовок включающий в себя данные для проверки подлинности.

Параметры:

  • redirect_uri - путь возврата данных из СМЭВ.

Для получения данных отправляется POST запрос на url:

https://demo.gate.esia.pro/auth/userinfo

со следующими параметрами запроса:

  • redirect_uri=https://ya.ru/userinfo/callback - путь возврата данных из СМЭВ.

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

  • Authorization: Bearer [access_token]

Пример запроса на получение данных:

curl -X POST https://demo.gate.esia.pro/auth/userinfo?redirect_uri=https://ya.ru/userinfo/callback -H "Authorization: Bearer eyJraWQiOiJGMGZhSE0yeHVic0pobXRSYmJmN1c1bzFGV1hpTTFLQ3JTRmZVV1Y0SmlNIiwidHlwIjoiSldUIiwic2J0IjoiYWNjZXNzIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJFc2lhLnBybyIsImlhdCI6MTY0NDI0MjYwMCwianRpIjoiNTFhZDU3MWQtMzBlOS00MjAwLWI2YjItOWVkOTdjOTFiM2UyIiwidXNlciI6eyJpZCI6MywidWlkIjoiMTAwMDQ4NjQ0NiIsImVzaWFfdG9rZW4iOiJleUoyWlhJaU9qRXNJblI1Y0NJNklrcFhWQ0lzSW5OaWRDSTZJbUZqWTJWemN5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnVZbVlpT2pFMk5EUXlOREkxTmpJc0luTmpiM0JsSWpvaVpuVnNiRzVoYldVX2IybGtQVEV3TURBME9EWTBORFlnYjNCbGJtbGtJaXdpYVhOeklqb2lhSFIwY0RwY0wxd3ZaWE5wWVMxd2IzSjBZV3d4TG5SbGMzUXVaMjl6ZFhOc2RXZHBMbkoxWEM4aUxDSjFjbTQ2WlhOcFlUcHphV1FpT2lKaE4yWm1NR1E1TlMwMVpHWTBMVFJqTVdFdFlqVTROQzAxTXpKa1pXUTBOV0psTVRZaUxDSjFjbTQ2WlhOcFlUcHpZbXBmYVdRaU9qRXdNREEwT0RZME5EWXNJbVY0Y0NJNk1UWTBOREkwTXpFMk1pd2lhV0YwSWpveE5qUTBNalF5TlRZeUxDSmpiR2xsYm5SZmFXUWlPaUl5TlRBMU1ERWlmUS50YlMyUHltUVd3TXhtM0phOWZlWmNWV0ZUSnJpNWFBd2M4VTJjek1McVduVDhxdUFUN2RXUEEzTlVGMHR6REJBQ3hQVXAwa2N2dzAxalluX0lpWEpxN1VFQVBQTnVQcGhjNnl6VkgyWXpmVkd4bDEwUzYwc1BHSGs4Mk5mVnVhdHVKQ0hpWkZtNzhSUmZhZEZVNXVxN0FQdkpYeTdUMDFFN1ItM0Mza1RrQWFYNExmaFVMTjF3cDJyYkVQQUpSRTJtdGw3WTdIR195YXdvTkNhMGJaNDlxWUFRN2hUUXNOWVNHd3hXNUZvQTZtM2lDOUp3VFA0Q21fTklHd1lhWTUtX0JnOXU1a2xKYU84aUZha2FXakl1ckNWWURNNm1nZ0ZwUmtuLUs4VU9VNkhraG5ydVV6TXQ5N1c3Z1lHell2WjJZR1dZY0hhZ2VYZVBaM1NqYkloMEEiLCJlYnNfc2Vzc2lvbl9pZCI6bnVsbH0sImNpX3N5c3RlbSI6eyJpZCI6M319.sHqzx-2BHrq2pu6MgsAQYdOFoqQGwHLkevHZB5IqPwrQdovwjjHfOu6R6iNYIflmQKxRThsM3DOblZcjmvZq8VXWtrTPC-GkQnXklwPnqZ22jMS_UF8fIOUtKOlKVShmrAmUInrPQ0S-RvFWdpP7tudFiePR-GfukgEtVTosIHaMO1K3x55ON5aTix0i9UEYERon0IJ0rX0vF3NibBkOgHqTmPGni5eFMdgKPy1W8jEWu0OS-IIN495cSTq3WMSiY899A8ZkowNBJTdD61XSBS2n-vGL0kM2yrRBx9KKcfCIelj8p1GDHR09KY-YmBJ8o1-nAPPHKa4Xd693VwdDVw"

На основе полученного токена доступа Шлюз отправит запрос в СМЭВ по виду сведений "Запрос персональных данных пользователя ЕСИА при наличии его согласия" и вернет КИС ответ с уникальным идентификатором Шлюза для запроса в СМЭВ.

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

В случае успешной отправки запроса в СМЭВ Шлюз вернет идентификатор запроса:

{
  "ticket_id": "gosmev-ticket-f7e17168-bb4c-4db1-841b-477bb9a8f02a"
}

В случае возникновения ошибок будет получен ответ вида:

{
  "error": "invalid_token",
  "error_description": "Неверный токен доступа"
}

Обработка callback-а Шлюзом при получении ответа из СМЭВ

После получения ответа из СМЭВ шлюз обрабатывает XML: извлекает файлы из архива и преобразует структуру ответа в удобный для дальнейшего использования формат. По завершении обработки шлюз отправляет POST-запрос на указанный redirect_uri, переданный при инициировании запроса на получение данных пользователя.

Структура финального ответа

Параметр Обязательный Описание Пример
ticket_id да Идентификатор запроса в СМЭВ gosmev-ticket-f7e17168-bb4c-4db1-841b-477bb9a8f02a
info да (при успешном ответе) Объект с персональными данными и документами пользователя См. описание поля ниже
provider_id да (при успешном ответе) Идентификатор сообщения в СМЭВ 94e3c70c-1e1f-11f1-879d-16dff30dd83d
scope да Массив запрошенных scope ["fullname", "birthdate"]
error да (при ошибке) Код ошибки unexpected_error
error_description да (при ошибке) Описание ошибки Отправитель сообщения не зарегистрирован

Структура поля info

Поле info содержит два вида данных: персональные данные и документы.

Персональные данные (когда статус SUCCEEDED)

Для следующих scope-ов данные попадают в плоскую структуру info:

Scope Описание Пример
fullname Фамилия, имя, отчество { "firstName": "Александр", "middleName": "Викторович", "lastName": "Наличников" }
birthdate Дата рождения "04.10.1995"
birthplace Место рождения "г. Москва"
gender Пол "M" или "F"
snils СНИЛС "159-756-279 05"
inn ИНН "330077654542"
registrationAddress Адрес регистрации структура адреса ниже
homeAddress Адрес проживания структура адреса ниже
mobile Номер мобильного телефона "+7(999)5675677"
email Адрес электронной почты "user@example.com"

Адреса представлены объектом:

{
  "addressStr": "г Ростов-на-Дону, ул Ткацкая, д. 3",
  "region": "Ростовская",
  "countryId": "RUS",
  "house": "3",
  "zipCode": "344016",
  "city": "Ростов-на-Дону",
  "street": "Ткацкая",
  "fiasCode": "0482362b-51ca-4193-89fd-0edbca514c66"
}
Документы info.documents

Каждый документ представлен объектом:

Параметр Обязательный Описание Пример
type при валидном ответе Тип документа (см. примеры ниже) "RF_PASSPORT"
status при SUCCEEDED Статус обработки документа "verified_by_request"
oid при PROCESSING Идентификатор пользователя "1000482766"
requestId при PROCESSING Идентификатор запроса документа "116850525746"
errorStatusInfo при FAULT Информация об ошибке структура ниже
files при наличии файлов Массив файлов с base64-содержимым структура ниже

XML документы, которые имеют ключи на латинице будут встроены в ответ с фильтрации всех xml-namespace. Схемы ответов по всем scope можно найти в документации по виду сведений "Запрос персональных данных пользователя ЕСИА при наличии его согласия".

Типы документов (data_type из СМЭВ):

Код документа Название
RF_PASSPORT Паспорт гражданина РФ
FRGN_PASS Заграничный паспорт
RF_DRIVING_LICENSE Водительское удостоверение
ILS_PFR Сведения о состоянии ИСС
INCOME_REFERENCE Справка 2-НДФЛ
ELECTRONIC_WORKBOOK Электронная трудовая
…  

Полный список типов документов можно найти в документации по виду сведений "Запрос персональных данных пользователя ЕСИА при наличии его согласия".

Структура errorStatusInfo:

{
  "code": "ESIA-035000",
  "message": "Пользователь не найден"
}

Структура files:

{
  "file": "JVBERi0xLjYK...9GCg==",
  "name": "PFR_777000_SZI-ILS_20260116_a570b736-f2c2-11f0-9df2-5ea1d225dce6.pdf",
  "metadata": "application/pdf",
  "sign": "MIIE...ABAgM=" 
}

Примеры ответов

Успешное получение персональных данных и документов

{
  "ticket_id": "gosmev-ticket-9d04abcf-35bf-45cc-8cdd-5a85aeb09bf8",
  "info": {
    "firstName": "Александр",
    "middleName": "Викторович",
    "lastName": "Наличников",
    "snils": "159-756-279 05",
    "inn": "330077654542",
    "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"
    },
    "documents": [
      {
        "type": "RF_PASSPORT",
        "status": "verified_by_validate",
        "receiptDocDate": "1614526986650",
        "validateDateDoc": "1614526986000",
        "baseDoc": {
          "series": "4712",
          "number": "720101",
          "issued": "12.04.2008"
        },
        "issuedBy": "ОТДЕЛЕНИЕМ УФМС РОССИИ ПО ЭНСКОМУ КРАЮ В ГОРОДЕ ЭНСКЕ",
        "issueId": "485024",
        "files": [
          {
            "file": "PD94bWwgdmVy...0Pgo=",
            "name": "RF_PASSPORT_edd0efa7-ab22-4801-8dd6-a8ffd90f96ed.xml",
            "metadata": "application/xml"
          }
        ]
      },
      {
        "type": "ILS_PFR",
        "status": "verified_by_request",
        "receiptDocDate": "1768644838273",
        "validateDateDoc": "1768644838273",
        "files": [
          {
            "file": "JVBERi0xLjYK...9GCg==",
            "name": "PFR_777000_SZI-ILS_20260117_b81e1c6f-f366-11f0-bd40-5ea6041d7ea7.pdf",
            "metadata": "application/pdf"
          },
          {
            "file": "PD94bWwgdmVyc...CgPg==",
            "name": "PFR_777000_SZI-ILS_20260117_b81e1c6f-f366-11f0-bd40-5ea6041d7ea7.xml",
            "metadata": "application/xml"
          }
        ]
      },
      {
        "type": "ELECTRONIC_WORKBOOK",
        "requestId": "116850525746",
        "oid": "1094980461"
      }
    ]
  },
  "provider_id": "94e3c70c-1e1f-11f1-879d-16dff30dd83d",
  "scope": [
    "fullname",
    "birthdate",
    "snils",
    "inn",
    "id_doc",
    "ils_doc",
    "electronic_workbook"
  ]
}

Статус PROCESSING (документ отсутствует в СМЭВ)

{
  "ticket_id": "gosmev-ticket-abc123",
  "info": {
    "documents": [
      {
        "type": "PENSION_REFERENCE",
        "requestId": "6242357477",
        "oid": "1063913797"
      }
    ]
  },
  "provider_id": "7475b0c9-13b0-11f1-9c51-82ae8eff723c",
  "scope": ["pension_reference"]
}

Описание: Документ запрашивается в ведомстве. Необходимо совершить повторный запрос по этому scope позже.

Статус FAULT (ошибка обработки документа)

{
  "ticket_id": "gosmev-ticket-1d77321d-56f7-4fd9-8c68-83ab5c003078",
  "info": {
    "documents": [
      {
        "type": "PENSION_REFERENCE",
        "errorStatusInfo": {
          "code": "ESIA-201584",
          "message": "Отсутствует актуальное согласие пользователя на передачу персональных данных указанного типа"
        }
      }
    ]
  },
  "provider_id": "7475b0c9-13b0-11f1-9c51-82ae8eff723c",
  "scope": ["pension_reference"]
}

Непредвиденная ошибка

Данный ответ может возникнуть, если от СМЭВ пришла ошибка в виде текста или Шлюз не смог обработать ответ

{
  "ticket_id": "gosmev-ticket-49d481fa-f96e-4ebe-8011-e069f6034035",
  "error": "unexpected_error",
  "error_description": "SOAP-ENV:Client: Отправитель сообщения не зарегистрирован.",
  "scope": ["fullname", "birthdate"]
}

Получение согласий пользователя из Цифрового профиля

/auth/user_permissions

Заголовки:

  • Authorization - заголовок включающий в себя данные для проверки подлинности.

Для получения данных отправляется GET или POST запрос на url:

https://demo.gate.esia.pro/auth/user_permissions

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

  • Authorization: Bearer [access_token]

Пример запроса на получение данных:

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": "Министерство внутренних дел Российской Федерации"
          }
        ]
      },
      "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/smev_oauth/logout_callback
  • Взаимодействие со шлюзом в рамках СМЭВ HTTP API
  • Схема процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и СМЭВ
  • Авторизация (Получение авторизационного кода)
  • Примеры
  • Получение токена доступа (Обмен авторизационного кода на токен доступа)
  • Перевыпуск токена доступа (Обмен токена обновления на токен доступа)
  • Отправка запроса в СМЭВ на получение данных пользователя
  • Примеры ответа:
  • Обработка callback-а Шлюзом при получении ответа из СМЭВ
  • Структура финального ответа
  • Структура поля info
  • Примеры ответов
  • Успешное получение персональных данных и документов
  • Статус PROCESSING (документ отсутствует в СМЭВ)
  • Статус FAULT (ошибка обработки документа)
  • Непредвиденная ошибка
  • Получение согласий пользователя из Цифрового профиля
  • Выход из системы ЕСИА