API за валидиране на BIC / SWIFT кодове

Как да интегрирате API за валидиране на BIC във вашия софтуер

1. Какво представлява API за валидиране на BIC?

При обработката на банкови плащания и работа с транзакции, свързани с IBAN, предоставянето на правилния SWIFT / BIC код е от голямо значение за успешните плащания.
Нашата компания е лицензирала официалната BIC Директория от S.W.I.F.T SCRL, за да осигури мощен и лесен начин за автоматично потвърждаване на BIC. Тази услуга ви позволява да интегрирате BIC код търсенето на директория във вашия софтуер за вътрешни цели.

API-то за валидиране на BIC съдържа данни от SWIFTRef. Данните за BIC се използват с разрешение на S.W.I.F.T. SCRL. Правата за бази данни са запазени2019

2. Характеристика

Ключови характеристики на API за валидиране на BIC:

  • Изтеглете информация за банката въз основа на BIC.
  • Търсете в BIC директорията по част от името на банката и страната.
  • Търсете в BIC директорията за стари записи.
  • Използвайте както цялостен, така и опростен API отговор за по-лесно интегриране.


3. Използване на API

API за валидиране на BIC е REST базиран и поддържа прости HTTP GET или POST заявки.

Приетите параметри са изброени в таблицата по-долу:

Име на полето Дължина Тип Описание
bic 11 String BIC / SWIFT код за търсене. Може да бъде 8 или 11 знака.
bank_name 256 String Част от името на банката за извършване на търсене в директорията на BIC.
country 2 String Двубуквен код на държава. Задължително при търсене по име на банка.
api_key 128 String Вашият персонален API ключ.
format 4 String Задължително е да се определи формата на върнатите данни. В момента се поддържат стойности: json, xml
limit Integer Незадължително: може да се използва за ограничаване на броя на резултатите при търсене по име на банка.
hist integer Незадължително: може да се използва за показване на история от базата данни за банково и BIC търсене.
Във вашия онлайн портал можете да намерите своя API ключ и URL адрес на заявката, който се използва за защита на заявките за търсене.


4. Структура на API за във формат XML

Можете да изтеглите XSD Схема на API отговора.
Подробно описание на връщаните полета можете да видите в таблицата по-долу:

Име на полето Тип Дължина Винаги присъства Описание
MODIFICATION FLAG Alphabetic 1 Да В делта файлове:
• A (прибавяне)
• M (модификация)
• D (триене)
• A (прибавяне)
CHANGED FIELD Numeric 186 Не Записва полето (или TAG), което се е променило в резултат на промяна на запис или в резултат на ново СЪБИТИЕ.
Една или повече колони са обозначени като последователност от числа, като всеки номер представлява колоната, променена от предишния пример на запис или предишното СЪБИТИЕ.
Пример "6,7,8,9"
Това означава, че EVENT TYPE, EVENT DATE, BIC8, и BRANCH BIC са се
променили.
Следните FIELDS са изключени от запис в CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alphanumeric 12 Да Уникалният ключ на записа във файла
Всеки запис представлява събитие в жизнения цикъл на BIC.
Веднъж зададено, RECORD KEY не се променя.
PREVIOUS RECORD KEY Alphanumeric 12 Не RECORD KEY от предишния свързан EVENT
Всички свързани събития са свързани и могат да се намират, като се използва тази информация.
NEXT RECORD KEY Alphanumeric 12 Не RECORD KEY на следващото свързано събитие
Всички зависещи помежду си събития са свързани и могат да се намират, като се използва тази информация
EVENT TYPE Alphabetic 32 Yes 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 Alphanumeric 8 Да Дата на EVENT
BIC8 Alphanumeric 8 Да BIC (суфикс на институция, държава и страна), където:
• суфикс на институция (4 char)
• Код на държава (2 char)
• суфикс на страна(2 char)
BRANCH BIC Alphanumeric 3 Да Идентификаторът на BIC клона, свързан с 8-знаковия BIC. Ако не съществува идентификатор на клон, тогава се използва XXX.
BIC Alphanumeric 11 Да Пълният BIC: 8-знаков BIC и идентификатор на клон
RECORD STATUS Alphabetic 1 Да Показва състоянието на записа:
• [C] = Текущи, представляващи последното събитие във веригата до датата на публикуване, с изключение на бъдещи събития
• [H] = Исторически записи във веригата на събитията
• [F] = Бъдещо събитие, което ще се случи след датата на публикуване на директорията. Посоченото по-рано текущо събитие ще бъде валидно до датата, посочена в бъдещото събитието.
За бъдещи събития датата показва от кога промяната ще бъде ВАЛИДНА.
OPERATIONALLY ACTIVE RECORD Alpha 1 Yes Има няколко записа за един и същ BIC. Това поле показва коя от записите за една и съща BIC е оперативно активната BIC и трябва да се използва.
• [Y] Оперативно активен
• [N] Оперативно неактивен
За всеки уникален BIC има един запис, показващ активен статус (Y).
Записи с Исторически(H) винаги ще показват [N].
Записи с текущ [C] може да индикират с [Y] или [N].
Записи с [F] винаги ще показват [N].
SUBTYPE INDICATOR Any type 4 Да Бизнес типът на предприятието. Индикаторът за подтип се предоставя само за записи с BIC.
SWIFT FIN Alphabetic 1 Да Състояние на връзката с FIN:
• [Y] свързано с FIN
• [N] не е свързано с FIN
SWIFT FA Alphabetic 1 Да Статут на достижимостта чрез FileAct:
• [Y] свързано с FileAct
• [N] не е свързано с FileAct
SWIFT IA Alpha 1 Да Състояние на достъпността на предприятието чрез InterAct:
• [Y] свързано с InterAct
• [N] не е свързано с InterAct
LEGAL NAME Any 105 Не Правно наименование на институцията
INSTITUTION NAME Any 105 Да Търговско име на институцията (публикувано име)
INSTITUTION TYPE Alphabetic 12 Да Организация, която основно се занимава с финансово посредничество и / или със спомагателни финансови дейности
Вид институция:
• FINANCIAL
• NONFINANCIAL
Тип Alphabetic 16 Yes Определя типът
• Legal Entity
• Branch
• Operational
RE STREET ADDRESS 1 Any 35 Не [Регистрация] Номер на улица
RE STREET ADDRESS 2 Any 35 Не [Регистрация] Номер на улица
RE STREET ADDRESS 3 Any 35 Не [Регистрация] Сграда, име на сграда, етаж
RE STREET ADDRESS 4 Any 35 Не [Регистрация] Област
RE CITY Any 35 Не [Регистрация]Име на града на институцията / клона
RE CPS Any 90 Не [Регистрация] Област, провинция, държава или друг административен район на институцията / клона на собственика
RE ZIP CODE Any 15 Не [Регистрация] Пощенски код на институцията / клона
RE POB NUMBER Any 35 Не Полето, разделено със запетая с номер на началник на институцията / клона и съответния пощенски код.
Пример
"POB 103352, 40024"
Това позволява на клиентите да използват пълния POB адрес:
POB 103352
40024, ДЮСЕЛДОРФ(ГРАД)
OP STREET ADDRESS 1 Any 35 Не [Оперативен] Име на улица
OP STREET ADDRESS 2 Any 35 Не [Оперативен] Номер на улица
OP STREET ADDRESS 3 Any 35 Не [Оперативен] Сграда, име на сграда, етаж
OP STREET ADDRESS 4 Any 35 Не [Оперативен] Област
OP CITY Any 35 Не [Оперативен] Име на града на институцията / клона
OP CPS Any 90 Не [Оперативен] Област, провинция, държава или друг административен район на институцията / клона на собственика
OP ZIP CODE Any 15 Не [Оперативен] Пощенски код на институцията / клона
OP POB NUMBER Any 35 Не Пощенски код на полето, отделено от институцията / ома, с POB номера на институцията / клона и съответния пощенски код
Пример
"POB 103352, 40024"
Това позволява на клиентите да използват пълния POB адрес:
POB 103352
40024, ДЮСЕЛДОРФ (ГРАД)
BR STREET ADDRESS 1 Any 35 Не [Клон] Име на улица
BR STREET ADDRESS 2 Any 35 Не [Клон] Номер на улица
BR STREET ADDRESS 3 Any 35 Не [Клон] Сграда, име на сграда, етаж
BR STREET ADDRESS 4 Any 35 Не [Клон] Area
BR CITY Any 35 Не [Клон] Браншово име на институцията / клона
BR CPS Any 90 Не [Клон] Област, провинция, държава или друг административен район на институцията / клона на собственика
BR ZIP CODE Any 15 Не [Клон] Пощенски код на институцията / клона
BR POB NUMBER Any 35 Не Полето, разделено със запетая с номер на началник на институцията / клона и съответния пощенски код.
Пример
"POB 103352, 40024"
Това позволява на клиентите да използват пълния POB адрес:
POB 103352
40024, ДЮСЕЛДОРФ (ГРАД))
BRANCH INFORMATION Any 70 Не Информация за клона
Това е свободно текстово описание на клона, предоставено от финансовата институция, към която принадлежи. За момента това ще се предоставя само за вписвания с BIC и само когато съответната финансова институция иска да предостави тази допълнителна информация. Информацията е получена от BIC Directory.
COUNTRY NAME Any 70 Да Името на държавата на институцията / клона, както е посочено в ISO 3166
ISO COUNTRY CODE Alphabetic 2 Да Код по ISO 3166-1 алфа-2 на страната на институцията / клона
LOCATION CODE Any type 1 Да Съдържа местоположението (официално в позиция 7 на стандарта BIC: 2009)
Примери:
• В FR, BIC в Париж = P
• В BE, BIC в Брюксел = B
• В US, BIC на Източният Бряг = 3
FIN SERVICE CODES Any type 60 Не FIN кодове на услуги (наричани още кодове за услуги с добавена стойност). Кодовете за обслужване се предоставят само за записи, съдържащи BIC.
Полето може да съдържа до 20 трибуквени кода по азбучен ред.
RECORD KEY BDP Alphanumeric 12 Не Уникалният ключ на записа на Bank Directory Plus във файла.
FIELD A Any 1 Не Запазено за бъдещо ползване
FIELD B Any 64 Не Запазено за бъдещо ползване
FIELD C Any 128 Не Запазено за бъдещо ползване
FIELD D Any 256 Не Запазено за бъдещо ползване
FIELD E Any 11 Не Запазено за бъдещо ползване
FIELD F Any 12 Не Запазено за бъдещо ползване
API системата връща резултати в XML формат, който е лесно да се анализира в различни програмни езици и платформи.

Примерният 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 отговор, съдържащ съобщението за грешка.

XML таговете се връщат без никакви други полета в XML отговора.

По-долу можете да намерите описание на всички възможни съобщения за грешки, които могат да бъдат върнати:

Статус код Тип Описание
301 Account Error Ключът на API е невалиден
302 Account Error Абонаментът изтече
303 Account Error Няма налични заявки
304 Account Error Нямате достъп до този API
401 Input Error Валидната дължина на SWIFT е 8 или 11 знака
402 Input Error Името на банката е невалидно! Банковото търсене трябва да бъде минимум 4 знака.
Разрешени символи: a-z, A-Z, 0-9, [space]!
403 Input Error Кодът на държавата е неправилен! Позволен е 2-буквен код на държава. Пример: UK, DE, FR