Дата обновления БД:
19.04.2024
Добавлено/обновлено документов:
72 / 276
Всего документов в БД:
133027
ПОСТАНОВЛЕНИЕ ПРАВЛЕНИЯ НАЦИОНАЛЬНОГО БАНКА РЕСПУБЛИКИ БЕЛАРУСЬ
от 26 августа 2022 года №314
Об утверждении стандартов проведения расчетов
На основании абзаца шестьдесят шестого статьи 26 и части первой статьи 39 Банковского кодекса Республики Беларусь Правление Национального банка Республики Беларусь ПОСТАНОВЛЯЕТ:
1. Утвердить:
2. Настоящее постановление вступает в силу после его официального опубликования.
Председатель Правления
П.В.Каллаур
Утвержден Постановлением Правления Национального банка Республики Беларусь от 26 августа 2022 года №314
Стандарт проведения расчетов СПР 6.02-1-2022 "Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Спецификация"
Раздел I. Общие положения
1. Настоящий стандарт проведения расчетов (далее – стандарт) устанавливает требования к открытым платежным банковским интерфейсам программирования приложений (интерфейсам прикладного программирования, API) (далее, если не указано иное, – API), методам и параметрам API, посредством которых предоставляется:
1.1. получение информации о банковском счете (далее – счет) (счетах) клиента:
создание и получение статуса согласия для получения информации о счете (счетах) клиента;
удаление (отзыв) согласия на получение информации о счете (счетах) клиента;
получение информации о счете (счетах);
получение информации о балансе счета (всех счетов);
создание выписки по счету и получение выписки по счету по созданному идентификатору выписки;
создание перечня транзакций по счету и получение перечня транзакций по счету по созданному идентификатору списка транзакций;
1.2. инициирование платежей:
создание и получение статуса согласия на инициирование всех видов платежей;
создание и получение статуса платежного указания на инициирование платежа плательщиком за товары, работы, услуги;
создание и получение статуса платежного указания на инициирование платежа плательщиком в бюджет;
создание и получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров;
создание и получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета;
создание и получение статуса платежного указания на инициирование платежа бенефициаром за товары, работы, услуги;
создание и получение статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет;
создание и получение статуса платежного указания на инициирование платежа из состава рекуррентных платежей;
отзыв платежного указания на инициирование всех видов платежей.
2. Настоящий стандарт предназначен для участников экосистемы открытого банкинга с целью реализации процессов на этапе разработки API. Настоящий стандарт не распространяется на инициирование платежей посредством программно-технической инфраструктуры, предназначенной для приема банковских платежных карточек на физическом носителе.
3. Настоящий стандарт применяется совместно со стандартом проведения расчетов СПР 6.01-2020 "Банковская деятельность. Информационные технологии. Открытые банковские API. Регламент взаимодействия поставщиков API и пользователей API", утвержденным постановлением Правления Национального банка Республики Беларусь от 31 декабря 2019 г. №552 (далее – СПР 6.01).
4. В настоящем стандарте используются термины в значениях, установленных в нормативных правовых актах Национального банка, в том числе принятых совместно с иными государственными органами, СПР 6.01, а также следующие термины и их определения:
долгосрочное согласие – согласие, которое предоставляется клиентом на стороне поставщика API для осуществления обмена данными между пользователем API и поставщиком API на длительный срок (не более трех лет);
краткосрочное согласие – однократное согласие, которое предоставляется клиентом на стороне поставщика API для осуществления обмена данными между пользователем API и поставщиком API на инициирование только одного платежа;
идемпотентность – свойство объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом;
открытый банкинг – комплекс подходов к предоставлению банковских услуг, основанный на простом, удобном, эффективном, мгновенном и безопасном способе оказания пользователям таких услуг, в том числе посредством предоставления их юридическим лицам, не являющимся финансовыми организациями, доступа к информации о банковских услугах и клиентах банков в соответствии с требованиями, установленными законодательством;
пагинация – механизм разбивки списка записей на страницы при предоставлении больших наборов данных через API;
полезная нагрузка – часть пакета данных (сообщения) без служебной информации (без заголовка, битов синхронизации иной служебной информации);
пользователь API второго типа – юридическое лицо, использующее API для предоставления услуг клиентам, получающий монетизацию за счет дополнительных сервисов поставщиков API;
пользователь API первого типа – клиент, использующий API в личных целях, а также для получения конкурентных преимуществ в процессе последующего производства товаров, выполнения работ, оказания услуг (без непосредственного использования API для оказания услуг клиентам);
поставщик информационных платежных услуг – пользователь API второго типа, предоставляющий клиенту услугу получения информации о счете (счетах) клиента;
поставщик платежных услуг инициирования платежа – пользователь API второго типа, предоставляющий клиенту услугу инициирования перевода денежных средств;
рекуррентный платеж – платеж, инициируемый с определенной периодичностью пользователем API второго типа на основании предоставленного ему согласия клиента посредством использования реквизитов счета клиента;
ресурс – любая сущность (платеж, счет, транзакция) в определенном формате (JSON или ином). Каждый ресурс идентифицируется посредством постоянного идентификатора, который не меняется при изменении состояния ресурса;
согласие – согласие клиента на предоставление данных клиента, данных, необходимых для проведения транзакций клиента, на инициирование платежа клиента пользователю API второго типа от поставщика API и/или на передачу данных пользователю API второго типа поставщику API от имени клиента, выраженное в письменной форме лично поставщику API, либо согласие, представленное поставщику API в электронном виде с применением программно-аппаратных средств и технологий, позволяющих достоверно установить, что оно исходит от соответствующих лиц;
токен доступа – свидетельство, представляющее авторизацию, выданную клиенту сервером авторизации с одобрения владельца ресурса. Токен доступа содержит указание на конкретные области действия, к которым разрешен доступ, длительность доступа и другие параметры;
экосистема открытого банкинга – взаимосвязанная группа лиц, взаимодействующих в процессе создания, реализации, использования и вывода из эксплуатации открытых API для достижения взаимовыгодных целей, непосредственно сами открытые API, а также программные продукты, внедряемые при их использовании.
В настоящем стандарте используются следующие обозначения:
О – наличие компонента и (или) элемента данных обязательно;
Н – наличие компонента и (или) элемента данных необязательно;
У – наличие компонента и (или) элемента данных определяется по условию;
DELETE – метод HTTP для удаления указанного ресурса;
GET – метод HTTP для запроса содержимого указанного ресурса;
HTTPS – расширение протокола HTTP для поддержки шифрования в целях повышения безопасности;
JSON – текстовый формат обмена данными, основанный на JavaScript;
OAuth 2.0 – открытый протокол (схема) авторизации, который позволяет предоставить пользователю API ограниченный доступ к защищенным ресурсам клиента без необходимости передавать ему (пользователю API) логин и пароль;
POST – метод HTTP для отправки содержимого указанного ресурса на сервер;
REST – архитектурный стиль взаимодействия компонентов распределенного приложения в сети. REST представляет собой согласованный набор ограничений, учитываемых при проектировании распределенной системы;
XML – расширяемый язык разметки, определяющий набор правил для кодирования документов в формате, который удобен для чтения как человеком, так и компьютером.
5. Для API определена архитектура, соответствующая концепции RESTful API.
6. Для обеспечения структурного контроля сообщений на физическом уровне применяются JSON-схемы соответствующих электронных сообщений.
7. Текст сообщения должен быть сформирован в кодовой странице UTF-8.
8. Участники экосистемы открытого банкинга взаимодействуют согласно логической структуре. Структура взаимодействия участников в случае участия пользователя API второго типа представлена на рисунке 1.
Рисунок 1
Структура взаимодействия участников в случае участия пользователя API первого типа представлена на рисунке 2.
Рисунок 2
9. Клиент предоставляет долгосрочное согласие поставщику API для осуществления обмена данными между пользователем API второго типа и поставщиком API в рамках согласия на длительный срок (не более трех лет). В любой момент клиент может отозвать долгосрочное согласие как через открытые API, так и через предоставляемые средства поставщика API.
10. Клиент предоставляет краткосрочное согласие поставщику API для инициирования платежа.
11. Поставщик API при применении настоящего стандарта руководствуется банковским законодательством, законодательством об информации, информатизации и защите информации, о персональных данных.
Раздел II. Общие требования к API
Глава 1. Требования к элементам данных
12. Разрешенное к использованию символьное множество элементов данных включает в себя следующий набор символов:
A…Z – прописные латинские буквы;
a…z – строчные латинские буквы;
А…Я – прописные буквы кириллицы, включая I, Ё и Ў;
а…я – строчные буквы кириллицы, включая i, ё и ў;
0…9 – цифры;
/ – + = _ . , : ; " " " "" "" " " ~ ! @ # №$ % ^ ? * ( ) [ ] { } – специальные графические символы: пробел, дробная черта правая и левая, дефис (минус), плюс, равно, нижнее подчеркивание, точка, запятая, двоеточие, точка с запятой, апостроф, одиночные, парные и угловые кавычки (левые и правые), тильда, восклицательный знак, коммерческое at, решетка, знак номера, знак доллара, процент, карет, знак вопроса, звездочка, круглые, квадратные и фигурные скобки (левые и правые).
Десятичные числа указываются в следующем формате: m<=decimal<=M td=T fd=F, где m – минимальное значение, M – максимальное значение, Т – общее количество цифр, F – количество цифр в дробной части.
13. Обозначения размерности заключаются в фигурные скобки и указываются после перечисления допустимых символов:
{m} – точно m символов;
{m,n} – не менее чем m символов, но не более чем n символов;
text{m,n} – минимальная (m) и максимальная (n) длина текстового элемента данных, состоящего из разрешенного набора символов.
14. Для указания кратности повторений (или множественности) компонентов или элементов данных используются обозначения, заключаемые в квадратные скобки [ ]:
[1..1] – элемент данных обязателен, повторения не допускаются;
[1..*] – элемент данных обязателен, может повторяться без ограничений;
[1..n] – элемент данных обязателен, может повторяться не более n раз (n > 1);
[m..*] – элемент данных обязателен, должен повторяться не менее m раз (m > 1);
[m..n] – элемент данных обязателен, должен повторяться не менее m раз и не более n раз (m > 0, n > m);
[0..1] – элемент данных необязателен, повторения не допускаются;
[0..n] – элемент данных необязателен, может повторяться не более n раз (n > 1).
Если кратность повторения компонента или элемента данных не указана, то они заполняются однократно.
15. Необязательная часть значения элемента данных заключается в круглые скобки, после которых ставится знак вопроса "?", например: [A-Z0-9]{9}([A-Z]{3})?.
16. В API используются основные элементы данных и компоненты, формат которых является одинаковым для всех API, если об этом не указано отдельно в описании конкретного API.
16.1. Элемент данных "Наименование".
Элемент данных "Наименование" (name) должен содержать краткое наименование банка, организации или фамилию, собственное имя и отчество (при наличии) физического лица или наименование описываемого компонента.
Элемент данных "Наименование" имеет неструктурированный тип данных Max140Text.
16.2. Элемент данных "Международный номер банковского счета".
Элемент данных "Международный номер банковского счета" должен соответствовать требованиям государственного стандарта Республики Беларусь СТБ ISO 13616-1-2015 "Финансовые услуги. Международный номер банковского счета (IBAN). Часть 1. Структура IBAN", утвержденного постановлением Государственного комитета по стандартизации Республики Беларусь от 7 октября 2015 г. №47.
Элемент данных "Международный номер банковского счета" для номера банковского счета, открытого в банке-участнике системы BISS, за исключением банков-нерезидентов Республики Беларусь, имеет тип данных IBAN2007Identifier и формат фиксированной длины, равный 28 символам: [A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{4}[A-Z0-9]{16}, где:
[A-Z]{2} – международный код страны согласно справочнику N013 (таблица 80);
[0-9]{2} – контрольные цифры номера банковского счета, которые используются для проверки его достоверности и вычисляются согласно СТБ ISO 13616-1-2015;
[A-Z0-9]{4} – первые четыре символа банковского идентификационного кода банков, их филиалов;
[0-9]{4} – балансовый счет согласно плану счетов бухгалтерского учета;
[A-Z0-9]{16} – номер индивидуального счета.
Элемент данных "Международный номер банковского счета" для номера банковского счета, открытого в банке-нерезиденте Республики Беларусь, имеет тип данных IBAN2007Identifier и формат: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}.
16.3. Элемент данных "Зарегистрированный код BIC".
Элемент данных "Зарегистрированный код BIC" должен соответствовать требованиям государственного стандарта Республики Беларусь СТБ ISO 9362-2015 "Банковская деятельность. Сообщения, передаваемые по каналам связи. Бизнес-идентификационные коды (BIC)", утвержденного постановлением Государственного комитета по стандартизации Республики Беларусь от 7 октября 2015 г. №47.
Элемент данных "Зарегистрированный код BIC" (BICFI) банков-участников системы BISS имеет формат [A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?, где:
[A-Z0-9]{4} – цифробуквенный код, однозначно идентифицирующий банк Республики Беларусь, банк-нерезидент (префикс бизнес-участника);
[A-Z]{2} – буквенный код страны согласно справочнику N013 (таблица 80);
[A-Z0-9]{2} – цифробуквенный код местоположения участника расчетов (суффикс бизнес-участника);
[A-Z0-9]{3} – необязательные разряды, которые могут содержать значение условного номера участника расчетов, который используется только для идентификации филиалов.
Элемент данных "Зарегистрированный код BIC" (BICFI) банков не участников системы BISS имеет формат [A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?.
16.4. Элементы данных, содержащие значения суммы, валюты, обменного курса денежных средств и процентов.
Элементы данных, содержащие значения сумм денежных средств (amount, chargeAmount, balanceAmount и т.д.), должны иметь формат 0<=decimal td=18 fd=5 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ "." (точка);
общее количество цифр не должно превышать 18, разделитель не учитывается;
целая часть должна содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
дробная часть указывается, если в данной валюте она присутствует;
количество цифр в дробной части суммы не может превышать пяти и должно соответствовать общегосударственному классификатору Республики Беларусь ОКРБ 016-99 "Валюты", утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. №8 (далее – ОКРБ 016);
если дробная часть в данной валюте присутствует и равна нолю, то количество символов "0" в дробной части должно быть равно максимально допустимому количеству знаков в дробной части для данной валюты, например: 126.00.
Значения сумм денежных средств, представленных в белорусских рублях (amount, equivalentAmount, balanceEquivalentAmount и т.д.), должны иметь формат 0<=decimal td=18 fd=2.
Элементы данных, содержащие значения обменного курса валют (exchangeRate), должны иметь формат 0<=decimal td=11 fd=10 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ "." (точка);
общее количество цифр не должно превышать 11, разделитель не учитывается;
целая и дробная части должны содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
в дробной части ноли после последней значащей цифры отсутствуют.
Курс белорусского рубля указывается к единице той или иной валюты без использования шкалы курса, например: 0.034539 соответствует 3,4539 BYN за 100 RUB.
Элементы данных, содержащие значения процентов (rate), должны иметь формат 0<=decimal<=100 td=11 fd=10 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ "." (точка);
общее количество цифр не должно превышать 11, разделитель не учитывается;
целая и дробная части должны содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
в дробной части ноли после последней значащей цифры отсутствуют;
максимальное значение не должно превышать 100.
Например: 20.0 соответствует 20 0.05 соответствует 0,05 %.
Элемент данных "Валюта" (currency, sourceCurrency, targetCurrency, unitCurrency и т.д.) содержит значение кода валюты, указывается согласно ОКРБ 016 (справочник N003, таблица 80), имеет тип данных CurrencyCode и формат [A-Z]{3}, например: BYN.
16.5. Элементы данных, содержащие значения даты и времени.
Элемент данных "Дата" (valueDate, fromBookingDate, toBookingDate, expirationDate, transactionFromDate, transactionToDate и т.д.) – элемент данных, содержащий значение даты, указывается согласно расширенному формату межгосударственного стандарта ГОСТ ИСО 8601-2001 "Система стандартов по информации, библиотечному и издательскому делу. Представление дат и времени. Общие требования", утвержденного постановлением Комитета по стандартизации, метрологии и сертификации при Совете Министров Республики Беларусь от 22 августа 2002 г. №37 (далее – ГОСТ ИСО 8601), имеет тип данных ISODate и формат YYYY-MM-DD (год-месяц-день).
Элемент данных "Дата и время" (toBookingDateTime, fromBookingDateTime, creationDateTime, statusUpdateDateTime и т.д.) – элемент данных, содержащий значение даты и времени, указывается согласно расширенному формату ГОСТ ИСО 8601, имеет тип данных ISODateTime и формат YYYY-MM-DDThh:mm:ss±hh:mm. Например, для указания даты и времени 26 марта 2021 года 17 ч. 19 мин. 33 сек. (по Минскому времени): 2021-03-26Т17:19:33+03:00.
Элемент данных "Время" – элемент данных, содержащий значение времени, указывается согласно формату ГОСТ ИСО 8601, имеет тип данных ISOTime и формат hh:mm:ss±hh:mm.
Время указывается с учетом часового пояса страны, в случае Республики Беларусь используется GMT+3.
16.6. Элемент данных "Страна".
Элемент данных "Страна" (country) указывается в кодированной форме согласно общегосударственному классификатору Республики Беларусь ОКРБ 017-99 "Страны мира", утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. №8 (далее – ОКРБ 017), (справочник N013, таблица 80), имеет структурированный тип данных CountryCode и формат [A-Z]{2}, например: PL.
Элемент данных "Страна" должен указываться при идентификации нерезидентов Республики Беларусь.
16.7. Элемент данных "Идентификационный налоговый номер".
В элементе данных "Идентификационный налоговый номер" (taxIdentification) указываются статус стороны и учетный номер плательщика (далее – УНП), присвоенный налоговыми органами, в формате [A-Z]{3}[A-Z0-9]{9}, где:
[A-Z]{3} – значение статуса стороны согласно справочнику N061, таблица 80 (INB, INI, INN, INP, INU, INZ);
[A-Z0-9]{9} – УНП.
Глава 2. Требования к структуре API
17. Структура пути 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/payments;
https://api.bank.by/oapi-channel/open-banking/v1.0/accountConsents;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/1234;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/1234/transactions.
18. Заголовки запросов (headers).
Применяемость атрибутов заголовка в зависимости от метода указана в таблице 1.
Таблица 1
|
Параметр |
Определение и правила использования |
Метод |
Метод |
Метод |
|
Content-Type |
Стандартный заголовок HTTP, представляет формат полезной нагрузки в запросе. |
О |
– |
– |
|
Accept |
Стандартный HTTP заголовок, определяющий тип контента, который требуется от сервера. |
Н |
Н |
– |
|
Authorization |
Стандартный заголовок HTTP, используется для пользователей API второго типа. |
О |
О |
О |
|
x-jws-signature |
Указывает, что JSON запрос подписан |
У |
У |
У |
|
x-fapi-auth-date |
Дата последней авторизации в систему пользователя API второго типа. |
Н |
Н |
Н |
|
x-fapi-customer-ipaddress |
IP-адрес клиента, если клиент в данный момент подключен к пользователю API второго типа (в приложении пользователя API второго типа) |
Н |
Н |
Н |
|
x-fapi-interaction-id |
RFC4122 UID, используемый в качестве идентификатора корреляции. |
О |
О |
О |
|
x-idempotency-key |
Уникальный идентификатор запроса для поддержки идемпотентности. |
Н |
– |
– |
|
x-customer-useragent |
В заголовке указывается тип устройства (user-agent), который использует клиент. |
Н |
Н |
Н |
|
x-api-key |
Идентификатор Apikey, сгенерированный в системе дистанционного банковского обслуживания (далее – СДБО) поставщика API, и предназначенный для идентификации и авторизации запросов пользователя API первого типа |
О |
О |
О |
|
x-accountConsentId |
Идентификатор согласия, в рамках которого отправляется запрос. Предназначен для идентификации и авторизации запросов на получение информации по счету (счетам) пользователя API первого типа |
Н |
Н |
Н |
19. Атрибуты заголовков ответов указаны в таблице 2.
Таблица 2
|
Параметр |
Определение и правила использования |
Применяемость |
|
Content-Type |
Стандартный параметр заголовка HTTP. Представляет формат полезной нагрузки, возвращаемой в ответе |
О |
|
Retry-After |
Параметр заголовка, указывающий время (в секундах), в течение которого пользователь API второго типа ожидает перед повторением операции. |
Н |
|
x-jws-signature |
Указывает, что JSON запрос подписан |
У |
|
x-fapi-interaction-id |
RFC4122 UID, используемый в качестве идентификатора корреляции. |
О |
20. Коды статусов исполнения запросов.
В таблице 3 приведены коды статусов исполнения запросов HTTP для различных методов HTTP, которые могут быть получены в результате работы определенных запросов. Перечень ответов не является исчерпывающим.
Таблица 3
|
Код HTTP статуса |
Наименование |
Описание |
Метод |
Метод |
Метод |
|
200 |
OK |
Запрос успешно выполнен |
нет |
да |
нет |
|
201 |
Created |
Операция создания выполнена успешно. Результатом операции является создание нового ресурса |
да |
нет |
нет |
|
204 |
No Content |
Операция удаления успешно завершена |
нет |
нет |
да |
|
400 |
Bad Request |
Запрос имеет неверные отсутствующее или несовместимое тело JSON, параметры URL или поля заголовка. Запрошенная операция не будет выполнена |
да |
да |
да |
|
401 |
Unauthorized |
Заголовок авторизации отсутствует или неверный токен доступа. |
да |
да |
да |
|
403 |
Forbidden |
Токен доступа имеет неверную область действия или была нарушена политика безопасности. |
да |
да |
да |
|
404 |
(Not Found) |
1. Пользователь API второго типа пытается получить ресурс, который указан в спецификации, но не реализован на стороне поставщика API (например, поставщик API решил не реализовывать конечную точку API статуса для внутренних запланированных платежей). |
да |
да |
да |
|
405 |
Method Not Allowed |
Пользователь API второго типа попытался получить доступ к ресурсу с помощью метода, который не поддерживается |
да |
да |
да |
|
406 |
Not Acceptable |
Запрос содержал параметр заголовка Accept, отличный от разрешенных media types, и набор символов, отличный от UTF-8 |
да |
да |
да |
|
415 |
Unsupported Media Type |
Операция была отклонена, поскольку полезная нагрузка находится в формате, не поддерживаемом этим методом на целевом ресурсе |
да |
нет |
нет |
|
429 |
Too Many Requests |
Операция была отклонена, так как слишком много запросов было сделано в течение определенного периода времени. |
да |
да |
да |
|
500 |
Internal Server Error |
Внутренняя ошибка сервера. |
да |
да |
да |
|
503 |
Service Unavailable |
Устаревшая версия сервера. |
да |
да |
да |
Глава 3. Общая модель данных
21. В настоящей главе описана общая верхнеуровневая структура полезной нагрузки запросов и ответов. Подробные структуры запросов и ответов для конкретных методов API приведены в соответствующих разделах стандарта.
21.1. Структура запросов.
Структура верхнего уровня для запросов API имеет следующий вид:
Request Line
Message Headers
{
"data": {
...
},
"risk": {
...
}
}
Строка запроса содержит метод передачи, путь URI для обращения к конкретному запросу API и версию протокола HTTP.Request Line.
Заголовки запросов (Message Headers) характеризуют тело сообщения, параметры передачи и прочие сведения.
Раздел "data" содержит данные для конкретного запроса API. Структура этого элемента отличается для каждой конечной точки API.
Раздел "risk" содержит индикаторы риска для конкретного запроса API, предоставленного пользователем API второго типа.
Индикаторы риска, содержащиеся в этом элементе, могут отличаться для каждой конечной точки API.
21.2. Структура ответов.
Верхнеуровневая структура ответов API имеет следующий вид:
Response Line
Message Headers
{
"data": {
...
},
"risk": {
...
}
"links": {
...
},
"meta": {
...
}
}
В ответы включаются следующие дополнительные верхнеуровневые разделы:
links – данный блок содержит ссылку на текущий запрос и может для системы пагинации содержать ссылки на первую страницу, текущую и на следующую страницу;
meta – данный блок содержит метаинформацию о странице: сколько страниц в системе пагинации и, например, для транзакций, дата и время первой и последней транзакции по счету.
В соответствии с принципом RESTful API полный ресурс воспроизводится как часть ответа.
21.3. В объектах, где значение для необязательного поля [0..1] не указано, поле исключается из полезной нагрузки JSON.
Например, не допускаются следующие варианты:
"unstructed": "";
"unstructed": 0;
"unstructed": {};
"unstructed": "null".
В объектах, где поле массива определено как имеющее значения 0..n, поле массива включается в полезную нагрузку с пустым массивом.
Например, правильный вариант: "balances": [ ].
21.4. В настоящем стандарте некоторые модели запросов и ответов включают в себя объект дополнительных данных (Supplementary Data).
Данный объект позволяет поставщику API принимать или передавать данные, которые не входят в структурированные блоки.
Объект дополнительных данных (Supplementary Data) определяется как пустой объект JSON в настоящем стандарте.
Если поставщик API использует структуру с дополнительными данными (Supplementary Data), то он выкладывает детальное описание структуры в своих ресурсах. Поставщик API не использует структуру Supplementary Data, если добавляемый туда элемент уже существует в структурированных блоках.
22. Структура ответов с ошибками указана общая для всех методов API, описанных в данном документе.
22.1. Структура для ответов с ошибками API имеет следующий вид:
{
"code": "...",
"id": "...",
"message": "...",
"errors": [
{
"errorCode": "...",
"message": "...",
"path": "...",
"url": "..."
}
]
}
22.2. Описание элементов данных ответов с ошибками приведено в таблице 4.
Таблица 4
|
Наименование |
Описание |
Кратность |
Тип данных/ | |
|
errorResponse |
Массив подробных кодов ошибок сообщений и URL-адресов к документации для помощи в исправлении |
– |
– | |
|
code |
Высокоуровневый код ошибки, необходимый для классификации |
[1..1] |
Max40Text | |
|
id |
Уникальный идентификатор ошибки |
[0..1] |
Max40Text | |
|
message |
Краткое описание ошибки. Например: "Что-то не так с предоставленными параметрами запроса" |
[1..1] |
Max500Text | |
|
errors |
Массив ошибок с описанием |
[1..n] |
– | |
|
errorCode |
Низкоуровневое описание ошибки |
[1..1] |
errorCode | |
|
message |
Детализированное описание ошибки. Например: "Обязательное поле не указано" |
[1..1] |
Max500Text | |
|
path |
Путь к элементу с ошибкой в JSON объекте |
[0..1] |
Max500Text | |
|
url |
URL для помощи в устранении проблемы. В данном элементе может быть ссылка на веб-страницу, объясняющую правильное поведение. |
[0..1] |
xs:anyURI | |
22.3. Примерный список кодов низкоуровневых ошибок представлен в таблице 5 с учетом кода ответа HTTP.
Таблица 5
|
Значение |
HTTP-статус |
Описание |
|
BY.NBRB.Field.Expected |
400 |
Если элементы передаются парой (ключ-значение) и значение не было передано. В элементе path должен передаваться путь к ожидаемому элементу (например, errorResponse. errors.path "accountResponse.data.account.accountDetails.identification"). Например, для допустимого значения элемента "schemeName" должно передаваться соответствующее значение идентификатора в элементе "identification" |
|
BY.NBRB.Field.Invalid |
400 |
В элементе указано недопустимое значение или длина предоставленного значения превышает соответствующую максимальную длину элемента в домене поставщика API. Ссылка на недопустимый элемент должна быть указана в элементе path (например, errorResponse.errors.path "accountResponse.data.account.accountDetails. schemeName"). Проблема должна быть подробно описана в сообщении об ошибке, указан конкретный элемент |
|
BY.NBRB.Field.InvalidDate |
400 |
Указана неверная дата. В сообщении можно указать актуальную проблему с датой. Ссылка на недопустимый элемент должна быть указана в элементе path |
|
BY.NBRB.Field.Missing |
400 |
Обязательный элемент отсутствует. Данный код ошибки можно использовать, если ошибка еще не определена при проверке BY.NBRB.Resource.InvalidFormat. Ссылка на отсутствующий элемент должна быть указана в элементе path |
|
BY.NBRB.Header.Invalid |
400 |
В элементе заголовка HTTP указано неверное значение. Элемент заголовка HTTP должен быть указан в элементе path |
|
BY.NBRB.Header.Missing |
400 |
Обязательный элемент HTTP-заголовка не был предоставлен. Элемент заголовка HTTP должен быть указан в элементе path |
|
BY.NBRB.Resource.ConsentMismatch |
400 |
Несоответствие ресурсов согласия и платежного указания. Например, если элемент в разделе "initiation" или "risk" ресурса платежного указания не совпадает с одноименным элементом в соответствующем разделе ресурса согласия. Элемент path должен быть заполнен элементом ресурса платежного указания, который не соответствует согласию |
|
BY.NBRB.Resource.InvalidConsentStatus |
400 |
Согласие, соответствующее ресурсу, находится в некорректном статусе, который бы позволил создать ресурс или выполнить запрос. Например, если ресурс согласия имеет статус AwaitingAuthorisation или Rejected, то ресурс не может быть создан с таким статусом соответствующего ему согласия. Элемент path должен быть заполнен элементом ресурса согласия, который является недопустимым |
|
BY.NBRB.Resource.InvalidFormat |
400 |
Когда json-схема полезной нагрузки не соответствует конечной точке. Например, конечная точка POST/payments вызывается с полезной нагрузкой JSON, которая не может быть проанализирована в классе запроса платежного указания |
|
BY.NBRB.Resource.NotFound |
400 |
Ресурс с указанным идентификатором не существует (ресурс не может быть обработан) |
|
BY.NBRB.Resource.NotCreated |
400 |
Ресурс с указанным идентификатором еще не создан и не может быть передан в ответном сообщении. Для асинхронных вызовов. Например, получение выписки по счету, где сначала создается ресурс выписки (метод POST/statements/{accountId}) и в ответном сообщении приходит идентификатор созданного ресурса выписки, но для наполнения выписки данными поставщика API требуется некоторое время. Соответственно будет приходить данное сообщение об ошибке |
|
BY.NBRB.Resource.NotCancel |
400 |
Ресурс не может быть отозван |
|
BY.NBRB.Rules.AfterCutOffDateTime |
400 |
Ресурс согласия или ресурс платежного указания запрашивается после даты cutOffDateTime |
|
BY.NBRB.Signature.Invalid |
400 |
Заголовок подписи x-jws-signature был проанализирован и имеет действительный заголовок JOSE, соответствующий спецификации, но сама подпись не может быть проверена |
|
BY.NBRB.Signature.InvalidClaim |
400 |
Заголовок JOSE в элементе x-jws-signature имеет одно или несколько утверждений (claim) с недопустимым значением (например, утверждение kid, которое не принимает сертификат). Наименование отсутствующего утверждения должно передаваться в элементе path ответа об ошибке |
|
BY.NBRB.Signature.MissingClaim |
400 |
Заголовок JOSE в элементе x-jws-signature имеет одно или несколько обязательных утверждений, которые не указаны. Имя пропущенного утверждения должно быть указано в элементе path ответа об ошибке |
|
BY.NBRB.Signature.Malformed |
400 |
x-jws-signature в заголовке запроса была искажена и не могла быть проанализирована как допустимый JWS |
|
BY.NBRB.Signature.Missing |
400 |
Запрос API предполагает x-jws-signature в заголовке, но элемент отсутствовал |
|
BY.NBRB.Unsupported.AccountIdentifier |
400 |
Идентификатор счета не поддерживается для данной схемы. Элемент path содержит путь к элементу accountIdentifier |
|
BY.NBRB.Unsupported.LocalInstrument |
400 |
Указанный localInstrument не поддерживается поставщиком API. Элемент path содержит путь к элементу localInstrument. Элемент URL должен быть заполнен ссылкой на документацию поставщика API со списком поддерживаемых localInstrument |
|
BY.NBRB.Reauthenticate |
403 |
Для обработки запроса требуется повторная аутентификация клиента |
|
BY.NBRB.Rules.ResourceAlreadyExists |
409 |
Ресурс с такими же параметрами уже существует |
|
BY.NBRB.UnexpectedError |
5хх |
Возникновение непредвиденной ошибки. Поставщик API должен заполнить сообщение детальным описанием ошибки, не раскрывая конфиденциальную информацию |
Перечень низкоуровневых текстовых ошибок не является исчерпывающим и может быть дополнен поставщиком API, используя свою схему нумерации ошибок "BY.NAME_BANK.errorCode".
Пример:
{
"code": "400 Bad Request",
"id": "2b5f0fb2-730b-11e8-adc0-fa7ae0ghfsfh",
"message": "Невалидные параметры запроса",
"errors": [
{
"errorCode": "BY.NBRB.Resource.ConsentMismatch",
"message": "Элементы initiation в paymentConsents и в payments не совпадают между собой",
"path": "data.initiation"
}
]
}
23. Система пагинации для больших json ответов.
Поставщик API предоставляет постраничный ответ для методов GET, которые возвращают множественные записи.
Если существует следующая страница записей, то поставщик API предоставляет ссылку на следующую страницу записей в элементе links.next ответа. Отсутствие следующей ссылки будет означать, что текущая страница является последней страницей записей.
Для многостраничных ответов поставщик API гарантирует, что количество записей на одной странице составляет минимум 25 записей (кроме последней страницы, где больше нет записей) и максимум 100 записей.
Поставщик API включает "self" ссылку на ресурс в элементе links.self.
Дополнительно поставщик API предоставляет:
ссылку на первую страницу записей в элементе links.first;
общее количество страниц в элементе meta.totalPages.
Настоящий стандарт не определяет, каким образом параметры перелистывания страниц передаются поставщиком API. Каждый поставщик API может использовать свои собственные механизмы для разбивки ответа. Если исходный запрос от пользователя API включал параметры фильтра, то в ответе возвращаются только те результаты (разбитые на страницы), которые соответствуют фильтру.
Пример второй страницы из многостраничного ответа:
{
"data": {
...
},
"links": {
"self": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23?pg=2",
"first": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23",
"next": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23?pg=3"
},
"meta": {
"totalPages": 6,
"firstAvailableDateTime": "2019-05-03T00:00:00+00:00",
"lastAvailableDateTime": "2019-12-03T00:00:00+00:00"
}
}
Пример ответа, когда нет данных:
{
"data": {
"transactionListId": "23",
"transaction": [ ] },
"links": {
"self": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23"
},
"meta": {
"totalPages": 1
}
}
Полный текст доступен после регистрации и оплаты доступа.
Постановление Правления Национального банка Республики Беларусь от 26 августа 2022 года №314
"Об утверждении стандартов проведения расчетов"
О документе
| Номер документа: | 314 |
| Дата принятия: | 26.08.2022 |
| Состояние документа: | Действует |
| Начало действия документа: | 19.10.2022 |
| Органы эмитенты: |
Банки |
Опубликование документа
Национальный правовой Интернет-портал Республики Беларусь от 18 октября 2022 года, 8/38836
Примечание к документу
В соответствии с пунктом 2 настоящее Постановление вступает в силу после его официального опубликования - с 19 октября 2022 года.