Получение данных пользователя из ЦОИД

Для того, чтобы воспользоваться услугой получения данных пользователя через ЦОИД системы Aitu Passport необходимо чтобы Партнер:

был зарегистрирован в соответствующем окружении Aitu Passport (на тестовой площадке, на продакшн площадке)
создал свой сервис в соответствующем окружении Aitu Passport
подключил к своему сервису сервис (scope) для взаимодействия с ЦОИД "idpc_verification"
установил на свои ресурсы и настроил приложение "Адаптер ЦОИД". Обязательное условие для продакшн среды.
передал сотрудникам Aitu Passport ACCESS_LOGIN и ACCESS_PASSWORD, указанные при настройке Адаптера ЦОИД. Обязательное условие для продакшн среды.

Схема получения данных пользователя через ЦОИД

Схема процесса получения данных пользователя через ЦОИД выглядит следующим образом:

Описание процесса получения данных пользователя через ЦОИД

Пользователь инициирует процесс авторизации с помощью Aitu Passport в приложении Партнера (нажимает на кнопку или ссылку в приложении Партнера). Стрелка 1 на схеме.
Приложение партнера формирует ссылку-запрос авторизации (Стрелка 4 на схеме). С методом генерации ссылки-запроса авторизации oauth2/auth можно ознакомиться здесь, процесс авторизации детально описан в статье "Авторизация" -> глава "Авторизация в Aitu Passport". Важные моменты при формировании параметров для ссылки-запроса авторизации в процессе получения данных пользователя через ЦОИД:
- В случае, если по условиям договора на оказание услуг Aitu Passport, номер мобильного телефона Пользователя верифицирует:
  - Партнер самостоятельно, то приложение Партнера должно в ссылке-запросе авторизации (oauth2/auth) передать параметр otp_confirmation. Чтобы получить значение для параметра otp_confirmation, приложение Партнера должно вызвать метод api/v1/trusted-phone. Значение для параметра otp_confirmation передается в параметре secret ответа метода api/v1/trusted-phone. Внимание! secret, а соответственно и значение в параметре otp_confirmation является одноразовым, его необходимо получать для каждого запроса авторизации заново!
  - Aitu Passport, то параметр otp_confirmation в ссылке-запросе на авторизацию (oauth2/auth) не передается, метод api/v1/trusted-phone вызывать не нужно.
  Процесс получения значения для параметра otp_confirmation обозначен стрелками 2 и 3 на схеме;
- В параметре scope обязательно указывается значение idpc_verification (приложение Партнера запрашивает от Aitu Passport услугу получения данных пользователя их ЦОИД);
- Если известен ИИН Пользователя в параметре iin ссылки-запроса авторизации указывается значение ИИН;
- Если необходимо обновить requestId для обращения в ЦОИД, то в запросе авторизации указывается параметр Refresh_request_id_coid = true.
Осуществляется редирект Пользователя в Aitu Passport, где пользователь проходит процессы авторизации, идентификации в Aitu Passport (Стрелки 5 - 11 на схеме). Путь пользователя в Aitu Passport определяется параметрами переданными в ссылке-запросе авторизации.

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

4. Если ИИН Пользователя не передан в ссылке-запросе авторизации, то Aitu Passport запрашивает у Пользователя ИИН (стрелки 12 - 13 на схеме)

5. Aitu Passport проводит проверку ИИН и фотографии с изображением лица Пользователя, полученной при биометрической идентификации, в ЦОИД через Адаптер ЦОИД (стрелки 14 - 18 на схеме). В результате проверки данных Пользователя в ЦОИД на странице AituPassport, могут выводится следующие сообщения об ошибках:

Ошибки при взаимодействии с ЦОИД:

№

Сообщение об ошибке для пользователя

Комментарий

Ошибка на сервисе государственного органа

Сервис ЦОИД не доступен

Рекомендация:

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

ИИН не найден в базе данных государственного органа. Проверку можно пройти при наличии гражданства Республики Казахстан или Вида на жительство. Проверьте правильность ввода ИИН или обратитесь в службу поддержки

Указанный Пользователем ИИН не найден в базе данных ЦОИД

Рекомендация:

Пользователь должен указать другой ИИН

Ваше фото не совпадает с фото из государственной базы данных. Проверьте правильность введенного ИИН или попробуйте пройти видео-проверку заново

ЦОИД отклонил данные предоставленные Пользователем через AituPassort (изображение лица и ИИН) так как при сравнении предоставленного изображения лица с эталонным изображением, закрепленным за указанным ИИН, система ЦОИД не нашла достаточного уровня совпадения.

Рекомендация:

Если ИИН указан корректно, то необходимо повторить видео-проверку в хорошо освещенном месте, на лице Пользователя не должно быть тени. Пользователь должен прямо смотреть в камеру, необходимо исключить наклоны/повороты лица, моргание и т.д.
Если повторное прохождение видео-проверки не помогло, то возможно потребуется смена документов, так как эталонное фото лица, хранящееся в ЦОИД и закрепленное за указанным ИИН не соответствует текущему изображению лица Пользователя

Проверку можно пройти при достижении 16 летнего возраста

ЦОИД отклонил данные, так как пройти проверку пытается лицо не достигшее 16 летнего возраста.

Рекомендация:

Проверку в ЦОИД должны проходить лица достигшие 16-летнего возраста

6. Aitu Passport генерирует код авторизации и передает его приложению Партнера. Описание данного процесса см. в статье "Авторизация" -> глава "Авторизация в Aitu Passport. Стрелки 20 и 21 на схеме.

7. Приложение Партнера (серверная часть приложения) обменивает полученный код авторизации на токены (access_token, id_token). Описание данного процесса см. в статье "Авторизация" -> глава "Авторизация в Aitu Passport. Стрелки 22 и 23 на схеме

Сроки действия объектов

Внимание:

Параметр otp_confirmation действителен в течение 60 минут с момента генерации;
Код авторизации (code) действителен в течение 5 минут с момента генерации;
Токен авторизации (access_token ) действителен в течение 30 дней с момента генерации;
Токен пользователя на устройстве действителен 1 год с момента генерации.

Получение данных Пользователя из ЦОИД

В ответе на запрос получения токенов, см., на схеме стрелки 22 и 23, приложение Партнера получает access_token и id_token.

Параметр id_token представляет собой jwt-токен и содержит в себе текстовые данные. Для того чтобы извлечь текстовые данные из id_token вы можете воспользоваться https://jwt.io/, так же на данном сайте описано, как данный jwt-токен можно распарсить в коде.

Приложение Пртнера из id_token должно получить объект idpc_verification с параметрами iin и requestId, описание объекта см. в статье "Получение данных пользователя" в разделе "Структура объекта: “idpc_verification” (Стрелка 24 на схеме).

Для получения доступа к персональным данным Пользователя, полученным из ЦОИД, пожалуйста, свяжитесь с представителями Aitu Passport

Далее приложение Партнера должно отправить запрос в Адаптер ЦОИД для получения персональных данных Пользователя.

Описание API методов ЦОИД адаптера см., тут.

Метод ЦОИД адаптера для получения персональных данных - /v1/personal-data. Для получения данных в запросе к методу /v1/personal-data передаются параметры requestId и iin, полученные из id_token.

Приложение Партнера должно отправлять запрос, для получения персональных данных Пользователя, к ЦОИД Адаптеру, а не к Aitu Passport.

Для доступа к методу /v1/personal-data используется basic Autorization, в качестве логина должно передаваться значение параметра ACCESS_LOGIN, в качестве пароля должно передаваться значение параметра ACCESS_PERSONAL_DATA_PASSWORD. Параметры задаются при настройке Адаптера ЦОИД, см. статью "Настройка Адаптера ЦОИД"

Представление процесса получения персональных данных Пользователя партнера из ЦОИД через ЦОИД Адаптер см. стрелки 25 - 30 на схеме

Описание метода /v1/personal-data

Данные пользователя будут переданы в приложение Партнера только в том случае, если Партнер является объектом фин., мониторинга в РК и у Партнера заключен договор присоединения к ЦОИД КЦМР. Подробней описано в статье Aitu Passport -> ЦОИД

Параметры запроса метода /v1/personal-data

№

Параметр

Required

Тип

Описание

Источник

iin

Required

String

ИИН Пользователя

id_token -> объект idpc_verification -> iin

requestId

Required

String

Идентификатор запроса

id_token -> объект idpc_verification -> iin

Параметры ответа метода /v1/personal-data

№

Параметр

Тип

Описание

person

Object

Объект, содержащий данные пользователя, полученные из ЦОИД

1.1

documents

Array

Массив с данными документов пользователя. Документ передается в виде объекта Documents. Описание объекта Documents см. раздел "Объект Documents"

1.2

name

String

Имя пользователя

1.3

surname

String

Фамилия пользователя

1.4

patronymic

String

Отчество пользователя

1.5

birthDate

Date

Дата рождения пользователя

1.6

iin

String

ИИН пользователя

1.7

birthPlace

Object

Объект BirthPlace, содержащий данные о месте рождения пользователя. Описание объекта BirthPlace см. раздел "Объект BirthPlace"

1.8

lifeStatus

Object

Объект DictionaryItem, содержащий данные из справочника "Жизненный статус пользователя". Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

1.9

gender

Object

Пол - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

1.10

nationality

Object

Национальность - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

1.11

citizenship

Object

Гражданство - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

1.12

regAddress

Object

Адрес регистрации - объект RegAddress. Описание объекта RegAddress см. раздел "Объект RegAddress"

Объект Documents

№

Параметр

Тип

Описание

name

String

Имя владельца документа

surname

String

Фамилия владельца документа

patronymic

String

Отчество владельца документа

number

String

Номер документа

birthDate

Date

Дата рождения владельца документа

beginDate

Date

Дата начала действия документа

endDate

Date

Дата окончания дествия документа

status

Object

Статус документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

issueOrganization

Object

Организация, выдавшая документ - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

type

Object

Тип документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

Объект BirthPlace

№

Параметр

Тип

Описание

city

String

Город

country

Object

Страна - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

district

Object

Район - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

region

Object

Область - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem"

Объект DictionaryItem

№

Параметр

Тип

Описание

code

String

Кодовое обозначение справочного значения

nameKz

String

Наименование справочного значения на казахском языке

nameRu

String

Наименование справочного значения на русском языке

changeDate

DateTime

Дата и время изменения справочного значения

Объект RegAddress

№

Параметр

Тип

Описание

building

String

Номер дома

street

String

Улица

city

String

Город

country

Object

district

Object

region

Object

beginDate

Date

Дата начала регистрации

Дополнительные данные

В ответе ЦОИД адаптера дополнительно передаются следующие данные:

Компонент VerifyResponse

Параметр

Тип

Описание

minConfidenceLevel

number(double)

Минимальное значение коэффициента схожести лиц. Передается обязательно

photo

string (base64)

Эталонное фото с изображением лица

requisites

компонент Organization

Данные организации запросившей биометрическую идентификацию

Компонент Organization

Параметр

Тип

Описание

name

string

Наименование организации

bin

string

БИН организации

Тестирование получения данных пользователя из ЦОИД

Для тестовой интеграции предлагаем использовать текущую схему Aitu Passport, без развертывания ЦОИД адаптера на ресурсах Партнера. В результате будет использоваться тестовый ЦОИД адаптер, развернутый в тестовом контуре Aitu Passport, который всегда возвращает положительные ответы из "ЦОИД"

Для доступа к тестовому ЦОИД адаптеру, развернутому в тестовом контуре Aitu Passport, используйте следующие данные:

ACCESS_LOGIN: admin
ACCESS_PERSONAL_DATA_PASSWORD: coidtestpassword

Если в процессе тестирования вы хотите проверить отработку ошибок, которые отображаются Пользователю на экран в Aitu Passport в результате проверки данных в ЦОИД, то передайте следующие ИИН:

ИИН

Сообщение об ошибке для пользователя

000000000001

000000000002

Проверку можно пройти при достижении 16 летнего возраста

000000000003

000000000004

Ошибка на сервисе государственного органа (сервис не доступен)

000000000005

Ошибка на сервисе государственного органа (Партнеру запрещен доступ к данным)

Для всех остальных ИИН, тестовый ЦОИД адаптер, развернутый в тестовом контуре Aitu Passport, вернет фиксированный ответ с данными.

Связанные статьи:

PreviousAitu Passport -> ЦОИД NextЦОИД идентификация - подписание документов ЭЦП

Last updated 2 months ago

Was this helpful?