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

Общие сведения#

Сервис импорта учетной записи пользователя ЕСИА обеспечивает возможность проверки наличия учетной записи пользователя, а в случае её отсутствия – регистрации пользователя в ЕСИА. При обнаружении стандартной учетной записи (учетной записи, готовой к подтверждению) сервис производит подтверждение учетной записи. ESIA-Bridge позволяет вызывать сервис импорта в следующих режимах:

  • импорт пользователей в ЕСИА с подтверждением кодом из SMS через API — в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен ввести в интерфейс приложения, которое в свою очередь отправит этот код в ЕСИА для проверки;

  • импорт пользователей в ЕСИА с подтверждением посредством отправки пользователем ответной SMS — в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен отправить обратным сообщением в ЕСИА;

  • устаревший импорт пользователей в ЕСИА — существует для обратной совместимости интегрированных ранее приложений и не включает в себя функцию подтверждения упрощенных учетных записей.

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

Доступ к сервису#

Доступ к сервису имеют исключительно доверенные организации, обеспечивающие подтверждение личности при предоставлении своих услуг пользователям. Например, сервис может быть предоставлен банкам для самостоятельной регистрации пользователя из его учетной записи интернет-банка. В этом случае банк должен гарантировать, что передаваемые пользователем данные – фамилия, имя, отчество и паспортные данные – принадлежат именно пользователю, инициирующему регистрацию.

Технически доступ к сервису имеют системы, получившие возможность получать маркеры доступа на разрешение (scope) типа ext_imp.

Включение функции регистрации#

Для включения функции регистрации в ESIA-Bridge необходимо внести следующие изменения в конфигурационный файл ESIA-Bridge.conf:

  1. Указать корректное значения параметра esia.host – домена среды ЕСИА, в которую будет осуществляться импорт. Возможны следующие значения:

    • esia-portal1.test.gosuslugi.ru – тестовая среда ЕСИА;

    • esia.gosuslugi.ru – продуктивная среда ЕСИА.

  2. Указать корректные настройки электронной подписи ИС, используемой для взаимодействия с ЕСИА, согласно п. 2.4.1 данного документа.

  3. Добавить в раздел rest/esia параметр следующего содержания:

    endpoint_rs="https://"${app.esia.host}"/esia-rs/"

  4. Добавить в раздел oauth/client конфигурационного файла новый блок следующего вида:

    reg {
            requested_scopes = "http://esia.gosuslugi.ru/ext_imp",
        licenseKey = "811301161|1488574800|U2Ac1SsJp+eHNOs2fbsnLKbzUCFsat+tLxuOxurcwtBnd3F0DPDi5lQuHdinerjFfv6M2ONhscQgdMOvM/w/2Q=="
    }

    В этом блоке используются параметры:

    • requested_scope — запрашиваемый системой scope для операции импорта (по умолчанию – ext_imp);

    • licenseKey – лицензия, позволяющая системе вызывать сервис регистрации.

    После добавления этого блока с валидной лицензией и перезапуска ESIA-Bridge будет доступен сервис регистрации (импорта) пользователей.

    Важно

    Поскольку при вызове сервиса не проводится авторизация вызывающей системы, то адрес сервиса <hostname>/blitz/bridge/reg следует сделать доступным исключительно для системы, осуществляющей вызов – например, для системы интернет-банкинга.

Вызов сервиса#

Для вызова сервиса следует направить HTTP-запрос методом PUT на один из следующих адресов в зависимости от того, какой режим планируется использовать:

URL сервиса

Режим работы

/blitz/bridge/v2/reg/req

Импорт пользователей в ЕСИА с подтверждением кодом из SMS через API. При использовании этого режима нужно предусмотреть вызов сервиса ЕСИА по передачи кода из SMS

/blitz/bridge/v2/reg

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

/blitz/bridge/reg

Устаревший импорт пользователей в ЕСИА

В заголовке (http header) необходимо указать параметр Content-Type со значением application/json. В теле (body) запроса необходимо указать параметры пользователя, которые включают в себя атрибуты регистрируемого пользователя в виде json:

  • firstName – имя;

  • lastName – фамилия;

  • middleName – отчество;

  • birthDate – дата рождения в формате ДД.ММ.ГГГГ;

  • gender – пол (M – мужской, F – женский);

  • birthPlace – место рождения;

  • citizenship – гражданство (по умолчанию RUS для России, можно не указывать);

  • snils – СНИЛС (в формате ХХХ-ХХХ-ХХХ ХХ);

  • passport – данные паспорта, включают в себя:

    • type – тип документа (по умолчанию имеет значение “RF_PASSPORT”, можно не указывать);

    • series – серия;

    • number – номер;

    • issueDate – дата выдачи в формате ДД.ММ.ГГГГ;

    • issueId – код подразделения;

    • issuedBy – кем выдан;

  • mobile – мобильный телефон пользователя; включает в себя:

    • value – значение (в формате +7(ХХХ)ХХХХХХХ);

  • email – адрес электронной почты пользователя (не обязательно); включает в себя:

    • value – значение;

  • liveAddress – адрес места проживания (не обязательно); включает в себя:

    • fiasCode – код ФИАС;

    • addressStr – адрес в виде строки;

    • zipCode – индекс;

    • countryId – идентификатор страны, для России принимает значение RUS;

    • region – регион;

    • city – город;

    • district – внутригородской район;

    • area – район;

    • settlement – поселение;

    • additionArea – доп. территория;

    • additionAreaStreet – улица на доп. территории;

    • street – улица;

    • house – дом;

    • building – строение;

    • frame – корпус;

    • flat – квартира.

  • registerAddress – адрес регистрации (не обязательно); включает в себя те же параметры, что и адрес места проживания.

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

PUT https://<ESIA_BRIDGE_HOST>/blitz/bridge/v2/reg
Content-Type: application/json
{
"firstName":"Иван",
"lastName":"Иванов",
"middleName":"Иванович",
"birthDate":"01.01.1999",
"birthPlace":"Москва",
"gender":"M",
"snils":"000-000-001 89",
"mobile": {"value": "+7(888)9999999"},
"email":  {"value": "test@test.st"},
"passport":{
    "series":"9999",
    "number":"889999",
    "issueId":"111001",
    "issuedBy":"РУВД г.Москвы",
    "issueDate":"18.03.2016"
},
"liveAddress":{
        "addressStr":"Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа",
        "countryId": "RUS",
        "zipCode": "394000",
        "region":"Кемеровская Область",
        "area": "Таштагольский Район",
        "city":"Шерегеш Поселок городского типа",
        "district": "нет",
        "settlement":"Усть-Анзас Поселок",
        "street": "Советская Улица",
        "additionArea":"Регион Садовое неком-е товарищество",
        "additionAreaStreet":"Тест",
        "house": "86/1",
        "building": "e",
        "frame": "204у",
        "flat":"пом.419",
        "fiasCode":"77-0-000-000-000-000-4236-0000-000"
    },
"registerAddress":{
        "addressStr":"Кемеровская Область, Таштагольский Район, Шерегеш Поселок городского типа",
        "countryId": "RUS",
        "zipCode": "394000",
        "region":"Кемеровская Область",
        "area": "Таштагольский Район",
        "city":"Шерегеш Поселок городского типа",
        "district": "нет",
        "settlement":"Усть-Анзас Поселок",
        "street": "Советская Улица",
        "additionArea":"Регион Садовое неком-е товарищество",
        "additionAreaStreet":"Тест",
        "house": "86/1",
        "building": "e",
        "frame": "204у",
        "flat":"пом.419",
        "fiasCode":"77-0-000-000-000-000-4236-0000-000"
    }
}

Ответ содержит параметры, представленные в таблице ниже.

Параметр

Описание

Комментарий

requestId

заявки на регистрацию

Возвращается в случае создания заявки на регистрацию.

code

Код завершения операции

Может быть возращён в виде значений:

  • 0 или 1 – выполнен импорт УЗ;

  • 2 – создана заявка на импорт (регистрацию) учетной записи;

  • 3 – выполняется запрос паспортного досье (отправлен ранее);

  • 4 – отправлен запрос для получения паспортного досье;

  • код ошибки.

description

Текстовое описание кода завершения операции

Описание для кодов успешного импорта учётной записи в ЕСИА (code = 0, 1 или 2) и для code =ESIA-03200.

message

Текстовое описание кода ошибки выполнения операции

Описание для кодов ошибок при импорте учётной записи в ЕСИА (за исключением кода ESIA-03200)

availableAttemptsCount

Оставшееся количество попыток ввода кода подтверждения

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

maxInputAttemptsCount

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

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

periodsForNextGeneration

Интервал времени между переотправкой СМС

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

resendCount

Количество попыток по переотправке СМС с кодом подтверждения

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

timeToLive

Срок жизни кода подтверждения

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

maxResendCount

Максимальное количество попыток на переотправку СМС

Возвращается в ответе при импорте пользователей в ЕСИА с подтверждением кодом из SMS через API

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

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 21 Apr 2020 15:41:55 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
{"code":"1", "description":"Person successfully confirmed as trusted in ESIA"}

Другие примеры ответов сервиса, а также детальное описание кодов ошибок приведено в Методических рекомендациях по использованию ЕСИА.

Отправка кода подтверждения#

Если используется режим импорта пользователей в ЕСИА с подтверждением кодом из SMS через API, то в этом случае после подачи заявки на импорт ЕСИА отправит пользователю SMS, код из которой он должен ввести в интерфейс приложения. На стороне приложения необходимо предусмотреть поле для ввода кода. При его получении приложение должно отправить код в ЕСИА посредством вызова сервиса /blitz/bridge/v2/confirm методом POST, а в теле указать следующие параметры:

  • requestId – идентификатор запрос на импорт, полученный ранее от ЕСИА;

  • code – код, введенный пользователем.

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

POST https://<ESIA_BRIDGE_HOST>/blitz/bridge/v2/confirm
Content-Type: application/json
{
 "requestId": "AAAAD2CA4140654F9D0ED2F2574B8F11A896D8EC1CAAAEA50255",
 "code": "2783"
}

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

{
 "requestId":"AAAA0EF8369F965664CB48D753590B7269A3CF453DD0554E4DBA",
 "createdTime":1557766520905,
 "mobile":"79000000000",
 "status":"ОК",
 "confirmationWay":"REST_API",
 "availableAttemptsCount":5,
 "maxInputAttemptsCount":5,
 "periodsForNextGeneration":[
 60000,
 60000,
 60000
 ],
 "resendCount":1,
"maxResendCount":5,
 "timeToLive":86400000
}

Значение OK параметра status свидетельствует о том, что значение из SMS введено корректно.

Проверка статуса заявки на регистрацию#

Для вызова сервиса проверки статуса заявки следует направить HTTP-запрос методом GET на адрес /blitz/bridge/req с query-параметром req_id, равным идентификатору заявки. Пример запроса:

GET https:///blitz/bridge/req?req_id=AAAAA4E84240654F9D0E46BC8A0D51AD HTTP/1.1

В качестве ответа сервис вернет статус исполнения заявки на регистрацию учетной записи. В ответе ключевым является параметр status, принимающий значения:

  • VALIDATING – идет проверка данных учетной записи в ПФР или ФМС России;

  • VALIDATION_FAILED – ошибка при проверке данных учетной записи в БГИР, детализация ошибки содержится в параметре errorStatusInfo;

  • SUCCEEDED – операция успешно выполнена.

Параметр errorStatusInfo включает в себя, в частности, код ошибки (code) и ее описание (message). Пример ответа при успешной регистрации учетной записи:

{
  "stateFacts": [
    "Identifiable"
  ],
  "status": "SUCCEEDED",
  "personOid": 1000352622
}

Пример ответа при ошибке:

{
  "stateFacts": [
    "Identifiable"
  ],
  "status": "VALIDATION_FAILED",
  "flowDetails": [
    {
      "name": "validateRfPassport",
      "status": "F",
      "error": {
        "code": "ESIA-910100",
        "message": "В автоматическом режиме не удалось произвести проверку вашего паспорта."
      }
    }
  ],
  "errorStatusInfo": {
    "code": "ESIA-910100",
    "message": "В автоматическом режиме не удалось произвести проверку вашего паспорта."
  }
}

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