Интеграция ЦРТР с 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 ЦОИД

Диаграмма последовательности

Процесс получения согласия

Шаг 1 - Инициатор подаёт заявление

Инициатор подаёт заявление в МТСЗН РК на получение выплат по АСП, указав сведения о составе семьи.

Шаг 2 - Запрос OAuth-URL

МТСЗН РК формирует запрос в АО «НПК» на получение URL-адреса индивидуально для Инициатора и каждого члена семьи.

Формат запроса:

POST https://api.stage.npck.kz/v1/auth/generate-user-url
Content-Type: application/json
Accept: application/json
Authorization: ••••••

{
  "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
}

Формат ответа:

{
  "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 запрашивает от Инициатора и членов семьи прохождение следующих процедур:

Двухфакторная аутентификация:
- Запрос по подтверждению ИИН
- Биометрическая идентификация личности: liveness-проверка и процедура сопоставления фотоизображения
Ввод одноразового кода, направленного по SMS на мобильный номер
Регистрация согласия на сбор, обработку и передачу третьим лицам персональных данных и сведений по банковским счетам, остаткам и (или) движению денег

Важно: Получение информации о счёте без действующего согласия со стороны Инициатора и (или) членов семьи исключено.

Шаг 5 - Auto-exchange и поллинг токена

После предоставления согласия AUTH не выполняет перенаправление на redirectUri ввиду его отсутствия у ЦРТР. Вместо этого AUTH самостоятельно:

Получает authorization_code от OAUTH
Производит обмен кода на JWT access-token (POST /oauth2/token)
Сохраняет токен в сессии для последующего извлечения

С момента инициации флоу ЦРТР периодически опрашивает AUTH через ШЭП → СОД и забирает токен по завершении идентификации пользователя.

Рекомендация: Интервал поллинга - не чаще одного запроса в 3 секунды во избежание избыточной нагрузки на сервис.

Формат запроса на получение токена:

POST https://api.stage.npck.kz/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: ••••••

grant_type=<string>
code=<string>
redirect_uri=<string>

Формат ответа:

{
  "access_token": "string",
  "scope": "string",
  "id_token": "string",
  "token_type": "string",
  "expires_in": 0
}

Шаг 6 - Запрос данных по счетам

С полученным токеном ЦРТР обращается к эндпоинтам accounts-api через ШЭП → СОД → API Gateway ЦОИД.

Обязательные заголовки запроса:

Authorization: Bearer <access-token>
x-provider-id: {providerId}

API Gateway выполняет стандартный набор проверок:

Валидация подписи JWT
Проверка активности токена (не истёк, не отозван)
Проверка активности clientId владельца токена
Проверка вхождения x-provider-id в скоуп токена (изоляция провайдеров)
Проверка активности поставщика и публикации вызываемого API

Условия неуспешного прохождения

Прохождение процедур признаётся неуспешным в следующих случаях:

Инициатором и (или) членами семьи не осуществлён переход по URL-адресу в установленный период
Инициатором и (или) членами семьи не предоставлено согласие на сбор, обработку и передачу данных по банковским счетам

Важно: Если один из членов семьи отклоняет согласие - процесс прекращается, запрос отклоняется.

При частичном отказе допускается повторное обращение за назначением АСП в пределах установленного периода. При повторном обращении запрашивается согласие только у тех членов семьи, которые ранее его не предоставили.

Если в течение установленного квартального периода согласие так и не было направлено - предоставление услуги становится невозможным, а все ранее переданные БВУ сведения подлежат уничтожению в порядке, предусмотренном законодательством Республики Казахстан.

Важно: Хранение данных без действующего согласия Инициатора и всех участников семьи является недопустимым.

Форс-мажоры в рамках взаимодействия

К обстоятельствам, которые могут повлиять на процесс генерации, доставки или использования URL-адреса, относятся:

Технические сбои в ИС МТСЗН РК
Технический сбой Системы Open API
Неисправности в сервисе рассылки SMS-уведомлений (1414)
Обновления и техническое обслуживание систем
Невозможность доставки уведомлений по причинам, не зависящим от оператора связи
Ошибки или сбои на стороне пользователей
Форс-мажорные обстоятельства (стихийные бедствия, военные конфликты, эпидемии и т.д.)
Ошибки в работе сгенерированного URL-адреса

Получение данных от БВУ

Система Open API направляет запросы во все БВУ. Запросы формируются без учёта родственных связей или семейных уз - их обработка осуществляется на стороне МТСЗН РК. В БВУ передаётся запрос исключительно на физическое лицо, давшее согласие на передачу и обработку своих данных.

Методы API

Система Open API взаимодействует с БВУ по следующим методам (спецификация: https://accounts-openapi.npck.kz/#tag/Accounts/operation/getAccountsV3):

Метод

Эндпоинт

Описание

Список счетов

GET /v3/accounts

Предоставляет информацию об имеющихся банковских счетах Инициатора и членов семьи за установленный период (3 месяца). Возвращает тип счёта, статус, валюту и другие сведения

Баланс счёта

GET /v3/accounts/{accountId}/balances

Предоставляет информацию о текущем балансе по конкретному счёту на последний день установленного периода

Транзакции счёта

GET /v3/accounts/{accountId}/transactions

Предоставляет список транзакций по конкретному счёту. Включает сумму, дату, описание и другие данные о каждой транзакции

Важно: Номер счёта (accountId) передаётся в формате UUID. Для конвертации IBAN в UUID используется метод getOBIDsByIBANs: https://obid-openapi.npck.kz/#tag/OBID/operation/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

Стандартные

Идентичны стандартному флоу

PreviousСервис получения статуса API участников NextОбщая информация

Last updated 12 days ago