Инструкция по взаимодействию с мобильным API ЕБС

Мобильное API предназначено для осуществления биометрической идентификации клиента в мобильном приложении с использованием официального SDK ЕБС, соответствует и полностью совместимо с типовым решением от ЕБС.

Взаимодействие с мобильным API должно производиться в соответствии с руководством пользователя по работе с библиотекой ЕБС.SDK.Адаптер. Скачать последнюю версию руководства и библиотеки можно с официального сайта ЕБС в разделе "документы -> софт".

Спецификация API в формате OpenAPI 3.0 доступна по URL: https://demo.gate.esia.pro/api-docs/index.html

Дополнительная информация по использованию мобильного SDK ЕБС

ЕСИА шлюз работает и совместим с вариантом SDK ЕБС.SDK.Адаптер (Android версия 1.0.0, iOS версия 1.0.1). Перед началом встраивания рекомендуется ознакомиться с официальной документацией по SDK. Нами проверена и гарантирована работа SDK в режиме VerificationRequestMode.CUSTOM. В этом режиме само приложение организует последовательность действий по проверке наличия установленного МП "Биометрия" и запросу необходимых разрешений.

Для тестирования клиентского мобильного приложения рекомендуется установить дистрибутив МП "Биометрия" для интеграционного тестирования (версия 2.3.3), которое доступно для скачивания на официальном сайте ЕБС в разделе "документы -> софт". Данный дистрибутив работает с тестовым контуром ЕБС в отличие от дистрибутива, который устанавливается из магазина приложений.

Подготовка к использованию ЕБС Mobile API

В административной панели шлюза в соотвествующей КИС, у которой включена поддержка ЕБС МП, необходимо добавить два URL возврата для получения результата верификации в клиентскую систему. Эти URL указываются при инициализации сессии /api/v1/vrf/create.

Описание API

ЕСИА шлюз предоставляет внутреннее и внешнее API для взаимодействия с мобильным приложением, мобильным SDK и МП "Биометрия".

Внешнее API используется для взаимодействия с мобильным SDK и МП "Биометрия". Внутреннее API предназначено для взаимодействия клиентской ИС (КИС) с ЕСИА шлюзом.

Процесс взаимодействия компонентов системы представлен на схеме:

Инициализация сессии идентификации со стороны клиентской ИС

Клиентская ИС получив запрос от пользователя системы из мобильного приложения (МП) на получение услуги принимает решение инициировать биометрическую верификацию пользователя.

POST /api/v1/vrf/create

В заголовке авторизации необходимо передать токен доступа к API:

Authorization: Bearer <токен доступа>

Значение токена доступа доступно в административной панели шлюза в разделе КИС -> Карточка КИС -> Токен доступа к API ЕБС МП.

Параметры передаются в теле запроса в формате JSON. Допустимые параметры:

• sid - Идентификатор сессии. Формируется на стороне КИС;
• dbo_ko_uri - внутренний URI КИС для получения результата биометрической идентификации и персональных данных пользователя *;

• dbo_ko_public_uri - публичный (доступный из сети Интернет) URI, на который шлюз должен перенаправить пользователя в случае успешного завершения процесса удаленной идентификации или возникновения ошибки *.

  Важно: * Оба вышеописанных URI получения результата необходимо зарегистрировать в списке Пути возврата в настройках КИС.

Ответ приходит в формате JSON, дополнительно используются HTTP статусы для индикации ошибок:

{
  "code": "код ошибки",
  "message": "текстовое описание ошибки"
}

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

POST https://demo.gate.esia.pro/api/v1/vrf/create HTTP/1.1
Authorization: Bearer mts1r7zpya06kjq3h694n0b7go7edzk2
Content-Type: application/json
{
  "sid": "5b9dcd00-71a6-4293-ac6c-f367a2ebef7f",
  "dbo_ko_uri": "https://test.bank.ru/ebs-result",
  "dbo_ko_public_uri": "https://test.bank.ru/ebs-public-result"
}

Получение результата идентификации в клиентской ИС

По окончанию процесса верификации шлюз отправляет в клиентскую ИС результат верификации на переданный ранее в запросе инициализации сессии идентификации коллбэк dbo_ko_uri.

В теле запроса присутствует поле res_secret, этот идентификатор так же передаётся в мобильное приложение. Используя этот идентификатор, мобильное приложение позднее может запросить персональные данные пользователя у КИС.

POST <dbo_ko_uri>

Параметры передаются в теле запроса в формате JSON. Допустимые параметры:

• sid - Обязательный параметр, строка. Идентификатор сессии изначально сгенерированный в КИС;
• auth_result - Обязательный параметр, булево выражение. Результат процесса удаленной идентификации с использованием ЕСИА и ЕБС;
• code - Необязательный параметр, строка. Присутствует только в случае возникновения ошибки выполнения процесса удаленной идентификации с использованием ЕСИА и ЕБС. Код ошибки;
• message - Необязательный параметр, строка. Присутствует только в случае возникновения ошибки выполнения процесса удаленной идентификации с использованием ЕСИА и ЕБС. Описание ошибки;
• res_secret - Необязательный параметр, строка. Присутствует только в случае успешного прохождения пользователем процесса удаленной идентификации с использованием ЕСИА и ЕБС. Параметр, с использованием которого далее происходит взаимодействие пользователя и КИС;
• extended_result - Необязательный параметр, строка. Присутствует только в случае успешного прохождения пользователем процесса удаленной идентификации с использованием ЕСИА и ЕБС. Расширенный результат верификации, полученный от ЕБС, содержащий степени схожести (общая и по каждой из модальностей). Параметр передается в формате JWT токена;
• user_data - Необязательный параметр. Присутствует только в случае успешного прохождения пользователем процесса удаленной идентификации с использованием ЕСИА и ЕБС. Полученные из ЕСИА ПДн пользователя. Также в данных пользователя присутствует расшифрованный результат верификации, полученный от ЕБС, содержащий степени схожести.

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

POST https://test.bank.ru/ebs-result HTTP/1.1
Content-Type: application/json

{
  "sid": "dc61c027-22e2-4eb6-9fda-6ad930301015",
  "auth_result": true,
  "res_secret": "bd852fe0-f612-013a-01d4-0242ac110004",
  "extended_result": "eyJraWQiOiJlM2UyYjg1MS1iMDNmLTRkZTAtOTM5Zi0xZmYzNDFmMjJkMmMiLCJ0eXAiOiJKV1QiLCJhbGciOiJHT1NUMzQxMF8yMDEyXzI1NiJ9.eyJyZXN1bHQiOnRydWUsInN1YiI6IjEwMDA1NTAzODMiLCJhdWQiOiIyNTA1MDEiLCJuYmYiOjE2NTk2MTA4OTksImlzcyI6IlVCU19ERVYiLCJtYXRjaCI6IntcIm92ZXJhbGxcIjowLjk5OTk5OTk5OTk0NDM1MTgsXCJmYWNlXCI6MC45OTk5OTkwMjIsXCJ2b2ljZVwiOjAuOTk5OTQzMX0iLCJleHAiOjE2NTk2MTE1MDAsImlhdCI6MTY1OTYxMDg5OH0.fFtjomYigoTa4wdHwgp4W_SIdPQmiLX4G0jzs9S26fUMEsOVuO3Hr5FxigCs8DM8O3-SrTIiYOxqSTw9jXjs6w",
  "user_data": {
    "stateFacts": [
      "EntityRoot"
    ],
    "firstName": "Константин",
    "middleName": "Константинович",
    "lastName": "Константинопольский",
    "birthDate": "01.01.1990",
    "birthPlace": "г. Большие Васюки",
    "gender": "M",
    "trusted": true,
    "citizenship": "RUS",
    "snils": "012-345-678 90",
    "inn": "123456789012",
    "updatedOn": 1657091110,
    "status": "REGISTERED",
    "verifying": false,
    "rIdDoc": 123456,
    "containsUpCfmCode": false,
    "eTag": "A57AA24477534FD93EFA23F49EDCBDEE4FB42592",
    "contacts": [
      {
        "stateFacts": [
          "Identifiable"
        ],
        "id": 12345678,
        "type": "MBT",
        "vrfStu": "VERIFIED",
        "value": "+7(123)4567890",
        "eTag": "DBDCA55E7EF7C27CA29CBA37DD5E4CDAA72FD535"
      }
    ],
    "mobile": "+7(123)4567890",
    "addresses": {},
    "documents": {
      "rf_passport": [
        {
          "stateFacts": [
            "Identifiable"
          ],
          "id": 123456,
          "type": "RF_PASSPORT",
          "vrfStu": "VERIFIED",
          "series": "6543",
          "number": "123456",
          "issueDate": "01.01.2008",
          "issueId": "612345",
          "issuedBy": "ОВД Центрального района города Большие Васюки",
          "eTag": "F53D4DB9D73744CAA49AE7ADE9773494C3F3A37F"
        }
      ]
    },
    "ebs_result": {
      "overall": 0.9999999999443518,
      "face": 0.999999022,
      "voice": 0.9999431
    }
  }
}