Bestellung versenden

Mit der PSB API können Sie Bestellungen an Ihre Lieferanten über das Peppol-Netzwerk versenden. Der Prozess funktioniert ähnlich wie das Versenden von Rechnungen: Sie senden ein UBL Order XML-Dokument an die API, und der PSB übernimmt Validierung, Routing und Zustellung.

Endpoint

POST /api/v1/{partyId}/purchaseOrder/send

Die Anfrage enthält das UBL Order XML-Dokument als Body mit Content-Type application/xml. Die {partyId} ist der Peppol-Identifier der sendenden Organisation (des Käufers).

Bestellprofile

Der PSB unterstützt zwei Peppol-Bestellprofile:

Profil

ProfileID

Verwendung

Order Only

urn:fdc:peppol.eu:poacc:bis:order_only:3

Einwegbestellung ohne Antwort

Advanced Ordering

urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3

Vollständiger Bestellprozess mit Antwort, Änderungen und Stornierungen

Bei Order Only sendet der Käufer eine Bestellung und der Prozess ist abgeschlossen. Bei Advanced Ordering kann der Lieferant mit einer Order Response antworten, und der Käufer kann die Bestellung später ändern oder stornieren.

Tipp: Verwenden Sie das Advanced Ordering-Profil, wenn Sie möchten, dass der Lieferant die Bestellung bestätigt, oder wenn Sie Bestellungen später anpassen möchten.

Grundlegender Ablauf

Upload: Senden Sie das UBL Order XML-Dokument an den Endpoint
Validierung: Der PSB validiert das Dokument gegen XSD-Schema und Geschäftsregeln
Routing: Der PSB führt einen SML/SMP-Lookup durch, um festzustellen, wie der Empfänger erreichbar ist
Zustellung: Das Dokument wird über Peppol an den Lieferanten zugestellt
Statusaktualisierung: Sie erhalten einen OrderSent-Webhook mit dem Zustellungsstatus

Idempotency

Verwenden Sie den X-EConnect-DocumentId-Header, um doppelte Verarbeitung zu vermeiden:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Wenn Sie dieselbe DocumentId erneut senden, gibt die API 409 Conflict zurück. Verwenden Sie immer eine UUID/GUID, niemals eine Bestellnummer.

Fehlerbehandlung

Bei einer fehlgeschlagenen Zustellung wendet der PSB automatisch Retries an:

Maximal 8 Versuche verteilt über etwa 35 Stunden
Nur bei 5xx-Serverfehlern (temporäre Fehler auf Empfängerseite)
Pro Versuch wird ein OrderSentRetry-Event veröffentlicht
Bei endgültigem Fehlschlag erhalten Sie ein OrderSentError-Event

Fehler

Ursache

Lösung

Validierungsfehler (4xx)

Dokument entspricht nicht dem Peppol-Standard

Prüfen Sie das Dokument mit der Validate API

Empfänger nicht gefunden

Identifier nicht bei Peppol registriert

Prüfen Sie über queryRecipientParty, ob der Lieferant Bestellungen empfangen kann

409 Conflict

Dokument mit dieser DocumentId wurde bereits verarbeitet

Keine Aktion erforderlich

Webhook-Topics

Richten Sie Webhooks für die folgenden Topics ein, um den Bestellprozess zu verfolgen:

Topic

Wann

OrderSent

Bestellung wurde erfolgreich zugestellt

OrderSentRetry

Zustellung wird erneut versucht

OrderSentError

Bestellung konnte nicht zugestellt werden

OrderResponseReceived

Lieferant hat auf die Bestellung geantwortet

OrderChangeReceived

Eine Änderung der Bestellung wurde empfangen

OrderCancellationReceived

Eine Stornierung der Bestellung wurde empfangen

Response

Ein erfolgreicher Upload gibt 201 Created mit der Dokument-ID im PSB zurück. Verwenden Sie diese ID, um die Bestellung über die API oder über Webhooks zu verfolgen.

Häufig gestellte Fragen

Wann wähle ich Order Only und wann Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) ist eine Einwegbestellung ohne weiteren Nachrichtenfluss. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) ist erforderlich, wenn der Lieferant mit einer Order Response antworten muss oder wenn Sie Bestellungen später ändern oder stornieren möchten. Wählen Sie Advanced, wenn Sie diesen vollständigen Prozess benötigen.

Wie verhindere ich doppelte Verarbeitung beim Senden einer Bestellung?

Senden Sie den Header X-EConnect-DocumentId mit einer eindeutigen UUID oder GUID mit. Wenn Sie dieselbe documentId erneut verwenden, antwortet die API mit 409 Conflict. Verwenden Sie keine Bestellnummer als Idempotency-Key, da diese nicht für diesen Mechanismus vorgesehen ist.

Was passiert bei temporären Zustellfehlern und welche Webhooks erhalte ich?

Bei 5xx-Fehlern auf der Empfängerseite versucht die PSB automatisch erneut zuzustellen (maximal 8 Versuche über etwa 35 Stunden). Sie sehen OrderSentRetry pro Versuch und bei endgültigem Fehlschlag OrderSentError. Bei Erfolg erhalten Sie OrderSent.

Die vollständige API-Spezifikation finden Sie unter psb.econnect.eu mit allen Parametern und Beispiel-Payloads.

In der API ausprobieren

Verwandt