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

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

* был зарегистрирован в соответствующем окружении Aitu Passport (на тестовой площадке, на продакшн площадке)
* создал свой сервис в соответствующем окружении Aitu Passport
* подключил к своему сервису сервис (scope) для взаимодействия с ЦОИД "**idpc\_verification**"
* установил на свои ресурсы и настроил приложение "Адаптер ЦОИД". Обязательное условие для продакшн среды.
* передал сотрудникам Aitu Passport ACCESS\_LOGIN и ACCESS\_PASSWORD, указанные при настройке Адаптера ЦОИД. Обязательное условие для продакшн среды.
  {% endhint %}

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

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

![](/files/pp8uWMxZZtGs7oxCdJJn)

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

1. Пользователь инициирует процесс авторизации с помощью Aitu Passport в приложении Партнера (нажимает на кнопку или ссылку в приложении Партнера). Стрелка 1 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid).
2. Приложение партнера формирует ссылку-запрос авторизации (Стрелка 4 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid)). С методом генерации ссылки-запроса авторизации oauth2/auth можно ознакомиться [здесь](https://docs.passport.aitu.io/#operation/oauthAuth), процесс авторизации детально описан в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport)". Важные моменты при формировании параметров для ссылки-запроса авторизации в процессе получения данных пользователя через ЦОИД:
   * В случае, если по условиям договора на оказание услуг Aitu Passport, номер мобильного телефона Пользователя верифицирует:

     * **Партнер** самостоятельно, то приложение Партнера должно в ссылке-запросе авторизации ([oauth2/auth](https://docs.passport.aitu.io/#operation/oauthAuth)) передать параметр `otp_confirmation`. Чтобы получить значение для параметра `otp_confirmation`**,** приложение Партнера должно вызвать метод [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone). Значение для параметра `otp_confirmation` передается в параметре `secret` ответа метода [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone).  **Внимание!** `secret`, а соответственно и значение в параметре `otp_confirmation` является одноразовым, его необходимо получать для каждого запроса авторизации заново!&#x20;
     * **Aitu Passport**, то параметр `otp_confirmation` в ссылке-запросе на авторизацию ([oauth2/auth](https://docs.passport.aitu.io/#operation/oauthAuth)) не передается, метод [api/v1/trusted-phone](https://docs.passport.aitu.io/#operation/createTrustedPhone) вызывать не нужно.&#x20;

     Процесс получения значения для параметра `otp_confirmation` обозначен стрелками 2 и 3 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid);
   * В параметре `scope` обязательно указывается значение `idpc_verification` (приложение Партнера запрашивает от Aitu Passport услугу получения данных пользователя их ЦОИД);
   * Если известен ИИН Пользователя в параметре iin ссылки-запроса авторизации указывается значение ИИН;
   * Если необходимо обновить requestId для обращения в ЦОИД, то в запросе авторизации указывается параметр Refresh\_request\_id\_coid = true.
3. Осуществляется редирект Пользователя в Aitu Passport, где пользователь проходит процессы авторизации, идентификации в Aitu Passport (Стрелки 5 - 11 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid)). Путь пользователя в Aitu Passport определяется параметрами переданными в ссылке-запросе авторизации.&#x20;

{% hint style="warning" %}
Для успешного прохождения этапа биометрической идентификации скорость подключения устройства Пользователя к сети интернет должна быть не менее 100кб/сек
{% endhint %}

4\. Если ИИН Пользователя не передан в ссылке-запросе авторизации, то Aitu Passport запрашивает у Пользователя ИИН (стрелки 12 - 13 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid))

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

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

<table><thead><tr><th width="71">№</th><th width="302">Сообщение об ошибке для пользователя</th><th>Комментарий</th></tr></thead><tbody><tr><td>1</td><td>Ошибка на сервисе государственного органа</td><td><p>Сервис ЦОИД не доступен</p><p></p><p><em>Рекомендация:</em></p><ul><li>Пользователь может попробовать пройти видео-проверку позже после восстановления работоспособности ЦОИД</li><li>Партнеру запрещен доступ к данным ЦОИД, необходимо получить доступ и после этого Пользователь сможет пойти идентификацию в ЦОИД</li></ul></td></tr><tr><td>2</td><td>ИИН не найден в базе данных государственного органа. Проверку можно пройти при наличии гражданства Республики Казахстан или Вида на жительство. Проверьте правильность ввода ИИН или обратитесь в службу поддержки</td><td><p>Указанный Пользователем ИИН не найден в базе данных ЦОИД </p><p></p><p><em>Рекомендация:</em> </p><p>Пользователь должен указать другой ИИН</p></td></tr><tr><td>3</td><td>Ваше фото не совпадает с фото из государственной базы данных. Проверьте правильность введенного ИИН или попробуйте пройти видео-проверку заново</td><td><p>ЦОИД отклонил данные предоставленные Пользователем через AituPassort (изображение лица и ИИН) так как при сравнении предоставленного изображения лица с эталонным изображением, закрепленным за указанным ИИН, система ЦОИД не нашла достаточного уровня совпадения. </p><p></p><p><em>Рекомендация:</em> </p><ul><li>Если ИИН указан корректно, то необходимо повторить видео-проверку в хорошо освещенном месте, на лице Пользователя не должно быть тени. Пользователь должен прямо смотреть в камеру, необходимо исключить наклоны/повороты лица, моргание и т.д.</li><li>Если повторное прохождение видео-проверки не помогло, то возможно потребуется смена документов, так как эталонное фото лица, хранящееся в ЦОИД и закрепленное за указанным ИИН не соответствует текущему изображению лица Пользователя </li></ul></td></tr><tr><td>4</td><td>Проверку можно пройти при достижении 16 летнего возраста</td><td><p>ЦОИД отклонил данные, так как пройти проверку пытается лицо не достигшее 16 летнего возраста. </p><p></p><p><em>Рекомендация:</em> </p><p>Проверку в ЦОИД должны проходить лица достигшие 16-летнего возраста</p></td></tr></tbody></table>

6\. Aitu Passport генерирует код авторизации и передает его приложению Партнера. Описание данного процесса см. в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport). Стрелки 20 и 21 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid).

7\. Приложение Партнера (серверная часть приложения) обменивает полученный код авторизации на токены (access\_token, id\_token). Описание данного процесса см. в статье "Авторизация" -> глава "[Авторизация в Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport). Стрелки 22 и 23 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid)

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

{% hint style="warning" %}
**Внимание:**

* Параметр `otp_confirmation`  действителен в течение **60 минут** с момента генерации;&#x20;
* Код авторизации (code) действителен  в течение **5 минут** с момента генерации;
* Токен авторизации (access\_token ) действителен в течение **30 дней** с момента генерации;
* Токен пользователя на устройстве действителен **1 год** с момента генерации.
  {% endhint %}

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

В ответе на запрос получения токенов, см., на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid) стрелки 22 и 23,  приложение Партнера получает access\_token и id\_token.

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

Приложение Пртнера из id\_token должно получить объект idpc\_verification с параметрами iin и requestI&#x64;**,** описание объекта см. в статье "Получение данных пользователя" в разделе "[Структура объекта: “idpc\_verification](/aituapps/aitu-passport/integraciya-s-aitu-passport/poluchenie-dannykh-polzovatelya.md#struktura-obekta-idpc_verification)**”**  (Стрелка 24 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid)).

{% hint style="warning" %}
Для получения доступа к персональным данным Пользователя, полученным из ЦОИД, пожалуйста, свяжитесь с представителями Aitu Passport
{% endhint %}

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

Описание API методов ЦОИД адаптера см., [тут](https://coid-adapter-docs.passport.aitu.io/).

Метод ЦОИД адаптера для получения  персональных данных - [/v1/personal-data](https://coid-adapter-docs.passport.aitu.io/#operation/getPersonalData). Для получения данных в запросе к методу [/v1/personal-data](https://coid-adapter-docs.passport.aitu.io/#operation/getPersonalData) передаются параметры requestId и iin, полученные из id\_token.&#x20;

{% hint style="info" %}
Приложение Партнера должно отправлять запрос, для получения персональных данных Пользователя, к **ЦОИД Адаптеру**, а не к Aitu Passport.
{% endhint %}

Для доступа к методу [/v1/personal-data](https://coid-adapter-docs.passport.aitu.io/#operation/getPersonalData) используется basic Autorization, в качестве логина должно передаваться значение параметра **ACCESS\_LOGIN**, в качестве пароля должно передаваться значение параметра **ACCESS\_PERSONAL\_DATA\_PASSWORD**. Параметры задаются при настройке Адаптера ЦОИД, см. статью "[Настройка Адаптера ЦОИД](/aituapps/aitu-passport/integraciya-s-aitu-passport/aitu-passport-greater-than-coid.md#nastroika-adaptera-coid)"

Представление процесса получения персональных данных Пользователя партнера из ЦОИД через ЦОИД Адаптер см. стрелки 25 - 30 на [схеме](#skhema-polucheniya-dannykh-polzovatelya-cherez-coid)

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

{% hint style="warning" %}
Данные пользователя будут переданы в приложение Партнера только в том случае, если Партнер является объектом фин., мониторинга в РК и у Партнера заключен договор присоединения к ЦОИД КЦМР. Подробней описано в статье [Aitu Passport -> ЦОИД](/aituapps/aitu-passport/integraciya-s-aitu-passport/aitu-passport-greater-than-coid.md)
{% endhint %}

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

<table><thead><tr><th width="74">№</th><th width="119">Параметр</th><th width="105">Required</th><th width="78">Тип</th><th width="156">Описание</th><th>Источник</th></tr></thead><tbody><tr><td>1</td><td>iin</td><td>Required</td><td>String</td><td>ИИН Пользователя</td><td>id_token -> объект idpc_verification -> iin</td></tr><tr><td>2</td><td>requestId</td><td>Required</td><td>String</td><td>Идентификатор запроса</td><td>id_token -> объект idpc_verification -> iin</td></tr></tbody></table>

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

<table><thead><tr><th width="91">№</th><th width="139">Параметр</th><th width="88">Тип</th><th>Описание</th></tr></thead><tbody><tr><td><strong>1</strong></td><td><strong>person</strong></td><td><strong>Object</strong></td><td><strong>Объект, содержащий данные пользователя, полученные из ЦОИД</strong></td></tr><tr><td>1.1</td><td>  documents</td><td>Array</td><td>Массив с данными документов пользователя. Документ передается в виде объекта Documents. Описание объекта Documents см. раздел "<a href="#undefined">Объект Documents</a>"</td></tr><tr><td>1.2</td><td>  name</td><td>String</td><td>Имя пользователя</td></tr><tr><td>1.3</td><td>  surname</td><td>String</td><td>Фамилия пользователя</td></tr><tr><td>1.4</td><td>  patronymic</td><td>String</td><td>Отчество пользователя</td></tr><tr><td>1.5</td><td>  birthDate</td><td>Date</td><td>Дата рождения пользователя</td></tr><tr><td>1.6</td><td>  iin</td><td>String</td><td>ИИН пользователя</td></tr><tr><td>1.7</td><td>  birthPlace</td><td>Object</td><td>Объект BirthPlace, содержащий данные о месте рождения пользователя. Описание объекта BirthPlace см. раздел "<a href="#obekt-birthplace">Объект BirthPlac</a>e"</td></tr><tr><td>1.8</td><td>  lifeStatus</td><td>Object</td><td>Объект DictionaryItem, содержащий данные из справочника "Жизненный статус пользователя". Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>1.9</td><td>gender</td><td>Object</td><td>Пол - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>1.10</td><td>nationality</td><td>Object</td><td>Национальность - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>1.11</td><td>citizenship</td><td>Object</td><td>Гражданство - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>1.12</td><td>regAddress</td><td>Object</td><td>Адрес регистрации - объект RegAddress. Описание объекта RegAddress см. раздел "<a href="#undefined">Объект RegAddress</a>"</td></tr></tbody></table>

#### Объект Documents

<table><thead><tr><th width="78">№</th><th width="172">Параметр</th><th width="101">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>name</td><td>String</td><td>Имя владельца документа</td></tr><tr><td>2</td><td>surname</td><td>String</td><td>Фамилия владельца документа</td></tr><tr><td>3</td><td>patronymic</td><td>String</td><td>Отчество владельца документа</td></tr><tr><td>4</td><td>number</td><td>String</td><td>Номер документа</td></tr><tr><td>5</td><td>birthDate</td><td>Date</td><td>Дата рождения владельца документа</td></tr><tr><td>6</td><td>beginDate</td><td>Date</td><td>Дата начала действия документа</td></tr><tr><td>7</td><td>endDate</td><td>Date</td><td>Дата окончания дествия документа</td></tr><tr><td>8</td><td>status</td><td>Object</td><td>Статус документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>9</td><td>issueOrganization</td><td>Object</td><td>Организация, выдавшая документ - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>10</td><td>type</td><td>Object</td><td>Тип документа - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr></tbody></table>

#### Объект BirthPlace

<table><thead><tr><th width="63">№</th><th width="127">Параметр</th><th width="104">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>city</td><td>String</td><td>Город</td></tr><tr><td>2</td><td>country</td><td>Object</td><td>Страна - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>3</td><td>district</td><td>Object</td><td>Район - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>4</td><td>region</td><td>Object</td><td>Область - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr></tbody></table>

#### Объект DictionaryItem

<table><thead><tr><th width="70">№</th><th width="140">Параметр</th><th width="109">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>Кодовое обозначение справочного значения</td></tr><tr><td>2</td><td>nameKz</td><td>String</td><td>Наименование справочного значения на казахском языке</td></tr><tr><td>3</td><td>nameRu</td><td>String</td><td>Наименование справочного значения на русском языке</td></tr><tr><td>4</td><td>changeDate</td><td>DateTime</td><td>Дата и время изменения справочного значения</td></tr></tbody></table>

#### Объект RegAddress

<table><thead><tr><th width="67">№</th><th width="133">Параметр</th><th width="116">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>building</td><td>String</td><td>Номер дома</td></tr><tr><td>2</td><td>street</td><td>String</td><td>Улица</td></tr><tr><td>3</td><td>city</td><td>String</td><td>Город</td></tr><tr><td>4</td><td>country</td><td>Object</td><td>Страна - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>5</td><td>district</td><td>Object</td><td>Район - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>6</td><td>region</td><td>Object</td><td>Область - объект DictionaryItem, содержащий данные из справочника. Описание объекта DictionaryItem см. раздел "<a href="#undefined">Объект DictionaryItem</a>"</td></tr><tr><td>7</td><td>beginDate</td><td>Date</td><td>Дата начала регистрации</td></tr></tbody></table>

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

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

#### Компонент VerifyResponse

<table><thead><tr><th width="86">N</th><th width="189">Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>minConfidenceLevel</td><td><code>number</code>(<code>double)</code></td><td>Минимальное значение коэффициента схожести лиц. Передается обязательно</td></tr><tr><td>2</td><td>photo</td><td>string (base64)</td><td>Эталонное фото с изображением лица</td></tr><tr><td>3</td><td>requisites</td><td>компонент Organization</td><td>Данные организации запросившей биометрическую идентификацию</td></tr></tbody></table>

#### Компонент Organization

<table><thead><tr><th width="70">N</th><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>1</td><td>name</td><td>string</td><td>Наименование организации</td></tr><tr><td>2</td><td>bin</td><td>string</td><td>БИН организации</td></tr></tbody></table>

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

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

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

* ACCESS\_LOGIN: **admin**&#x20;
* ACCESS\_PERSONAL\_DATA\_PASSWORD: **coidtestpassword**

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

<table><thead><tr><th width="186">ИИН</th><th>Сообщение об ошибке для пользователя</th></tr></thead><tbody><tr><td>000000000001</td><td>Ваше фото не совпадает с фото из государственной базы данных. Проверьте правильность введенного ИИН или попробуйте пройти видео-проверку заново</td></tr><tr><td>000000000002</td><td>Проверку можно пройти при достижении 16 летнего возраста</td></tr><tr><td>000000000003</td><td>ИИН не найден в базе данных государственного органа. Проверку можно пройти при наличии гражданства Республики Казахстан или Вида на жительство. Проверьте правильность ввода ИИН или обратитесь в службу поддержки</td></tr><tr><td>000000000004</td><td>Ошибка на сервисе государственного органа (сервис не доступен)</td></tr><tr><td>000000000005</td><td>Ошибка на сервисе государственного органа (Партнеру запрещен доступ к данным)</td></tr></tbody></table>

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

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

* [Термины и определения](/aituapps/aitu-passport/osnovnye-terminy-i-opredeleniya.md)
* [Окружение системы Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/resursy-dlya-integracii.md)
* [Регистрация Партнера](/aituapps/aitu-passport/integraciya-s-aitu-passport/registraciya-v-klientskoi-konsoli.md)
* [Создание сервиса Партнера](/aituapps/aitu-passport/integraciya-s-aitu-passport/sozdanie-servisa.md)
* [Список сервисов Aitu Passport](/aituapps/aitu-passport/integraciya-s-aitu-passport/spisok-servisov-aitu-passport-scope.md)
* [Авторизация](/aituapps/aitu-passport/integraciya-s-aitu-passport/avtorizaciya.md#avtorizaciya-v-aitu-passport)
* [Настройка Адаптера ЦОИД](/aituapps/aitu-passport/integraciya-s-aitu-passport/aitu-passport-greater-than-coid.md#nastroika-adaptera-coid)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aitu.io/aituapps/aitu-passport/integraciya-s-aitu-passport/aitu-passport-greater-than-coid/poluchenie-dannykh-polzovatelya-iz-coid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.