Zum Inhalt springen
IBANforge

IBANs im Stapel prüfen

Prüfen Sie 1 bis 100 IBANs pro Anfrage. Jeder Eintrag hat ein eigenes Ergebnis: Eine ungültige IBAN entfernt weder die anderen Ergebnisse noch ihre eigene Zeile. Die Prüfung bestätigt weder die Existenz eines Kontos noch die Identität des Kontoinhabers.

POST https://api.ibanforge.com/v1/iban/batch

Zugang und Kosten

Ein API-Schlüssel oder eine x402-Zahlung ist erforderlich. Der schlüssellose Test der Einzelvalidierung gilt nicht für diese Route. Behalten Sie denselben Schlüssel für Nutzungsabfragen und Aufladungen; legen Sie ihn nicht in einer öffentlichen Seite oder einem Repository ab.

Mit einem Schlüssel verbraucht jeder übermittelte Eintrag eine Kontingenteinheit oder ein vorausbezahltes Guthaben, auch Duplikate und ungültige IBANs. cost_usdc ist dann 0; das bedeutet nicht, dass der Stapel keine Einheiten verbraucht. Reichen die verfügbaren Einheiten nicht aus, wird der gesamte Stapel mit 402 abgelehnt, ohne Teilergebnisse. Kontingent und Guthaben können einen Stapel gemeinsam finanzieren.

Mit x402 beträgt der Preis 0,002 USDC je IBAN. Ein x402-Client signiert die mit 402 erhaltenen Anforderungen; ein leerer Header ist keine Zahlung. Der x402-Leitfaden beschreibt v2 PAYMENT-SIGNATURE und die Kompatibilität mit v1 X-PAYMENT.

Anfrage mit Schlüssel

Die Beispiele verwenden einen bereits gespeicherten Schlüssel aus der serverseitigen Umgebungsvariable IBANFORGE_API_KEY. Schlüssel beziehen und behalten. Die IBANs sind Dokumentationsbeispiele, keine Zahlungsempfänger.

curl --fail-with-body --silent --show-error \
  https://api.ibanforge.com/v1/iban/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
  -d '{"ibans":["CH1000230000000012345","DE89370400440532013000","INVALID123"]}'

ibans ist ein Array mit 1 bis 100 Zeichenketten. Die Aliasse iban_list und list werden ebenfalls akzeptiert; verwenden Sie nur ein Feld. Der Validator normalisiert Leerzeichen, ASCII-Bindestriche und Kleinbuchstaben. Eine leere Zeichenkette bleibt ein ungültiger Eintrag; eine Zahl oder ein Objekt macht die gesamte Anfrage ungültig.

Python

import json
import os
import urllib.request
 
ibans = ["CH1000230000000012345", "DE89370400440532013000", "INVALID123"]
request = urllib.request.Request(
    "https://api.ibanforge.com/v1/iban/batch",
    data=json.dumps({"ibans": ibans}).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer " + os.environ["IBANFORGE_API_KEY"],
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response:
    data = json.load(response)
 
if len(data["results"]) != len(ibans):
    raise ValueError("results / ibans")
for index, result in enumerate(data["results"]):
    print(json.dumps({"index": index, "input": ibans[index], "result": result}))

Node.js / TypeScript

const key = process.env.IBANFORGE_API_KEY;
if (!key) throw new Error("IBANFORGE_API_KEY");
const ibans = ["CH1000230000000012345", "DE89370400440532013000", "INVALID123"];
const response = await fetch("https://api.ibanforge.com/v1/iban/batch", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
  body: JSON.stringify({ ibans }),
  signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
if (!Array.isArray(data.results) || data.results.length !== ibans.length) {
  throw new Error("results / ibans");
}
for (const [index, result] of data.results.entries()) {
  console.log(JSON.stringify({ index, input: ibans[index], result }));
}

Antwort auswerten

Ein 200 bedeutet, dass der Stapel verarbeitet wurde, nicht dass jede IBAN gültig ist. results[i] entspricht ibans[i], in derselben Reihenfolge und ohne Deduplizierung. Bewahren Sie Ihre ursprüngliche Zeilenkennung neben diesem Index auf.

FeldBedeutung
resultsEine Validierungsantwort pro Eintrag; zuerst valid, dann die Prüfungen und ihre Quellen lesen.
countAnzahl verarbeiteter Einträge einschließlich Duplikaten.
valid_countAnzahl mit valid: true; keine Zahl existierender Konten oder freigegebener Zahlungen.
cost_usdcUSDC-Betrag dieses Aufrufs; mit Schlüssel null.
processing_msVerarbeitungsdauer dieser Antwort, keine Zusage zur Antwortzeit.
attributionQuellennachweise, falls die Antwort sie enthält; zusammen mit den Ergebnissen erhalten.

Jeder Eintrag folgt der Referenz zur Einzelvalidierung. bank_code_holder, bank_code_check, bic, checks und ihre Quellen unterscheiden bestätigte Referenzen, Ableitungen und fehlende Daten. Einige Blöcke fehlen oder sind null, abhängig von IBAN und verfügbaren Quellen. Die Stapelprüfung liefert nicht den zusätzlichen Compliance-Block.

Fehler und Fortsetzung

Status / CodeBehandlung
400 invalid_jsonUngültiges JSON.
400 invalid_requestFehlendes Feld, erwartetes Array oder nicht textueller Eintrag.
400 empty_batchLeeres Array.
400 batch_too_largeMehr als 100 Einträge; Eingaben vor dem Aufruf aufteilen.
402Fehlender oder unbrauchbarer Schlüssel oder zu wenige Einheiten; Antwort und Header lesen.
429Ratenlimit; Retry-After abwarten.

Ein 200 kann valid: false mit error und error_detail enthalten. Bei einem Netzwerkfehler nach dem Absenden kann die Verarbeitung bereits erfolgt sein: Spielen Sie nicht automatisch den gesamten Stapel erneut ein, als hätte er nichts verbraucht. Erhalten Sie bearbeitete Zeilen und prüfen Sie den Schlüsselverbrauch. Auch bei ungewissem x402-Zahlungsausgang muss vor einer erneuten Zahlung geprüft werden.

Für Dateien: Dateiprüfung oder Lieferantenablauf. Für die Automatisierung: Rezepte. Zum Einstieg: Erste Schritte. Die Fehlerreferenz erklärt Kontingente und Ratenlimits.

Nutzen Sie die Prüfungen für Ihren Anwendungsfall

Wählen Sie den ersten Schritt für Ihre Software oder Ihre Lieferantendatei.

Eine Lieferantendatei prüfen

Laden Sie eine CSV- oder Excel-Datei hoch und sehen Sie die Ergebnisse kostenlos in der Vorschau. Bei Bedarf kaufen Sie die kommentierte Arbeitsmappe. Ohne Konto oder Abonnement.

Dateiprüfung kennenlernen

IBAN-Prüfungen in Ihre Software integrieren

Testen Sie eine Validierung, sehen Sie sich die Antwort an und verbinden Sie Ihre Anwendung über die API oder eine vorhandene Integration.

API-Ablauf ansehen

Die verfügbaren Bankinformationen hängen von Land und Quelle ab. Diese Prüfungen bestätigen weder den Kontoinhaber noch die erfolgreiche Ausführung einer Zahlung.