ProductKennisDevelopers
Platform Control
Order verzenden via de API

Een UBL Order verzenden via de PSB API: endpoint, profielen, idempotency en statustracking.

Met de PSB API kun je inkooporders (purchase orders) verzenden naar je leveranciers via het Peppol-netwerk. Het proces werkt vergelijkbaar met het verzenden van facturen: je stuurt een UBL Order XML-document naar de API, en de PSB zorgt voor validatie, routering en aflevering.

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

Het request bevat het UBL Order XML-document als body met content-type application/xml. De {partyId} is de Peppol-identifier van de verzendende organisatie (de koper).

Order-profielen

De PSB ondersteunt twee Peppol-orderprofielen:

ProfielProfileIDGebruikOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Eenrichtingsorder zonder responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Volledig orderproces met response, wijzigingen en annuleringen

Bij Order Only stuurt de koper een order en is het proces klaar. Bij Advanced Ordering kan de leverancier reageren met een Order Response, en kan de koper de order later wijzigen of annuleren.

Tip: Gebruik het Advanced Ordering-profiel als je wilt dat de leverancier de order bevestigt of als je orders later wilt kunnen aanpassen.

Basisflow
  1. Upload: stuur het UBL Order XML-document naar het endpoint
  2. Validatie: de PSB valideert het document op XSD-schema en business rules
  3. Routering: de PSB zoekt via SML/SMP op hoe de ontvanger bereikbaar is
  4. Aflevering: het document wordt via Peppol afgeleverd bij de leverancier
  5. Statusupdate: je ontvangt een OrderSent-webhook met de afleveringsstatus
Idempotency

Gebruik de X-EConnect-DocumentId header om dubbele verwerking te voorkomen:

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

Als je hetzelfde documentId nogmaals stuurt, retourneert de API 409 Conflict. Gebruik altijd een UUID/GUID, nooit een ordernummer.

Foutafhandeling

Bij een mislukte aflevering past de PSB automatisch retries toe:

  • Maximaal 8 pogingen verspreid over circa 35 uur
  • Alleen bij 5xx server errors (tijdelijke fouten aan de ontvangende kant)
  • Per poging wordt een OrderSentRetry-event gepubliceerd
  • Bij definitief falen ontvang je een OrderSentError-event
FoutOorzaakOplossingValidatiefout (4xx)Document voldoet niet aan de Peppol-standaardControleer het document met de Validate APIOntvanger niet gevondenIdentifier niet geregistreerd in PeppolControleer via queryRecipientParty of de leverancier orders kan ontvangen409 ConflictDocument met dit documentId is al verwerktGeen actie nodigHTTP 500 bij grote payloadRequest overschrijdt de 24 MB webserver-limiet (inclusief overhead)Verklein het document of de bijlagen; houd rekening met ~33% base64-overhead
Webhooktopics

Stel webhooks in voor de volgende topics om het orderproces te volgen:

TopicWanneerOrderSentOrder is succesvol afgeleverdOrderSentRetryAflevering wordt opnieuw geprobeerdOrderSentErrorOrder kon niet worden afgeleverdOrderResponseReceivedLeverancier heeft gereageerd op de orderOrderChangeReceivedWijziging op de order is ontvangenOrderCancellationReceivedAnnulering op de order is ontvangen
Response

Een succesvolle upload retourneert 200 OK met de document-ID in de PSB. Gebruik deze ID om de order te volgen via de API of via webhooks.

Veelgestelde vragen
Wanneer kies ik Order Only en wanneer Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) is een eenrichtingsorder zonder verdere berichtenstroom. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) is nodig als de leverancier met een Order Response moet reageren of als je orders later wilt wijzigen of annuleren. Kies Advanced als je dat volledige proces nodig hebt.

Hoe voorkom ik dubbele verwerking bij het verzenden van een order?

Stuur de header X-EConnect-DocumentId mee met een unieke UUID of GUID. Als je hetzelfde documentId opnieuw gebruikt, antwoordt de API met 409 Conflict. Gebruik geen ordernummer als idempotency-key; dat is niet bedoeld voor dit mechanisme.

Wat gebeurt er bij tijdelijke afleverfouten en welke webhooks krijg ik?

Bij 5xx-fouten aan de ontvangende kant probeert de PSB automatisch opnieuw af te leveren (maximaal 8 pogingen over circa 35 uur). Je ziet OrderSentRetry per poging en bij definitief falen OrderSentError. Bij succes ontvang je OrderSent.

Bekijk de volledige API-specificatie op psb.econnect.eu voor alle parameters en voorbeeldpayloads.

Probeer het in de API

Gerelateerd
PreviousSelf-billing ontvangen
NextOrder ontvangen