Zielgruppe & Rolle

Rolle: IT-Administrator / Softwarearchitekt / Entwickler / Support

BZSt eVatR Statuscodes & Fehlerbehandlung

Die BZSt eVatR REST-Schnittstelle liefert strukturierte Statuscodes zurück. ConnectCLOUD übersetzt diese Codes in verständliche Statusmeldungen und leitet entsprechende Aktionen (Sperren, Protokollierung, Retries) ab.

1. BZSt Hauptstatuscodes

BZSt Code	Interner Code	UI-Anzeige	Bedeutung & Folgeaktion
evatr-0000	VALID	Gültig / Qualifiziert bestätigt	Die angefragte USt-IdNr. ist gültig. Bei qualifizierten Anfragen werden zusätzlich die Einzelergebnisse (ErgName, ErgStr, ErgPlz, ErgOrt) ausgewertet.
evatr-2001	VAT_NOT_ASSIGNED	Ungültig (Nicht vergeben)	Die angefragte USt-IdNr. ist nicht vergeben oder wurde gelöscht. Eventuelle Adresssperre greift.
evatr-2002	VAT_INVALID	Ungültig	Die angefragte USt-IdNr. ist ungültig. Eventuelle Adresssperre greift.
evatr-2003	OWN_VAT_INVALID	Konfigurationsfehler (Eigene USt-IdNr. ungültig)	Die in den Firmenstammdaten hinterlegte anfragende eigene USt-IdNr. ist ungültig. Bitte eigene USt-IdNr. in microtech prüfen.
evatr-2004	MEMBER_STATE_UNAVAILABLE	EU-Mitgliedstaat nicht erreichbar	Die nationale Datenbank des EU-Mitgliedstaates ist vorübergehend nicht erreichbar. Die Prüfung wird beim nächsten Intervall wiederholt.
evatr-2005	MEMBER_STATE_TIMEOUT	Zeitüberschreitung EU-Mitgliedstaat	Zeitüberschreitung bei der Kommunikation mit dem Mitgliedstaat. Automatische Wiederholung.
evatr-2006	SERVER_BUSY	Server überlastet	Das BZSt-System ist derzeit ausgelastet. Backoff & automatischer Retry.
evatr-2007	INVALID_INPUT	Ungültige Eingabedaten	Die übermittelten Anfragedaten sind syntaktisch fehlerhaft.
evatr-2015	DATA_NOT_VERIFIED	Daten nicht bestätigt	Die angefragten Daten konnten vom EU-Mitgliedstaat nicht bestätigt werden.
evatr-0011	SERVICE_UNAVAILABLE	Dienst nicht verfügbar	BZSt-Wartungsfenster oder Ausfall. Der Service führt automatische Retries mit Exponential Backoff & Jitter durch.

2. Abgleichscodes für qualifizierte Bestätigung

Bei ausländischen EU-USt-IdNrn. vergleicht das BZSt die übermittelten Adressdaten mit dem Register des jeweiligen EU-Mitgliedstaates und liefert für jedes Feld (ErgName, ErgStr, ErgPlz, ErgOrt) einen Ergebnisbuchstaben:

Code	Bezeichnung	Bedeutung
A	Stimmt überein	Der übermittelte Wert stimmt mit dem behördlich registrierten Datensatz überein.
B	Stimmt nicht überein	Der übermittelte Wert weicht vom behördlich registrierten Datensatz ab. Führt zu Status Eingeschränkt bestätigt und optionaler ERP-Sperre.
C	Nicht angefragt	Dieses Feld wurde bei der Anfrage nicht übermittelt.
D	Nicht mitgeteilt	Der EU-Mitgliedstaat stellt für dieses Feld keine behördlichen Abgleichsdaten bereit (z. B. manche Länder teilen keine Straßennamen mit).

3. Ermittlung des Gesamtergebnisses

Aus der Kombination des Hauptstatus und der Feldabgleiche berechnet vat-validation-go den Gesamtstatus:

Hauptstatus evatr-0000 (Gültig)?
  ├── NEIN ──────────────────────────────────────────> Status: INVALID (Ungültig)
  └── JA
       ├── Alle angefragten Felder haben Code 'A'? ──> Status: QUALIFIED_CONFIRMED (Qualifiziert bestätigt)
       └── Mindestens ein Feld hat Code 'B'? ────────> Status: PARTIALLY_CONFIRMED (Eingeschränkt bestätigt)

4. Inländische Statuscodes (Deutschland)

Für deutsche USt-IdNrn. werden folgende Statuswerte generiert:

Statuscode	UI-Anzeige	Kriterium
FORMALLY_VALID_NO_OFFICIAL_CHECK	Formal gültig (keine amtliche Prüfung)	USt-IdNr. entspricht dem Regex ^DE\d{9}$ und besteht die Modulo-11,10-Prüfziffernvalidierung.
FORMALLY_INVALID	Formal ungültig	USt-IdNr. weicht vom vorgeschriebenen DE-Muster ab.
MISSING_VAT_ID	Keine USt-IdNr.	Im Adressdatensatz ist keine USt-IdNr. gepflegt.