Ein Lieferantenformular, eine per OCR erfasste Rechnung und eine Datenmigration können eine IBAN enthalten. Unterscheiden Sie zuerst zwischen einem Strukturfehler, einer verfügbaren Bankreferenz und einer Information, die unbekannt bleibt. Diese Ergebnisse erfordern unterschiedliche Schritte.
IBANforge prüft die IBAN-Struktur und sucht verfügbare Bankreferenzen. Die API bestätigt weder die Existenz des Kontos noch dessen Inhaber und gibt keine Zahlung frei. Die folgenden Werte dienen der Entwicklung und sind keine Zahlungsanweisungen.
1. Einen ersten Aufruf ohne Schlüssel ausführen
Der Test ohne Schlüssel ist für POST /v1/iban/validate verfügbar. Kontingent und Erneuerung stehen in der Validierungsreferenz. Der Block trial in der Antwort nennt den verbleibenden Umfang und den nächsten Rücksetzzeitpunkt. Dieser Test öffnet nicht alle Endpunkte ohne Schlüssel.
curl --fail-with-body --max-time 15 \
https://api.ibanforge.com/v1/iban/validate \
-H 'Content-Type: application/json' \
-d '{"iban":"CH1000230000000012345"}'HTTP 200 bedeutet, dass die Anfrage verarbeitet wurde. Lesen Sie zusätzlich valid und die weiteren Prüfungen: Auch eine ungültige IBAN kann HTTP 200 ergeben. Wenn das Testkontingent ausgeschöpft ist, wiederholen Sie den Aufruf nicht in einer Schleife. Lesen Sie den Fehler und folgen Sie dem Einstieg mit einem dauerhaft verwendeten Schlüssel. Das Beispiel erzeugt keine Zahlungssignatur.
2. Das Ergebnis innerhalb seiner Aussagegrenzen lesen
| Feld | Bedeutung für die Auswertung |
|---|---|
valid | Ergebnis der Strukturprüfung; fasst nicht alle zusätzlichen Bank- oder nationalen Prüfungen zusammen. |
checks | Einzelprüfungen mit Fehlern und unbekannten Ergebnissen. Die nationale Prüfung lesen, wenn sie verfügbar ist. |
bank_code_holder | Identifizierung des Inhabers des Bankcodes, nicht des Kontoinhabers. |
bank_code_check | Abgefragte Referenz, Ergebnis, Aussageumfang und Datum as_of. Eine fehlende oder unvollständige Quelle belegt keine Nichtexistenz. |
bic | Gefundener BIC, soweit vorhanden. basis, authoritative, source und as_of lesen; der Block kann fehlen oder null sein. |
sepa und VoP | Je nach Feld Angaben zu Land, Bank oder Register; kein Ergebnis einer Empfängernamensprüfung. |
Ein fehlender BIC macht eine IBAN allein nicht ungültig. Eine bestätigte Bankreferenz bestätigt nicht das Konto. Die Abdeckung nach Quelle und der Leitfaden zum VoP-Register erläutern diese Grenzen. Befunde und Herkunft aufbewahren, bevor die Anwendung daraus eine Anzeige für den Benutzer ableitet.
3. Denselben Schlüssel auf dem Server weiterverwenden
Für wiederholte Aufrufe einmal einen Schlüssel nach der Schlüsseldokumentation erstellen und in IBANFORGE_API_KEY speichern. Nicht bei jedem Lauf einen neuen Schlüssel erstellen. Kontingente und kostenpflichtige Optionen stehen auf der Preisseite; die Beispiele kaufen weder Guthaben noch ein Abonnement.
Python mit der Standardbibliothek
Dieser Code läuft auf dem Server. Er begrenzt die Wartezeit, prüft den HTTP-Status vor dem Lesen des JSON und folgt keinen Weiterleitungen. Die ausgegebene Zusammenfassung enthält nicht die eingegebene IBAN. Die vollständige Antwort nur in einem für die Anwendung geeigneten Speicher aufbewahren.
import http.client
import json
import os
key = os.environ.get("IBANFORGE_API_KEY", "").strip()
if not key:
raise SystemExit("IBANFORGE_API_KEY is required")
connection = http.client.HTTPSConnection("api.ibanforge.com", timeout=10)
try:
connection.request(
"POST", "/v1/iban/validate",
body=json.dumps({"iban": "CH1000230000000012345"}),
headers={"Content-Type": "application/json", "Authorization": f"Bearer {key}"},
)
response = connection.getresponse()
if response.status != 200:
raise SystemExit(f"API HTTP {response.status}")
result = json.load(response)
finally:
connection.close()
if not isinstance(result, dict) or type(result.get("valid")) is not bool:
raise SystemExit("Unexpected API response")
print(json.dumps({
"valid": result["valid"],
"bank_code_holder": result.get("bank_code_holder"),
"bic": (result.get("bic") or {}).get("code"),
}))TypeScript oder JavaScript auf dem Server
Beispiel für Node.js 22 oder neuer. Einen geheimen Schlüssel nicht in JavaScript einbauen, das an den Browser ausgeliefert wird. Bei einem Webformular den Aufruf auf dem Server ausführen; Fehler und Authentifizierung stehen in der API-Referenz.
Den Block als erster-aufruf.mjs speichern und mit node erster-aufruf.mjs starten: await auf oberster Ebene benötigt ein ES-Modul.
const key = process.env.IBANFORGE_API_KEY?.trim();
if (!key) throw new Error('IBANFORGE_API_KEY is required');
const response = await fetch('https://api.ibanforge.com/v1/iban/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
body: JSON.stringify({ iban: 'CH1000230000000012345' }),
signal: AbortSignal.timeout(10_000),
redirect: 'error',
});
if (response.status !== 200) throw new Error(`API HTTP ${response.status}`);
const result = await response.json();
if (typeof result?.valid !== 'boolean') throw new Error('Unexpected API response');
console.log({
valid: result.valid,
bank_code_holder: result.bank_code_holder ?? null,
bic: result.bic?.code ?? null,
});Diese Beispiele stoppen bei HTTP-Fehlern und wiederholen Aufrufe nicht automatisch. Ein Netzwerkfehler oder Zeitlimit ist von einem Ergebnis «IBAN ungültig» zu unterscheiden.
4. Einen bereits angegebenen BIC nachschlagen
Wenn ein Dokument bereits einen BIC enthält, liefert die BIC-Suche dessen Bankreferenz. Mit derselben gesetzten Schlüsselvariable:
curl --fail-with-body --max-time 15 \
https://api.ibanforge.com/v1/bic/UBSWCHZH80A \
-H "Authorization: Bearer ${IBANFORGE_API_KEY}"Diese Abfrage belegt nicht, dass der BIC zur eingegebenen IBAN gehört. Bei Abweichungen zwischen vorhandenen Angaben und Referenz beide erhalten und eine Prüfung vorsehen; den Lieferantenstamm nicht still überschreiben.
5. Einen kleinen Stapel und anschliessend den Prüfablauf erproben
Die Stapelprüfung benötigt ihren eigenen Zugang. Das Kontingent für Einzelprüfungen ohne Schlüssel gilt hier nicht. Der folgende erste Stapel enthält zwei Demonstrationswerte, davon einen mit falscher Prüfsumme.
curl --fail-with-body --max-time 15 \
https://api.ibanforge.com/v1/iban/batch \
-H "Authorization: Bearer ${IBANFORGE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"ibans":["CH1000230000000012345","CH0000230000000012345"]}'Vor der Zuordnung zu Dateizeilen die Anzahl der Ergebnisse und die Übereinstimmung jeder IBAN prüfen. Eine unvollständige, vertauschte oder unbekannte Antwort muss die automatische Zuordnung stoppen; die Quelldatei erhalten. HTTP 200 allein bestätigt nicht den ganzen Stapel.
Der Leitfaden zur Prüfung vor einer Migration enthält ein Python-Beispiel, das Original, Befunde und Vorschläge trennt. Die Integrationsrezepte bieten auch eine n8n-Vorlage. Zuerst einen konkreten Anwendungsfall mit Demonstrationsdaten erproben und vor dem echten Einsatz prüfen, wie die Anwendung mit unbekannten Ergebnissen umgeht.