> 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/open-banking/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-po-realizacii-integracii-dlya-polzovatelya-api.md).

# Рекомендации по реализации интеграции для Пользователя API

{% hint style="info" %}
Необходимо, чтобы Пользователь API:

1\.  Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в [3. Регистрация и авторизация в Портале НПК](/registraciya-i-avtorizaciya/3.-registraciya-i-avtorizaciya-v-portale-npk.md))

2\. Подал заявку на подключение к Open Banking в качестве Пользователя API (см. подробнее в [5.2 Подключение к Open Banking/Open API](/registraciya-i-avtorizaciya/5.-podacha-zayavki-na-podklyuchenie-k-servisam/5.2-podklyuchenie-k-open-banking-open-api.md))

3\. Зарегистрировал приложение Участника (см. подробнее в [6. Добавление и использование приложения](/registraciya-i-avtorizaciya/6.-dobavlenie-i-ispolzovanie-prilozheniya.md))
{% endhint %}

## Общее описание процесса:

{% hint style="info" %}
Пользователю API  необходимо выполнить доработку программного обеспечения:

* Реализовать перенаправление Клиента для прохождения аутентификации и регистрации его согласия на доступ к данным, реализовать получение кода авторизации.
* Реализовать получение токена доступа.
* Реализовать получение данных посредством интерфейсов API. Для получения информации посредством интерфейсов API используется полученный токен доступа.
* Реализовать отображение клиенту полученной информации в приложении Пользователя API.
  {% endhint %}

<figure><img src="/files/PVg8COrcyWCyPfbMNo5A" alt=""><figcaption><p>Общая схема процесса получения сведений о банковском счете клиента</p></figcaption></figure>

1. Клиент инициирует в приложении Пользователя API получение информации о его банковских счетах.

> Если клиент уже дал согласие на доступ к его счетам для приложения Пользователя API и токен доступа не истек, то выполняется переход к шагу 7.
>
> Если клиент еще не дал согласие на доступ к его счетам для приложения Пользователя API, необходимо изменить список банков, на доступ к счетам в которых предоставляется согласие, или истек токен доступа, то выполняется переход к шагу 2.

2. Для предоставления согласия на доступ к данным приложение Пользователя API перенаправляет клиента на Платформу.

<figure><img src="/files/j7ugF6NpcQapcpUITiVP" alt=""><figcaption><p>Общая диаграмма взаимодействия</p></figcaption></figure>

{% hint style="warning" %}
Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров:

*webView\.settings.allowContentAccess = true; webView\.settings.mediaPlaybackRequiresUserGesture = false; webView\.settings.domStorageEnabled = true*

WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте webView указать данную настройку.
{% endhint %}

<figure><img src="/files/oLiWIMREOpKd8CbybRhA" alt="" width="143"><figcaption><p>Пример отсутствия доступа к контенту для WebView</p></figcaption></figure>

{% hint style="warning" %}
В IOS необходимо использовать SafariWebView. WKWebView не поддерживается.
{% endhint %}

<details>

<summary> Перенаправления клиента для прохождения аутентификации</summary>

Для перенаправления клиента для прохождения аутентификации необходимо:

1\) Реализовать получение URL-адреса для перенаправления клиента. Описание метода «Получить URL-адрес для перенаправления клиента» (POST /v1/auth/generate-user-url) приведено в <https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl>.

&#x20;

*Примечание: Метод получения URL-адрес для перенаправления клиента POST /oauth2/generate-user-url (см.* [*https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated*](https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated)*) является устаревшим, рекомендуется перейти на использование метода POST /v1/auth/generate-user-url (см.* [*https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl*](https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl)*).*

2\) Реализовать перенаправление пользователя на полученный URL-адрес.

</details>

{% hint style="info" %}
То к каким данным клиента запрашивается доступ определяется значениями, указанными в параметре scopes (могут быть указаны несколько значений) при запросе URL-адреса для перенаправления клиента:

* accounts - доступ к списку счетов клиента&#x20;
* account\_balance - доступ к информации о балансе счета
* account\_transactions - доступ к списку транзакций счета
  {% endhint %}

{% hint style="warning" %}
Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут
{% endhint %}

3. Клиенту отображается форма аутентификации. Клиент проходит двухфакторную аутентификацию личности.&#x20;
4. Клиент должен дать согласие на доступ к его данным для приложения Пользователя API.

{% hint style="info" %}
Клиент может отклонить согласие на доступ к его данным.&#x20;

Если клиент отклоняет согласие на доступ к его данным или происходит  ошибка, то клиент будет перенаправлен на указанный на шаге 2 **redirectUri**, с указанием кода ошибки, по следующему шаблону:

`[redirectUri]?errorCode=[error code]&state=[state]`

В таком случае процесс завершается, код авторизации не предоставляется.&#x20;
{% endhint %}

5. После того, как клиент выполнит все действия по предоставлению согласия на доступ к его данным, осуществляется его возврат в приложение Пользователя API.

{% hint style="info" %}
Если аутентификация клиента проходит успешно и он дает согласие на доступ к его данным, то клиент перенаправляется обратно в приложение Пользователя API (на указанный в запросе *redirectUri*) с одноразовым кодом авторизации (code), по следующему шаблону:

`[redirectUri]?code=[authorization code]&state=[state]`
{% endhint %}

{% hint style="warning" %}
Код авторизации является одноразовым.&#x20;

Время действия кода авторизации (время «жизни») составляет 300 секунд
{% endhint %}

{% hint style="warning" %}
Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink)
{% endhint %}

6. Приложение Пользователя API получает токен доступа, используя полученный на предыдущем шаге код авторизации.

<details>

<summary>Получение токена доступа</summary>

Для получения токена доступа необходимо:

1\) Реализовать формирование запроса получения токена доступа, используя полученный код авторизации. Описание используемого для этого метода приведено в <https://auth-openapi.npck.kz/#tag/Auth/operation/getOauthToken>.&#x20;

{% hint style="info" %}
Срок действия `access_token` зависит от того, какие данные запрашиваются (scope):

* Для получения информации о счетах клиента (`accounts`, `account_balance`, `account_transactions`) — **30 дней**.
* Для аутентификации клиента через FinID (`openid`, `iin`, `first_name` и т.д.) — **12 часов**.
* Для работы с облачной ЭЦП (`esign`, `organization_esign`) — **5 минут**.
  {% endhint %}

2\) Реализовать отправку сформированного запроса и получение токена доступа.

Токен доступа имеет формате JWT (см. RFC 7519). Токен доступа может использоваться для получения сведений о счете клиента посредством API, в течении срока его действия, после истечения срока действия необходимо получить новый токен доступа.

*Примечание: Дополнительно доступен метод получения списка публичных ключей для проверки токена (см.* [*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)*). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метаданных.*

</details>

{% hint style="warning" %}
Важно! Токен доступа должен сохраняться в тайне и не передаваться в публичный доступ, должен храниться на серверной стороне приложения, и вся обработка, связанная с ним, должна производиться на серверной стороне приложения.
{% endhint %}

7. Приложение Пользователя API получает информацию о счетах клиента посредством интерфейсов API используется токен доступа, полученный на предыдущем шаге. Перечень методов API для получения информации о банковском счете клиента, описание форматов запросов и ответов приведены в <https://accounts-openapi.npck.kz/>.

{% hint style="info" %}
*API v2 является устаревшим, рекомендуется перейти на использование API v3*
{% endhint %}

7. Приложение Пользователя API отображает клиенту полученную информацию о его счетах (см. рекомендации [Рекомендации для мобильного приложения](/open-banking/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-dlya-mobilnogo-prilozheniya.md)).