Получение данных пользователя из ЦОИД
Last updated
Last updated
Для того, чтобы воспользоваться услугой получения данных пользователя через ЦОИД системы 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 ссылки-запроса авторизации указывается значение ИИН
Осуществляется редирект Пользователя в Aitu Passport, где пользователь проходит процессы авторизации, идентификации в Aitu Passport (Стрелки 5 - 11 на схеме). Путь пользователя в Aitu Passport определяется параметрами переданными в ссылке-запросе авторизации.
Для успешного прохождения этапа биометрической идентификации скорость подключения устройства Пользователя к сети интернет должна быть не менее 100кб/сек
4. Если ИИН Пользователя не передан в ссылке-запросе авторизации, то Aitu Passport запрашивает у Пользователя ИИН (стрелки 12 - 13 на схеме)
5. Aitu Passport проводит проверку ИИН и фотографии с изображением лица Пользователя, полученной при биометрической идентификации, в ЦОИД через Адаптер ЦОИД (стрелки 14 - 18 на схеме). В результате проверки данных Пользователя в ЦОИД на странице AituPassport, могут выводится следующие сообщения об ошибках:
| № | Сообщение об ошибке для пользователя | Комментарий |
|---|---|---|
1 | Ошибка на сервисе государственного органа | Сервис ЦОИД не доступен Рекомендация:
|
2 | ИИН не найден в базе данных государственного органа. Проверку можно пройти при наличии гражданства Республики Казахстан или Вида на жительство. Проверьте правильность ввода ИИН или обратитесь в службу поддержки | Указанный Пользователем ИИН не найден в базе данных ЦОИД Рекомендация: Пользователь должен указать другой ИИН |
3 | Ваше фото не совпадает с фото из государственной базы данных. Проверьте правильность введенного ИИН или попробуйте пройти видео-проверку заново | ЦОИД отклонил данные предоставленные Пользователем через AituPassort (изображение лица и ИИН) так как при сравнении предоставленного изображения лица с эталонным изображением, закрепленным за указанным ИИН, система ЦОИД не нашла достаточного уровня совпадения. Рекомендация:
|
4 | Проверку можно пройти при достижении 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 на схеме
Данные пользователя будут переданы в приложение Партнера только в том случае, если Партнер является объектом фин., мониторинга в РК и у Партнера заключен договор присоединения к ЦОИД КЦМР. Подробней описано в статье Aitu Passport -> ЦОИД
| № | Параметр | Required | Тип | Описание | Источник |
|---|---|---|---|---|---|
1 | iin | Required | String | ИИН Пользователя | id_token -> объект idpc_verification -> iin |
2 | requestId | Required | String | Идентификатор запроса | id_token -> объект idpc_verification -> iin |
| № | Параметр | Тип | Описание |
|---|---|---|---|
1 | 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" |
| № | Параметр | Тип | Описание |
|---|---|---|---|
1 | name | String | Имя владельца документа |
2 | surname | String | Фамилия владельца документа |
3 | patronymic | String | Отчество владельца документа |
4 | number | String | Номер документа |
5 | birthDate | Date | Дата рождения владельца документа |
6 | beginDate | Date | Дата начала действия документа |
7 | endDate | Date | Дата окончания дествия документа |
8 | status | Object | Статус документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
9 | issueOrganization | Object | Организация, выдавшая документ - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
10 | type | Object | Тип документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
| № | Параметр | Тип | Описание |
|---|---|---|---|
1 | city | String | Город |
2 | country | Object | Страна - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
3 | district | Object | Район - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
4 | region | Object | Область - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
| № | Параметр | Тип | Описание |
|---|---|---|---|
1 | code | String | Кодовое обозначение справочного значения |
2 | nameKz | String | Наименование справочного значения на казахском языке |
3 | nameRu | String | Наименование справочного значения на русском языке |
4 | changeDate | DateTime | Дата и время изменения справочного значения |
| № | Параметр | Тип | Описание |
|---|---|---|---|
1 | building | String | Номер дома |
2 | street | String | Улица |
3 | city | String | Город |
4 | country | Object | Страна - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
5 | district | Object | Район - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
6 | region | Object | Область - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "Объект DictionaryItem" |
7 | beginDate | Date | Дата начала регистрации |
Для тестовой интеграции предлагаем использовать текущую схему Aitu Passport, без развертывания ЦОИД адаптера на ресурсах Партнера. В результате будет использоваться тестовый ЦОИД адаптер, развернутый в тестовом контуре Aitu Passport, который всегда возвращает положительные ответы из "ЦОИД"
Для доступа к тестовому ЦОИД адаптеру, развернутому в тестовом контуре Aitu Passport, используйте следующие данные:
ACCESS_LOGIN: admin
ACCESS_PERSONAL_DATA_PASSWORD: coidtestpassword
Если в процессе тестирования вы хотите проверить отработку ошибок, которые отображаются Пользователю на экран в Aitu Passport в результате проверки данных в ЦОИД, то передайте следующие ИИН:
| ИИН | Сообщение об ошибке для пользователя |
|---|---|
000000000001 | Ваше фото не совпадает с фото из государственной базы данных. Проверьте правильность введенного ИИН или попробуйте пройти видео-проверку заново |
000000000002 | Проверку можно пройти при достижении 16 летнего возраста |
000000000003 | ИИН не найден в базе данных государственного органа. Проверку можно пройти при наличии гражданства Республики Казахстан или Вида на жительство. Проверьте правильность ввода ИИН или обратитесь в службу поддержки |
000000000004 | Ошибка на сервисе государственного органа (сервис не доступен) |
000000000005 | Ошибка на сервисе государственного органа (Партнеру запрещен доступ к данным) |
Для всех остальных ИИН, тестовый ЦОИД адаптер, развернутый в тестовом контуре Aitu Passport, вернет фиксированный ответ с данными.
