Beim Versand von Rechnungen und anderen Dokumenten über eine API besteht immer das Risiko doppelter Sendungen. Ein Netzwerk-Timeout, ein Neustart Ihrer Anwendung oder ein unerwarteter Fehler kann dazu führen, dass Sie nicht sicher wissen, ob ein Dokument tatsächlich verarbeitet wurde. Ohne Schutz könnten Sie dasselbe Dokument erneut senden, mit doppelten Rechnungen als Folge.

Die PSB API bietet einen eingebauten Idempotency-Mechanismus, der dieses Problem löst. Indem Sie bei jedem Upload eine eindeutige DocumentId mitsenden, erkennt der PSB doppelte Versuche und verhindert, dass dasselbe Dokument zweimal verarbeitet wird.

Der Idempotency-Mechanismus dreht sich um den HTTP-Header X-EConnect-DocumentId. Beim Senden eines Dokuments fügen Sie diesen Header mit einem eindeutigen Wert hinzu, der das Dokument identifiziert.

POST /api/v1/{partyId}/salesInvoice/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {token}
Content-Type: application/xml
X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  ...
</Invoice>

Der PSB verarbeitet das Dokument und speichert die DocumentId. Wenn Sie dieselbe Anfrage erneut senden (zum Beispiel als Retry nach einem Timeout), erkennt der PSB, dass die DocumentId bereits existiert, und gibt eine 409 Conflict-Antwort zurück, anstatt das Dokument ein zweites Mal zu verarbeiten.

HTTP/1.1 409 Conflict

Dieser 409 ist keine Fehlermeldung im herkömmlichen Sinne. Er ist eine Bestätigung, dass das Dokument bereits zuvor erfolgreich verarbeitet wurde. Ihre Anwendung kann die Anfrage sicher als abgeschlossen markieren.

Die DocumentId, die Sie im X-EConnect-DocumentId-Header mitsenden, muss einige Anforderungen erfüllen:

Wichtig: Verwenden Sie niemals die Rechnungsnummer als DocumentId. Eine Rechnungsnummer kann für eine Gutschrift oder eine korrigierte Rechnung wiederverwendet werden, was zu Konflikten führt. Verwenden Sie stattdessen eine UUID/GUID, die Sie pro Sendungsversuch generieren.

Eine UUID ist die empfohlene Wahl. Sie ist garantiert eindeutig und wird in allen Programmiersprachen umfassend unterstützt.

Gut:    550e8400-e29b-41d4-a716-446655440000  (UUID)
Gut:    DOC2026030800142                       (eigene Sequenz, sofern eindeutig)
Falsch: INV-2026-001                           (Rechnungsnummer, nicht verwenden)
Falsch: ab@cd                                  (Sonderzeichen)
Falsch: abc                                    (zu kurz)

Idempotency wird in Kombination mit Retry-Logik am wertvollsten. Wenn ein API-Aufruf aufgrund eines Netzwerkfehlers oder eines 5xx-Serverfehlers fehlschlägt, möchten Sie die Anfrage erneut senden, ohne das Risiko einer doppelten Verarbeitung.

Die empfohlene Vorgehensweise funktioniert wie folgt:

1. Generieren Sie eine eindeutige DocumentId (UUID), bevor Sie die Anfrage senden.
2. Senden Sie das Dokument mit dem X-EConnect-DocumentId-Header.
3. Wenn Sie 200 OK erhalten: Das Dokument wurde verarbeitet, fertig.
4. Wenn Sie 409 Conflict erhalten: Das Dokument wurde bei einem früheren Versuch bereits verarbeitet, fertig.
5. Wenn Sie einen 5xx-Fehler oder einen Timeout erhalten: Warten Sie und wiederholen Sie die Anfrage mit derselben DocumentId.
6. Wenn Sie einen 4xx-Fehler erhalten (außer 409): Es gibt ein Problem mit der Anfrage selbst. Ein Retry hilft nicht; der Fehler muss behoben werden.

Tipp: Verwenden Sie exponentiellen Backoff bei Retries. Beginnen Sie mit einer kurzen Wartezeit (zum Beispiel 1 Sekunde) und verdoppeln Sie diese bei jedem weiteren Versuch, bis zu einem Maximum von zum Beispiel 60 Sekunden. Der PSB selbst verwendet eine Retry-Richtlinie von maximal 8 Versuchen über etwa 35 Stunden bei 5xx-Fehlern.

Der X-EConnect-DocumentId-Header wird auf allen Endpoints unterstützt, über die Sie Dokumente zum PSB hochladen. Die wichtigsten sind:

Für Empfangs-Endpoints (Download von Dokumenten) gilt Idempotency nicht: Das Abrufen eines Dokuments ist von Natur aus idempotent, da es keine Daten verändert.

Idempotency ist ein kleiner Mechanismus mit großer Wirkung. Indem Sie konsequent eine X-EConnect-DocumentId bei jedem Dokumentupload mitsenden, schützen Sie sich vor doppelten Sendungen. In Kombination mit Retry-Logik und exponentiellem Backoff bauen Sie eine robuste Integration, die Netzwerkproblemen und temporären Serverfehlern standhält.