Collegamento dinamico tra il sistema e-Procurement dell'Acquirente e lo Store del Fornitore

Lo Shopping: PunchOut Transaction

Il momento centrale dell’intero protocollo cXML è la possibilità di agganciare il carrello acquisti (Shopping Cart) direttamente ai portali Erp o Procurement (Ariba, Coupa, Jaggaer ecc.).

Supporto in F-Merchant: supportato come scenario primario di integrazione B2B.

Direzione tipica: in ingresso verso F-Merchant per l’apertura sessione, poi in uscita verso il buyer con il PunchOutOrderMessage.

Chi deve leggerla: integration developer, team eProcurement lato buyer, team e-commerce lato fornitore.

Sistemi coinvolti di solito: piattaforma procurement del buyer, store F-Merchant, ERP o middleware per allineamento articoli, prezzi e ordini.

Cos’è il PunchOut

Il PunchOut Transaction permette a un acquirente di “uscire” (punch-out) temporaneamente dalla propria piattaforma di spesa aziendale per “entrare” (punch-in) in uno store creato appositamente dal fornitore. Il passaggio avviene scambiando un PunchOutSetupRequest.

Checklist minima di implementazione

Per completare una prima integrazione PunchOut servono almeno questi elementi:

• endpoint HTTP/HTTPS che riceve la PunchOutSetupRequest;
• credenziali coerenti tra From, To, Sender e SharedSecret;
• regola di identificazione buyer o account che apra il catalogo corretto;
• URL di ritorno (BrowserFormPost/URL) validato e raggiungibile;
• mapping tra SupplierPartID, prezzi, unità di misura e tassonomia articoli;
• gestione del ritorno carrello con PunchOutOrderMessage.

Se uno di questi punti manca, il progetto entra quasi sempre in stallo prima ancora del collaudo funzionale.

Tipi di PunchOut (operation)

L’attributo operation della PunchOutSetupRequest determina la modalità con cui viene avviata la sessione di shopping. I valori previsti sono tre:

• create — Avvia una nuova sessione di shopping. È il valore predefinito e il più frequente: l’utente parte da un carrello vuoto e naviga il catalogo del fornitore.
• inspect — Consente di consultare un ordine o un carrello già trasmesso in precedenza, senza possibilità di modifica. Utile per verificare prezzi e disponibilità a posteriori.
• edit — Riapre un carrello esistente per modificarlo (ad esempio per aggiornare quantità, rimuovere articoli o aggiungerne di nuovi). Il fornitore riceve gli item originali e li ripropone in sessione.

Esempio di PunchOutSetupRequest

Di seguito un estratto semplificato del documento XML inviato dall’acquirente per aprire la sessione:

<cXML timestamp="2026-01-15T10:30:00+01:00" payloadID="2026.01.15.001@buyer.com">
  <Header>
    <From>
      <Credential domain="DUNS">
        <Identity>123456789</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>987654321</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>buyer-system</Identity>
        <SharedSecret>s3cr3t-t0k3n</SharedSecret>
      </Credential>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>req-78432-session-a1b2c3</BuyerCookie>
      <BrowserFormPost>
        <URL>https://procurement.buyer.com/punchout/return</URL>
      </BrowserFormPost>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Il campo <BuyerCookie> contiene un token opaco generato dal sistema dell’acquirente. Al termine della sessione di shopping, il fornitore restituisce lo stesso valore all’interno del PunchOutOrderMessage. In questo modo l’acquirente ricollega il carrello ricevuto alla richiesta di acquisto interna da cui era partita la sessione.

Campi minimi richiesti

Per un flusso PunchOut standard, i campi da considerare essenziali sono:

Campi come utente finale, lingua, valuta, address o segmentazioni commerciali sono spesso opzionali a livello protocollo, ma possono essere obbligatori nel progetto reale.

Esempio minimo valido di risposta

Una PunchOutSetupResponse di successo contiene almeno l’URL di atterraggio da aprire nel browser utente:

<cXML payloadID="resp-2026-01-15-01@supplier.com" timestamp="2026-01-15T10:30:01+01:00">
  <Response>
    <Status code="200" text="OK">PunchOut session created</Status>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>https://supplier.example.com/punchout/session/abc123</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

In pratica, quel link deve già riflettere il contesto corretto: buyer riconosciuto, listino applicato, lingua e utente instradato sul catalogo autorizzato.

Sequenza visiva del flusso

Buyer Platform          Browser / Utente          F-Merchant               Buyer Procurement
     |                        |                       |                              |
     | -- PunchOutSetupRequest --------------------> |                              |
     | <--------------- PunchOutSetupResponse ------ |                              |
     |                        | -- apre StartPage -->|                              |
     |                        | <- shopping session ->|                              |
     |                        |                       | -- PunchOutOrderMessage ---> |
     |                        |                       |                              |

Lettura pratica del diagramma:

1. la piattaforma buyer apre la sessione con PunchOutSetupRequest;
2. F-Merchant restituisce l’URL valido della sessione;
3. l’utente naviga e compone il carrello nello store;
4. F-Merchant restituisce il carrello alla piattaforma buyer con PunchOutOrderMessage.

Il flusso completo

Il protocollo cXML definisce dei messaggi per la gestione del singolo shopping trip:

1. L’Acquirente inoltra la PunchOutSetupRequest (Contiene credenziali, utente e URL di destinazione del carrello).
2. Il fornitore verifica il documento e risponde in sincrono con una PunchOutSetupResponse indicando lo “StartPageURL” validato su cui l’utente atterrerà.
3. L’acquirente riempie il carrello sul sito B2B del fornitore.
4. L’Acquirente inoltra il proprio carrello completo al Procurement generato da Fornitore. Questa trasmissione prende il nome di PunchOutOrderMessage (POM). Oltre agli item acquistati, il messaggio trasporta i prezzi uniti a tasse o spese di spedizioni stimate.

<PunchOutOrderMessage>
  <BuyerCookie>req-78432-session-a1b2c3</BuyerCookie>
  <PunchOutOrderMessageHeader operationAllowed="create">
    <Total>
      <Money currency="EUR">150.00</Money>
    </Total>
  </PunchOutOrderMessageHeader>
  <ItemIn quantity="2">
    <ItemID>
      <SupplierPartID>BETA124</SupplierPartID>
    </ItemID>
    <ItemDetail>
      <UnitPrice>
        <Money currency="EUR">75.00</Money>
      </UnitPrice>
      <Description xml:lang="it">Toner compatibile nero per stampante laser</Description>
      <UnitOfMeasure>EA</UnitOfMeasure>
      <Classification domain="UNSPSC">44103105</Classification>
    </ItemDetail>
  </ItemIn>
</PunchOutOrderMessage>

[!NOTE] Un PunchOutOrderMessage NON È un ordine di acquisto. È letteralmente un preventivo firmato o un “carrello esploso”, che verrà trasformato nel prossimo step, dalle procedure interne dell’acquirente in formale autorizzazione di spesa (Purchase Requisition).

Note di implementazione F-Merchant

In un progetto F-Merchant, la parte più delicata non è aprire la sessione, ma aprirla con il contesto corretto. Di norma bisogna mappare:

• identità buyer o network verso account, listino o catalogo dedicato;
• utente e centro di costo, se il buyer li trasmette;
• valuta e regole fiscali per il buyer specifico;
• disponibilità e assortment coerenti con il contratto attivo;
• SupplierPartID restituiti nel carrello verso codici noti a ERP o middleware.

La regola pratica è semplice: se il buyer entra con un’identità valida ma vede catalogo, prezzo o tassazione sbagliati, il PunchOut è tecnicamente attivo ma funzionalmente fallito.

Mapping minimo consigliato

Errori comuni e cause tipiche

Test minimi consigliati

Prima del go-live, almeno questi scenari dovrebbero passare:

1. apertura sessione create con buyer valido;
2. ritorno carrello con uno o più item e BuyerCookie coerente;
3. verifica di listino, valuta e catalogo corretti per buyer;
4. scenario negativo con credenziali errate;
5. scenario negativo con URL di ritorno non raggiungibile;
6. verifica che gli stessi codici articolo siano poi accettati nell’OrderRequest.