Leitfaden Für Validierungsläufe

Verwenden Sie USt-IdNr.-Validierungsläufe, wenn Sie einen oder mehrere Datensätze validieren und Unternehmensstammdaten wie Name, Straße, Postleitzahl und Stadt vergleichen müssen.

Synchron Oder Asynchron

Beide Create-Endpunkte starten denselben Validierungsworkflow und geben dieselbe Antwortstruktur zurück. Der Unterschied ist, wie lange der erste HTTP-Request wartet.

Verwendung	Endpunkt	Am besten für
Synchrone Validierung	POST /api/v1/integration/vat/validations	Kleine Batches, bei denen der Client den HTTP-Request offen halten kann, bis die Validierung abgeschlossen ist.
Asynchrone Validierung	POST /api/v1/integration/vat/validations/async	Größere Batches, automatisierte Importe, Client-Timeouts, wiederholungssichere Jobs und PDF-erzeugende Workflows.

Für die meisten Produktionsintegrationen ist der asynchrone Endpunkt vorzuziehen. Er vermeidet lang laufende HTTP-Requests und gibt dem Client einen klaren Polling-Ablauf.

Verarbeitungszeit hängt von externen Behörden ab

Jede USt-IdNr.-Validierung wird in Echtzeit über die jeweils zuständigen Behörden der EU-Mitgliedstaaten durchgeführt. Antwortzeiten können daher je nach Mitgliedstaat, Verfügbarkeit externer Systeme und aktueller Systemlast deutlich variieren.

Nach unserer Erfahrung liegt die typische Verarbeitungszeit außerhalb von Spitzenzeiten bei ungefähr 3-5 Sekunden pro USt-IdNr. Bei der Validierung mehrerer USt-IdNrn. kann sich die Gesamtverarbeitungszeit entsprechend addieren. Die Validierung von 20 USt-IdNrn. kann zum Beispiel ungefähr 1 bis 3 Minuten dauern, abhängig von den Antwortzeiten der externen Systeme.

Asynchroner Ablauf

Wenn der asynchrone Endpunkt einen noch laufenden Lauf annimmt, gibt er zurück:

• HTTP 202 Accepted
• status: "Running"
• operationId
• Retry-After
• Cache-Control: no-store
• Location mit Verweis auf den Operation-Status-Endpunkt

Speichern Sie die operationId und pollen Sie anschließend:

GET /api/v1/integration/vat/validations/{operationId}

Warten Sie mindestens die Anzahl Sekunden aus Retry-After, bevor Sie erneut pollen.

Wenn Ihr System den Idempotency Key natürlicher speichert als die Operation ID, können Sie den Lauf auch so abrufen:

GET /api/v1/integration/vat/validations/by-idempotency-key/{idempotencyKey}

Request-Datensätze

Jeder Datensatz unterstützt diese erstklassigen VAT-Felder:

• vatId
• companyName
• street
• zip
• city

Zusätzliche JSON-Eigenschaften werden als Custom Fields akzeptiert. Verwenden Sie sie für eigene Zeilen- oder Dokumentkennungen, weil eine USt-IdNr. nicht immer eindeutig genug ist, um ein Ergebnis auf einen Quelldatensatz zurückzuführen.

{
  "records": [
    {
      "vatId": "DE284700631",
      "companyName": "Optimus Software GmbH",
      "street": "Tal 44",
      "zip": "80331",
      "city": "München",
      "sourceSystemReferenceId": "ERP-SUPPLIER-77821"
    }
  ],
  "options": {
    "checkType": "Qualified",
    "sendNotificationEmail": false,
    "createSnapshot": true,
    "retryDuration": "OneHour",
    "include": [
      "addressStreetName",
      "addressHouseNumber"
    ],
    "pdf": {
      "create": true,
      "sign": false,
      "sendByEmail": false,
      "returnAsBase64": false,
      "returnAsUrl": true
    }
  }
}

checkType ist Standard oder Qualified. retryDuration unterstützt None, OneHour, TwoHours, FourHours, EightHours und TwentyFourHours.

Verwenden Sie options.include, wenn abgeschlossene Datensätze zusätzliche aufgelöste USt-Daten enthalten sollen. Unterstützte Werte sind addressStreetName und addressHouseNumber. Das ist hilfreich, wenn Ihr System Straßenname und Hausnummer getrennt speichert, während das normale Validierungsfeld weiterhin street bleibt.

Laufstatus

Status	Bedeutung
Running	Der Validierungslauf wird noch verarbeitet. Nach Retry-After erneut pollen.
Completed	Die Validierung ist abgeschlossen und records enthält Ergebnisse pro Datensatz.
Failed	Der Lauf ist fehlgeschlagen, bevor verwertbare Datensatzergebnisse erzeugt wurden. error lesen.

records ist nur verfügbar, nachdem die Operation Completed ist. Bei Running-Operationen wird records ausgelassen. Bei Failed-Operationen kann records ausgelassen werden, wenn der Workflow vor der Erzeugung von Ergebnisdaten fehlgeschlagen ist.

Datensatzergebnisse Interpretieren

Verwenden Sie den status jedes Datensatzes für das USt-IdNr.-Ergebnis:

Status	Bedeutung
Valid	Die USt-IdNr. wurde als gültig aufgelöst.
Invalid	Die USt-IdNr. wurde als ungültig aufgelöst.
Unavailable	Das Provider-Ergebnis war temporär nicht verfügbar. Retry-Behandlung kann sinnvoll sein.

Verwenden Sie flags für zusätzlichen Kontext wie ungültige Syntax, vollständig verifizierte Daten, ungültige Unternehmens-/Adressfelder, qualifizierte Verifikation, fehlende Pflichtdaten oder ein nicht berechtigtes Land.

Verwenden Sie companyName, street, zip und city, um eingereichte Stammdaten mit dem offiziellen Ergebnis zu vergleichen:

Feldeigenschaft	Bedeutung
value	Originalwert, der vom Client eingereicht wurde.
matchStatus	Match, NoMatch, NotQueried oder NotReturned.
correctionValue	Offizieller oder korrigierter Wert, wenn verfügbar.

Verwenden Sie customFields, um das Ergebnis auf Ihr Quellsystem zurückzuführen.

Wenn options.include zusätzliche Felder angefordert hat und die Daten aufgelöst werden konnten, kann jeder abgeschlossene Datensatz auch included enthalten:

{
  "vatId": "DE284700631",
  "status": "Valid",
  "street": {
    "value": "Tal 44",
    "matchStatus": "Match"
  },
  "included": {
    "addressStreetName": "Tal",
    "addressHouseNumber": "44"
  }
}

PDF-Ergebnisse

Setzen Sie options.pdf.create auf true, wenn Sie einen PDF-Bericht benötigen.

PDF-Auslieferungsoptionen sind unabhängig:

Option	Ergebnis
returnAsBase64: true	Bettet das Base64-PDF in pdfDocument.base64 ein.
returnAsUrl: true	Enthält eine Download-URL in pdfDocument.url.
sendByEmail: true	Sendet das PDF über den Validierungsworkflow.
sign: true	Signiert das erzeugte PDF.

PDF-Auslieferungsoptionen erfordern pdf.create: true. PDF-Signierung erfordert ebenfalls pdf.create: true.

Wenn URL-Auslieferung verwendet wird, laden Sie die Datei nach Abschluss des Laufs herunter:

GET /api/v1/integration/vat/validations/{operationId}/pdf

Wenn der Lauf noch verarbeitet wird, gibt der PDF-Endpunkt 409 Conflict zurück. Wenn für die Operation kein PDF existiert, gibt er 404 Not Found zurück.

Ergebnisaufbewahrung

Die Antwort enthält expiresAt. Behandeln Sie diesen Zeitstempel als spätesten Zeitpunkt, zu dem die Operationsdaten noch abrufbar sein können.

Speichern Sie die Felder, die Sie benötigen, nach Erhalt eines abgeschlossenen Ergebnisses in Ihrem eigenen System, insbesondere wenn Sie langfristige Prüfung, ERP-Synchronisierung oder PDF-Archivdaten benötigen.

Empfohlenes Produktionsmuster

Für transaktionsartige Prüfungen mit kurzen Client-Timeouts:

1. Idempotency Key erzeugen und speichern.
2. POST /api/v1/integration/vat/validations/async aufrufen.
3. operationId speichern.
4. GET /api/v1/integration/vat/validations/{operationId} mit Retry-After pollen.
5. Bei Completed records lesen und das Ergebnis pro Quellzeile speichern.
6. Wenn PDF-URL-Auslieferung angefordert wurde, pdfDocument.url speichern oder herunterladen.

Für kleine interne Jobs, bei denen Blockieren akzeptabel ist:

1. Idempotency Key erzeugen und speichern.
2. POST /api/v1/integration/vat/validations aufrufen.
3. records direkt aus der Antwort lesen, wenn status Completed ist.
4. Wenn der Request fehlschlägt oder mit Timeout endet, per Idempotency Key erneut lesen.