> For the complete documentation index, see [llms.txt](https://docs.aitu.io/aituapps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aitu.io/aituapps/aitu-passport/customer-identification-cid-modul/biometricheskaya-autentifikaciya-po-dokumentu.md).

# Биометрическая аутентификация по документу

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

## Основные этапы биометрической аутентификации по  документу в CID:

1\) ИС партнера запрашивает токен по логину и паролю, предоставленному CID

2\) ИС партнера производит старт сессии в CID по полученному токену

3\) СID стартует сессию и отображает пользователю ИС партнера экран выбора типа документа, если в запросе от ИС Парнера не указан тип документа или указано более 1 типа документа.

<figure><img src="/files/kqn6o9VcSacqRD0Alp5K" alt="" width="302"><figcaption></figcaption></figure>

4\) Получение данных документа удостоверяющего личность

4.1) Сканирование документа

Пользователь выбирает тип документа (удостоверение личности гражданина РК, Вид на жительство РК, Паспорт иностранного гражданина) и CID отображает экран сканирования документа. Экран сканирования документа может отображаться сразу после перехода в CID, если указан один тип документа для сканирования в параметрах запроса. В зависимости от выбранного документа сканируется:

* &#x20;2 стороны документа: лицевая и оборотная для удостоверения личности гражданина РК и для вида на жительство иностранного гражданина в РК,
* только одно фото с документа при выборе международного паспорта (паспорт иностранного гражданина)

<div><figure><img src="/files/KlBwIxW3vj1F7orEicBh" alt=""><figcaption></figcaption></figure> <figure><img src="/files/8INEsWxqBGEKcUry1OWZ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/VExxtqXXtU1W5ALzG040" alt=""><figcaption></figcaption></figure> <figure><img src="/files/UIWORdPNpbSsiPYkKcpH" alt=""><figcaption></figcaption></figure></div>

4.2) Сканирование QR/ввод кода цифрового документа

&#x20;Пользователь выбирает "Сканировать QR или ввести код" и CID отображает экран сканирования QR, пользователь может отсканировать QR или выбрать "Ввести код"

<div><figure><img src="/files/beJiGJkjqZwKAIACDSAS" alt="" width="221"><figcaption></figcaption></figure> <figure><img src="/files/B1YZBF5UtTJfEiIo5KZp" alt="" width="220"><figcaption></figcaption></figure></div>

5\) Отображение данных документа

5.1) Если Пользователь осуществляет сканирование документа клиента и  CID распознает данные документа, то отображается экран с данными распознанного документа.&#x20;

5.2) Если Пользователь сканирует QR или вводит код, то CID отправляет запрос для получения даных цифрового документа  и отображает экран с данными документа,  если данные получены из гос., системы "Цифровые документы"

<figure><img src="/files/usCfTEr1SxO0fappzr6r" alt="" width="242"><figcaption></figcaption></figure>

6\) Пользователь подтверждает распознанные данные и CID отображает экран биометрической аутентификации

<figure><img src="/files/itUfJUecnE1LCnhLc21k" alt="" width="239"><figcaption></figcaption></figure>

7\) Пользователь осуществляет  сканирования лица клиента и CID проводит определение живости лица и выделение лучшего кадра

8\) CID проводит сверку фото лица из документа с фото лица, полученного при аутентификации, завершает сессию и передает номер сессии в ИС партнера на указанный URI

9\) ИС - партнера по номеру сессии получает данные сессии (данные документа, результаты биометрической аутентификации)

{% hint style="info" %}
Токен, получаемый ИС партнера для сессии - одноразовый. Период жизни токена составляет 15 минут
{% endhint %}

## Методы взаимодействия

### Получение токена

#### Запрос

{% code overflow="wrap" %}

```java

curl --location 'http://cid.test.supreme-team.tech/api/v1/customer-identification/session-token?identificationType=SCAN_DOCUMENT&redirectUri=https%3A%2F%2Foidcdebugger.com%2Fdebug&state=someState' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Y2lkLWNsaWVudDpwYXNzd29yZA==' \
--data '{
    "documentTypes": ["INTERNATIONAL_PASSPORT"]
}'
```

{% endcode %}

#### Параметры запроса

Заголовок

<table><thead><tr><th width="210">Параметр</th><th width="229">Значение</th><th width="151">Обязательный</th><th>Коментарий</th></tr></thead><tbody><tr><td>identificationType</td><td>SCAN_DOCUMENT</td><td>Нет</td><td>Указатель на запуск сессии биометрической аутентификации по изображению с отсканированного документа, удостоверяющего личность</td></tr><tr><td>redirectUri</td><td>Указывается в ИС Партнера</td><td>Да</td><td><p>ИС Партнера передает ссылку на ресурс, куда CID вернет данные сессии.</p><p>Ограничения - указанная ссылка на ресурс должна быть в списке разрешенных. Партнер за ранее должен предоставить BTSD список uri для включения в список разрешенных</p></td></tr><tr><td>state</td><td>Указывается в ИС Партнера</td><td>Нет</td><td>Состояние системы Партнера которое будет передано CID  в редиректе на ресурс ИС партнера в неизменном состоянии. Длина параметра должна быть не более 500 символов</td></tr></tbody></table>

Параметры запроса

<table><thead><tr><th width="240">Параметр</th><th width="149">Тип</th><th width="154">Обязательный</th><th>Описание</th></tr></thead><tbody><tr><td>documentTypes</td><td>ARRAY (String)</td><td>Нет</td><td><p>Передаются типы документов для сканирования. Если параметр не передан, то пользователь увидит экран с выбором для сканирования следующих типов документов: Удостоверение личности РК, Вид на жительство иностранца РК, Международный паспорт иностранца. В массиве могут быть переданы следующие типы документов: </p><ul><li>RESIDENCE_PERMIT - Вид на жительство РК</li><li>ID_CARD - УЛ гражданина РК</li><li>INTERNATIONA_PASSPORT - международный паспорт иностранца</li></ul><p></p></td></tr><tr><td>confidenceLevel</td><td>String</td><td>Нет</td><td><p>Коэффициент схожести, определенный партнером. Указывается десятичная дробь.</p><p>Допустимое значение должно входить в диапазон от 0,3 до 0,6</p><p>Если параметр не передан, то для процесса биометрической аутентификации берется значение confidenceLevel заданное по умолчанию и равное 0,4</p></td></tr><tr><td>allowFaceMatchFailure</td><td>Boolean</td><td>Нет</td><td><p>Признак низко-рисковой операции, если в параметре передано значение TRUE.</p><p>При низко-рисковой операции в случае, если биометрическая аутентификация будет не пройдена клиентом, то ИС Партнера получит  ответ в котором будут переданы параметры следующих объектов: document, liveness, errorInfo</p></td></tr></tbody></table>

#### Ответ

{% code overflow="wrap" %}

```
{
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uU2VjcmV0IjoiMjI3MmQyODAtZjA4Zi00M2VmLWJkODQtM2E0M2JkZDM1Mjc1IiwiZXhwIjoxNzQyOTgzNzg1fQ.oOptJPqKxv1LMUKfKnNevyx0hyYstjXiNIW2gbwpfAxoTxzoKd8FHYU2UYu-R79o4-1hbjIGNQUmRDW5X2DmQQ"
}
```

{% endcode %}

### Старт сессии

```
https://cid.test.supreme-team.tech?token=$token
```

#### **Структура запроса**

<table data-header-hidden><thead><tr><th width="148"></th><th width="87"></th><th width="159"></th><th></th></tr></thead><tbody><tr><td>Параметр</td><td>Тип</td><td>Обязательный</td><td>Описание</td></tr><tr><td>token</td><td>String</td><td>Yes</td><td>Токен, полученный в методе получения токена</td></tr></tbody></table>

### Получение данных сессии

#### Запрос

```
curl --location 'http://cid.test.supreme-team.tech/api/v1/customer-identification/6cd28065-a96e-40c0-91be-35da38610e1e/identification-result
' \
--header 'Authorization: Basic Y2lkLWNsaWVudDpwYXNzd29yZA==' \
--data ''
```

#### Структура запроса

<table data-header-hidden><thead><tr><th></th><th width="85"></th><th width="95"></th><th></th></tr></thead><tbody><tr><td>Параметр</td><td>Тип</td><td>Обязательный</td><td>Описание</td></tr><tr><td>&#x3C;идентификатор сессии></td><td>String</td><td>Yes</td><td>Уникальный идентификатор сессии в CID</td></tr><tr><td>identification-result</td><td>String</td><td>Yes</td><td><p>Тип запрашиваемых данных.</p><p><a href="https://cid-backend.stage.supreme-team.tech/v1/customer-identification/6cd28065-a96e-40c0-91be-35da38610e1e/identification-result">identification-result</a> - вернуть результат сессии. </p><p>В случае если сессия завершилась успешно, то ИС получит данные документа удостоверяющего личность и данные биометрической аутентификации.</p><p>В случае если сессия завершилась успешно, то ИС получит данные ошибки</p></td></tr></tbody></table>

#### Ответ

Пример - сессия завершена успешно (пользователь прошел биометрическую аутентификацию, данные документа удостоверения личности получены)

```
{
    "sessionId": "6cd28065-a96e-40c0-91be-35da38610e1e",
    "sessionStarted": "2024-03-27T12:10:34.745435Z",
    "sessionEnd": "2024-03-27T12:13:11.813523Z",
    "sessionStatus": "SUCCESS",
    "document": {
        "recognizedDocumentType": "ID_CARD",
        "countryCode": "KAZ",
        "documentNumber": "12345678",
        "firstName": "МАРЖАН",
        "lastName": "ТҰРСЫН",
        "patronymic": "АЛИ",
        "gender": "F",
        "dateOfBirth": "1986-07-12",
        "placeOfBirth": "АЛМАТЫ ОБЛ.",
        "nationality": "ҚАЗАҚ",
        "issueDate": "2020-10-08",
        "expireDate": "2030-10-07",
        "authority": "ҚАЗАҚСТАН РЕСПУБЛИКАСЫ ІІМ",
        "identificationNumber": "860712401756"
    },
    "liveness": {
        "verificationType": "VERIFICATION_3D",
        "selfieConfidenceLevel": 0.91967,
        "creationTime": "2024-03-27T12:13:07.397741Z",
        "responseTime": "2024-03-27T12:13:11.813523Z"
    },
    "errorInfo": null
}
```

Пример - сессия завершена не успешно пользователь завершил сессию (пользователь не прошел процесс получения данных с документа удостоверяющего личность или биометрическую аутентификацию)

```
{
    "sessionId": "bc8f8267-0c1d-44d0-8473-927035688941",
    "sessionStarted": "2024-03-28T07:48:25.045395Z",
    "sessionEnd": "2024-03-28T07:50:52.255556Z",
    "sessionStatus": "FAILED",
    "document": null,
    "liveness": null,
    "errorInfo": {
        "eventType": "LIVENESS_FAILED",
        "error": "CID_9",
        "errorMessage": "The face in the photo and the face on the document did not match, start the whole process again"
    }
}
```

#### Структура ответа

<table data-header-hidden><thead><tr><th width="251"></th><th width="117"></th><th width="100"></th><th></th></tr></thead><tbody><tr><td>Параметр</td><td>Тип</td><td>Обязательный</td><td>Описание</td></tr><tr><td>sessionId</td><td>String</td><td>Yes</td><td>Уникальный идентификатор сессии в CID</td></tr><tr><td>sessionStarted</td><td>DateTime</td><td>Yes</td><td>Дата/время начала сессии в CID</td></tr><tr><td>sessionEnd</td><td>DateTime</td><td>Yes</td><td>Дата/время окончания сессии в CID</td></tr><tr><td>sessionStatus</td><td>String</td><td>Yes</td><td><p>Статус сессии в CID. Может принимать следующие значения:</p><ul><li>SUCCESS - сессия завершена успешно биометрическая аутентификация пройдена</li><li>FAILED - сессия не завершена, остановлена пользователем</li></ul></td></tr><tr><td>document</td><td>Object</td><td>No</td><td>Данные документа, удостоверяющего личность</td></tr><tr><td><ul><li>recognizedDocumentType</li></ul></td><td>String</td><td>YES</td><td><p>Вид документа удостоверяющего личность. Может принимать следующие значения</p><ul><li>RESIDENCE_PERMIT - Вид на жительство РК</li><li>ID_CARD - УЛ гражданина РК</li><li>PA - Международный паспорт</li></ul></td></tr><tr><td><ul><li>countryCode</li></ul></td><td>String</td><td>YES</td><td><p>Код страны (ISO 3166-1 Alfa-3), выдавшей документ</p><ul><li>Для УЛ РК и ВНЖ РК - KAZ</li><li>Для паспортов иностранцев, код указанный в их документах</li></ul></td></tr><tr><td><ul><li>documentNumber</li></ul></td><td>String</td><td>YES</td><td>Номер документа</td></tr><tr><td><ul><li>firstName</li></ul></td><td>String</td><td>YES</td><td>Имя</td></tr><tr><td><ul><li>lastName</li></ul></td><td>String</td><td>YES</td><td>Фамилия</td></tr><tr><td><ul><li>patronymic</li></ul></td><td>String</td><td>NO</td><td>Отчество</td></tr><tr><td><ul><li>gender</li></ul></td><td>String</td><td>YES</td><td><p>Пол. Передается:</p><ul><li>F - для женщин</li><li>M - для мужчин</li></ul></td></tr><tr><td><ul><li>dateOfBirth</li></ul></td><td>Data</td><td>YES</td><td>Дата рождения</td></tr><tr><td><ul><li>placeOfBirth</li></ul></td><td>String</td><td>NO</td><td>Место рождения</td></tr><tr><td><ul><li>nationality</li></ul></td><td>String</td><td>YES</td><td><ul><li>Указывается страна гражданства для документов: RESIDENCE_PERMIT и FOREIGN_PASSPORT</li><li>Указывается национальность для УЛ РК документа ID_CARD</li></ul></td></tr><tr><td><ul><li>issueDate</li></ul></td><td>Data</td><td>NO</td><td>Дата выдачи</td></tr><tr><td><ul><li>expireDate</li></ul></td><td>Data</td><td>YES</td><td>Срок действия</td></tr><tr><td><ul><li>authority</li></ul></td><td>String</td><td>NO</td><td>Орган выдавший документ</td></tr><tr><td><ul><li>identificationNumber</li></ul></td><td>String</td><td>NO</td><td>ИИН</td></tr><tr><td>liveness</td><td>Object</td><td>No</td><td>Данные биометрической аутентификации</td></tr><tr><td><ul><li>verificationType</li></ul></td><td>String</td><td>YES</td><td><p>Тип биометрической верификации примененной CID. </p><ul><li>VERIFICATION_3D - была применена 3D Liveness</li></ul></td></tr><tr><td><ul><li>selfieConfidenceLevel</li></ul></td><td>String</td><td>YES</td><td>Полученный коэффициент схожести лиц при сравнении эталонной фото лица в CID с лучшим кадром из процесса определения витальности лица </td></tr><tr><td><ul><li>creationTime</li></ul></td><td>DateTime</td><td>YES</td><td>Дата создания медиа материалов (прохождение лайвнеса)</td></tr><tr><td><ul><li>responseTime</li></ul></td><td>DateTime</td><td>YES</td><td>Дата/время формирования ответа</td></tr><tr><td>errorInfo</td><td>Object</td><td>No</td><td>Данные об ошибке</td></tr><tr><td><ul><li>eventType</li></ul></td><td>String</td><td>Yes</td><td>Событие/этап на котором произошла ошибка</td></tr><tr><td><ul><li>error</li></ul></td><td>String</td><td>Yes</td><td>Код ошибки</td></tr><tr><td><ul><li>errorMessage</li></ul></td><td>String</td><td>Yes</td><td>Текст ошибки</td></tr></tbody></table>

#### Ошибки

Перечень ошибок см., статью [Ошибки сервисов CID](/aituapps/aitu-passport/customer-identification-cid-modul/oshibki-servisov-cid.md)

### Получение медиа-данных сессии

В рамках данной сессии в CID фиксируются следующие медиа-данные

* Лучший снимок с изображением лица;
* Видо-ролик определеия живости лица;
* Фото документа удостоверяющеего личнность клиента.

Описание методов получения медиа-данных см., статью[ ](#poluchenie-media-dannykh-sessii)[Получение медиа-данных сессии](#poluchenie-media-dannykh-sessii)