Как интегрировать API-интерфейс для проверки BIC в ваше программное обеспечение
1. Что такое API-интерфейс для проверки BIC?
При обработке безналичных платежей и проведении транзакций, в которых используется IBAN, использование правильного BIC или SWIFT кода является залогом успешной оплаты.Наша компания имеет доступ к официальному каталогу BIC кодов от S.W.I.F.T SCRL, что позволяет использовать простой и удобный способ автоматической проверки BIC. Наше решение позволяет интегрировать систему проверки BIC-кода прямо в ваше программное обеспечение, и использовать его для решения внутренних проблем и вопросов
API-интерфейс для проверки BIC предоставляет доступ к SWIFTRef данным. Вся информация о BIC используется с согласия S.W.I.F.T. SCRL. Все права на базу данных кодов принадлежат нашей компании 2019
2. Основные функции
Ключевые функции API-интерфейса для проверки BIC:- Получение информации о банке на основе BIC.
- Поиск по каталогу кодов с использованием наименования банка и страны.
- Поиск по каталогу кодов и ранее сделанным записям.
- Использование базового и расширенного API-интерфейса для простой и быстрой интеграции.
3. Использование API
API-интерфейс для проверки BIC основан на технологии REST, и поддерживает простые запросы HTTP GET и POST.Допустимые параметры представлены в таблице ниже:
| Наименование поля | Длина | Тип | Описание |
|---|---|---|---|
| bic | 11 | Строка | Поиск по коду BIC или SWIFT. Включает в себя 8 или 11 символов. |
| bank_name | 256 | Строка | Часть наименования банка для поиска в каталоге кодов. |
| country | 2 | Строка | Код страны из двух букв. Требуется при поиске информации по наименованию банка. |
| api_key | 128 | Строка | Ваш личный API-ключ. |
| format | 4 | Строка | Используется для определения формата получаемых данных. В настоящее время поддерживаются следующие значения: json, xml |
| limit | Целое число | Опционально: может использоваться для ограничения количества результатов при поиске по наименованию банка. | |
| hist | Целое число | Опционально: может использоваться для отображения ранее созданных записей при поиске по коду или наименованию банка. |
4. Структура ответа API XML
Вы всегда можете скачать XSD схему ответа API.Кроме того, подробное описание возможных ответов представлено в таблице ниже:
| Наименование поля | Тип | Длина | Всегда присутствует | Описание |
|---|---|---|---|---|
| MODIFICATION FLAG | Только буквы | 1 | Да | В дельта-файлах: • A (добавление) • M (изменение) • D (удаление): • A (добавление) |
| CHANGED FIELD | Только числа | 186 | Нет | Сохраняет информацию о поле или теге, которые были изменены как в результате запроса на внесение изменений, так и в результате нового события EVENT. Одна или несколько колонок, представляющие собой комбинацию цифр, при этом, каждое число отображает изменения, который произошли после нового события EVENT. Пример "6,7,8,9" Получается, что EVENT TYPE, EVENT DATE, BIC8, и BRANCH BIC были изменены. Следующие поля не указываются при отображении поля CHANGED FIELD: • RECORD KEY • CHANGED FIELD • MODIFICATION FLAG |
| RECORD KEY | Только числа и буквы | 12 | Да | Уникальный ключ выбранной записи Каждая запись представляет собой отдельное событие в цикле существования BIC. Поле RECORD KEY никогда не изменяется после первичного назначения. |
| PREVIOUS RECORD KEY | Только числа и буквы | 12 | Нет | Поле RECORD KEY предыдущего связанного события EVENT Все события связаны между собой, и могут быть обнаружены благодаря использованию данной информации. |
| NEXT RECORD KEY | Только числа и буквы | 12 | Нет | Поле RECORD KEY следующего связанного события EVENT Все события связаны между собой, и могут быть обнаружены благодаря использованию данной информации. |
| EVENT TYPE | Только буквы | 32 | Да | Событие EVENT, или изменение описания BIC, которое произошло, происходит или произойдет в будущем. Типы событий: • BIC ISSUED • BIC EXPIRED • BIC ACTIVATED ON FIN • BIC ACTIVATED ON FA • BIC ACTIVATED ON IA • BIC DEACTIVATED ON FIN • BIC DEACTIVATED ON FA • BIC DEACTIVATED ON IA • BIC DEACTIVATED • BIC SUSPENDED • BIC REACTIVATED • BIC PUBLISHED • BIC LEGAL NAME CHANGED • BIC INSTITUTION NAME CHANGED • BIC ADDRESS CHANGED • FIN SERVICE CODE CHANGED Дата последнего обновления представляет собой дату последней записи в BIC. При добавлении нового события EVENT, поля MODIFICATION FLAG и CHANGED FIELD будут обновлены с удалением информации о последнем произошедшем событии EVENT. |
| EVENT DATE | Только числа и буквы | 8 | Да | Дата события EVENT |
| BIC8 | Только числа и буквы | 8 | Да | BIC (учреждение, страна и участник), где: • Префикс (4 симв.) • Код страны (2 симв.) • Суффикс (2 симв.) |
| BRANCH BIC | Только числа и буквы | 3 | Да | Идентификатор отделения BIC, связанный с 8-значным кодом BIC. При отсутствии отделения используется XXX. |
| BIC | Только числа и буквы | 11 | Да | Полный BIC: 8-значный идентификатор отделения BIC |
| RECORD STATUS | Только буквы | 1 | Да | Указывает текущее состояние записи: • [C] = текущая запись, которая используется для отображение последнего события на момент публикации, за исключением будущих событий (F). • [H] = исторические записи для выбранного кода. • [F] = будущие события, которые произойдут после публикации данных. Текущее событие (С) будет действовать до момента, определенного в одном из будущих (F) событий. Для будущий событий FUTURE, дата начала действия указывается в поле VALID FROM. |
| OPERATIONALLY ACTIVE RECORD | Альфа | 1 | Да | Существует большое количество записей для одного BIC. Данное поле указывает, какая из имеющихся записей о BIC является активной, и должна использования для ведения операционной деятельности. • [Y] Активно • [N] Неактивно Для каждого кода BIC существует всего одна активная запись, имеющая статус ACTIVE (Y). Исторические записи [H] всегда обозначены символом [N]. Текущие записи могут иметь статус [Y] или [N]. Будущие записи [F] всегда обозначены символом[N]. |
| SUBTYPE INDICATOR | Любое | 4 | Да | Юридическая форма компании. Поле Subtype Indicator используется только для записей, имеющих BIC. |
| SWIFT FIN | Только буквы | 1 | Да | Наличие или отсутствия подключения к FIN: • [Y] - подключено к FIN • [N] - не подключено к FIN |
| SWIFT FA | Только буквы | 1 | Да | Доступность юридического лица через FileAct: • [Y] - подключено к FileAct • [N] - не подключено к FileAct |
| SWIFT IA | Только буквы | 1 | Да | Доступность юридического лица через InterAct: • [Y] - подключено к InterAct • [N] - не подключено к InterAct |
| LEGAL NAME | Любое | 105 | Нет | Официальное наименование юридического лица |
| INSTITUTION NAME | Любое | 105 | Да | Торговое наименование юридического лица (опубликовано) |
| INSTITUTION TYPE | Только буквы | 12 | Да | Компания, выполняющая роль посредника в предоставлении финансовых услуг Тип организации: • FINANCIAL • NONFINANCIAL |
| ENTITY TYPE | Только буквы | 16 | Да | Определяет организационно-правовую форму компании: • Юридическое лицо • Отделение • Операционная касса |
| RE STREET ADDRESS 1 | Любое | 35 | Нет | Адрес регистрации |
| RE STREET ADDRESS 2 | Любое | 35 | Нет | Адрес регистрации |
| RE STREET ADDRESS 3 | Любое | 35 | Нет | Номер дома, строения и офиса |
| RE STREET ADDRESS 4 | Любое | 35 | Нет | Район регистрации |
| RE CITY | Любое | 35 | Нет | Город регистрации отделения или юридического лица |
| RE CPS | Любое | 90 | Нет | Страна, штат или регион регистрации юридического лица или отделения |
| RE ZIP CODE | Любое | 15 | Нет | Индекс регистрации юридического лица или отделения |
| RE POB NUMBER | Любое | 35 | Нет | Разделенные запятыми значения POB отделения или юридического лица, а также индекс. Например, "POB 103352, 40024" Клиенты получают возможность использования полного адреса: POB 103352 40024, DUESSELDORF (CITY) |
| OP STREET ADDRESS 1 | Любое | 35 | Нет | Улица, на которой ведется операционная деятельность |
| OP STREET ADDRESS 2 | Любое | 35 | Нет | Улица, на которой ведется операционная деятельность |
| OP STREET ADDRESS 3 | Любое | 35 | Нет | Номер дома, строения и офиса, в котором ведется операционная деятельность |
| OP STREET ADDRESS 4 | Любое | 35 | Нет | Район, в котором ведется операционная деятельность |
| OP CITY | Любое | 35 | Нет | Город, в котором ведется операционная деятельность |
| OP CPS | Любое | 90 | Нет | Страна штат или регион, в котором ведется операционная деятельность |
| OP ZIP CODE | Любое | 15 | Нет | Индекс, на территории действия которого ведется операционная деятельность |
| OP POB NUMBER | Любое | 35 | Нет | Разделенные запятыми значения POB отделения или юридического лица, а также индекс. Например, "POB 103352, 40024" Клиенты получают возможность использования полного адреса: POB 103352 40024, DUESSELDORF (CITY) |
| BR STREET ADDRESS 1 | Любое | 35 | Нет | Улица, на которой ведется деятельность отделения |
| BR STREET ADDRESS 2 | Любое | 35 | Нет | Улица, на которой ведется деятельность отделения |
| BR STREET ADDRESS 3 | Любое | 35 | Нет | Номер дома, строения и офиса, в котором ведется деятельность отделения |
| BR STREET ADDRESS 4 | Любое | 35 | Нет | Район, в котором ведется деятельность отделения |
| BR CITY | Любое | 35 | Нет | Город, в котором ведется деятельность отделения |
| BR CPS | Любое | 90 | Нет | Страна, штат или регион, в котором ведется деятельность отделения |
| BR ZIP CODE | Любое | 15 | Нет | Индекс, на территории действия которого ведется деятельность отделения |
| BR POB NUMBER | Любое | 35 | Нет | Разделенные запятыми значения POB отделения или юридического лица, а также индекс. Например, "POB 103352, 40024" Клиенты получают возможность использования полного адреса: POB 103352 40024, DUESSELDORF (CITY) |
| BRANCH INFORMATION | Любое | 70 | Нет | Информация об отделении Текстовое описание отделения, предоставленное финансовой организацией, к которой оно относится. В настоящее время данная информация доступна только для записей с BIC, а также только в том случае, если компания хочет предоставить такую информацию. Информация загружается из каталога BIC. |
| COUNTRY NAME | Любое | 70 | Да | Название страны, на территории которой работает юридическое лицо, в соответствии со стандартом ISO 3166 |
| ISO COUNTRY CODE | Только буквы | 2 | Да | Двухзначный код страны в соответствии с ISO 3166-1 |
| LOCATION CODE | Любое | 1 | Да | Указывает на расположение (обычно находится на 7 позиции стандарта BIC 2009) Например: • Для FR, BIC в Париже = P • Для BE, BIC в Брюсселе = B • Для US, BIC на Восточном Побережье = 3 |
| FIN SERVICE CODES | Любое | 60 | Нет | Служебные коды FIN (коды для обозначения дополнительных услуг). Такие коды указываются только для записей с BIC. Данное поле может содержать до двадцати кратких буквенных обозначений. |
| RECORD KEY BDP | Только числа и буквы | 12 | Нет | Уникальный код записи Bank Directory Plus в файле. |
| FIELD A | Любое | 1 | Нет | В настоящее время не используется |
| FIELD B | Любое | 64 | Нет | В настоящее время не используется |
| FIELD C | Любое | 128 | Нет | В настоящее время не используется |
| FIELD D | Любое | 256 | Нет | В настоящее время не используется |
| FIELD E | Любое | 11 | Нет | В настоящее время не используется |
| FIELD F | Любое | 12 | Нет | В настоящее время не используется |
Пример ответа в формате XML от API-интерфейса при поиске BIC будет выглядеть следующим образом:
<result> <bicdata> <row> <modification_flag>A</modification_flag> <changed_field>34</changed_field> <record_key>BP0000004OQQ</record_key> <previous_record_key>BP00000030XZ</previous_record_key> <next_record_key/> <event_type>BIC ADDRESS CHANGED</event_type> <event_date>20150606</event_date> <bic8>BARCGB22</bic8> <branch_bic>XXX</branch_bic> <bic>BARCGB22XXX</bic> <record_status>C</record_status> <operationally_active_record>Y</operationally_active_record> <subtype_indicator>SUPE</subtype_indicator> <swift_fin>Y</swift_fin> <swift_fa>N</swift_fa> <swift_ia>N</swift_ia> <legal_name>BARCLAYS BANK PLC</legal_name> <institution_name>BARCLAYS BANK PLC</institution_name> <institution_type>FINANCIAL</institution_type> <entity_type>Legal Entity</entity_type> <re_street_address_1>1, CHURCHILL PLACE</re_street_address_1> <re_street_address_2/> <re_street_address_3/> <re_street_address_4/> <re_city>LONDON</re_city> <re_cps/> <re_zip_code>E14 5HP</re_zip_code> <re_pob_number/> <op_street_address_1>1 CHURCHILL PLACE</op_street_address_1> <op_street_address_2/> <op_street_address_3/> <op_street_address_4/> <op_city>LONDON</op_city> <op_cps>LONDON E14 5HP</op_cps> <op_zip_code/> <op_pob_number/> <br_street_address_1/> <br_street_address_2/> <br_street_address_3/> <br_street_address_4/> <br_city/> <br_cps/> <br_zip_code/> <br_pob_number/> <branch_information>(ALL U.K. OFFICES)</branch_information> <country_name>UNITED KINGDOM</country_name> <iso_country_code>GB</iso_country_code> <location_code>2</location_code> <fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes> <record_key_bdp>BD00000006FO</record_key_bdp> <field_a/> <field_b/> <field_c/> <field_d/> <field_e/> <field_f></field_f> </row> </bicdata> <errors/> </result>
5. Ошибки API
В случае возникновения ошибки, API возвращает XML-ответ с текстом ошибки.Теги
Ниже представлено подробное описание всех возможных ошибок:
| Status Code | Тип | Описание |
|---|---|---|
| 301 | Ошибка учетной записи | Неправильный API-ключ |
| 302 | Ошибка учетной записи | Истек срок действия подписки |
| 303 | Ошибка учетной записи | Нет доступных записей |
| 304 | Ошибка учетной записи | У вас нет доступа к API |
| 401 | Ошибка ввода | Максимальная длина SWIFT составляет 8 или 11 символов' |
| 402 | Ошибка ввода | Неправильное наименование банка. Может содержать не менее 4 символов.
Доступные значения: a-z, A-Z, 0-9, [пробел]! |
| 403 | Ошибка ввода | Неправильный код страны! Необходимо использовать двухзначный код. Например: UK, DE, FR |