BIC / SWIFT Kód Hitelesítő API

Hogyan integráljuk a BIC Hitelesítő API-t a szoftverünkbe

1. Mi az a BIC Hitelesítő API?

A fizetések feldolgozása és az IBAN-ra vonatkozó tranzakciók kezelése során a megfelelő SWIFT / BIC-kód biztosítása nélkülözhetetlen a sikeres kifizetésekhez.
Cégünk számára engedélyezte a S.W.I.F.T SCRL hivatalos BIC Könyvtárát, ezzel biztosítva egy hatékony és egyszerű módját a BIC automatikus hitelesítésének. Ez a szolgáltatás lehetővé teszi, hogy belső célokra integrálja a BIC-kódkönyvtár-keresést a szoftverébe.

A BIC Hitelesítő API SWIFTRef Data Inside-al rendelkezik. A BIC adatok a S.W.I.F.T. engedélyével használhatók. SCRL. Adatbázis jogai fenntartva 2019

2. Jellemzők

BIC Hitelesítő API főbb jellemzői:

  • A banki adatok lekérése a BIC alapján.
  • Keresés a BIC könyvtárban a banknév és az ország alapján.
  • Keresés a BIC könyvtárban régebbi feljegyzésekre.
  • A könnyebb integráció érdekében mind teljes, mind egyszerűsített API-válasz használata.


3. API Használata

A BIC Hitelesítő API REST alapú és az egyszerű HTTP GET vagy POST lekérdezéseket támogatja.

Az elfogadott paraméterek az alábbi táblázatban találhatók:

Mező neve Hossz Típus Leírás
bic 11 String SWIFT / BIC kód. 8 vagy 11 karakter.
bank_name 256 String BIC címtárkeresés részleges banknévvel.
country 2 String Kétbetűs országkód. Szükséges a banknév alapján történő kereséshez.
api_key 128 String Személyes API kulcs.
format 4 String A visszaadott adatok formátumának megadása szükséges. Jelenleg támogatott formátumok: json, xml
limit Integer Opcionális: bankszámmal történő keresés során korlátozható az eredmények száma.
hist integer Opcionális: a banki és a BIC-keresési adatbázisokból származó régebbi rekordok megjelenítésére is használható.
Az online portálon megtalálja az API kulcsot és a lekérdezési végpont URL-jét, amelyet a keresési kérelmek biztosítására használnak.


4. API XML Válasz Struktúra

Letölthet egy XSD Schema -t az API válaszról.
A visszatérési mezők részletes leírása az alábbi táblázatban található:

                                                                                                                                                                                                                                                                                                                                     
Mező neve Típus Hossz Mindig megjelenik Leírás
MODIFICATION FLAG Alfabetikus 1 Igen Delta fájlokban: :
• A (hozzáadás)
• M (módosítás)
• D (törlés) teljes fileokban:
• A (hozzáadás)
CHANGED FIELD Numerikus 186 Nem Minden olyan módosítást vagy új eseményt rögzít, amely a mezőt vagy a TAG-t megváltoztatta.
Ezt egy vagy több olyan szám jelzi, amely egy számot jelenít meg, ami az előző EVENT vagy a rekordpéldány oszlopának változásait mutatja.
Példa "6,7,8,9"
Ez azt jelenti, hogy az EVENT TYPE, EVENT DATE, BIC8, és BRANCH BIC megváltozott.
A következő MEZŐK nem lehetnek a CHANGED FIELD-ben:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alfanumerikus 12 Igen A rögzített fájl egyedi kulcsa.
A BIC életciklusának minden eseményét egy rekord képviseli.
Elosztása után a RECORD KEY változatlan.
PREVIOUS RECORD KEY Alfanumerikus 12 Nem A korábban kapcsolódó EVENT RECORD KEY.
Ezek az adatok felhasználhatók a kapcsolódó események megtalálásához, mivel ezek mindegyike összekapcsolódik.
NEXT RECORD KEY Alfanumerikus 12 Nem Az ezt követő összekapcsolt esemény RECORD KEY.
Ezek az adatok felhasználhatók az összes kapcsolódó esemény megtalálásához
EVENT TYPE Alfabetikus 32 Igen A változás leírása vagy az esemény, ami BIC-hez kapcsolódik és jelen, múltban vagy jövőben történik.
Esemény típusok:
• 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
Az utolsó frissítési dátum a BIC sorozat utolsó sora (azaz a legutóbbi bejegyzés)
Új esemény felvételekor a CHANGED és MODIFICATION FLAG
FIELD oszlop frissül az előző eseményhez kapcsolódó eseményen.
EVENT DATE Alfanumerikus 8 Igen Az esemény időpontja.
BIC8 Alfanumerikus 8 Igen BIC (ország, intézmény és fél utótag) ahol:
• országkód (2 karakter)
• fél előtag (4 karakter) )
• fél utótag (2 karakter)
BRANCH BIC Alfanumerikus 3 Igen A BIC 8-karakteres BIC-fiókazonosítója. Ha nincs fiókazonosító, akkor a XXX van írva.
BIC Alfanumerikus 11 Igen A teljes BIC: Branch azonosító és 8 karakter BIC.
RECORD STATUS Alfabetikus 1 Igen A rekord állapotának megjelölése:
• [C] = Jelenleg a közzétételi dátumig a legújabb lánc eseményt képviseli, nem tartalmazza az [F] eseményeket.
• [H] = Az eseménylánc történelmi rekordjai.
• [F] = A jövőben megjelenő esemény a könyvtár közzétételi dátuma után. A fent említett [C] aktuális esemény az [F] rendezvényen megadott időpontig érvényes.
A FUTURE események tartalmazzák a VALID FROM változás dátumát.
OPERATIONALLY ACTIVE RECORD Alpha 1 Igen A BIC-k több rekordot tartalmaznak azokkal kapcsolatban. Ebben a mezőben a működési szempontból aktív BIC (a használni kívánt) szerepel.
• [Y] Működőképes
• [N] Működési szempontból inaktív
Minden egyedi BIC-hez egyetlen ACTIVE (Y) rekord bejegyzés tartozik.
A [H] történelmi rekordokat mindig [N] jelzi.
A [C] aktuális rekordokat az [Y] vagy [N] jelzi.
Az [F] rekordokat mindig [N] jelzi.
SUBTYPE INDICATOR Bármilyen típus 4 Igen Az egység üzleti típusa. Csak a BIC-t tartalmazó rekordokhoz tartozik egy altípus-jelző.
SWIFT FIN Alfabetikus 1 Igen A gazdálkodó egység FIN-hez való csatlakozási állapota:
• [Y] csatlakozik FIN-hez
• [N] nem csatlakozik FIN-hez
SWIFT FA Alfabetikus 1 Igen Az entitás elérhetőségi állapota a FileAct-n keresztül:
• [Y] csatlakozik a FileAct-hez
• [N] nem csatlakozik a FileAct-hez
SWIFT IA Alpha 1 Igen Az entitás elérhetőségi állapota az InterAct-on keresztül:
• [Y] csatlakozik az InterAct-hez
• [N] nem csatlakozik az InterAct-hez
LEGAL NAME Bármilyen 105 Nem Az intézmény jogi neve.
INSTITUTION NAME Bármilyen 105 Igen Az intézmény közzétett kereskedelmi neve.
INSTITUTION TYPE Alfabetikus 12 Igen Szervezet, amely elsősorban pénzügyi közvetítéssel és / vagy kiegészítő pénzügyi tevékenységekkel foglalkozik  Intézmény típusa:
 • PÉNZÜGYI KÖZLEMÉNY  • NINFINANCIAL
ENTITY TYPE alfabetikus 16 Igen Meghatározza a pénzügyi entitás típusát:
 • Jogi jogi személy  • fiókfiók  • Működési
RE STREET ADDRESS 1 Bármilyen 35 Nem [Regisztráció] Utca neve
RE STREET ADDRESS 2 Bármilyen 35 Nem [Regisztráció] Utcai szám
RE STREET ADDRESS 3 Bármilyen 35 Nem [Regisztráció] Épület, épület neve, padló
RE STREET ADDRESS 4 Bármilyen 35 Nem [Regisztráció] terület
RE CITY Bármilyen 35 Nem [Regisztráció] Az intézmény / fiók város neve
RE CPS Bármilyen 90 Nem [Regisztráció] Megye, tartomány, állam, vagy a tulajdonos intézmény / fiók egyéb közigazgatási területe
RE ZIP kód Bármilyen 15 Nem [Regisztráció] Az intézmény / fiók irányítószám
RE POB NUMBER Bármilyen 35 Nem vesszővel elválasztott mező az intézmény / ág POB-számával és a kapcsolódó irányítószámmal.
 példa katalógusa  "POB 103352, 40024"  Ez lehetővé teszi az ügyfelek számára a teljes POB cím használatát:
 POB 103352
 40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 Bármilyen 35 Nem [Működési] Utca neve
OP STREET ADDRESS 2 Bármilyen 35 Nem [Működési] Utcai szám
OP STREET ADDRESS 3 Bármilyen 35 Nem [Működési] épület, épület neve, padló
OP STREET ADDRESS 4 Bármilyen 35 Nem [Működési] terület
OP CITY Bármilyen 35 Nem [Intézmény] Az intézmény / fiók város neve
OP CPS Bármilyen 90 Nem [Működési] Megye, tartomány, állam vagy a tulajdonosi intézmény / fiók egyéb közigazgatási területe
OP ZIP CODE Bármilyen 15 Nem [Intézmény] Az intézmény / fiók postai azonosítója
OP POB NUMBER Bármilyen 35 Nem vesszővel elválasztott mező az intézmény / ág POB-számával és a kapcsolódó irányítószámmal.
 példa katalógusa  "POB 103352, 40024"  Ez lehetővé teszi az ügyfelek számára a teljes POB cím használatát:
 POB 103352
 40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Bármilyen 35 Nem [Ágazat] Utca neve
BR STREET ADDRESS 2 Bármilyen 35 Nem [Branch] Utcai szám
BR STREET ADDRESS 3 Bármilyen 35 Nem [Fiók] Épület, épület neve, emelet
BR STREET ADDRESS 4 Bármilyen 35 Nem [Branch] Terület
BR CITY Bármilyen 35 Nem [Branch] Az intézmény / fiók város neve
BR CPS Bármilyen 90 Nem [Branch] County, province, state, or other administrative region of the owner institution/branch
BR ZIP CODE Bármilyen 15 Nem [Ágazat] Az intézmény / fiók irányítószáma
BR POB NUMBER Bármilyen 35 Nem A mező vesszővel elválasztva, amely fiók / intézmény POB-számát és a kapcsolódó irányítószámot tartalmazza.
Példa
"POB 103352, 40024"
kliensek teljes POB címet használhatnak:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Bármilyen 70 Nem Branch information
Ágazati információk Ez a leírás a fióktelep szabad szöveges változata, amelyet a tulajdonos pénzügyi intézmény nyújt. Jelenleg csak a BIC-be való bejegyzésre, és csak az érintett pénzügyi intézmény beleegyezésére adják meg. Ezek az adatok BIC Directory-forrásból származnak.
COUNTRY NAME Bármilyen 70 Igen Az intézmény ország neve az ISO 3166 szerint.
ISO COUNTRY CODE Alfabetikus 2 Igen Az intézmény ország alpha-2 kódja az ISO 3166-1 szerint.
LOCATION CODE Bármilyen típus 1 Igen Tartózkodási hely (a 7. pozícióban a hivatalos BIC szabvány szerint: 2009).
Példák:
• FR, BIC Párisz = P
• BE, BIC Brüsszel = B
• US, BIC Kelet = 3
FIN SERVICE CODES Bármilyen típus 60 Nem A hozzáadottérték-szolgáltatási kódok a FIN szolgáltatáskódok másik neve. A BIC-vel rendelkező rekordok az egyetlenek, amelyek szolgáltatási kódokat tartalmaznak.
Ez a mező akár 20 alfabetikus 3 karakteres kódot is tartalmazhat.
RECORD KEY BDP Alfanumerikus 12 Nem A Bank Directory Plus egyedi kulcs a fájlban.
FIELD A Bármilyen 1 Nem Jövőbeni használatra fenntartva
FIELD B Bármilyen 64 Nem Jövőbeni használatra fenntartva
FIELD C Bármilyen 128 Nem Jövőbeni használatra fenntartva
FIELD D Bármilyen 256 Nem Jövőbeni használatra fenntartva
FIELD E Bármilyen 11 Nem Jövőbeni használatra fenntartva
FIELD F Bármilyen 12 Nem Jövőbeni használatra fenntartva
Az API-rendszer XML-formátumú eredményeket ad vissza, melyet különféle programozási nyelveken és platformokon könnyű elemezni.

A BIC-kereséshez az API-ból származó XML-válasz például:


<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 Hibák

Hiba esetén az API visszaküldi a hibaüzenetet tartalmazó XML-választ.

A XML-címkék más mezők nélkül kerülnek visszaadásra az XML-válaszban.

Az alábbiakban megtalálhatja az összes lehetséges visszatérő hibaüzenet leírását:

Státusz Kód Típus Leírás
301 Fiókhiba Érvénytelen API kulcs.
302 Fiókhiba Az előfizetés lejárt.
303 Fiókhiba Nincs elérhető lekérdezés.
304 Fiókhiba Nincs hozzáférése ehhez az API-hoz
401 Bemeneti hiba Az elfogadható SWIFT hosszúság 8 vagy 11 karakter.
402 Bemeneti hiba A bank neve érvénytelen! A keresésben legalább 4 karaktert kell használni.
Engedélyezett karakterek a-z, A-Z, 0-9, [space]!
403 Bemeneti hiba Az országkód helytelen! Kétbetűs országkód a megengedett ... Pl. DE, FR, UK