/ docs
ProduitConnaissancesDéveloppeurs
Plateforme Control
Envoyer une commande via l'API

Envoyer une commande UBL via l'API PSB : endpoint, profils, idempotency et suivi de statut.

Avec l'API PSB, vous pouvez envoyer des commandes d'achat (purchase orders) à vos fournisseurs via le réseau Peppol. Le processus fonctionne de manière similaire à l'envoi de factures : vous envoyez un document XML UBL Order à l'API, et le PSB se charge de la validation, du routage et de la livraison.

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

La requête contient le document XML UBL Order dans le body avec le content-type application/xml. Le {partyId} est l'identifiant Peppol de l'organisation expéditrice (l'acheteur).

Profils de commande

Le PSB prend en charge deux profils de commande Peppol :

ProfilProfileIDUtilisationOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Commande unidirectionnelle sans responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Processus de commande complet avec response, modifications et annulations

Avec Order Only, l'acheteur envoie une commande et le processus est terminé. Avec Advanced Ordering, le fournisseur peut répondre avec une Order Response, et l'acheteur peut modifier ou annuler la commande ultérieurement.

Conseil : utilisez le profil Advanced Ordering si vous souhaitez que le fournisseur confirme la commande ou si vous voulez pouvoir modifier les commandes par la suite.

Flux de base
  1. Upload : envoyez le document XML UBL Order à l'endpoint
  2. Validation : le PSB valide le document selon le schéma XSD et les règles métier
  3. Routage : le PSB recherche via SML/SMP comment joindre le destinataire
  4. Livraison : le document est livré via Peppol au fournisseur
  5. Mise à jour de statut : vous recevez un webhook OrderSent avec le statut de livraison
Idempotency

Utilisez le header X-EConnect-DocumentId pour éviter le traitement en double :

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

Si vous envoyez le même documentId une seconde fois, l'API retourne 409 Conflict. Utilisez toujours un UUID/GUID, jamais un numéro de commande.

Gestion des erreurs

En cas d'échec de livraison, le PSB applique automatiquement des retries :

  • Maximum 8 tentatives réparties sur environ 35 heures
  • Uniquement en cas d'erreurs serveur 5xx (erreurs temporaires côté destinataire)
  • À chaque tentative, un événement OrderSentRetry est publié
  • En cas d'échec définitif, vous recevez un événement OrderSentError
ErreurCauseSolutionErreur de validation (4xx)Le document ne respecte pas la norme PeppolVérifiez le document avec la Validate APIDestinataire non trouvéIdentifiant non enregistré dans PeppolVérifiez via queryRecipientParty si le fournisseur peut recevoir des commandes409 ConflictUn document avec ce documentId a déjà été traitéAucune action nécessaire
Topics webhook

Configurez des webhooks pour les topics suivants afin de suivre le processus de commande :

TopicQuandOrderSentCommande livrée avec succèsOrderSentRetryNouvelle tentative de livraisonOrderSentErrorLa commande n'a pas pu être livréeOrderResponseReceivedLe fournisseur a répondu à la commandeOrderChangeReceivedUne modification de la commande a été reçueOrderCancellationReceivedUne annulation de la commande a été reçue
Réponse

Un upload réussi retourne 201 Created avec l'ID du document dans le PSB. Utilisez cet ID pour suivre la commande via l'API ou via les webhooks.

Questions fréquentes
Quand choisir Order Only et quand Advanced Ordering ?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) est une commande unidirectionnelle sans flux de messages supplémentaire. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) est nécessaire lorsque le fournisseur doit répondre avec une Order Response ou lorsque vous souhaitez modifier ou annuler des commandes ultérieurement. Choisissez Advanced si vous avez besoin de ce processus complet.

Comment éviter le traitement en double lors de l'envoi d'une commande ?

Envoyez l'en-tête X-EConnect-DocumentId avec un UUID ou GUID unique. Si vous réutilisez le même documentId, l'API répond avec 409 Conflict. N'utilisez pas un numéro de commande comme clé d'idempotence, car il n'est pas prévu pour ce mécanisme.

Que se passe-t-il en cas d'échecs de livraison temporaires et quels webhooks reçoit-on ?

En cas d'erreurs 5xx du côté récepteur, le PSB tente automatiquement une nouvelle livraison (jusqu'à 8 tentatives sur environ 35 heures). Vous verrez OrderSentRetry pour chaque tentative et OrderSentError en cas d'échec définitif. En cas de succès, vous recevez OrderSent.

Consultez la spécification API complète sur psb.econnect.eu pour tous les paramètres et exemples de payloads.

Essayer dans l'API

Articles associés
PreviousSelf-billing recevoir
NextRecevoir une commande