API dokumentacija za IBAN kalkulacije

Ovaj API je deo našeg IBAN paketa usluga

API vodič za integraciju

1. Šta je IBAN API za kalkulaciju?

IBAN engine za kalkulaciju (odnosno IBAN konverzija) je programski sistem koji omogućava klijentima da pretvaraju domaće bankovne kodove i kombinacije brojeva računa u proverene Međunarodne brojeve bankovnih računa ( IBAN ).

Sistem pruža našim klijentima ručni interfejs, te dozvoljava API integraciju u njihove interne preduzetne sisteme.

Sistem takođe identifikuje banke i finansijske institucije, te pruža detalje našim klijentima.

2. Značajke

Ispod su navedene neke od ključnih značajki našeg IBAN engine-a za kalkulacije:

  • Provera lokalnih bankovnih kodove / čeksuma brojeva naloga ( * pogledati podržane države )
  • Dobivanje informacija o banci na osnovu lokalnog koda banke/filijale.
  • Automatsko generisanje važećeg IBAN formata za dati kod i broj računa banke/filijale
  • Sistem podržava višestruke formate odgovora ( JSON / XML )

3. Podržane države

IBAN API kalkulacije trenutno podržava sledeće države i polja koja naš API zahteva za kalkulaciju IBAN koda.

Kod države Naziv države Kod banke Filijala Nalog Kontrolni broj **
AT Austrija DA   DA  
BE Belgija DA   DA DA
CH Švajcarska DA   DA  
DE Nemačka DA   DA  
EE Estonija     DA  
ES Španija DA DA DA DA
FI Finska     DA DA
FR Francuska DA DA DA DA
GB Velika Britanija DA   DA DA
HU Mađarska     DA DA
IE Irska DA   DA DA
IT Italija DA DA DA DA
MC Monako DA DA DA DA
MR Mauritanija DA DA DA  
MT Malta DA   DA  
NO Norveška     DA DA
PT Portugal DA DA DA DA
SM San  Marino DA DA DA  
CZ Češka Republika DA   DA DA
AL Albanija DA   DA  
SK Slovačka DA   DA DA
SI Slovenija DA   DA DA
PL Poljska DA   DA DA
PK Pakistan DA   DA  
SE Švedska DA   DA DA
NL Nizozemska DA DA
Kolona kontrolnog broja navodi da li država podržava broj naloga i/ili validaciju kontrolnog broja bankovnog koda.

Validacija kontrolnog broja je dodatni sloj zaštite podatkovnog integriteta od grešaka prilikom unosa.

4. API unosi

API prihvaća i HTTP GET i POST zahteve kao oblike unosa.
Prihvaćeni parametri su navedeni u tabeli ispod:

Naziv polja Tip Opis
api_key String Vaš lični API ključ. Dobiva se u zoni za klijente.
format String Format API odgovora ( xml ili json )
država String dvoslovni kod države ( UK/US/DE/FR )
bankovni kod String Jedinstveni identifikator banke. Različit je za svaku državu. ( opciono ). Neke države samo traže broj naloga.
filijala String Jedinstveni lokalni identifikator filijale ( opciono )
nalog String Broj ličnog naloga
cd Broj Kontrolni brojevi u nekim državama.
prefiks broj Trenutno potreban isključivo za Češku Republiku ( opciono )
Prvi argument je API ključ, ovo je jedinstveni string koji našem sistemu pomaže da identificira vas kao korisnika i omogući vam pristup API-ju.

API podržava višestruke formate odgovora kako bi se osigurala jednostavnija integracija. Trenutno su podržani XML i JSON formati.

Argumenti države se moraju sastojati od dvoslovnog ISO koda države kao što je UK za Veliku Britaniju, DE za Nemačku, FR za Francusku...
Bankovni kod ima različitu dužinu i strukturu za svaku državu.

Kod filijale je opcioni argument i potreban je isključivo za neke države ( pogledati primere )
Broj naloga je potreban za sve države, a u nekim slučajevima to je jedini parametar koji se koristi za kalkulaciju IBAN-a.

Kontrolni brojevi su potrebni isključivo za neke države koje su implementovale takve algoritme validacije u svojim domaćim strukturama brojeva bankovnih naloga. ( pogledati Primere )

Prefiks je polje koje je opciono potrebno samo za kalkulacije IBAN-a za Češku Republiku.

5. API primeri

U tabeli ispod možete pronaći primer aktivnog GET upita za naš API za svaku državu.

Država Primer upita (GET ZAHTEV)
AT ?country=AT&format=json&bankcode=12000&account=52700357958
BE ?country=BE&format=json&bankcode=250&account=0135106&cd=70
CH ?country=CH&format=json&bankcode=0240&account=240C08011570
DE ?country=DE&format=json&bankcode=BLZ37010050&account=399509
EE ?country=EE&format=json&account=55000005511439
ES ?country=ES&format=json&bankcode=0081&branch=1731&cd=91&account=0006040912
FI ?country=FI&format=json&account=52900261901092
FR ?country=FR&format=json&bankcode=30056&branch=00264&account=02640016443
GB ?country=GB&format=json&bankcode=090127&account=93496333
HU ?country=HU&format=json&account=107000240416330551100005
IE ?country=IE&format=json&bankcode=905838&account=71924374
IT ?country=IT&format=json&country=IT&bankcode=02008&branch=30545&account=000103685854
MC ?country=MC&format=json&country=MC&bankcode=30002&branch=03260&account=0000079112A
MR ?country=MR&format=json&bankcode=00012&branch=00001&account=00000078326
MT ?country=MT&format=json&bankcode=07113&account=199008240010
NO ?country=NO&format=json&account=96803502045
PT ?country=PT&format=json&bankcode=0038&branch=0000&cd=81&account=39551148771
PK ?country=PK&format=json&bankcode=HABBPKKA&account=39551148771
SE ?country=SE&format=json&bankcode=9150&account=0092395696
SM ?country=SM&format=json&country=SM&bankcode=03034&branch=09800&account=000060164676
CZ ?country=CZ&format=json&prefix=51&account=1707230277&bankcode=0100
AL ?country=AL&format=json&bankcode=20511117&account=374362CLPRCFEURC
SK ?country=SK&format=json&prefix=&account=4110053902&bankcode=3100
SI ?country=SI&format=json&bankcode=33000&account=0000102423
PL ?country=PL&format=xml&bankcode=11402004&account=0000360275244226
SE ?country=SE&format=json&bankcode=9300&account=5913222524
NL ?country=NL&format=json&account=0006642318

6. Struktura API XML odgovora

Detaljan opis potencijalnih polja koja mogu biti vraćena odgovorom je prikazan u tabeli ispod:

Naziv polja Tip Opis
adresa String Adresa filijale ili centrale banke
banka String Naziv banke ili finansijske institucije
bic String BIC ( Identifikacioni kod banke ) banke
filijala String Naziv filijale identifikovan od strane koda banke
grad String Naziv grada gde je filijala locirana.
država String Dvoslovna skraćenica koda države, npr. US, UK, AU, FR … i sl.
e-mail String Dodeljena kontaktna e-mail adresa banke ili filijale
faks String Faks broj filijale/banke
telefon String Kontaktni telefonski broj banke/filijale
savezna država String Savezna država adrese banke/filijale
veb sajt String Veb sajt adresa banke/filijale
poštanski broj String Poštanski broj adrese banke
API sistem vraća rezultate u XML ili JSON formatima, koje je lako parsirati u mnogim programskim jezicima i platformama.

Primer XML odgovora iz API-ja za pretragu SORT koda i broja naloga u Velikoj Britaniji bi bio sledeći:

URL upita:

?api_key=9834hAHx78ba4g8habsdk&country=GB&format=json&bankcode=110377&account=10218962

<result>
<iban>GB20ULSB98006054100029</iban>
<account>54100029</account>
<sort_code>980060</sort_code>
<bank>ULSTER BANK LTD</bank>
<branch>BELFAST CITY OFFICE 1</branch>
<bic>ULSBGB2BXXX</bic>
<address>PO BOX 232 11-16 DONEGALL SQUARE EAST </address>
<city>BT1 5UB</city>
<country>GB<country/>
<phone>028 90244112</phone>
</result>

Odgovor za isti upit ako korisnik odabere JSON formatiranje bi bio:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","branch":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","address":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","city":"BT1 5UB","country":"GB","phone":"028 90244112"

7. API greške

U slučaju greške IBAN kalkulacije, API vraća XML ili JSON odgovor koji sadrži poruku pogreške.
<error></error> XML oznake se vraćaju bez ikakvih drugih polja u XML odgovoru.
Ispod možete pronaći opis svih mogućih poruka pogreške koje mogu biti vraćene:

<error>Čeksum broja naloga je nevažeći.</error>
<error>Broj naloga (čeksum) nije tačan.</error>
<error>Broj naloga mora biti dug 11 znakova</error>
<error>Broj naloga mora biti dug 14 znakova</error>
<error>Broj naloga mora biti dug 24 znaka</error>
<error>Broj naloga je nevažeći</error>
<error>Broj naloga SORT koda je nevažeći</error>
<error>Prefiks broja naloga je predugačak.</error>
<error>Broj naloga je predugačak.</error>
<error>Bankovni/filijalni kod / KIB (čeksum) nije tačan.</error>
<error>Bankovni kod/ filijalni kod/ Broj naloga je predugačak.</error>
<error>Bankovni kod/ filijalni kod (čeksum) nije tačan.</error>
<error>Bankovni kod je nevažeći</error>
<error>Bankovni kod je predugačak.</error>
<error>Banka nije pronađena</error>
<error>Banka nije prepoznata</error>
<error>BBAN / NIB (čeksum) nije tačan.</error>
<error>BLZ/Bankovni kod nije važeći</error>
<error>Filijala/agencija nije pronađena</error>
<error>Filijalni kod je predugačak.</error>
<error>Filijala nije pronađena</error>
<error>Kontrolni broj je predugačak.</error>
<error>Clearingnummer/Broj naloga nije važeći. Kontrolni broj je netačan.</error>
<error>Clearingnummer / Bankovni kod ne može biti identifikovan. IBAN se ne može izračunati.</error>
<error>Clearingnummer ili broj naloga su predugački.</error>
<error>Codice ABI della Banca/Bankovnikod nije važeći</error>
<error>Codice CAB della Filiale/Filijalni kod nije važeći</error>
<error>Kod države nije važeći</error>
<error>Država ili banka nisu podržani</error>
<error>IBAN kod nije važeći</error>
<error>Kontonummer/Broj naloga nije važeći</error>
<error>Nedostaju polja</error>
<error>Nije FR IBAN</error>
<error>Nije FR IBAN država</error>
<error>Potrebna polja nedostaju. Molimo unesite bankovni kod ili broj naloga</error>
<error>Potrebna polja nisu podnesena.</error>
<error>RIB je nevažeći</error>
<error>Sort kod / Bankovni kod ne mogu biti identifikovani. IBAN se ne može izračunati.</error>
<error>Sort kod ne može biti pronađen</error>