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

Сервис предназначен для сканирования и распознавания документа, удостоверяющего личность: удостоверение личности гражданина РК, вид на жительство иностранца РК, международный паспорт иностранца.

Основные этапы процесса распознавания:

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

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

3) СID стартует сессию и отображает экран сканирования документа

4) Пользователь осуществляет сканирование документа, подтверждает результат распознавания

5) CID завершает сессию и передает номер сессии в ИС партнера на указанный URI

6) ИС - партнера по номеру сессии получает данные сессии (отсканированный документ и распознанные данные)

Токен, получаемый ИС партнера для сессии - одноразовый. Период жизни токена составляет 15 минут

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

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

Запрос

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

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

Заголовок

Параметр	Значение	Обязательный	Коментарий
identificationType	SCAN_DOCUMENT_ONLY	Да	Указатель на запуск сессии сканирования документа
redirectUri	Указывается в ИС Партнера	Да	С Партнера передает ссылку на ресурс, куда CID вернет данные сессии. Ограничения - указанная ссылка на ресурс должна быть в списке разрешенных. Партнер за ранее должен предоставить BTSD список uri для включенния в список разрешенных
state	Указывается в ИС Партнера	Нет	Состояние системы Партнера которое будет передано CID в редиректе на ресурс ИС партнера в неизменном состоянии. Длина параметра должна быть не более 500 символов

Параметр

Значение

Обязательный

Коментарий

identificationType

SCAN_DOCUMENT_ONLY

Да

Указатель на запуск сессии сканирования документа

redirectUri

Указывается в ИС Партнера

Да

С Партнера передает ссылку на ресурс, куда CID вернет данные сессии.

Ограничения - указанная ссылка на ресурс должна быть в списке разрешенных. Партнер за ранее должен предоставить BTSD список uri для включенния в список разрешенных

state

Указывается в ИС Партнера

Нет

Состояние системы Партнера которое будет передано CID в редиректе на ресурс ИС партнера в неизменном состоянии. Длина параметра должна быть не более 500 символов

Тело запроса

documentType

String

Да

Тип документа для сканирования:

RESIDENCE_PERMIT - Вид на жительство РК
ID_CARD - УЛ гражданина РК
INTERNATIONAL_PASSPORT - Международный паспорт

Ответ

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

Старт сессии

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

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

Параметр

Тип

Обязательный

Описание

token

String

Yes

Токен, полученный в методе получения токена

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

Запрос

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

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

Параметр

Тип

Обязательный

Описание

<идентификатор сессии>

String

Yes

Уникальный идентификатор сессии в CID

identification-result

String

Yes

Тип запрашиваемых данных.

identification-result - вернуть результат сессии.

В случае если сессия завершилась успешно, то ИС получит данные отсканированного документа.

В случае если сессия завершилась успешно, то ИС получит данные ошибки

Ответ

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

{
    "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"
    },
    "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": "ERROR_TYPE",
        "error": "CID_23",
        "errorMessage": "The description of error"
    }
}

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

Параметр

Тип

Обязательный

Описание

sessionId

String

Yes

Уникальный идентификатор сессии в CID

sessionStarted

DateTime

Yes

Дата/время начала сессии в CID

sessionEnd

DateTime

Yes

Дата/время окончания сессии в CID

sessionStatus

String

Yes

Статус сессии в CID. Может принимать следующие значения:

SUCCESS - сессия завершена успешно биометрическая аутентификация пройдена
FAILED - сессия не завершена, остановлена пользователем

document

Object

Данные документа, удостоверяющего личность

recognizedDocumentType

String

YES

Вид документа удостоверяющего личность. Может принимать следующие значения

RESIDENCE_PERMIT - Вид на жительство РК
ID_CARD - УЛ гражданина РК
PA - Международный паспорт

countryCode

String

YES

Код страны (ISO 3166-1 Alfa-3), выдавшей документ

Для УЛ РК и ВНЖ РК - KAZ
Для паспортов иностранцев, код указанный в их документах

documentNumber

String

YES

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

firstName

String

YES

Имя

lastName

String

YES

Фамилия

patronymic

String

Отчество

gender

String

YES

Пол. Передается:

F - для женщин
M - для мужчин

dateOfBirth

Data

YES

Дата рождения

placeOfBirth

String

Место рождения

nationality

String

YES

Указывается страна гражданства для документов: RESIDENCE_PERMIT и FOREIGN_PASSPORT
Указывается национальность для УЛ РК документа ID_CARD

issueDate

Data

Дата выдачи

expireDate

Data

YES

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

authority

String

Орган выдавший документ

identificationNumber

String

ИИН

errorInfo

Object

Данные об ошибке

eventType

String

Yes

Событие/этап на котором произошла ошибка

error

String

Yes

Код ошибки

errorMessage

String

Yes

Текст ошибки

Ошибки

Перечень ошибок см., статью Ошибки сервисов CID

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

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

Фото отсканированного документа.

Описание методов получения медиа-данных см., статью Получение медиа-данных сессии

PreviousБиометрическая аутентификация по эталонной фото, полученной от ИС партнера NextПолучение медиа-данных сессии

Last updated 2 months ago