> 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/integraciya-crtr-s-openbanking.md). # Интеграция ЦРТР с OpenBanking ### Назначение и цель **ЦРТР** (Центр развития трудовых ресурсов) использует OpenBanking в рамках пилотного проекта по апробированию механизма назначения **адресной социальной помощи (АСП)**. АСП - это государственная выплата в денежной форме, предоставляемая физическим лицам с месячным среднедушевым доходом ниже черты бедности, установленной в областях, городах республиканского значения и столице. Для определения права на получение АСП Министерство труда и социальной защиты населения РК (МТСЗН РК) использует данные о банковских счетах, остатках и движении денег по ним, получаемые от банков второго уровня (БВУ) через OpenBanking. **Расчёт права на АСП:** | Условие | Решение | | ------------------------------------------------------- | ------------------ | | Среднедушевой доход семьи < Черты бедности (36 196 тг.) | АСП назначается | | Среднедушевой доход семьи ≥ Черты бедности | АСП не назначается | | Среднедушевой расход семьи ≥ Черты бедности | АСП не назначается | > **Справочно:** Черта бедности (ЧБ) = 35% от регионального медианного дохода, но не ниже 70% от регионального прожиточного минимума. Таким образом, ЦРТР запрашивает через OpenBanking данные по счетам заявителя и членов его семьи с их явного согласия, передаёт их в МТСЗН РК для расчёта среднедушевого дохода и принятия решения о назначении АСП. *** ### Термины и определения | Термин | Определение | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **АО «НПК»** | АО «Национальная платёжная корпорация Национального Банка Республики Казахстан» | | **Инициатор** | Физическое лицо, претендующее на получение адресной социальной помощи от государства | | **Члены семьи** | Совместно проживающие члены семьи, связанные имущественными и личными неимущественными правами и обязанностями, вытекающими из брака (супружества), родства, свойства, усыновления (удочерения) или иной формы принятия детей на воспитание, а также совместно проживающие лица, фактически сожительствующие, но не состоящие в браке. За исключением лиц: 1) на полном государственном обеспечении; 2) на срочной воинской службе; 3) в местах лишения свободы, на принудительном лечении | | **ГБД ФЛ** | Государственная база данных «Физические лица» | | **ИС** | Информационная система | | **Система Open API** | Информационная система, состоящая из программных и аппаратных средств, предназначенных для технологического и безопасного взаимодействия по передаче информации, относящейся к банковской тайне | | **АСП** | Адресная социальная помощь - государственная выплата в денежной форме физическим лицам с месячным среднедушевым доходом ниже черты бедности | | **БВУ** | Банки второго уровня - банки-поставщики данных по счетам через OpenBanking | | **МТСЗН РК** | Министерство труда и социальной защиты населения Республики Казахстан | | **ЦРТР** | Центр развития трудовых ресурсов | | **ШЭП** | Шлюз электронного правительства | | **СОД** | Сервис обмена данными - шлюз между ЦОИД и ШЭП | *** ### Технические особенности ЦРТР - сервис, расположенный в контуре ШЭП. В отличие от стандартных Клиентов API, ЦРТР имеет два архитектурных ограничения: * **Отсутствие публичного URL** - сервис не способен принять редирект с `authorization_code` из сети интернет * **Отсутствие прямого доступа к ЦОИД** - все запросы маршрутизируются исключительно через ШЭП → СОД Для подобных клиентов в AUTH предусмотрен механизм **auto-exchange**: `clientId` ЦРТР регистрируется в конфигурации AUTH в списке `auto-exchange.clientIds`. > **Важно:** Отличие от стандартного флоу затрагивает только два этапа: (а) доставка URL осуществляется посредством SMS, а не прямым перенаправлением в приложении; (б) токен извлекается через поллинг из AUTH, а не передаётся с callback-редиректом. Прочие этапы - идентификация, предоставление согласия, взаимодействие с поставщиками - выполняются по стандартной процедуре. *** ### Роль СОД в данном флоу СОД опубликован на ШЭП в двух ролях одновременно: | Роль | Описание | | ---------- | ----------------------------------------------------------------------------------------------- | | **Клиент** | Направляет запросы в ШЭП - в частности, запрашивает данные пользователя из ГБД ФЛ | | **Сервис** | Принимает входящие запросы из ШЭП и проксирует их через открытый интернет на публичные API ЦОИД | Двусторонняя роль СОД обеспечивает возможность взаимодействия ЦРТР, функционирующего исключительно в контуре ШЭП, с публичными API ЦОИД: ``` ЦРТР → ШЭП → СОД → публичные API ЦОИД ``` *** ### Диаграмма последовательности ```mermaid --- config: theme: neo look: neo --- %% Особый флоу для ЦРТР (через ШЭП и СОД) sequenceDiagram autonumber participant CRTR as ЦРТР participant SHEP as ШЭП participant SOD as СОД participant CL as Пользователь participant C as COID participant A as AUTH participant O as OAUTH participant GW as API Gateway participant B as Поставщик API Note over CRTR, B: 1. Запрос OAuth-URL через ШЭП CRTR->>SHEP: запрос generate-user-url
clientId + secret, iin, scopes SHEP->>SOD: проксирование SOD->>C: POST /v1/auth/generate-user-url C-->>SOD: URL на AUTH SOD-->>SHEP: URL SHEP-->>CRTR: URL Note over CRTR, B: 2. Доставка URL по SMS CRTR->>CL: SMS со ссылкой на AUTH Note over CRTR, B: 3. Идентификация и согласие (как обычно) CL->>A: переход по ссылке из SMS Note over A: Liveness + Facematch
SMS-OTP A->>O: переход на выдачу кода O->>CL: экран согласия CL-->>O: подтверждение Note over CRTR, B: 4. Auto-exchange в AUTH (вместо редиректа) O->>O: генерация authorization_code A->>O: обмен code на токен
(auto-exchange) O-->>A: JWT access-token A->>A: сохранить токен в сессии Note over CRTR, B: 5. Поллинг токена ЦРТР loop Пока токен не готов CRTR->>SHEP: запрос токена по sessionId SHEP->>SOD: проксирование SOD->>A: GET токена A-->>SOD: токен (или not ready) SOD-->>SHEP: ответ SHEP-->>CRTR: ответ end Note over CRTR, B: 6. Запрос данных по счетам через ШЭП CRTR->>SHEP: GET /v3/accounts
Bearer JWT, x-provider-id SHEP->>SOD: проксирование SOD->>GW: проксирование Note over GW: валидация JWT,
x-provider-id ⊂ scope,
биллинг GW->>B: GET /v3/accounts B-->>GW: список счетов GW-->>SOD: список счетов SOD-->>SHEP: ответ SHEP-->>CRTR: ответ ``` *** ### Процесс получения согласия #### Шаг 1 - Инициатор подаёт заявление Инициатор подаёт заявление в МТСЗН РК на получение выплат по АСП, указав сведения о составе семьи. *** #### Шаг 2 - Запрос OAuth-URL МТСЗН РК формирует запрос в АО «НПК» на получение URL-адреса индивидуально для Инициатора и каждого члена семьи. **Формат запроса:** ``` POST https://api.stage.npck.kz/v1/auth/generate-user-url Content-Type: application/json Accept: application/json Authorization: •••••• ``` ```json { "scopes": [ "openid", "accounts", "account_balance", "account_transactions" ], "redirectUri": "https://www.google.com/", "state": "examplestate", "phone": "+77070000000", "iin": "123456789123", // ИИН передаётся в хэшированном виде по алгоритму SHA-512 при масштабировании "accountsScopeData": { "providerIds": [ "76714972-02ee-4cea-88c1-933b2034da4d" ] }, "accountBalanceScopeData": { "providerIds": [ "76714972-02ee-4cea-88c1-933b2034da4d" ] }, "accountTransactionsScopeData": { "providerIds": [ "76714972-02ee-4cea-88c1-933b2034da4d" ] }, "language": "ru", "serviceCode": "OB_SERVICE", "consentExpiresAt": "2027-08-24T14:15:22Z", "dataRetentionPeriod": 1 } ``` **Формат ответа:** ```json { "url": "https://auth.stage.npck.kz/oauth?session-id=4204be02-1db0-4798-8c56-a40eddd6e0c7" } ``` *** #### Шаг 3 - Генерация и доставка URL по SMS АО «НПК» генерирует уникальный URL-адрес и перенаправляет его в ИС МТСЗН РК. ИС МТСЗН РК направляет URL-адрес Инициатору и совершеннолетним членам семьи посредством SMS-уведомления от сервиса рассылки единого контакт-центра **1414**. > **Важно:** Срок действия сгенерированного URL-адреса составляет **24 часа**. *** #### Шаг 4 - Идентификация и предоставление согласия После перехода по URL-адресу Система Open API запрашивает от Инициатора и членов семьи прохождение следующих процедур: 1. **Двухфакторная аутентификация:** * Запрос по подтверждению ИИН * Биометрическая идентификация личности: liveness-проверка и процедура сопоставления фотоизображения 2. **Ввод одноразового кода**, направленного по SMS на мобильный номер 3. **Регистрация согласия** на сбор, обработку и передачу третьим лицам персональных данных и сведений по банковским счетам, остаткам и (или) движению денег > **Важно:** Получение информации о счёте без действующего согласия со стороны Инициатора и (или) членов семьи исключено. *** #### Шаг 5 - Auto-exchange и поллинг токена После предоставления согласия AUTH **не выполняет перенаправление** на `redirectUri` ввиду его отсутствия у ЦРТР. Вместо этого AUTH самостоятельно: 1. Получает `authorization_code` от OAUTH 2. Производит обмен кода на JWT `access-token` (`POST /oauth2/token`) 3. Сохраняет токен в сессии для последующего извлечения С момента инициации флоу ЦРТР периодически опрашивает AUTH через **ШЭП → СОД** и забирает токен по завершении идентификации пользователя. > **Рекомендация:** Интервал поллинга - не чаще одного запроса в 3 секунды во избежание избыточной нагрузки на сервис. **Формат запроса на получение токена:** ``` POST https://api.stage.npck.kz/oauth2/token Content-Type: application/x-www-form-urlencoded Authorization: •••••• grant_type= code= redirect_uri= ``` **Формат ответа:** ```json { "access_token": "string", "scope": "string", "id_token": "string", "token_type": "string", "expires_in": 0 } ``` *** #### Шаг 6 - Запрос данных по счетам С полученным токеном ЦРТР обращается к эндпоинтам `accounts-api` через **ШЭП → СОД → API Gateway ЦОИД**. Обязательные заголовки запроса: ``` Authorization: Bearer x-provider-id: {providerId} ``` API Gateway выполняет стандартный набор проверок: * Валидация подписи JWT * Проверка активности токена (не истёк, не отозван) * Проверка активности `clientId` владельца токена * Проверка вхождения `x-provider-id` в скоуп токена (изоляция провайдеров) * Проверка активности поставщика и публикации вызываемого API *** #### Условия неуспешного прохождения Прохождение процедур признаётся неуспешным в следующих случаях: * Инициатором и (или) членами семьи не осуществлён переход по URL-адресу в установленный период * Инициатором и (или) членами семьи не предоставлено согласие на сбор, обработку и передачу данных по банковским счетам > **Важно:** Если один из членов семьи отклоняет согласие - процесс прекращается, запрос отклоняется. При частичном отказе допускается повторное обращение за назначением АСП в пределах установленного периода. При повторном обращении запрашивается согласие только у тех членов семьи, которые ранее его не предоставили. Если в течение установленного квартального периода согласие так и не было направлено - предоставление услуги становится невозможным, а все ранее переданные БВУ сведения подлежат уничтожению в порядке, предусмотренном законодательством Республики Казахстан. > **Важно:** Хранение данных без действующего согласия Инициатора и всех участников семьи является недопустимым. *** #### Форс-мажоры в рамках взаимодействия К обстоятельствам, которые могут повлиять на процесс генерации, доставки или использования URL-адреса, относятся: 1. Технические сбои в ИС МТСЗН РК 2. Технический сбой Системы Open API 3. Неисправности в сервисе рассылки SMS-уведомлений (1414) 4. Обновления и техническое обслуживание систем 5. Невозможность доставки уведомлений по причинам, не зависящим от оператора связи 6. Ошибки или сбои на стороне пользователей 7. Форс-мажорные обстоятельства (стихийные бедствия, военные конфликты, эпидемии и т.д.) 8. Ошибки в работе сгенерированного URL-адреса *** ### Получение данных от БВУ Система Open API направляет запросы **во все БВУ**. Запросы формируются без учёта родственных связей или семейных уз - их обработка осуществляется на стороне МТСЗН РК. В БВУ передаётся запрос исключительно на физическое лицо, давшее согласие на передачу и обработку своих данных. #### Методы API Система Open API взаимодействует с БВУ по следующим методам (спецификация: ): | Метод | Эндпоинт | Описание | | ---------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Список счетов | `GET /v3/accounts` | Предоставляет информацию об имеющихся банковских счетах Инициатора и членов семьи за установленный период (3 месяца). Возвращает тип счёта, статус, валюту и другие сведения | | Баланс счёта | `GET /v3/accounts/{accountId}/balances` | Предоставляет информацию о текущем балансе по конкретному счёту на последний день установленного периода | | Транзакции счёта | `GET /v3/accounts/{accountId}/transactions` | Предоставляет список транзакций по конкретному счёту. Включает сумму, дату, описание и другие данные о каждой транзакции | > **Важно:** Номер счёта (`accountId`) передаётся в формате **UUID**. Для конвертации IBAN в UUID используется метод `getOBIDsByIBANs`: *** #### Анализ операций МТСЗН РК анализирует два типа операций: **Внутрибанковские переводы** Фильтрация выполняется по ИИН получателя и отправителя. Если хэшированный ИИН получателя (`iinReciever`) или отправителя (`iinSender`), полученный от БВУ, совпадает с хэшированным ИИН Инициатора или одного из членов семьи - перевод идентифицируется как **внутрисемейный** и исключается из расчётов. Если получатель не входит в состав семьи - перевод рассматривается как **внешний** и учитывается в расчётах. **Межбанковские переводы** Фильтрация выполняется по атрибутам `transactionId`, `reference` и `RRN`. При осуществлении перевода между банками используются следующие идентификаторы: | Атрибут | Сторона | Описание | | ---------------------------------- | --------------------------- | ---------------------------------------------------------- | | `Reference` | Банк-отправитель (Банк «А») | Уникальный идентификатор операции на стороне отправителя | | `RRN` (Reference Retrieval Number) | Банк-получатель (Банк «Б») | Кроссовый атрибут операции банка «А» на стороне получателя | | `transactionId` | Оба банка | Единый уникальный идентификатор при переводах через СМП | МТСЗН РК при получении всех транзакций от БВУ, для исключения межбанковских операций по типу «семейные переводы» и «переводы самому себе», применяет следующую логику: * **`Reference`** - используется при операциях типа «Перевод» (Transfer) у банка-отправителя * **`RRN`** - используется при операциях типа «Поступление» (Income) у банка-получателя * **`transactionId`** - единый идентификатор для обоих банков при переводах через СМП *** ### Требования при масштабировании По результатам пилотного проекта в рамках фокус-группы планируется масштабирование на всю территорию Республики Казахстан. В связи с этим необходимо реализовать следующие доработки: #### Хэширование ИИН (SHA-512) При масштабировании ИИН Инициатора и членов семьи должен передаваться в **хэшированном виде** по алгоритму **SHA-512**. > **Важно:** На текущий момент и в период проведения пилотного проекта в рамках фокус-группы данное требование не является критичным. Становится обязательным при масштабировании. Пример хэширования (SHA-512): ``` Исходный ИИН: 123456789123 SHA-512: cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e ``` *** #### Формат номера счёта (UUID) Номер счёта (`accountId`) при обращении к API БВУ передаётся в формате **UUID** (OBID), а не в формате IBAN. Для конвертации IBAN в UUID необходимо использовать метод `getOBIDsByIBANs`. **Эндпоинт конвертации:** ``` GET https://obid-openapi.npck.kz/#tag/OBID/operation/getOBIDsByIBANs ``` > **Важно:** На текущий момент и в период проведения пилотного проекта в рамках фокус-группы данное требование не является критичным. Становится обязательным при масштабировании. *** ### Сравнение со стандартным флоу | | Стандартный флоу | Флоу ЦРТР | | ------------------------- | ---------------------------------------- | --------------------------- | | Доставка URL пользователю | Редирект в приложении | SMS-сообщение со ссылкой | | Получение токена | Callback-редирект с `authorization_code` | Поллинг из AUTH | | Запросы к API ЦОИД | Напрямую из сети интернет | ШЭП → СОД → ЦОИД | | Идентификация и согласие | Стандартные | Идентичны стандартному флоу | | Проверки API Gateway | Стандартные | Идентичны стандартному флоу |