API pro validaci kódu BIC / SWIFT

Jak integrovat API pro validaci kódu BIC do vašeho softwaru

1. Co je API pro validaci kódu BIC?

Při zpracování elektronických plateb a při řešení transakcí souvisejících s IBAN je pro správný platební styk nezbytný správný SWIFT / BIC kód.
Naše společnost udělila licenci oficiálnímu adresáři BIC ze společnosti S.W.I.F.T SCRL, který poskytuje účinný a jednoduchý způsob ověřování BIC automaticky. Tato služba umožňuje integrovat vyhledávání adres BIC do vašeho softwaru pro interní účely

API pro validaci kódu BIC obsahuje uvnitř data SWIFTRef. Data BIC použitá se svolením společnosti S.W.I.F.T. SCRL. Databázová práva vyhrazena 2019

2. Vlastnosti

Klíčové vlastnosti API pro validaci BIC:

  • Získat informace o bance na základě BIC.
  • Vyhledat v adresáři BIC část názvu banky a země.
  • Vyhledat historické záznamy v adresáři BIC
  • Používání kompletní i zjednodušené odezvy API pro snadnější integraci.


3. Použití API

API pro validaci BIC je založeno na REST a podporuje jednoduché požadavky HTTP GET nebo POST.

Přijatelné parametry jsou uvedeny v následující tabulce:

Název pole Délka Typ Popis
bic 11 Řetězec BIC / SWIFT kód pro vyhledávání. Může mít 8 nebo 11 znaků
název_banky 256 Řetězec Část názvu banky k provedení vyhledávání v adresáři BIC.
země 2 Řetězec Dvoumístný kód země. Požadováno při vyhledávání podle názvu banky.
api_klíč 128 Řetězec Váš osobní API klíč.
formát 4 Řetězec Požadováno k zadání formátu vrácených dat. Aktuálně podporované hodnoty: json, xml
limit Celé číslo Volitelné: lze použít k omezení počtu výsledků při vyhledávání podle názvu banky.
hist celé číslo Volitelné: lze použít k zobrazení historických záznamů z databáze pro vyhledávání bank a BIC.
Uvnitř svého internetového portálu najdete klíč API a adresu URL požadavku na koncový bod, která slouží k zabezpečení požadavků na vyhledávání.


4. Struktura odpovědi API XML

Můžete si stáhnout XSD schéma odpovědi API.
Podrobný popis vrácených polí je uveden v tabulce níže:

Název pole Typ Délka Vždy přítomno Popis
VLAJKA ÚPRAV Abecední 1 Ano V souborech delta:
• A (dodatek)
• M (úprava)
• D (smazání) v úplných souborech V úplných souborech:
• A (dodatek)
ZMĚNĚNÉ POLE Číselné 186 Ne Zaznamenává pole (nebo ŠTÍTEK), které se změnilo buď v důsledku změny záznamu nebo jako výsledek nové události.
Jeden nebo více sloupců je označeno jako posloupnost čísel, přičemž každé číslo představující sloupec se změnilo od předchozí instance záznamu nebo předchozí události.
Příklad "6,7,8,9"
To znamená, že se TYP UDÁLOSTI, DATUM UDÁLOSTI, BIC8 a BIC POBOČKY
změnily
Následující položky POLE jsou vyloučeny z toho, aby byly zaznamenány v proměnné POLE:
• KLÍČ ZÁZNAMU
• ZMĚNĚNÉ POLE
• VLAJKA ÚPRAV
KLÍČ ZÁZNAMU Alfanumerické 12 Ano Jedinečný klíč záznamu v souboru
Každý záznam představuje událost v životním cyklu BIC.
Jakmile je přiřazen, KLÍČ ZÁZNAMU se nikdy nezmění.
PŘEDCHOZÍ KLÍČ ZÁZNAMU Alfanumerické 12 Ne KLÍČ ZÁZNAMU dříve připojené UDÁLOSTI
Všechny související události jsou propojeny a mohou být pomocí těchto informací umístěny.
NÁSLEDUJÍCÍ KLÍČ ZÁZNAMU Alfanumerické 12 Ne KLÍČ ZÁZNAMU následně připojené UDÁLOSTI
Všechny související události jsou propojeny a mohou být pomocí těchto informací umístěny
TYP UDÁLOSTI Abecední 32 Ano Popis události nebo změny týkající se BIC, ke které došlo v minulosti, v současnosti nebo v budoucnosti.
Typy událostí:
• BIC VYDÁN
• BIC VYPRŠEL
• BIC AKTIVOVÁN NA FIN
• BIC AKTIVOVÁN NA FA
• BIC AKTIVOVÁN NA IA
• BIC DEAKTIVOVÁN NA FIN
• BIC DEAKTIVOVÁN NA FA
• BIC DEAKTIVOVÁN NA IA
• BIC DEAKTIVOVÁN
• BIC POZASTAVEN
• BIC ZNOVU AKTIVOVÁN
• BIC ZVEŘEJNĚN
• BIC PRÁVNÍ NÁZEV ZMĚNĚN
• BIC INSTITUČNÍ NÁZEV ZMĚNĚN
• BIC ADRESA ZMĚNĚNA
• ZMĚNA FIN SERVISNÍHO KÓDU
Poslední datum aktualizace je poslední řádek sekvence BIC (tj. Poslední položka).
Když je přidán nová UDÁLOSTI, VLAJKA ZMĚN a ZMĚNA
Sloupec POLE bude aktualizován v bezprostřední předchozí související UDÁLOSTI.
DATUM UDÁLOSTI Alfanumerické 8 Ano Datum události
BIC8 Alfanumerické 8 Ano BIC (institution, country, and party suffix) where:
• Prefix skupiny (4 znaky)
• Kód země (2 znaky)
• Suffix skupiny (2 znaky)
BIC POBOČKY Alfanumerické 3 Ano Identifikátor pobočky BIC spojený s 8-znakovým BIC. Pokud neexistuje identifikátor pobočky, použije se XXX.
BIC Alfanumerické 11 Ano Plný BIC: 8-znakový BIC a identifikátor pobočky
STAV ZÁZNAMU Abecední 1 Ano Označuje stav záznamu:
• [C] = Aktuální představení poslední události v řetězci až do data zveřejnění, s výjimkou [F] budoucích událostí
• [H] = Historické záznamy v řetězci událostí
• [F] = Budoucí událost, která nastane po datu vydání adresáře. Dříve uvedená [C] současná událost bude platná až do data určeného v [F] budoucí události.
Datum u BUDOUCÍCH událostí označuje, od kdy bude změna PLATNÁ.
OPERATIVNĚ AKTIVNÍ ZÁZNAM Alfa 1 Ano Existuje více záznamů pro stejný BIC. Toto pole udává, který ze záznamů pro stejný BIC je provozně aktivní a který by měl být použit.
• [Y] Operačně aktivní
• [N] Operačně neaktivní
Pro každý jedinečný BIC existuje jedna položka záznamu označující AKTIVNÍ stav (Y).
Záznamy se stavem [H] historický se vždy označují [N].
Záznamy se stavem [C] současný se označují [Y] nebo [N]
Záznamy se stavem [F] budoucí se vždy označují [N].
INDIKÁTOR PODTYPU Jakýkoli typ 4 Ano Obchodní typ účetní jednotky. Indikátor podtypu je poskytován pouze pro záznamy s BIC.
SWIFT FIN Abecední 1 Ano Stav dosažitelnosti entity prostřednictvím FIN:
• [Y] připojeno k FIN
• [N] nepřipojeno k FIN
SWIFT FA Abecední 1 Ano Stav dosažitelnosti entity prostřednictvím FileAct:
• [Y] připojeno k FileAct
• [N] nepřipojeno k FileAct
SWIFT IA Alfa 1 Ano Stav dosažitelnosti entity prostřednictvím InterAct:
• [Y] připojeno k InterAct
• [N] nepřipojeno k InterAct
PRÁVNÍ NÁZEV Jakákoli 105 Ne Právní název instituce.
NÁZEV INSTITUCE Jakákoli 105 Ano Obchodní název instituce (zveřejněný název)
TYP INSTITUCE Abecední 12 Ano Organizace, která se zabývá zejména finančním zprostředkováním a / nebo pomocnými finančními činnostmi.
Typ instituce:
• FINANČNÍ
• NEFINANČNÍ
TYP ENTITY Abecední 16 Ano Identifikuje typ finanční entity:
• Právnická osoba
• Pobočka
• Provozní
RE ADRESA 1 Jakákoli 35 Ne [Registrace] Název ulice
RE ADRESA 2 Jakákoli 35 Ne [Registrace] Číslo ulice
RE ADRESA 3 Jakákoli 35 Ne [Registrace] Budova, název budovy, patro
RE ADRESA 4 Jakákoli 35 Ne [Registrace] Čtvrť
RE MĚSTO Jakákoli 35 Ne [Registrace] Název města instituce / pobočky
RE CPS Jakákoli 90 Ne [Registrace] Okres, provincie, stát nebo jiný správní region vlastnické instituce / pobočky
RE PSČ Jakákoli 15 Ne [Registrace] PSČ instituce / pobočky
RE ČÍSLO POŠTOVNÍ SCHRÁNKY (ČPS) Jakákoli 35 Ne Pole oddělené čárkou s číslem poštovní schránky instituce / pobočky a příslušným PSČ.
Příklad
"ČPS 103352, 40024"
To umožňuje zákazníkům používat plnou adresu ČPS:
ČPS 103352
40024, DUESSELDORF (MĚSTO)
OP ADRESA 1 Jakákoli 35 Ne [Funkční] Název ulice
OP ADRESA 2 Jakákoli 35 Ne [Funkční] Číslo ulice
OP ADRESA 3 Jakákoli 35 Ne [Funkční] Budova, název budovy, patro
OP ADRESA 4 Jakákoli 35 Ne [Funkční] Čtvrť
OP MĚSTO Jakákoli 35 Ne [Funkční] Název města instituce / pobočky
OP CPS Jakákoli 90 Ne [Funkční] Okres, provincie, stát nebo jiný správní region vlastnické instituce / pobočky
OP PSČ Jakákoli 15 Ne [Funkční] PSČ instituce / pobočky
OP ČÍSLO POŠTOVNÍ SCHRÁNKY (ČPS) Jakákoli 35 Ne Pole oddělené čárkou s číslem poštovní schránky instituce / pobočky a příslušným PSČ.
Příklad
"ČPS 103352, 40024"
To umožňuje zákazníkům používat plnou adresu ČPS:
ČPS 103352
40024, DUESSELDORF (MĚSTO)
BR ADRESA 1 Jakákoli 35 Ne [Pobočka] Název ulice
BR ADRESA 2 Jakákoli 35 Ne [Pobočka] Číslo ulice
BR ADRESA 3 Jakákoli 35 Ne [Pobočka] Budova, název budovy, patro
BR ADRESA 4 Jakákoli 35 Ne [Pobočka] Čtvrť
BR MĚSTO Jakákoli 35 Ne [Pobočka] Název města instituce / pobočky
BR CPS Jakákoli 90 Ne [Pobočka] Okres, provincie, stát nebo jiný správní region vlastnické instituce / pobočky
BR PSČ Jakákoli 15 Ne [Pobočka] PSČ instituce / pobočky
BR ČÍSLO POŠTOVNÍ SCHRÁNKY (ČPS) Jakákoli 35 Ne Pole oddělené čárkou s číslem poštovní schránky instituce / pobočky a příslušným PSČ.
Příklad
"ČPS 103352, 40024"
To umožňuje zákazníkům používat plnou adresu ČPS:
ČPS 103352
40024, DUESSELDORF (MĚSTO)
INFORMACE O POBOČCE Jakákoli 70 Ne Informace o pobočce
Jedná se o bezplatný textový popis pobočky poskytnutý finanční institucí, ke které patří. V současné době bude tato položka poskytnuta pouze pro zápisy do BIC a pouze tehdy, když chce dotyčná finanční instituce tyto doplňující informace poskytnout. Tyto informace pocházejí z adresáře BIC.
NÁZEV ZEMĚ Jakákoli 70 Ano Název země instituce / pobočky, jak je uvedeno v normě ISO 3166
ISO KÓD ZEMĚ Abecední 2 Ano Kód ISO 3166-1, který je složený ze 2 alfa znaků, země instituce / pobočky
KÓD LOKALITY Jakýkoli typ 1 Ano Obsahuje lokalitu (formálně v pozici 7 standardu BIC: 2009)
Příklady:
• V FR, BIC v Paříži = P
• V BE, BIC v Bruselu = B
• V US, BIC na východním pobřeží = 3
FIN KÓDY SLUŽBY Jakýkoli typ 60 Ne Kódy služby FIN (nazývané také kódy služby s přidanou hodnotou). Kódy služby jsou poskytovány pouze pro záznamy obsahující BIC.
Pole může obsahovat až 20 kódů složených ze tří znaků v abecedním pořadí.
KLÍČ ZÁZNAMU BDP Alfanumerické 12 Ne Jedinečný klíč záznamu bankovního adresáře Plus v souboru.
POLE A Jakákoli 1 Ne Vyhrazeno pro budoucí použití
POLE B Jakákoli 64 Ne Vyhrazeno pro budoucí použití
POLE C Jakákoli 128 Ne Vyhrazeno pro budoucí použití
POLE D Jakákoli 256 Ne Vyhrazeno pro budoucí použití
POLE E Jakákoli 11 Ne Vyhrazeno pro budoucí použití
POLE F Jakákoli 12 Ne Vyhrazeno pro budoucí použití
Systém API vrací výsledky ve formátu XML, který lze snadno analyzovat v různých programovacích jazycích a platformách.

Vzorová odpověď XML z rozhraní API pro vyhledávání BIC by byla:


<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. Chyby API

V případě chyby API je vrácena odpověď XML obsahující chybovou zprávu.

Štítky XML jsou vráceny bez jakýchkoli jiných polí v odpovědi XML.

Níže naleznete popis všech možných chybových zpráv, které mohou být vráceny:

Kód stavu Typ Popis
301 Chyba účtu Klíč API je neplatný
302 Chyba účtu Platnost předplatného vypršela
303 Chyba účtu Nejsou k dispozici žádné požadavky
304 Chyba účtu K tomuto rozhraní API nemáte přístup
401 Chyba vstupu Přijatelná délka SWIFT je 8 nebo 11 znaků '
402 Chyba vstupu Název banky je neplatný! Vyhledávání bank by mělo obsahovat minimálně 4 znaky.
Povolené znaky a-z, A-Z, 0-9, [mezera]!
403 Chyba vstupu Nesprávný kód země! Povolen je dvoumístný kód země. Příklad: UK, DE, FR