CZ
oto rozhraní API je součástí naší IBAN Suite služby
Průvodce implementace API
1. Co je rozhraní API pro výpočet IBAN?
Modul IBAN výpočet (IBAN konverze) je softwarový systém, který umožňuje našim klientům převést domácí bankovní kód a kombinace čísel účtů na platné mezinárodní čísla bankovních účtů (IBAN).Systém umožňuje našim klientům ruční rozhraní i rozhraní API umožňující integraci do vnitřních systémů společnosti.
Systém také identifikuje banky a finanční instituce a poskytuje informace našim zákazníkům.
2. Vlastnosti
Níže uvádíme některé z klíčových funkcí našeho výpočetního nástroje IBAN:- Ověření kontrolních kódů místní banky / čísla účtu (* viz podporované země)
- Získávání informací o bance podle kódu místní banky / pobočky.
- Automaticky vygeneruje platný formát IBAN pro zadaný kód banky / pobočky a číslo účtu
- Systém podporuje formátování více odezev (JSON / XML)
3. Podporované země
API pro výpočet čísla IBAN v současné době podporuje následující země a oblasti, které naše API vyžaduje pro výpočet IBAN.| Kód země | Název země | Kód banky | Pobočka | Účet | Kontrolní číslice ** |
|---|---|---|---|---|---|
| AT | Rakousko | ANO | ANO | ||
| BE | Belgie | ANO | ANO | ANO | |
| CH | Švýcarsko | ANO | ANO | ||
| DE | Německo | ANO | ANO | ||
| EE | Estonsko | ANO | |||
| ES | Španělsko | ANO | ANO | ANO | ANO |
| FI | Finsko | ANO | ANO | ||
| FR | Francie | ANO | ANO | ANO | ANO |
| GB | Velká Británie | ANO | ANO | ANO | |
| HU | Maďarsko | ANO | ANO | ||
| IE | Irsko | ANO | ANO | ANO | |
| IT | Itálie | ANO | ANO | ANO | ANO |
| MC | Monako | ANO | ANO | ANO | ANO |
| MR | Mauritánie | ANO | ANO | ANO | |
| MT | Malta | ANO | ANO | ||
| NO | Norsko | ANO | ANO | ||
| PT | Portugalsko | ANO | ANO | ANO | ANO |
| SM | San Marino | ANO | ANO | ANO | |
| CZ | Česká republika | ANO | ANO | ANO | |
| AL | Albánie | ANO | ANO | ||
| SK | Slovenská republika | ANO | ANO | ANO | |
| SI | Slovinsko | ANO | ANO | ANO | |
| PL | Polsko | ANO | ANO | ANO | |
| PK | Pákistán | ANO | ANO | ||
| SE | Švédsko | ANO | ANO | ANO | |
| NL | Nizozemsko | ANO | ANO |
Ověřování kontrolních číslic je dodatečnou vrstvou ochrany integrity dat proti chybám při psaní.
4. Vstupy API
API přijímá jak HTTP GET, tak POST požadavek na vstupní data.Přijaté parametry jsou uvedeny v následující tabulce:
| Název pole | Typ | Popis |
|---|---|---|
| api_klíč | Řetězec | Váš osobní API klíč. Získané v klientské oblasti. |
| formát | Řetězec | Formát odezvy API (xml nebo json) |
| země | Řetězec | Kód země se 2 písmeny (UK / US / DE / FR) |
| bankovníkód | Řetězec | Jedinečný identifikátor banky. Různé pro každou zemi (nepovinné). Některé země vyžadují pouze číslo účtu. |
| pobočka | Řetězec | Jedinečný identifikátor místní pobočky (nepovinné) |
| účet | Řetězec | Osobní číslo účtu |
| cd | Celé číslo | Kontrolní číslice používané v některých zemích. |
| prefix | Celé číslo | Požadováno pouze pro Českou republiku (nepovinné) |
Rozhraní API podporuje více formátů odezvy, aby byla usnadněna integrace. V současné době jsou podporovány XML a JSON.
Argumenty země se musí skládat z dvoumístného kódu země ISO, jako je například UK pro Spojené království, DE pro Německo, FR pro Francii …
Kód banky má pro každou zemi jinou délku a strukturu.
Kód pobočky je nepovinný argument, je vyžadován pouze u některých zemí (viz Příklady)
Číslo účtu je vyžadováno pro všechny země a v některých případech je to jediný parametr používaný pro výpočet IBAN.
Kontrolní číslice je vyžadována pouze pro některé země, které zahrnuly takové validační algoritmy do své struktury bankovních účtů. (viz Příklady)
Prefix je pole, které je povinné pouze pro výpočet IBAN v České republice.
5. API příklady
V níže uvedené tabulce naleznete příklad fungujícího dotazu GET pro naše API pro každou zemi.| Země | Příklad dotazu (GET REQUEST) |
|---|---|
| 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 odpovědi API XML
Podrobný popis možných vrácených polí je uveden v tabulce níže:| Název pole | Typ | Popis |
|---|---|---|
| adresa | Řetězec | Adresa pobočky nebo sídla banky |
| banka | Řetězec | Název banky nebo finanční instituce |
| bic | Řetězec | BIC (bankovní identifikační kód) banky |
| pobočka | Řetězec | Název pobočky identifikované kódem banky |
| město | Řetězec | Název města, ve kterém se pobočka nachází |
| země | Řetězec | Zkratka kódu země skládaná ze 2 písmen, např. US, UK, AU, FR… atd. |
| Řetězec | Jmenovaná kontaktní e-mailová adresa pro banku nebo pobočku | |
| fax | Řetězec | Faxové číslo banky / pobočky |
| telefon | Řetězec | Kontaktní telefonní číslo banky / pobočky |
| stát | Řetězec | Stát, ve kterém se banka / pobočka nachází |
| webovástránka | Řetězec | Adresa webové stránky banky / pobočky |
| psč | Řetězec | PSČ adresy pobočk banky |
Vzorová odpověď XML z rozhraní API pro kód SORT Spojeného království a hledání čísla účtu by byla:
URL dotazu:
?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>
Odpověď pro stejný dotaz, pokud uživatel zadal formátování JSON, bude:
"iban":"GB20ULSB98006054100029","účet":"54100029","sort_code":"980060","banka":"ULSTER BANK LTD","pobočka":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","adresa":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","město":"BT1 5UB","země":"GB","telefon":"028 90244112"
7. API chyby
V případě chyby API pro výpočet IBAN vrátí odpověď XML nebo JSON obsahující chybové hlášení.The<error></error>Š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é lze vrátit:
<error>Kontrolní součet čísla účtu je neplatný.</error>
<error>Číslo účtu (kontrolní součet) není správné.</error>
<error>Číslo účtu musí být 11 znaků dlouhé.</error>
<error>Číslo účtu musí být 14 znaků dlouhé.</error>
<error>Číslo účtu musí být 24 znaků dlouhé.</error>
<error>Číslo účtu je neplatné.</error>
<error>Sort Code čísla účtu je neplatný.</error>
<error>Prefix čísla účtu je příliš dlouhý.</error>
<error>Číslo účtu je příliš dlouhé.</error>
<error>Kód banky / pobočky / KIB (kontrolní součet) není správný.</error>
<error>Kód banky / pobočky / číslo účtu je příliš dlouhé.</error>
<error>Kód banky / pobočky (kontrolní součet) není správný.</error>
<error>Kód banky není platný.</error>
<error>Kód banky je příliš dlouhý.</error>
<error>Banka nebyla nalezena.</error>
<error>Banka nebyla rozpoznána.</error>
<error>BBAN / NIB (kontrolní součet) není správný.</error>
<error>BLZ / bankovní kód je neplatný.</error>
<error>Pobočka / agentura nebyla nalezena.</error>
<error>Kód pobočky je příliš dlouhý.</error>
<error>Pobočka nebyla nalezena.</error>
<error>Kontrolní číslice je příliš dlouhá.</error>
<error>Zúčtovací číslo / číslo účtu není platné. Chybná kontrolní číslice.</error>
<error>Zúčtovací číslo / bankovní kód nebyl identifikován. IBAN nemůže být vypočítán.</error>
<error>Zúčtovací číslo nebo číslo účtu je příliš dlouhé.</error>
<error>Codice ABI della Banca / Bankovní kód není platný.</error>
<error>Codice CAB della Filiale/ Kód pobočky není platný.</error>
<error>Kód země není platný.</error>
<error>Země nebo banka není podporována.</error>
<error>IBAN není platný.</error>
<error>Kontonummer/Číslo účtu není platné.</error>
<error>Chybějící pole</error>
<error>Není FR IBAN</error>
<error>Není FR IBAN země</error>
<error>Chybí povinné pole. Zadejte prosím kód banky a číslo účtu.</error>
<error>Požadovaná pole nebyla odeslána.</error>
<error>RIB je neplatný.</error>
<error>SortCode / Kód banky nebyl identifikován. IBAN nemůže být vypočítán.</error>
<error>Sort code nebyl nalezen.</error>