Zum Hauptinhalt springen

Idempotenz

Verwenden Sie den Header Idempotency-Key, wenn ein Client dieselbe Validierungsanfrage wiederholen könnte.

Idempotency-Key: vat-async-2026-05-12-001

Wenn derselbe Key mit demselben Payload erneut verwendet wird, gibt die API den bestehenden Validierungslauf zurück, statt doppelte Arbeit zu starten.

Wenn derselbe Key mit einem anderen Payload erneut verwendet wird, gibt die API zurück:

409 Conflict

Beispiel​

curl -X POST "https://app.optimussoftware.de/api/v1/integration/vat/validations/async" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: vat-async-2026-05-12-001" \
  -H "Content-Type: application/json" \
  -d @validation-request.json

Verwenden Sie stabile Keys aus Ihrem System, zum Beispiel eine Import-Job-ID oder Batch-ID, wenn Wiederholungssicherheit wichtig ist.

Wenn ein Create-Request fehlschlägt oder nach Annahme durch den Server mit Timeout endet, wiederholen Sie denselben Request mit demselben Idempotency Key. Wenn Sie den Lauf später prüfen müssen und den Key gespeichert haben, rufen Sie auf:

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

Key-Richtlinien​

  • Verwenden Sie einen Key für eine logische Validierungsanfrage.
  • Verwenden Sie denselben Key erneut, wenn Sie dieselbe Anfrage nach Timeout, Netzwerkfehler oder Client-Neustart wiederholen.
  • Verwenden Sie einen neuen Key, wenn sich der Request-Payload ändert.
  • Speichern Sie den Key mit Ihrem eigenen Importjob, Batch oder Dokumentdatensatz.
  • Verwenden Sie Zeitstempel nicht allein, wenn derselbe Job mit einem neuen Zeitstempel erneut versucht werden kann.

Für CLI-Nutzer erstellt und speichert Integration CLI Idempotency Keys automatisch in der gespeicherten State-Datei. API-Clients müssen eigene Keys senden und speichern, wenn Wiederholungssicherheit wichtig ist.