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

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

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\. Подал заявку на подключение к Open Banking в качестве Пользователя API (см. подробнее в [podklyuchenie-k-open-banking-open-api](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/podklyuchenie-k-open-banking-open-api "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="info" %}
Пользователю API  необходимо выполнить доработку программного обеспечения:

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

<figure><img src="https://3642634829-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoKJIIe9wXRYlANVFHqJE%2Fuploads%2F3LS60QJ8bt2sSZUOgBr6%2F1234567.png?alt=media&#x26;token=af1a7e82-a789-467a-9d0b-6a38c49f4992" alt=""><figcaption><p>Общая схема процесса получения сведений о банковском счете клиента</p></figcaption></figure>

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

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

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

<figure><img src="https://3642634829-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoKJIIe9wXRYlANVFHqJE%2Fuploads%2FlItRnxrSja2HQx3ehZSF%2Fimage.png?alt=media&#x26;token=329b11f9-ca4e-42c9-8a26-7187190f3128" 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="https://3642634829-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoKJIIe9wXRYlANVFHqJE%2Fuploads%2Fv00z0Vqu7vhGg5hJYRZ8%2Fcontent%20controll%20error.jpg?alt=media&#x26;token=e38af843-635c-41de-9d4f-e108b6925cb0" 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 отображает клиенту полученную информацию о его счетах (см. рекомендации [rekomendacii-dlya-mobilnogo-prilozheniya](https://docs.npck.kz/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-dlya-mobilnogo-prilozheniya "mention")).