# Рекомендации по реализации интеграции {% hint style="info" %} Для использования сервиса управления облачной ЭЦП Esign необходимо, чтобы Участник: 1\. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в [registraciya-i-avtorizaciya-v-portale-npk](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovym-portalom-npk/registraciya-i-avtorizaciya-v-portale-npk "mention")) 2\. Подал заявку на подключение к ЦОИД (см. подробнее в [podklyuchenie-k-coid](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/podklyuchenie-k-coid "mention")) 3\. Зарегистрировал приложение Участника (см. подробнее в [polzovatelyam-api-dobavlenie-i-ispolzovanie-prilozheniya](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovymi-servisami/polzovatelyam-api-dobavlenie-i-ispolzovanie-prilozheniya "mention")) {% endhint %} {% hint style="warning" %} Подписание документов ЭЦП доступно для людей, у которых имеется как минимум один из следующих документов: * удостоверение личности гражданина РК * паспорт гражданина РК * вид на жительство иностранца в РК * удостоверение лица без гражданства (казахстанского образца) {% endhint %} ## Рекомендация: отображение инструкции перед началом биометрии Перед запуском процесса биометрической аутентификации **рекомендуется отобразить пользователю инструкцию** с визуальными примерами и текстовыми пояснениями. Это поможет обеспечить корректное прохождение биометрии и повысить процент успешных распознаваний.\ **Основные рекомендации для пользователя** * **Лицо должно быть хорошо освещено.**\ Избегайте резкого света и теней на лице. * **Не должно быть яркого света за спиной.**\ Например, открытого окна или лампы позади. * **Держите устройство ровно и не двигайтесь.**\ Камера должна быть расположена на уровне лица * **В кадре не должно быть других лиц.**\ Лицо должно быть единственным объектом в кадре.

Пример интерфейса

## Общее описание процесса подписания документа ЭЦП

Общая диаграмма взаимодействия при подписании документов

1. Пользователь инициирует получение услуги в приложении Участника, для которой требуется подписание документа ЭЦП. 2. При отправке запроса на аутентификацию личности - ЦОИД осуществляет проверку соответствия номера телефона и ИИН в базе пользователей ЦОИД, а также в Базе мобильных граждан (БМГ) в случае, если указанный номер в запросе уже привязан к другому ИИН в базе пользователей ЦОИД.
3. В случае формирования ошибки "PHONE\_BELONGS\_TO\_ANOTHER\_IIN\_IN\_BMG" процедура аутентификации не проводится. В данном случае Участнику необходимо отобразить пользователю страницу с уведомлением о том, что указанный номер телефона зарегистрирован за другим ИИН, а также предоставить рекомендацию об обновлении данных в БМГ. {% hint style="info" %} **Рекомендации по тексту уведомления:** "Введенный номер телефона закреплен за другим ИИН. Пожалуйста, обновите номер телефона в Базе мобильных граждан, обратившись в единый контакт-центр 1414 на портале egov.kz" {% endhint %}

Пример для отображения в случае если номер телефона привязан к другому ИИН

**Загрузка документов для подписания** 4. Перед началом процесса подписания приложение Участника предварительно загружает документы, которые должны быть подписаны ЭЦП пользователя 5. Сервис поддерживает возможность множественного подписания электронных документов, при этом число подписантов не ограничено. {% hint style="warning" %} **Для использования функции множественного подписания при загрузке документа(-ов) необходимо указать параметр:** "allowMultipleSignatures": true Остальные методы реализации остаются без изменений. Процесс множественного подписания реализуется по принципу последовательного наложения подписей: * Документ подписывается первой стороной. * Сформированный подписанный файл (`signedDocument`) передаётся следующему подписанту. * Второй подписант загружает уже подписанный документ и накладывает свою подпись, не изменяя ранее добавленные подписи. * Аналогичным образом к документу последовательно добавляются подписи всех участников процесса. **Сценарий подписания и последовательность подписантов определяется Участником самостоятельно.** {% endhint %}
Загрузка документа для подписания Для загрузки документа для подписания Участнику необходимо: 1\) Реализовать формирование запроса отправки документа. Описание используемого для этого метода приведено в . 2\) Реализовать отправку сформированного запроса и получение в ответ идентификатора документа (id) для последующего его подписания.
{% hint style="warning" %} Срок хранения загруженного, но не подписанного документа составляет 24 часа с момента загрузки. По истечении 24 часов документ удаляется. Максимальный размер документа составляет 30 мб. Документов может быть загружено неограниченное количество. {% endhint %} {% hint style="info" %} Идентификатор загруженного документа используется при последующем запросе подписания документов, а также при получении подписанных документов. {% endhint %} {% hint style="info" %} Поддерживается подписание электронных документов в форматах PDF, XML, BLOB (документ в виде массива байт). {% endhint %} **Подписание документов пользователем** Для подписания документов ЭЦП приложение Участника перенаправляет клиента на Сервис управления облачной ЭЦП Esign. {% hint style="warning" %} Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров: *webView\.settings.allowContentAccess = true; webView\.settings.mediaPlaybackRequiresUserGesture = false; webView\.settings.domStorageEnabled = true* WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте webView указать данную настройку. {% endhint %}

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

{% hint style="warning" %} В IOS необходимо использовать SafariWebView. WKWebView не поддерживается. {% endhint %}
Перенаправления пользователя для подписания ЭЦП Для перенаправления пользователя для подписания документов ЭЦП Участнику необходимо: 1\) Реализовать получение URL-адреса для перенаправления пользователя. Описание метода «Получить URL-адрес для перенаправления клиента» (POST /v1/auth/generate-user-url) приведено в . Для подписания документов ЭЦП для физических лиц используется значение scopes **esign.** При этом, в параметре esignScopeData передаются идентификаторы документов, предварительно загруженных Участником. Значение **esign,** может использоваться совместно со значениями scopes для персональных данных и верификации физического лица (см. подробнее в [rekomendacii-po-realizacii-integracii](https://docs.npck.kz/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/rekomendacii-po-realizacii-integracii "mention")): 2\) Реализовать перенаправление пользователя на полученный URL-адрес для прохождения аутентификации пользователем и последующего подписания документов его ЭЦП.
{% hint style="info" %} Услуга, предоставляемая ЦОИД, определяется значениями, указанными в параметре scopes при формировании запроса на получение URL-адреса для перенаправления пользователя в ЦОИД: *Получение персональных данных:* * iin - доступ к ИИН пользователя * full\_name - доступ к ФИО пользователя * first\_name - доступ к имени пользователя * last\_name - доступ к фамилии пользователя * middle\_name - доступ к отчеству пользователя * date\_of\_birth - доступ к дате рождения пользователя * place\_of\_birth - доступ к месту рождения пользователя (описание объекта в [#ref130980979](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#ref130980979 "mention")) * gender - доступ к полу пользователя (описание объекта см. в [#toc165886969](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#toc165886969 "mention")) * nationality - доступ к национальности пользователя (описание объекта см. в [#toc165886969](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#toc165886969 "mention")) * registration\_address - доступ к адресу регистрации пользователя (описание объекта см. в [#id-3.-struktura-obekta-registration\_address-adres-registracii](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#id-3.-struktura-obekta-registration_address-adres-registracii "mention")) * document\_number - доступ к информации о номере документа, удостоверяющего личность пользователя * document\_type - доступ к типу документа, удостоверяющего личность пользователя (описание объекта см. в [#toc165886969](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#toc165886969 "mention")) * document\_issue\_date - доступ к информации о дате выдачи документа, удостоверяющего личность пользователя * document\_expiry\_date - доступ к дате истечения срока действия документа, удостоверяющего личность пользователя * document\_issue\_place - доступ к информации о том, кем был выдан документ, удостоверяющий личность пользователя (описание объекта см. в [#toc165886969](https://docs.npck.kz/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov#toc165886969 "mention")) *Верификация физического лица:* * openid - если необходима только верификация личности пользователя (без предоставления доступа к персональным данным), то в параметре scopes должно быть указано только значение openid * antifraud - доступ к информации о том, не числится ли пользователь в реестре лиц, причастных к мошенническим операциям. Статусы могут быть * grey — подозреваемый мошенник * black — мошенник * drug\_grey — подозреваемый в деятельности, связанной с наркотиками {% endhint %} {% hint style="warning" %} Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут. {% endhint %} 6. Пользователю отображается форма аутентификации ЦОИД. Пользователь проходит двухфакторную аутентификацию личности. Подписание документов ЭЦП осуществляется после проведения аутентификации личности пользователя. 7. После успешной аутентификации пользователя, ему отображается информация о документах, направленных для подписания. 8. Пользователь подписывает документы ЭЦП. {% hint style="info" %} Пользователь может отклонить подписание документов ЭЦП. Если Пользователь отклоняет подписание документов ЭЦП или происходит ошибка, то Пользователь будет направлен на указанный при запросе URL-адреса для перехода в ЦОИД (на шаге 4) **redirectUri**, с указанием кода ошибки, по следующему шаблону: `[redirectUri]?errorCode=[error code]&state=[state]` В таком случае процесс завершается, код авторизации не предоставляется. {% endhint %} 9. После того, как Пользователь выполнит все действия на стороне ЦОИД, осуществляется его возврат в приложение Участника. {% hint style="info" %} Если аутентификация Пользователя проходит успешно и он подписывает документы ЭЦП, то Пользователь перенаправляется обратно в приложение Участника (на указанный в запросе URL-адреса для перехода в ЦОИД redirectUri) с одноразовым кодом авторизации (code), по следующему шаблону: `[redirectUri]?code=[authorization code]&state=[state]` {% endhint %} {% hint style="warning" %} Код авторизации является одноразовым. Время действия кода авторизации (время «жизни») составляет 300 секунд. {% endhint %} {% hint style="warning" %} Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink). {% endhint %} 10. Приложение Участника получает токен доступа, используя полученный на предыдущем шаге код авторизации.
Получение токена Для получения токена доступа Участнику необходимо: 1\. Реализовать формирование запроса получения токена, используя полученный код авторизации. Описание используемого для этого метода приведено в . {% hint style="info" %} Срок действия `access_token` зависит от того, какие данные запрашиваются (scope): * Для аутентификации личности клиента через FinID (`openid`, `iin`, `first_name` и т.д.) — **12 часов**. * Для работы с облачной ЭЦП (`esign`, `organization_esign`) — **5 минут**. * Для получения информации о банковских счетах клиента (через Межбанковскую систему обмена информацией по открытым программным интерфейсам (Open API)) (`accounts`, `account_balance`, `account_transactions`) — **30 дней**. {% endhint %} 2\. Реализовать отправку сформированного запроса и получение токена. Токен доступа имеет формат JWT (см. RFC 7519) *Примечание: Дополнительно доступен метод получения списка публичных ключей для проверки токена (см.* [*https://auth-openapi.npck.kz/#tag/Auth/operation/wellKnown*](https://auth-openapi.npck.kz/#tag/Auth/operation/wellKnown)*).* *Дополнительно доступен метод получения* электронного документа по результатам проведения биометрической идентификации (см. ). *Дополнительно доступен опциональный метод интроспекции токена (см описание* [*https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect*](https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect)*). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метаданных.* Пример данных токена - **id\_token:** ```json { "active": true, "sub": "1234567890123", "document_number": "{\"document_number\":\"040100767\"}", "gender": "{\"gender\":{\"code\":\"1\",\"nameRu\":\"Мужской\",\"nameKz\":\"Ер\"}}", "openid": "{\"user_id\":379678}", "date_of_birth": "{\"date_of_birth\":\"1900-04-24\"}", "iss": "https://auth.npck.kz", "last_name": "{\"last_name\":\"ИВАНОВ\"}", "middle_name": "{\"middle_name\":\"ИВАНОВИЧ\"}", "sid": "07afcc54-5eb6-405d-b419-ab2b96b76e47", "iin": "{\"iin\":\"1234567890123\"}", "place_of_birth": "{\"place_of_birth\":{\"country\":{\"code\":\"398\",\"nameRu\":\"КАЗАХСТАН\",\"nameKz\":\"ҚАЗАҚСТАН\"},\"district\":{\"code\":\"1910\",\"nameRu\":\"АЛМАТЫ\",\"nameKz\":\"АЛМАТЫ\"},\"region\":{\"code\":\"1910264\",\"nameRu\":\"БОСТАНДЫКСКИЙ\",\"nameKz\":\"БОСТАНДЫҚ\"},\"foreignData\":{\"districtName\":null,\"regionName\":null},\"city\":\"-\",\"birthTeCodeAR\":null}}", "aud": [ "8e7179f7-ff5a-4342-a790-a5d2ec8ea658" ], "document_expiry_date": "{\"document_expiry_date\":\"2026-05-12\"}", "full_name": "{\"full_name\":\"ИВАНОВ ИВАН ИВАНОВИЧ\"}", "nationality": "{\"nationality\":{\"code\":\"001\",\"nameRu\":\"РУССКИЙ\",\"nameKz\":\"ОРЫС\"}}", "azp": "8e7179f7-ff5a-4342-a790-a5d2ec8ea658", "auth_time": 1761201137593, "document_issue_place": "{\"document_issue_place\":{\"code\":\"002\",\"nameRu\":\"МИНИСТЕРСТВО ВНУТРЕННИХ ДЕЛ РК\",\"nameKz\":\"ҚР ІШКІ ІСТЕР МИНИСТРЛІГІ\"}}", "registration_address": "{\"registration_address\":{\"country\":{\"code\":\"398\",\"nameRu\":\"КАЗАХСТАН\",\"nameKz\":\"ҚАЗАҚСТАН\"},\"district\":{\"code\":\"1910\",\"nameRu\":\"АЛМАТЫ\",\"nameKz\":\"АЛМАТЫ\"},\"region\":{\"code\":\"1910262\",\"nameRu\":\"АУЭЗОВСКИЙ\",\"nameKz\":\"ӘУЕЗОВ\"},\"foreignData\":{\"districtName\":null,\"regionName\":null},\"city\":null,\"street\":\"МИКРОРАЙОН Аксай-15\",\"building\":\"20\",\"corpus\":null,\"flat\":\"8\",\"beginDate\":\"2018-04-25T00:00:00.000+00:00\",\"endDate\":null,\"status\":{\"code\":\"1\",\"nameRu\":\"Зарегистрирован\",\"nameKz\":\"Тіркелді\",\"changeDate\":\"2013-11-29T17:36:46.000+00:00\"},\"invalidity\":{\"code\":\"0\",\"nameRu\":\"Зарегистрирован\",\"nameKz\":\"Тіркелді\",\"changeDate\":\"2013-11-29T17:36:46.000+00:00\"},\"arCode\":\"1201300109160222\"}}", "document_issue_date": "{\"document_issue_date\":\"2016-05-13\"}", "exp": 1761203091, "iat": 1761201291, "first_name": "{\"first_name\":\"ИВАН\"}", "document_type": "{\"document_type\":{\"code\":\"002\",\"nameRu\":\"УДОСТОВЕРЕНИЕ РК\",\"nameKz\":\"ҚР ЖЕКЕ КУӘЛІГІ\"}}", "client_id": "8e7179f7-ff5a-4342-a790-a5d2ec8ea658" } ```
{% hint style="info" %} Токен доступа необходим Участнику для последующего получения информации о подписанных документах (шаг 9) {% endhint %} {% hint style="warning" %} Важно! Токен доступа должен сохраняться в тайне и не передаваться в публичный доступ, должен храниться на серверной стороне приложения Участника, и вся обработка, связанная с ним, должна производиться на серверной стороне приложения. {% endhint %} {% hint style="info" %} В параметре access\_token (в формате JWT) , кроме всего прочего, в поле sid (session id) содержится идентификатор сессий пользователя, в рамках которой была проведена аутентификация. Рекомендуется сохранить на своей стороне значение sid. Используя это значение, можно будет получить информацию о сессии аутентификации пользователя (количество попыток прохождения livness-проверки, количество отправленных СМС-кодов, результат и т.д.) . {% endhint %} **Получение подписанных документов** 11. Приложение Участника получает подписанные документы, используя полученный на предыдущем шаге токен доступа.
Получение подписанных документов Для получения подписанных пользователем документов Участнику необходимо: 1\. Реализовать формирование запроса получения подписанных пользователем документов, используя полученный токен доступа. Описание используемого для этого метода приведено в . 2\. Реализовать отправку сформированного запроса и получение перечня подписанных документов. В ответе предоставляется перечень документов подписанных пользователем, включая: идентификатор документа, его наименование, тип, сам подписанный документ в формате base64, дату и время подписания
## Проверка подлинности цифровой подписи Метод проверки валидности ЭЦП зависит от того, документ какого типа был подписан: * для документов в формате BLOB (binary linked object) - используется метод, описание которого приведено в * для документов в формате PDF - используется метод, описание которого приведено в * для документов в формате XML - используется метод, описание которого приведено в {% hint style="warning" %} Электронная подпись не имеет ограниченного срока действия, и её подлинность можно проверить в любой момент. {% endhint %}