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

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

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

2\. Подал заявку на подключение к Open Banking в качестве Пользователя API (см. подробнее в [Подключение к Open Banking/Open API](/rabota-s-testovym-okruzheniem-is-npk/podklyuchenie-k-open-banking-open-api.md))

3\. Зарегистрировал приложение Участника (см. подробнее в [Пользователям API (добавление и использование приложения)](/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovymi-servisami/polzovatelyam-api-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 отображает клиенту полученную информацию о его счетах (см. рекомендации [Рекомендации для мобильного приложения](/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-dlya-mobilnogo-prilozheniya.md)).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.npck.kz/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-po-realizacii-integracii-dlya-polzovatelya-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.