Dokumentation der IBAN-Berechnungs-API
Anleitung zur API-Integration
1. Was ist die IBAN-Berechnungs-API?
Die IBAN-Berechnungs-Engine (auch IBAN-Umrechnungs-Engine) ist ein Softwaresystem, das es unseren Kunden erlaubt, Kombinationen aus inländischen Bankcodes und Kontonummern in gültige internationale Bankkontonummern (IBAN) umzuwandeln.
Das System bietet unseren Kunden sowohl eine manuelle Schnittstelle als auch eine API, die die Integration in die internen Systeme ihrer Unternehmen erlaubt.
Das System identifiziert außerdem die Banken und Fianzinstitute und liefert unseren Kunden die Details.
2. Funktionen
Im Folgenden finden Sie einige der Schlüsselfunktionen unserer IBAN-Berechnungs-Engine:
- Validierung der Prüfsummen lokaler Bankcodes/Kontonummern (* siehe unterstützte Länder)
- Informationen zur Bank auf Basis des lokalen Bank-/Filialcodes.
- Automatisches Erzeugen eines gültigen IBAN-Formats für den bereitgestellten Bank-/Filialcode und die Kontonummer.
- Das System unterstützt mehrere Antwortformate (JSON / XML)
3. Unterstützte Länder
Die IBAN-Berechnungs-API unterstützt derzeit die folgenden Länder sowie die von unserer API zur Berechnung einer IBAN erforderlichen Felder.
| Ländercode | Ländername | Bankcode | Filiale | Konto | Prüfziffer |
|---|---|---|---|---|---|
| AT | Österreich | JA | JA | ||
| BE | Belgien | JA | JA | JA | |
| CH | Schweiz | JA | JA | ||
| DE | Deutschland | JA | JA | ||
| EE | Estland | JA | |||
| ES | Spanien | JA | JA | JA | JA |
| FI | Finnland | JA | JA | ||
| FR | Frankreich | JA | JA | JA | JA |
| GB | Großbritannien | JA | JA | JA | |
| HU | Ungarn | JA | JA | ||
| IE | Irland | JA | JA | JA | |
| IT | Italien | JA | JA | JA | JA |
| MC | Monaco | JA | JA | JA | JA |
| MR | Mauretanien | JA | JA | JA | |
| MT | Malta | JA | JA | ||
| NO | Norwegen | JA | JA | ||
| PT | Portugal | JA | JA | JA | JA |
| SM | San Marino | JA | JA | JA | |
| CZ | Tschechische Republik | JA | JA | JA | |
| AL | Albanien | JA | JA | ||
| SK | Slowakische Republik | JA | JA | JA | |
| SI | Slowenien | JA | JA | JA | |
| PL | Polen | JA | JA | JA | |
| SE | Schweden | JA | JA | JA | |
| NL | Netherlandds | YES | YES |
Die Validierung mithilfe von Prüfziffern ist eine zusätzliche Sicherheitsschicht, um die Datenintegrität bei Tippfehlern zu schützen.
4. API-Eingaben
Die API akzeptiert sowohl HTTP GET als auch POST-Anfragen für Eingabedaten.
Die akzeptierten Parameter sind in der folgenden Tabelle aufgelistet:
| Feldname | Typ | Beschreibung |
|---|---|---|
| api_key | Zeichenkette | Ihr persönlicher API-Schlüssel Im Kundenbereich verfügbar. |
| format | Zeichenkette | API-Antwortformat (xml oder json) |
| country | Zeichenkette | Ländercode mit 2 Buchstaben (UK/US/DE/FR) |
| bankcode | Zeichenkette | Eine eindeutige Bankkennung. Für jedes Land unterschiedlich. (optional). Einige Länder erfordern lediglich eine Kontonummer. |
| branch | Zeichenkette | Eine eindeutige lokale Filialkennung (optional) |
| account | Zeichenkette | Persönliche Kontonummer |
| cd | Ganzzahl | In einigen Ländern verwendete Prüfziffern. |
| prefix | Ganzzahl | Derzeit nur für die Tschechische Republik erforderlich (optional) |
Die API unterstützt mehrere Antwortformate, um eine einfachere Integration zu ermöglichen. Derzeit werden XML und JSON unterstützt.
Die Länderargumente müssen aus einem ISO-Ländercode mit zwei Buchstaben bestehen, wie UK für das Vereinigte Königreich, DE für Deutschland, FR für Frankreich …
Der Bankcode hat eine für jedes Land unterschiedliche Länge und Struktur.
Der Filialcode ist ein optionales Argument und nur für bestimmte Länder erforderlich (siehe Beispiele)
Die Kontonummer ist für alle Länder erforderlich und in einigen Fällen der einzige für die Berechnung einer IBAN erforderliche Parameter.
Prüfziffern sind nur für bestimmte Länder erforderlich, die entsprechende Validierungsalgorithmen in der Struktur ihrer inländischen Bankkontonummern integriert haben. (siehe Beispiele)
Das Feld Prefix ist optional nur für die IBAN-Berechnung für die Tschechische Republik erforderlich.
5. API-Beispiele
In der folgenden Tabelle finden Sie ein Beispiel einer funktionierenden GET-Abfrage für unsere API für jedes Land.
| Land | Beispiel-Abfrage (GET-ANFRAGE) |
|---|---|
| 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 |
| 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. Struktur der XML-Antwort der API
Eine detaillierte Beschreibung der möglichen zurückgelieferten Felder lässt sich der folgenden Tabelle entnehmen:
| Feldname | Typ | Beschreibung |
|---|---|---|
| address | Zeichenkette | Adresse der Bankfiliale oder des Hauptsitzes |
| bank | Zeichenkette | Name der Bank oder des Finanzinstituts |
| bic | Zeichenkette | BIC (Bankkennungscode) der Bank |
| branch | Zeichenkette | Name der Filiale, die vom Bankcode identifiziert wird. |
| city | Zeichenkette | Name der Stadt, in welcher die Filiale ansässig ist. |
| country | Zeichenkette | Abkürzung des Ländercodes aus zwei Buchstaben, d.h. US, UK, AU, FR … etc. |
| Zeichenkette | Vereinbarte Kontakt-E-Mail-Adresse für die Bank oder Filiale | |
| fax | Zeichenkette | Faxnummer der Bank/Filiale |
| phone | Zeichenkette | Kontakt-Telefonnummer der Bank/Filiale |
| state | Zeichenkette | Bundesland der Bank-/Filialadresse |
| website | Zeichenkette | Website-Adresse der Bank/Filiale |
| zip | Zeichenkette | ZIP-Code oder Postleitzahl der Bankfilialadresse |
Eine beispielhafte XML-Antwort der API für einen SORT-Code aus dem Vereinigten Königreich und die dazugehörige Kontonummer wäre:
Abfrage-Adresse:
?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>
Die Antwort für die gleiche Abfrage, wenn der Benutzer das JSON-Format angegeben hat, wäre:
"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-Fehler
Im Falle eines Fehlers gibt die IBAN-Berechnungs-API eine XML- oder JSON-Antwort mit der Fehlermeldung zurück.
Die <error></error>-XML-Tags werden ohne weitere Felder in der XML-Antwort zurückgegeben.
Im Folgenden finden Sie eine Beschreibung aller möglichen Fehlermeldungen, die zurückgegeben werden können:
<error>Prüfsumme der Kontonummer ist ungültig.</error>
<error>Kontonummer (Prüfsumme) ist nicht korrekt.</error>
<error>Kontonummer muss 11 Zeichen lang sein</error>
<error>Kontonummer muss 14 Zeichen lang sein</error>
<error>Kontonummer muss 24 Zeichen lang sein</error>
<error>Kontonummer ist ungültig</error>
<error>Kontonummer des Sort-Codes ist ungültig</error>
<error>Präfix der Kontonummer ist zu lang.</error>
<error>Kontonummer ist zu lang.</error>
<error>Bank-/Filialcode/KIB (Prüfsumme) ist nicht korrekt.</error>
<error>Bankcode/Filialcode/Kontonummer ist zu lang.</error>
<error>Bankcode/Filialcode (Prüfsumme) ist nicht korrekt.</error>
<error>Bankcode ist ungültig</error>
<error>Bankcode ist zu lang.</error>
<error>Bank nicht gefunden</error>
<error>Bank nicht erkannt</error>
<error>BBAN / NIB (Prüfsumme) ist nicht korrekt.</error>
<error>BLZ/Bankcode ist ungültig</error>
<error>Filiale/Geschäftsstelle nicht gefunden</error>
<error>Filialcode ist zu lang.</error>
<error>Filiale nicht gefunden</error>
<error>Prüfziffer ist zu lang.</error>
<error>Clearingnummer/Kontonummer ist ungültig. Prüfziffer ist nicht korrekt.</error>
<error>Clearingnummer / Bankcode konnte nicht identifiziert werden. IBAN kann nicht berechnet werden.</error>
<error>Clearingnummer oder Kontonummer ist zu lang.</error>
<error>Codice ABI della Banca/Bankcode ungültig</error>
<error>Codice CAB della Filiale/Filialcode ungültig</error>
<error>Ländercode ist ungültig</error>
<error>Land oder Bank werden nicht unterstützt</error>
<error>IBAN ist ungültig</error>
<error>Kontonummer ist ungültig</error>
<error>Fehlende Felder</error>
<error>Nicht-FR-IBAN</error>
<error>Nicht-FR-IBAN-Land</error>
<error>Erforderliches Feld fehlt. Bitte geben Sie den Bankcode oder die Kontonummer ein</error>
<error>Erforderliche Felder wurde nicht übergeben.</error>
<error>RIB ist ungültig</error>
<error>Sort-Code / Bankcode konnte nicht identifiziert werden. IBAN kann nicht berechnet werden.</error>
<error>Sort-Code konnte nicht gefunden werden</error>