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": "…"
}
}