ПОСТАНОВЛЕНИЕ ПРАВЛЕНИЯ НАЦИОНАЛЬНОГО БАНКА РЕСПУБЛИКИ БЕЛАРУСЬ

от 27 ноября 2024 года №369

Об утверждении стандарта финансовых услуг и технологий

На основании абзаца пятьдесят седьмого статьи 26 и части первой статьи 39 Банковского кодекса Республики Беларусь Правление Национального банка Республики Беларусь ПОСТАНОВЛЯЕТ:

1. Утвердить стандарт финансовых услуг и технологий СФУТ 6.03-2024 "Открытые банковские API. Информационные API. Спецификация" (прилагается).

2. Настоящее постановление вступает в силу через шесть месяцев после его официального опубликования.

 

Утвержден Постановлением Правления Национального банка Республики Беларусь от 27 ноября 2024 года №369

Стандарт финансовых услуг и технологий СФУТ 6.03-2024 "Открытые банковские API. Информационные API. Спецификация"

Раздел I. Общие положения

1. Настоящий стандарт финансовых услуг и технологий (далее – стандарт) устанавливает требования к открытым информационным банковским интерфейсам программирования приложений (интерфейсам прикладного программирования, API) (далее, если не указано иное, – API), методам и параметрам API, посредством которых предоставляется информация:

о пунктах обслуживания клиентов банка (отделениях, обменных пунктах), банкоматах (далее – АТМ (Automated teller machine), платежно-справочных терминалах (далее – ПСТ) с указанием адреса и времени работы, контактных телефонов, адреса электронной почты, геолокации и иной информации;

об осуществляемых банковских, платежных операциях и связанных с ними услугах (далее – услуги) (привлечении денежных средств во вклады (депозиты) (далее – депозит), предоставлении кредитов, эмиссии банковских платежных карточек (далее – БПК), предоставлении информации об обменных курсах по валютно-обменным операциям (далее – обмен валют), привлечении драгоценных металлов в депозиты, реализации драгоценных камней, памятных и слитковых (инвестиционных) монет (далее, если не указано иное, – монеты), проведении переводов денежных средств (электронных денег) (далее – денежные средства), а также иная информация).

2. Настоящий стандарт предназначен для участников экосистемы открытого банкинга с целью разработки приложений, предоставляющих или использующих API.

3. Настоящий стандарт применяется совместно со стандартом проведения расчетов СПР 6.01-2020 "Банковская деятельность. Информационные технологии. Открытые банковские API. Регламент взаимодействия поставщиков API и пользователей API", утвержденным постановлением Правления Национального банка Республики Беларусь от 31 декабря 2019 г. №552 (далее – СПР 6.01).

4. В настоящем стандарте используются термины в значениях, установленных в нормативных правовых актах Национального банка, в том числе принятых совместно с иными государственными органами, СПР 6.01, стандарте проведения расчетов СПР 6.02-1-2022 "Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Спецификация", утвержденном постановлением Правления Национального банка Республики Беларусь от 26 августа 2022 г. №314.

5. В настоящем стандарте используются обозначения согласно стандарту проведения расчетов СПР 6.02-1-2022 "Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Спецификация".

6. Для обеспечения структурного контроля запроса на физическом уровне применяются JSON-схемы соответствующих электронных сообщений.

7. Текст запроса должен быть сформирован в кодовой странице UTF-8.

8. Основные требования к информационной безопасности описаны в СПР 6.01.

Раздел II. Общие требования к API

Глава 1. Требования к элементам данных

9. Разрешенное к использованию символьное множество элементов данных включает в себя следующий набор символов:

значения элементов данных должны выбираться из следующего набора символов, заключенных в квадратные скобки [ ]:

A…Z – прописные латинские буквы;

a…z – строчные латинские буквы;

А…Я – прописные буквы кириллицы, включая I, Ё и Ў;

а…я – строчные буквы кириллицы, включая i, ё и ў;

0…9 – цифры;

/ – + = _ . , : ; " " " " " " " ~ ! @ # №$ % ^ ? * ( ) [ ] { } – специальные графические символы: пробел, дробная черта правая и левая, дефис (минус), плюс, равно, нижнее подчеркивание, точка, запятая, двоеточие, точка с запятой, апостроф, одиночные, парные и угловые кавычки (левые и правые), тильда, восклицательный знак, коммерческое at, решетка, знак номера, знак доллара, процент, карет, знак вопроса, звездочка, круглые, квадратные и фигурные скобки (левые и правые).

Десятичные числа указываются в следующем формате: m<=decimal<=M td=T fd=F, где m – минимальное значение, M – максимальное значение, Т – общее количество цифр, F – количество цифр в дробной части. При этом элементы данных, прописанные в подпунктах 14.8, 14.9, 14.10 и 14.11 пункта 14 настоящего стандарта, указываются в JSON типом string.

10. Обозначения размерности заключаются в фигурные скобки и указываются после перечисления допустимых символов:

{n} – точно n символов;

{n,m} – не менее, чем n символов, но не более чем m символов;

text{n,m} – минимальная (n) и максимальная (m) длина текстового элемента данных, состоящего из разрешенного набора символов;

MaxMText – максимальная (M) длина текстового элемента данных, состоящего из разрешенного набора символов.

Различные значения, размещаемые при необходимости в одном элементе данных, разделяются двумя дробными чертами //.

11. Необязательная часть значения элемента данных заключается в круглые скобки, после которых ставится знак вопроса "?", например: [A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?.

12. Для указания кратности повторений (или множественности) компонентов или элементов данных используются обозначения, заключаемые в квадратные скобки [ ]:

[1..1] – элемент данных обязателен, повторения не допускаются;

[1..*] – элемент данных обязателен, может повторяться без ограничений;

[1..m] – элемент данных обязателен, может повторяться не более m раз (m > 1);

[n..*] – элемент данных обязателен, должен повторяться не менее n раз (n > 1);

[n..m] – элемент данных обязателен, должен повторяться не менее n раз и не более m раз (n > 0, m > n);

[0..1] – элемент данных необязателен, повторения не допускаются;

[0..*] – элемент данных необязателен, может повторяться без ограничений;

[0..m] – элемент данных необязателен, может повторяться не более m раз (m > 1).

Если кратность повторения компонента или элемента данных не указана, то они заполняются однократно.

13. Типы элементов данных, содержащихся в компонентах информационных данных и используемых при разработке информационных систем:

boolean: примитивный тип данных, принимающий два возможных значения, называемых истиной (true) и ложью (false). Для значения истина может использоваться 1, для значения ложь – 0;

decimal: в JSON тип данных string (для числовых полей с плавающей точкой (согласно описанию в подпунктах 14.8–14.11 пункта 14 настоящего стандарта);

float: в JSON тип данных number;

number: тип данных для обозначения чисел (для целочисленных значений);

string: строковый тип, содержащий символы из пункта 9 настоящего стандарта.

Массив [ ]: структура данных, содержащая набор значений (элементов массива).

14. В API используются основные элементы данных и компоненты, формат которых является одинаковым для всех API, если об этом не указано отдельно в описании конкретного API.

14.1. Элемент данных "Наименование".

Элемент данных "Наименование" должен содержать сокращенное наименование банка, иного юридического лица, или фамилию, собственное имя, отчество (при наличии) физического лица, нотариуса, индивидуального предпринимателя или наименование описываемого компонента.

Элемент данных "Наименование" имеет неструктурированный тип данных text{1,140}.

14.2. Элемент данных "Дата".

Элемент данных "Дата" – элемент данных, содержащий значение даты, указывается согласно расширенному формату межгосударственного стандарта ГОСТ ИСО 8601-2001 "Система стандартов по информации, библиотечному и издательскому делу. Представление дат и времени. Общие требования", утвержденного постановлением Комитета по стандартизации, метрологии и сертификации при Совете Министров Республики Беларусь от 22 августа 2002 г. №37 (далее – ГОСТ ИСО 8601), имеет тип данных ISODate и формат YYYY-ММ-DD (год-месяц-день).

14.3. Элемент данных "Дата и время".

Элемент данных "Дата и время" – элемент данных, содержащий значение даты и времени, указывается согласно расширенному формату ГОСТ ИСО 8601, имеет тип данных ISODateTime и формат YYYY-MM-DDThh:mm:ssZ или YYYY-MM-DDThh:mm:ss±hh:mm.

Например, для указания даты и времени 26 марта 2022 года 17 ч. 19 мин. 33 сек. (по Минскому времени) может использоваться один из вариантов: 2022-03-26Т17:19:33Z или 2022-03-26Т17:19:33+03:00.

Время указывается с учетом часового пояса страны, в случае Республики Беларусь используется GMT+3.

14.4. Элемент данных "Время".

Элемент данных "Время" – элемент данных, содержащий значение времени, указывается согласно формату ГОСТ ИСО 8601, имеет тип данных ISOTime и формат hh:mm:ss ±hh:mm.

Время указывается с учетом часового пояса страны, в случае Республики Беларусь используется GMT+3.

Окончание дня указывается в следующем виде: "23:59:59".

14.5. Элемент данных "Страна".

Элемент данных "Страна" указывается в кодированной форме согласно общегосударственному классификатору Республики Беларусь ОКРБ 017-99 "Страны мира", утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. №8, имеет структурированный тип данных CountryCode и формат [A-Z]{2}.

Элемент данных "Страна" должен указываться отдельным элементом данных при идентификации нерезидентов Республики Беларусь.

14.6. Элемент данных "Валюта".

Элемент данных "Валюта" содержит значение кода валюты, указывается согласно общегосударственному классификатору Республики Беларусь ОКРБ 016-99 "Валюты", утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. №8, имеет тип данных CurrencyCode и формат [A-Z]{3}.

14.7. Элемент данных "Идентификационный налоговый номер".

В элементе данных "Идентификационный налоговый номер" указываются статус партнера и учетный номер плательщика (далее – УНП), присвоенный налоговыми органами, в формате [A-Z]{3}[A-Z0-9]{9}, где:

[A-Z]{3} – значение статуса партнера согласно справочнику статусов субъектов N061 в таблице 125;

[A-Z0-9]{9} – УНП.

14.8. Элементы данных "Широта" и "Долгота".

Элементы данных, содержащие значения широты и долготы, должны иметь формат decimal td=8 fd=5 и формироваться в соответствии со следующими правилами:

значение состоит из целой части, разделителя и дробной части;

целая часть должна содержать хотя бы одну цифру;

в целой части ноли перед первой значащей цифрой отсутствуют;

в качестве разделителя целой и дробной частей должен присутствовать символ "." (точка);

дробная часть указывается, если в значении она присутствует;

в дробной части ноли после последней значащей цифры отсутствуют;

если дробная часть в значении присутствует и равна нулю, то количество символов "0" в дробной части должно быть равно максимально допустимому количеству знаков для выбранного параметра.

14.9. Элемент данных "Обменный курс".

Элемент данных, содержащий значения обменного курса, должен иметь формат 0<=decimal td=11 fd=10 и формироваться в соответствии со следующими правилами:

значение состоит из целой части, разделителя и дробной части;

в качестве разделителя целой и дробной частей используется символ "." (точка);

общее количество цифр не должно превышать 11, разделитель не учитывается;

целая и дробная части должны содержать хотя бы одну цифру;

в целой части ноли перед первой значащей цифрой отсутствуют;

в дробной части ноли после последней значащей цифры отсутствуют.

Обменный курс белорусского рубля указывается к единице той или иной валюты без использования шкалы курса, например: 0.034537 соответствует 3,4537 BYN за 100 RUB.

14.10. Элементы данных, содержащие значения процентов, и "Процентная ставка".

Элементы данных, содержащие значения процентов, и "Процентная ставка" должны иметь формат 0<=decimal<=100 td=11 fd=10 и формироваться в соответствии со следующими правилами:

значение состоит из целой части, разделителя и дробной части;

в качестве разделителя целой и дробной частей используется символ "." (точка);

общее количество цифр не должно превышать 11, разделитель не учитывается;

целая и дробная части должны содержать хотя бы одну цифру;

в целой части ноли перед первой значащей цифрой отсутствуют;

в дробной части ноли после последней значащей цифры отсутствуют;

максимальное значение не должно превышать 100.

Например: 20.0 соответствует 20 0.05 соответствует 0,05 %.

Дополнительное описание для элементов данных "Минимальное вознаграждение (плата), % (feeRateMin)" и "Максимальное вознаграждение (плата), % (feeRateMax)" представлено в таблице 1.

Таблица 1

Минимальное вознаграждение (плата), (%) (feeRateMin)	Максимальное вознаграждение (плата), (%) (feeRateMax)	Диапазон сумм
отсутствует	отсутствует	Для всех сумм
отсутствует	присутствует	От 0 до максимального вознаграждения (платы), (включая)
присутствует	отсутствует	От минимального вознаграждения (платы) (исключая) до суммы, превышающей максимальное вознаграждение (плату)
присутствует	присутствует	От минимального вознаграждения (платы) (исключая) до максимального вознаграждения (платы) (включая)

Дополнительное описание для элементов данных, содержащих значения процентов, и "Процентная ставка" может быть указано в поле rateFormula тип данных Max140Text text{1,140}.

14.11. Элементы данных, содержащие значения суммы, и "Сумма денежных средств".

Элементы данных, содержащие значения сумм, и "Сумма денежных средств" должны иметь формат 0<=decimal td=18 fd=5 и формироваться в соответствии со следующими правилами:

значение состоит из целой части, разделителя и дробной части;

в качестве разделителя целой и дробной частей используется символ "." (точка);

общее количество цифр не должно превышать 18, разделитель не учитывается;

целая часть должна содержать хотя бы одну цифру;

в целой части ноли перед первой значащей цифрой отсутствуют;

дробная часть указывается, если в данной валюте она присутствует;

количество цифр в дробной части суммы не может превышать пяти, не может превышать максимально допустимое число знаков для данной валюты и должно соответствовать общегосударственному классификатору Республики Беларусь ОКРБ 016-99 "Валюты";

если дробная часть в данной валюте присутствует и равна нулю, то количество символов "0" в дробной части должно быть равно максимально допустимому количеству знаков в дробной части для данной валюты, например: 126.00.

Значения сумм денежных средств, представленных в белорусских рублях, должны иметь формат 0<=decimal td=18 fd=2.

Дополнительное описание для элементов данных "Минимальная сумма (amountMin)" и "Максимальная сумма (amountMax)" представлено в таблице 2.

Таблица 2

Минимальная сумма (amountMin)	Максимальная сумма (amountMax)	Диапазон сумм денежных средств
отсутствует	отсутствует	Для всех сумм
отсутствует	присутствует	От 0 до максимальной суммы (включая)
присутствует	отсутствует	От минимальной суммы (включая) до суммы, превышающей максимальную
присутствует	присутствует	От минимальной суммы (включая) до максимальной суммы (включая)

14.12. Элемент данных "Период".

Элементы данных, содержащие значения периода размещения денежных средств и периода отсрочки платежа по кредитному договору, должны иметь тип number.

Дополнительное описание для элементов данных "Минимальное условие (termMin)" и "Максимальное условие (termMax)" представлено в таблице 3.

Таблица 3

Минимальное условие (termMin)	Максимальное условие (termMax)	Диапазон условий
отсутствует	отсутствует	Для всех периодов
отсутствует	присутствует	От 0 до максимального условия (включая)
присутствует	отсутствует	От минимального условия (исключая) до срока, превышающего максимальное условие
присутствует	присутствует	От минимального условия (исключая) до максимального условия (включая)

Дополнительное описание для элементов данных "Минимальный период (periodMin)" и "Максимальный период (periodMax)" представлено в таблице 4.

Таблица 4

Минимальный период (periodMin)	Максимальный период (periodMax)	Диапазон периодов
отсутствует	отсутствует	Для всех периодов
отсутствует	присутствует	От 0 до максимального периода (включая)
присутствует	отсутствует	От минимального периода (исключая) до периода, превышающего максимальный
присутствует	присутствует	От минимального периода (исключая) до максимального периода (включая)

Глава 2. Требования к структуре API

15. Структура пути URI.

Путь URI соответствует следующей структуре:

[participant-path-prefix]/open-banking/[version]/[resource]/[resource-id]/[sub-resource].

Структура URI пути состоит из следующих элементов:

[participant-path-prefix] – необязательный префикс поставщика API;

open-banking – постоянное значение "open-banking";

[version] – версия API, выраженная в виде /v[major-version].[minor-version]/;

[resource]/[resource-id] – наименование ресурса и его идентификатор;

[sub-resource] – наименование подресурса (ресурса 2-го уровня).

Поставщик API использует один и тот же participant-path-prefix и host name для всех своих ресурсов.

Пример:

https://api.bank.by/oapi-channel/open-banking/v1.0/banks/BANKBY2X/deposit.

16. Статусы исполнения запросов.

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

Таблица 5

Код ответа	Наименование	Описание
200	OK	Запрос успешно выполнен
400	Bad Request	Запрос имеет неверные отсутствующее или несовместимое тело JSON, параметры URL или поля заголовка. Запрошенная операция не будет выполнена
401	Unauthorized	Заголовок авторизации отсутствует или неверный токен. Операции было отказано в доступе. Повторная аутентификация клиента может привести к созданию соответствующего токена, который может быть использован
403	Forbidden	Токен имеет неверную область действия или была нарушена политика безопасности. Операции было отказано в доступе. Повторная аутентификация клиента может привести к созданию соответствующего токена, который может быть использован
404	Not Found	Отказ в исполнении запроса
406	Not Acceptable	Запрос содержал параметр заголовка Accept, отличный от разрешенных media types, и набор символов, отличный от UTF-8
419	Request Timeout	Время ожидания истекло
500	Internal Server Error	Внутренняя ошибка сервера. При попытке выполнения запроса на сервере произошла ошибка
503	Service Unavailable	Устаревшая версия сервера. Если API устарел и больше не поддерживается поставщиком API, его путь URI все еще может быть активным и принимать запросы. В этом контексте рекомендуется вернуть 503 Service Unavailable, чтобы уведомить, что версия API находится в offline режиме

Глава 3. Структура запросов и ответов

17. Структура запросов.

Структура верхнего уровня для запросов API имеет следующий вид:

Request Line

Message Headers

{

"data": {

...

}

}

Строка запроса содержит метод передачи, путь URI для обращения к конкретному запросу API и версию протокола HTTP.Request Line.

Заголовки запросов (Message Headers) характеризуют тело запроса, параметры передачи и прочие сведения.

Раздел "data" содержит данные для конкретного запроса API. Структура этого элемента отличается для каждой конечной точки API.

18. Структура ответов.

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

Верхнеуровневая структура ответов API имеет следующий вид:

Response Line

Message Headers

{

"data": {

...

},

"links": {

...

"self": "",

"next": ""

...

},

"meta": {

...

"totalPages": ""

...

}

}

В ответы включаются следующие дополнительные верхнеуровневые разделы:

links – данный блок является обязательным, содержит ссылку на текущий запрос и может для системы пагинации содержать ссылки на первую страницу, текущую и на следующую страницу;

meta – данный блок является обязательным, содержит метаинформацию о странице: сколько страниц в системе пагинации, например, для обменных курсов, дата и время получения информации о последнем обновлении обменных курсов.

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

Если существует следующая страница записей, то поставщик API предоставляет ссылку на следующую страницу записей в элементе links.next ответа. Отсутствие следующей ссылки будет означать, что текущая страница является последней страницей записей.

Для многостраничных ответов поставщик API гарантирует, что количество записей на одной странице составляет минимум 25 записей (кроме последней страницы, где больше нет записей) и максимум 100 записей.

Поставщик API включает "self" ссылку на ресурс в элементе links.self.

Дополнительно поставщик API предоставляет:

ссылку на получение оставшихся записей в элементе links.next;

общее количество страниц в элементе meta.totalPages.

Настоящий стандарт не определяет, каким образом параметры перелистывания страниц передаются поставщиком API. Каждый поставщик API может использовать свои собственные механизмы для разбивки ответа. Если исходный запрос от пользователя API включал параметры фильтра, то в ответе возвращаются только те результаты (разбитые на страницы), которые соответствуют фильтру.

19. Структура ответов с ошибками.

Структура для ответов с ошибками API имеет следующий вид:

{

"errorDateTime": "...",

"code": "...",

"id": "...",

"message": "...",

"errors": [

{

"errorCode": "...",

"message": "...",

"path": "...",

"URL": "..."

}

]

}

Описание элементов данных ответов с ошибками представлено в таблице 6.

Таблица 6

Название элемента данных

Описание элемента данных

Кратность элемента данных

Тип данных/ формат элемента данных