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

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

## Основные этапы биометрической аутентификации по  документу в 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)


---

# 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/customer-identification-cid-modul/biometricheskaya-autentifikaciya-po-dokumentu.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.