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:




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 Prüfziffer-Spalte gibt an, ob das Land die Validierung mithilfe der Prüfziffer von Kontonummer und/oder Bankcode unterstützt.

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)
Das erste Argument ist der API-Schlüssel. Dies ist eine eindeutige Zeichenkette, die unserem System dabei hilft, Sie als ein Benutzer zu identifizieren, und Ihnen den Zugriff auf die API erlaubt.

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.
email 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
Das API-System liefert Antworten im XML- oder JSON-Format zurück, das in vielen Programmiersprachen und auf vielen Plattformen einfach zu parsen ist.

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>