/ docs
ProdottoConoscenzaSviluppatori
Piattaforma Control
Inviare un ordine tramite l'API

Inviare un ordine UBL tramite la PSB API: endpoint, profili, idempotency e tracciamento dello stato.

Con la PSB API può inviare ordini d'acquisto (purchase order) ai Suoi fornitori tramite la rete Peppol. Il processo funziona in modo simile all'invio di fatture: si invia un documento UBL Order XML all'API, e la PSB si occupa della validazione, dell'instradamento e della consegna.

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

La richiesta contiene il documento UBL Order XML come body con content-type application/xml. Il {partyId} è l'identificativo Peppol dell'organizzazione mittente (l'acquirente).

Profili d'ordine

La PSB supporta due profili d'ordine Peppol:

ProfiloProfileIDUtilizzoOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Ordine unidirezionale senza responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Processo d'ordine completo con response, modifiche e annullamenti

Con Order Only l'acquirente invia un ordine e il processo è concluso. Con Advanced Ordering il fornitore può rispondere con un Order Response, e l'acquirente può modificare o annullare l'ordine successivamente.

Suggerimento: utilizzi il profilo Advanced Ordering se desidera che il fornitore confermi l'ordine o se vuole poter modificare gli ordini in seguito.

Flusso base
  1. Upload: invii il documento UBL Order XML all'endpoint
  2. Validazione: la PSB valida il documento rispetto allo schema XSD e alle regole di business
  3. Instradamento: la PSB cerca tramite SML/SMP come raggiungere il destinatario
  4. Consegna: il documento viene consegnato tramite Peppol al fornitore
  5. Aggiornamento stato: riceve un webhook OrderSent con lo stato della consegna
Idempotency

Utilizzi l'header X-EConnect-DocumentId per prevenire l'elaborazione duplicata:

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

Se si invia nuovamente lo stesso documentId, l'API restituisce 409 Conflict. Utilizzi sempre un UUID/GUID, mai un numero d'ordine.

Gestione degli errori

In caso di consegna fallita, la PSB applica automaticamente i retry:

  • Massimo 8 tentativi distribuiti su circa 35 ore
  • Solo per errori server 5xx (errori temporanei lato destinatario)
  • Per ogni tentativo viene pubblicato un evento OrderSentRetry
  • In caso di fallimento definitivo riceve un evento OrderSentError
ErroreCausaSoluzioneErrore di validazione (4xx)Il documento non è conforme allo standard PeppolVerifichi il documento con la Validate APIDestinatario non trovatoIdentificativo non registrato in PeppolVerifichi tramite queryRecipientParty se il fornitore può ricevere ordini409 ConflictUn documento con questo documentId è già stato elaboratoNessuna azione necessaria
Topic webhook

Configuri i webhook per i seguenti topic per seguire il processo d'ordine:

TopicQuandoOrderSentL'ordine è stato consegnato con successoOrderSentRetryLa consegna viene ritentataOrderSentErrorL'ordine non è stato consegnatoOrderResponseReceivedIl fornitore ha risposto all'ordineOrderChangeReceivedUna modifica all'ordine è stata ricevutaOrderCancellationReceivedUn annullamento dell'ordine è stato ricevuto
Risposta

Un upload riuscito restituisce 201 Created con l'ID del documento nella PSB. Utilizzi questo ID per seguire l'ordine tramite l'API o tramite i webhook.

Domande frequenti
Quando scegliere Order Only e quando Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) è un ordine unidirezionale senza ulteriore flusso di messaggi. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) è necessario quando il fornitore deve rispondere con una Order Response o quando si desidera modificare o annullare ordini in seguito. Scelga Advanced se necessita di questo processo completo.

Come evito l'elaborazione duplicata quando invio un ordine?

Invii l'header X-EConnect-DocumentId con un UUID o GUID univoco. Se riutilizza lo stesso documentId, l'API risponde con 409 Conflict. Non utilizzi un numero d'ordine come chiave di idempotenza, poiché non è previsto per questo meccanismo.

Cosa succede in caso di errori di consegna temporanei e quali webhook ricevo?

Per errori 5xx sul lato ricevente, la PSB ritenta automaticamente la consegna (fino a 8 tentativi nell'arco di circa 35 ore). Vedrà OrderSentRetry per ogni tentativo e OrderSentError in caso di fallimento definitivo. In caso di successo, riceverà OrderSent.

Consulti la specifica API completa su psb.econnect.eu per tutti i parametri e i payload di esempio.

Provi nell'API

Correlati
PreviousRicevere self-billing
NextRicevere un ordine