> For the complete documentation index, see [llms.txt](https://docs.npck.kz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.npck.kz/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign/dlya-podpisaniya-dokumentov-yuridicheskimi-licami/rekomendacii-po-realizacii-integracii.md).
# Рекомендации по реализации интеграции
{% hint style="info" %}
Для использования сервиса управления облачной ЭЦП Esign для юридических лиц необходимо, чтобы Участник:
1\. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в [3. Регистрация и авторизация в Портале НПК](/registraciya-i-avtorizaciya/3.-registraciya-i-avtorizaciya-v-portale-npk.md))
2\. Подал заявку на подключение к ЦОИД (см. подробнее в [5.1 Подключение к ЦОИД](/registraciya-i-avtorizaciya/5.-podacha-zayavki-na-podklyuchenie-k-servisam/5.1-podklyuchenie-k-coid.md))
3\. Зарегистрировал приложение Участника (см. подробнее в [6. Добавление и использование приложения](/registraciya-i-avtorizaciya/6.-dobavlenie-i-ispolzovanie-prilozheniya.md))
4. Зарегистрировал матрицу полномочий (см. подробнее в [Матрица полномочий](/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign/dlya-podpisaniya-dokumentov-yuridicheskimi-licami/matrica-polnomochii.md))
{% 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 organization\_esign**.**
При этом, в параметре organizationEsignScopeData передаются идентификаторы документов, предварительно загруженных Участником.
Значение organization\_esign**,** может использоваться совместно со значениями scopes для персональных данных и верификации физического лица (см. подробнее в [Рекомендации по реализации интеграции](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/rekomendacii-po-realizacii-integracii.md)):
2\) Реализовать перенаправление пользователя на полученный URL-адрес для прохождения аутентификации пользователем и последующего подписания документов его ЭЦП.
{% hint style="info" %}
Услуга, предоставляемая ЦОИД, определяется значениями, указанными в параметре `scopes` при формировании запроса на получение URL-адреса для перенаправления пользователя в ЦОИД.
*Получение персональных данных:*
* iin - доступ к ИИН пользователя
* full\_name - доступ к ФИО пользователя
* first\_name - доступ к имени пользователя
* last\_name - доступ к фамилии пользователя
* middle\_name - доступ к отчеству пользователя
* date\_of\_birth - доступ к дате рождения пользователя
* place\_of\_birth - доступ к месту рождения пользователя (описание объекта в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#ref130980979))
* gender - доступ к полу пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969))
* nationality - доступ к национальности пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969))
* registration\_address - доступ к адресу регистрации пользователя (описание объекта см. в [/pages/01xK7ZFhDPTSZqD3IIxW#id-3.-struktura-obekta-registration\_address-adres-registracii](https://docs.npck.kz/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign/dlya-podpisaniya-dokumentov-yuridicheskimi-licami/pages/01xK7ZFhDPTSZqD3IIxW#id-3.-struktura-obekta-registration_address-adres-registracii "mention"))
* document\_number - доступ к информации о номере документа, удостоверяющего личность пользователя
* document\_type - доступ к типу документа, удостоверяющего личность пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969))
* document\_issue\_date - доступ к информации о дате выдачи документа, удостоверяющего личность пользователя
* document\_expiry\_date - доступ к дате истечения срока действия документа, удостоверяющего личность пользователя
* document\_issue\_place - доступ к информации о том, кем был выдан документ, удостоверяющий личность пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969))
*Верификация физического лица:*
* openid - если необходима только верификация личности пользователя (без предоставления доступа к персональным данным), то в параметре scopes должно быть указано только значение openid
* antifraud - доступ к информации о том, не числится ли пользователь в реестре лиц, причастных к мошенническим операциям. Статусы могут быть:
Статусы antifraud
| Код статуса | Название | Описание |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GREY | Подозреваемый мошенник | Субъект выявлен в рамках мошеннических операций без подтверждения. Усиленная проверка, возможная приостановка операций и мониторинг. |
| BLACK | Мошенник | Подтверждённое мошенничество. Отказ в операциях, блокировка в рамках законодательства. |
| DROPPER | Дроппер | Лицо, предоставившее реквизиты или счёт третьим лицам. Ограничение расходных операций, выяснение источников средств. |
| VICTIM | Пострадавший | Информационная категория для фиксации пострадавшей стороны. Ограничения не применяются. |
| WITNESS | Свидетель | Лицо, ранее фигурировавшее в инциденте, но не подтвердившее участие. Используется для разблокировки и исключения из списков. |
| WHITE\_LIST | Белый список | Субъекты, которые не должны попадать под блокирующие категории: БВУ, финансовые организации, маркетплейсы, торговые магазины и др. |
| POTENCIAL\_VICTIM | Потенциальная жертва | Лица, которые могут быть атакованы мошенниками. |
| DRUG\_GREY | Подозреваемый наркопреступник | Подозрение выявлено финансовой организацией по наркотической тематике. Ограничение операций, регистрация инцидента. |
| DRUG\_CEPI\_GREY | Подозреваемый наркопреступник (ССЭП) | Подозрение по линии ССЭП/СЭР. Ограничение операций, ожидание результатов проверки. |
| PYRAMID\_GREY | Подозреваемый участник финансовой пирамиды | Подозрение выявлено финансовой организацией. Ограничение операций, регистрация инцидента. |
| PYRAMID\_CEPI\_GREY | Подозреваемый участник финансовой пирамиды (ССЭП) | Подозрение по материалам ССЭП. Ограничение операций, мониторинг. |
| CASINO\_GREY | Подозреваемый казино / букмекеры | Подозрение в операциях в пользу онлайн-казино или букмекеров, выявленное финансовой организацией. |
| CASINO\_CEPI\_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)*). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метаданных.*
{% 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, дату и время подписания.
12. В случае необходимости множественного подписания документа несколькими Клиентами, документ, подписанный первым Клиентом, повторно проходит описанную выше процедуру подписания для каждого последующего Клиента. Перед началом подписания каждому следующему Клиенту отображается информация о документе, включая данные о предыдущем подписанте.
## Проверка подлинности цифровой подписи
Метод проверки валидности ЭЦП зависит от того, документ какого типа был подписан:
* для документов в формате BLOB (binary linked object) - используется метод, описание которого приведено в
* для документов в формате PDF - используется метод, описание которого приведено в
* для документов в формате XML - используется метод, описание которого приведено в
{% hint style="warning" %}
Электронная подпись не имеет ограниченного срока действия, и её подлинность можно проверить в любой момент.\
Для проверки подлинности документа, подписанного с использованием облачной ЭЦП, вы можете воспользоваться сервисом проверки по ссылке: [Проверить документ](https://id.npck.kz/esign/verify)
{% endhint %}