Prüfungen

Zustandslose USt-IdNr.- und IBAN-Prüfung.

Authentifizierung

Jeder Request braucht einen API-Key im Header. Keys entstehen unter Einstellungen → API (nur Business-Tarif). Details zu Scopes, Idempotenz und Rate-Limits auf der Übersichtsseite.

Authorization: Bearer mxr_live_…

Bleibt in diesem Browser-Tab (sessionStorage), nur für „Ausprobieren“ auf dieser Seite, und geht direkt aus deinem Browser an /api/v1 — kein Versand an unseren Server, kein Log.

USt-IdNr. prüfen (VIES oder qualifiziert per BZSt)

get/api/v1/check/vat

Zustandslos — speichert nichts. Scope checks:read.

Ohne weitere Parameter: EU-weite VIES-Abfrage — method: "vies", status valid / invalid / not_eu / unavailable (reason nennt den Grund).

Mit requester_vat_id = deutscher USt-IdNr. plus name und city: qualifizierte BZSt-Bestätigung (§ 18e UStG) — method: "bzst", status valid / invalid / not_eligible (Problem mit der Absender-USt-IdNr.) / unavailable; bei valid liefert matches die Abgleichcodes A/B/C/D für Firmenname / Straße / PLZ / Ort.

Um das Ergebnis an einer Rechnung / einem Kunden festzuhalten: POST /invoices/{id}/vat-check bzw. POST /customers/{id}/vat-check.

Scope

checks:read

Parameter

  • vat_id query · string*
  • requester_vat_id query · stringDeutsche USt-IdNr. des Anfragenden. Ist sie gesetzt und deutsch, fragt die API das BZSt statt VIES, auch ohne Firmendaten (dann einfache Bestätigung).
  • name query · stringFirmenname (BZSt qualifiziert).
  • street query · string
  • postcode query · string
  • city query · stringOrt (BZSt qualifiziert).
curl -X GET "https://maxrechnung.de/api/v1/check/vat" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Prüfergebnis
  • 400 vat_id fehlt
  • 401 Kein oder ungültiger API-Key
  • 403 Scope checks:read fehlt
  • 429 Rate Limit überschritten

Schema 200

  • object "vat_check"
  • method "vies" | "bzst"
  • input string
  • status "valid" | "invalid" | "not_eu" | "not_eligible" | "unavailable"
  • countryCode string
  • vatNumber string
  • name string
  • address string
  • checkedAt string · date-time
  • reason string
  • code stringBZSt-Statuscode (evatr-*).
  • message string
  • qualified booleanNur BZSt, valid: Firmendaten wurden mitgeprüft (matches).
  • requestId stringNur BZSt, valid: Kennung der Anfrage beim BZSt (Nachweis).
  • note stringNur BZSt, valid: Zusatzhinweis des BZSt, sonst leer.
  • validFrom string
  • matches object
    • name string
    • street string
    • postcode string
    • city string

Beispiel 200

{
  "object": "vat_check",
  "method": "vies",
  "input": "…",
  "status": "valid",
  "countryCode": "…",
  "vatNumber": "…",
  "name": "…",
  "address": "…",
  "checkedAt": "2026-01-31T12:00:00Z",
  "reason": "…",
  "code": "…",
  "message": "…",
  "qualified": false,
  "requestId": "…",
  "note": "…",
  "validFrom": "…",
  "matches": {
    "name": "…",
    "street": "…",
    "postcode": "…",
    "city": "…"
  }
}

IBAN prüfen + Bankname

get/api/v1/check/iban

Zustandslos. Scope checks:read. Prüft Zeichen und Länge nach ISO 13616 (keine Mod-97-Prüfsumme) und liefert für gültige deutsche IBANs den Banknamen aus der vierteljährlichen Bundesbank-BLZ-Datei sowie die achtstellige blz. Für Nicht-DE-IBANs bleiben bank_name leer und blz null.

Scope

checks:read

Parameter

  • iban query · string*
curl -X GET "https://maxrechnung.de/api/v1/check/iban" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Prüfergebnis
  • 400 iban fehlt
  • 401 Kein oder ungültiger API-Key
  • 403 Scope fehlt oder der Tarif reicht nicht (plan_required)
  • 429 Rate Limit überschritten

Schema 200

  • object "iban_check"
  • input string
  • iban stringNormalisiert (ohne Leerzeichen, groß).
  • valid boolean
  • country stringISO-3166-1-alpha-2 aus den ersten zwei Zeichen.
  • bank_name string
  • blz string · nullable

Beispiel 200

{
  "object": "iban_check",
  "input": "…",
  "iban": "…",
  "valid": false,
  "country": "…",
  "bank_name": "…",
  "blz": "…"
}

Schemas

Von den Endpunkten oben referenzierte Objekte. Vollständig auch in der OpenAPI-Spezifikation.