FI
Tämä API on osa IBAN Suite -palveluamme
API:n integrointiopas
1. Mikä on IBAN-laskenta-API?
IBAN-laskentajärjestelmä (ts. IBAN-muunnosjärjestelmä) on ohjelmisto, jonka avulla asiakkaamme voivat muuntaa kotimaan pankkikoodit ja tilinumerot vahvistetuiksi kansainvälisiksi tilinumeroiksi (IBAN).Järjestelmän ansiosta asiakkaamme voivat käyttää manuaalista käyttöliittymää tai integroida API:n oman yrityksensä sisäisiin järjestelmiin.
Järjestelmä tunnistaa myös pankit ja rahoituslaitokset sekä tarjoaa tietoa asiakkaillemme.
2. Ominaisuudet
Alla on lueteltu IBAN-laskentajärjestelmämme tärkeimpiä ominaisuuksia:- Vahvista paikallinen pankkikoodi / tilinumeron tarkistenumero (* katso lisätietoa tuetuista)
- Hanki pankkitietoja paikallisen pankin/haarakonttorin koodin perusteella.
- Luo automaattisesti voimassaolevan IBAN-numeron toimitettujen pankin/haarakonttorin koodin ja tilinumeron perusteella
- Järjestelmä tukee monivastemuotoa (JSON/XML)
3. Tuetut maat
IBAN-laskenta-API tukee tällä hetkellä seuraavia maita ja kenttiä, jotka ovat pakollisia IBAN-numeron muodostamiseksi.| Maakoodi | Maan nimi | Pankkikoodi | Haarakonttori | Tili | Tarkistenumero ** |
|---|---|---|---|---|---|
| AT | Itävalta | KYLLÄ | KYLLÄ | ||
| BE | Belgia | KYLLÄ | KYLLÄ | KYLLÄ | |
| CH | Sveitsi | KYLLÄ | KYLLÄ | ||
| DE | Saksa | KYLLÄ | KYLLÄ | ||
| EE | Viro | KYLLÄ | |||
| ES | Espanja | KYLLÄ | KYLLÄ | KYLLÄ | KYLLÄ |
| FI | Suomi | KYLLÄ | KYLLÄ | ||
| FR | Ranska | KYLLÄ | KYLLÄ | KYLLÄ | KYLLÄ |
| GB | Iso-Britannia | KYLLÄ | KYLLÄ | KYLLÄ | |
| HU | Unkari | KYLLÄ | KYLLÄ | ||
| IE | Irlanti | KYLLÄ | KYLLÄ | KYLLÄ | |
| IT | Italia | KYLLÄ | KYLLÄ | KYLLÄ | KYLLÄ |
| MC | Monaco | KYLLÄ | KYLLÄ | KYLLÄ | KYLLÄ |
| MR | Mauritania | KYLLÄ | KYLLÄ | KYLLÄ | |
| MT | Malta | KYLLÄ | KYLLÄ | ||
| NO | Norja | KYLLÄ | KYLLÄ | ||
| PT | Portugali | KYLLÄ | KYLLÄ | KYLLÄ | KYLLÄ |
| SM | San Marino | KYLLÄ | KYLLÄ | KYLLÄ | |
| CZ | Tšekki | KYLLÄ | KYLLÄ | KYLLÄ | |
| AL | Albania | KYLLÄ | KYLLÄ | ||
| SK | Slovakia | KYLLÄ | KYLLÄ | KYLLÄ | |
| SI | Slovenia | KYLLÄ | KYLLÄ | KYLLÄ | |
| PL | Puola | KYLLÄ | KYLLÄ | KYLLÄ | |
| PK | Pakistan | KYLLÄ | KYLLÄ | ||
| SE | Ruotsi | KYLLÄ | KYLLÄ | KYLLÄ | |
| NL | Alankomaat | KYLLÄ | KYLLÄ |
Tarkistenumeron vahvistus on ylimääräinen tietosuojatarkistus kirjoitusvirheitä vastaan.
4. API-syötteet
API hyväksyy syötetyille tiedoille sekä HTTP GET - että POST-pyyntöjä.Hyväksytyt parametrit on listattu alla olevassa taulukossa:
| Kentän nimi | Tyyppi | Kuvaus |
|---|---|---|
| api_avain | Merkkijono | Oma API-avaimesi. Hankittu asiakasalueelta. |
| muoto | Merkkijono | API-vastausmuoto (xml tai json) |
| maa | Merkkijono | Kaksikirjaiminen maakoodi (UK/US/DE/FR) |
| pankkikoodi | Merkkijono | Ainutlaatuinen pankin tunniste. Eri jokaisessa maassa (valinnainen). Jotkin maat edellyttävät vain tilinumeron. |
| haarakonttori | Merkkijono | Ainutlaatuinen paikallisen haarakonttorin tunniste (valinnainen) |
| tili | Merkkijono | Oma tilinumero |
| cd | Kokonaisluku | Joissain maissa käytettävät tarkistenumerot. |
| etuliite | Kokonaisluku | Tällä hetkellä pakollinen vain Tšekissä (valinnainen) |
API tukee useita vastausmuotoja tarjotakseen helpomman integroinnin. Tällä hetkellä tuetut muodot: XML ja JSON.
Maakoodin tulee olla kaksimerkkinen ISO-maakoodi, kuten UK Yhdistyneelle kuningaskunnalle, DE Saksalle, FR Ranskalle…
Pankkikoodi on pituudeltaan ja rakenteeltaan erilainen kussakin maassa.
Haarakonttorin koodi on valinnainen, sillä tämä on pakollinen vain joissain maissa (katso lisätietoja esimerkeistä)
Tilinumero on pakollinen kaikille maille ja joissain tapauksissa se on IBAN-numeron muodostamisessa ainoa käytetty parametri.
Tarkistenumero on pakollinen vain tietyissä maissa, jotka ovat ottaneet kyseiset vahvistusalgoritmit käyttöön tilinumeroiden rakenteissa (katso lisätietoja esimerkeistä).
Etuliite on valinnainen kenttä, joka on pakollinen ainoastaan Tšekin IBAN-numeron muodostamisessa.
5. API-esimerkit
Alla olevasta taulukosta löytyy esimerkkejä GET-kyselyn tekemisestä kullekin maalle.| Maa | Esimerkkikysely (GET-PYYNTÖ) |
|---|---|
| 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. API XML -vastauksen rakenne
Alla olevassa taulukossa on yksityiskohtainen kuvaus mahdollisista palautettavista kentistä:| Kentän nimi | Tyyppi | Kuvaus |
|---|---|---|
| osoite | Merkkijono | Pankin haarakonttorin tai pääkonttorin osoite |
| pankki | Merkkijono | Pankin tai rahoituslaitoksen nimi |
| bic | Merkkijono | Pankin BIC-koodi (pankin tunnistekoodi) |
| haarakonttori | Merkkijono | Pankkikoodin perusteella tunnistetun haarakonttorin nimi |
| kaupunki | Merkkijono | Kaupunki, jossa haarakonttori sijaitsee. |
| maa | Merkkijono | Maakoodin kaksikirjaiminen lyhenne, esim. US, UK, AU, FR … jne. |
| sähköposti | Merkkijono | Pankin tai haarakonttorin yhteydenottosähköposti |
| faksi | Merkkijono | Pankin/haarakonttorin faksinumero |
| puhelin | Merkkijono | Pankin/haarakonttorin yhteydenottopuhelin |
| maakunta | Pankin/haarakonttorin maakunta | |
| verkkosivusto | Merkkijono | Pankin/haarakonttorin verkkosivuston osoite |
| postinumero | Merkkijono | Pankin postinumero |
API-järjestelmän XML-mallivastaus Yhdistyneen kuningaskunnan lajittelukoodille ja tilinumerolle olisi:
Kyselyn URL:
?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>
Saman kyselyn JSON-vastaus olisi:
"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-virheet
Virhetilanteessa IBAN-laskenta-API palauttaa XML- tai JSON-vastauksen, joka sisältää virheviestin.<error></error> XML-tunnisteet palautetaan ilman muita kenttiä.
Alta voit löytää kuvauksen kaikista mahdollisista virheviesteistä:
<error>Tilinumeron tarkistenumero on virheellinen.</error>
<error>Tilinumero (tarkistenumero) on virheellinen.</error>
<error>Tilinumeron on oltava 11 merkkiä pitkä</error>
<error>Tilinumeron on oltava 14 merkkiä pitkä</error>
<error>Tilinumeron on oltava 24 merkkiä pitkä</error>
<error>Tilinumero on virheellinen</error>
<error>Tilinumeron lajittelukoodi on virheellinen</error>
<error>Tilinumeron etuliite on liian pitkä.</error>
<error>Tilinumero on liian pitkä.</error>
<error>Pankin/haarakonttorin koodi/tarkistenumero on virheellinen.</error>
<error>Pankin/haarakonttorin koodi tai tilinumero on liian pitkä.</error>
<error>Pankin/haarakonttorin koodi (tarkistenumero) on virheellinen.</error>
<error>Pankkikoodi on virheellinen</error>
<error>Pankkikoodi on liian pitkä.</error>
<error>Pankkia ei löytynyt</error>
<error>Pankkia ei tunnistettu</error>
<error>BBAN/NIB (tarkistenumero) on virheellinen.</error>
<error>BLZ/pankkikoodi on virheellinen</error>
<error>Haarakonttoria ei löytynyt</error>
<error>Haarakonttorin koodi on liian pitkä.</error>
<error>Haarakonttoria ei löytynyt</error>
<error>Tarkistenumero on liian pitkä.</error>
<error>Selvitysnumero/tilinumero on virheellinen. Tarkistenumero on virheellinen.</error>
<error>Selvitysnumeroa/pankkikoodia ei voitu tunnistaa. IBAN-numeroa ei voida muodostaa.</error>
<error>Selvitysnumero tai tilinumero on liian pitkä.</error>
<error>Codice ABI della Banca / pankkikoodi on virheellinen</error>
<error>Codice CAB della Filiale / haarakonttorin koodi on virheellinen</error>
<error>Maakoodi on virheellinen</error>
<error>Maata tai pankkia ei tueta</error>
<error>IBAN on virheellinen</error>
<error>Kontonummer / tilinumero on virheellinen</error>
<error>Puuttuvia kenttiä</error>
<error>Ei FR IBAN</error>
<error>Ei FR IBAN maa</error>
<error>Pakollinen kenttä puuttuu. Syötä pankkikoodi ja tilinumero</error>
<error>Pakollisia kenttiä ei ole täytetty.</error>
<error>RIB on virheellinen</error>
<error>Lajittelukoodia/pankkikoodia ei voitu tunnistaa. IBAN-numeroa ei voida muodostaa.</error>
<error>Lajittelukoodia ei löytynyt</error>