/ docs
ProduktWissenEntwickler
Plattform Control
Dokumentfluss und Statusnachrichten

Wie ein Dokument die sechs Phasen des PSB durchläuft: von Submit bis Delivered oder Failed, mit Statusnachrichten, Webhooks und Retry-Richtlinie.

Ein über den PSB gesendetes Dokument durchläuft eine feste Abfolge von Verarbeitungsphasen — von der Einreichung bis zur bestätigten Zustellung oder dem endgültigen Fehlschlag. An jedem Übergangspunkt veröffentlicht der PSB eine Statusnachricht, die über die Status-API abgerufen oder per Webhook empfangen werden kann.

Dieser Artikel beschreibt den Fluss im Detail, welche Statuscodes und Topics der PSB veröffentlicht, wie der Status eines Dokuments abgefragt wird und was bei fehlgeschlagener Zustellung oder Webhook-Benachrichtigung passiert.

Die sechs Phasen eines Dokuments
Submit → Validate → Transform → Route → Acknowledge → Delivered
                                                   ↘ Failed
PhaseWas passiertTypische TopicsSubmitDas Dokument wurde über die API, einen Mailfrom-Hook, SFTP-Pull oder eine andere Inbound-Methode eingereicht.PendingValidateDer PSB validiert das Dokument gegen Schema und Geschäftsregeln (z.B. NLCIUS, Peppol BIS Billing, DICO).Validated, *ReceivedError bei FehlerTransformOptionale Formatkonvertierung über die Transform-Engine (z.B. UBL zu CII, PDF zu UBL via IDR). Dies ist ein interner Schritt.(intern, kein separates Topic)RouteDer PSB bestimmt das Ziel: Peppol, E-Mail, SFTP oder einen anderen Kanal oder eine Kombination.RoutedAcknowledgeBestätigung vom empfangenden Access Point oder Kanal.AcknowledgedDelivered / FailedDie Zustellung ist bestätigt oder nach Ausschöpfung aller Wiederholungsversuche endgültig fehlgeschlagen.*Sent, *SentError

Submit kann von verschiedenen Kanälen aus gestartet werden — REST-Upload, Mailfrom-Hook, SFTP-Pull, Office 365 oder ein anderer Hook-Typ. Ab Submit ist der Fluss für jeden Kanal identisch.

Statuscodes

Der PSB veröffentlicht folgende kanonische Statuses über Topics und die Status-API:

StatusBedeutungEndstatus?PendingEingereicht, Validierung noch nicht gestartetNeinValidatedValidierung erfolgreichNeinRoutedZiel bestimmt, bereit zur ZustellungNeinDeliveredZustellung vom Empfänger oder Kanal bestätigtJaRejectedVom Empfänger abgelehnt (z.B. via MLS Reject)JaFailedZustellung nach allen Wiederholungsversuchen endgültig fehlgeschlagenJa

Zusätzliche feinkörnige Topics wie InvoiceSentRetry, InvoiceSentError und MessageLevelStatusReceived stehen für das Monitoring über Webhooks zur Verfügung.

Status über die API abfragen

Der aktuelle Status eines Dokuments kann über einen Status-Endpunkt pro Dokumenttyp abgerufen werden:

  • GET /api/v1/{partyId}/salesInvoice/{documentId}/status
  • GET /api/v1/{partyId}/purchaseInvoice/{documentId}/status

Die Antwort enthält den aktuellen Status, den Zeitstempel der letzten Änderung und bei einem Fehler einen Fehlercode mit Beschreibung.

Statusaktualisierungen über Webhooks

Für die Echtzeitintegration ist Webhook-Routing gegenüber Polling vorzuziehen. Abonnieren Sie die relevanten Topics, um direkte Benachrichtigungen zu erhalten:

RichtungHäufige TopicsEingehendInvoiceReceived, InvoiceReceivedError, OrderReceived, MessageLevelStatusReceivedAusgehendInvoiceSent, InvoiceSentRetry, InvoiceSentError, OrderSent, OrderSentRetry, OrderSentErrorMonitoringHookSent, HookSentRetry, HookSentError
Retry-Richtlinie bei der Dokumentzustellung

Wenn ein Zustellversuch aufgrund eines Fehlers auf der Empfängerseite fehlschlägt (z.B. 5xx von einem Peppol Access Point), setzt der PSB die Zustellung automatisch mit exponentiellem Backoff fort.

ParameterWertMaximale Anzahl Versuche8Gesamte Retry-Dauer~3 Tage (ca. 72 Stunden) ab dem ersten VersuchWiederholbare Codes5xx und 429Nicht wiederholbar4xx (außer 429) — sofortiger *SentErrorBackoffExponentiell (zunehmende Wartezeit pro Versuch)

Bei jedem Zustellversuch veröffentlicht der PSB ein {DocumentType}SentRetry-Topic. Nach endgültigem Fehlschlag folgt {DocumentType}SentError.

Retry-Richtlinie bei der Webhook-Zustellung

Die Retry-Richtlinie für die Webhook-Zustellung — Benachrichtigungen an Ihren eigenen Endpunkt — ist unabhängig von der Zustellungs-Retry-Richtlinie.

ParameterWertMaximale Anzahl Versuche12Gesamte Retry-Dauer~6 Tage (ca. 137 Stunden) ab dem ersten VersuchBackoffExponentiell (zunehmende Wartezeit pro Versuch)Timeout pro Versuch100 SekundenEvent pro VersuchHookSentRetryEvent nach endgültigem FehlschlagHookSentError

Hinweis: Nach ca. 6 Tagen (137 Stunden) ohne erfolgreiche Zustellung stoppt der PSB die Wiederholungsversuche. Verpasste Events können über den Batch-Endpunkt abgerufen werden.

Idempotenz im Fluss

Submit-Endpunkte unterstützen Idempotenz über den Header X-EConnect-DocumentId. Bei einer doppelten Einreichung gibt der PSB HTTP 409 Conflict zurück.

Häufig gestellte Fragen
Wie verfolge ich den Status eines gesendeten Dokuments?

Sie haben zwei Optionen. Über die Status-API (GET …/salesInvoice/{documentId}/status) rufen Sie den aktuellen Status ab. Für Echtzeit-Monitoring richten Sie Webhooks auf die relevanten Topics ein, wie InvoiceSent, InvoiceSentRetry und InvoiceSentError. Webhooks sind gegenüber Polling zu bevorzugen.

Was passiert, wenn ein Dokument nicht zugestellt werden kann?

Der PSB wiederholt die Zustellung automatisch bis zu 8 Mal über ca. 3 Tage (72 Stunden). Nach endgültigem Fehlschlag folgt {DocumentType}SentError und es ist manuelle Aktion erforderlich.

Wie lange versucht der PSB, einen Webhook zuzustellen?

Der PSB versucht eine Webhook-Benachrichtigung bis zu 12 Mal zuzustellen, verteilt über ca. 6 Tage (137 Stunden). Nach endgültigem Fehlschlag folgt das HookSentError-Event.

Interaktive API-Dokumentation ansehen

Verwandt

PSB-Übersicht: Architektur und Möglichkeiten
Fehlerbehandlung und Retry-Logik
Idempotenz: doppelte Einreichungen verhindern
PreviousFehlerbehandlung
NextWebhooks einrichten