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

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

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

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 символов

Тело запроса

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	No	Данные документа, удостоверяющего личность
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	NO	Отчество
gender	String	YES	Пол. Передается: F - для женщин M - для мужчин
dateOfBirth	Data	YES	Дата рождения
placeOfBirth	String	NO	Место рождения
nationality	String	YES	Указывается страна гражданства для документов: RESIDENCE_PERMIT и FOREIGN_PASSPORT Указывается национальность для УЛ РК документа ID_CARD
issueDate	Data	NO	Дата выдачи
expireDate	Data	YES	Срок действия
authority	String	NO	Орган выдавший документ
identificationNumber	String	NO	ИИН
errorInfo	Object	No	Данные об ошибке
eventType	String	Yes	Событие/этап на котором произошла ошибка
error	String	Yes	Код ошибки
errorMessage	String	Yes	Текст ошибки

Ошибки

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

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

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

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

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