cXML e OCI: come funzionano i due protocolli PunchOut

cXML e OCI a confronto

PunchOut cXML: come funziona una sessione

In cXML ogni passaggio è un documento XML inviato tramite HTTPS. Il sistema del cliente e il tuo sistema si identificano reciprocamente tramite credenziali nell’header (per SAP Ariba, Network ID) e uno shared secret.

1. Richiesta di configurazione

   Il cliente seleziona il tuo catalogo; il suo sistema invia un PunchOutSetupRequest con credenziali, BuyerCookie e URL di ritorno.

2. Risposta di configurazione

   Il tuo sistema risponde con un URL StartPage; il browser del cliente apre il tuo e-commerce.

3. Acquisto

   Il cliente vede i prezzi contrattuali e riempie il carrello.

4. Ritorno del carrello

   Un PunchOutOrderMessage invia il carrello all’URL di ritorno per l’approvazione.

5. Ordine

   Dopo l’approvazione, l’ordine d’acquisto arriva come OrderRequest.

Esempio · PunchOutSetupRequest (abbreviato)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.069/cXML.dtd">
<cXML payloadID="1729332000.4711@buyer.example.com" timestamp="2026-10-19T10:00:00+02:00">
  <Header>
    <From><Credential domain="NetworkID"><Identity>AN01000000001</Identity></Credential></From>
    <To><Credential domain="NetworkID"><Identity>AN01000000002</Identity></Credential></To>
    <Sender>
      <Credential domain="NetworkID">
        <Identity>AN01000000001</Identity>
        <SharedSecret>••••••••</SharedSecret>
      </Credential>
      <UserAgent>Buyer procurement system</UserAgent>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>8f2c41d0a9</BuyerCookie>
      <BrowserFormPost><URL>https://buyer.example.com/punchout/return</URL></BrowserFormPost>
      <SupplierSetup><URL>https://gateway.example.com/setup</URL></SupplierSetup>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Esempio · PunchOutSetupResponse

<cXML payloadID="1729332001.88@gateway.example.com" timestamp="2026-10-19T10:00:01+02:00">
  <Response>
    <Status code="200" text="OK"/>
    <PunchOutSetupResponse>
      <StartPage><URL>https://gateway.example.com/session/7f3a…</URL></StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

Esempio · PunchOutOrderMessage

<cXML payloadID="1729332555.12@gateway.example.com" timestamp="2026-10-19T10:09:15+02:00">
  <Header>…</Header>
  <Message>
    <PunchOutOrderMessage>
      <BuyerCookie>8f2c41d0a9</BuyerCookie>
      <PunchOutOrderMessageHeader operationAllowed="edit">
        <Total><Money currency="EUR">96.00</Money></Total>
      </PunchOutOrderMessageHeader>
      <ItemIn quantity="20">
        <ItemID><SupplierPartID>GLV-09</SupplierPartID></ItemID>
        <ItemDetail>
          <UnitPrice><Money currency="EUR">4.80</Money></UnitPrice>
          <Description xml:lang="en">Safety gloves, size 9</Description>
          <UnitOfMeasure>PR</UnitOfMeasure>
          <Classification domain="UNSPSC">46181504</Classification>
        </ItemDetail>
      </ItemIn>
    </PunchOutOrderMessage>
  </Message>
</cXML>

PunchOut OCI: come funziona una sessione

OCI è più semplice e ha un’impostazione meno recente: non usa XML. SAP apre l’URL del tuo catalogo con i parametri di accesso e un HOOK_URL; al termine il tuo e-commerce invia il carrello a quell’indirizzo come campi di un modulo HTML.

1. Chiamata

   SAP apre l’URL del tuo catalogo con i parametri di accesso e l’HOOK_URL.

2. Acquisto

   Il cliente acquista con i propri prezzi contrattuali.

3. Ritorno del carrello

   Il tuo e-commerce invia il carrello come campi NEW_ITEM-* all’HOOK_URL.

4. Ordine

   OCI non trasporta l’ordine d’acquisto: ti arriva tramite un canale concordato con il cliente, per esempio email o il suo portale fornitori.

Esempio · Chiamata OCI con HOOK_URL

https://shop.example.com/oci?USERNAME=acme&PASSWORD=••••
  &HOOK_URL=https%3A%2F%2Fsap.buyer.example.com%2Fsap%2Fbc%2Fsrm%2Foci_return
  &OCI_VERSION=4.0&returntarget=_top

Esempio · Ritorno del carrello OCI all’HOOK_URL

<form method="post" action="{HOOK_URL}">
  <input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Safety gloves, size 9">
  <input type="hidden" name="NEW_ITEM-QUANTITY[1]"    value="20">
  <input type="hidden" name="NEW_ITEM-UNIT[1]"        value="PR">
  <input type="hidden" name="NEW_ITEM-PRICE[1]"       value="4.80">
  <input type="hidden" name="NEW_ITEM-CURRENCY[1]"    value="EUR">
  <input type="hidden" name="NEW_ITEM-MATGROUP[1]"    value="46181504">
  <input type="hidden" name="NEW_ITEM-VENDORMAT[1]"   value="GLV-09">
</form>

I nomi dei campi sono indicizzati per riga ([1], [2]…). La documentazione del cliente indica quali campi sono obbligatori, ad esempio il codice articolo del fornitore, un tempo di consegna o un testo esteso.

Quale usa il tuo cliente?

In caso di dubbi, la documentazione fornitore del cliente lo indica nelle prime pagine. Alcuni clienti SAP usano SAP Ariba per la spesa indiretta e cataloghi OCI in S/4HANA per i materiali diretti: potrebbero servirLe entrambi.

Integrazione del catalogo PunchOut cXML: cosa cambia nel tuo e-commerce

Qualunque sia il protocollo, un e-commerce necessita degli stessi cinque elementi per funzionare come catalogo PunchOut:

• Catalogo e prezzi specifici per ogni cliente
• Un codice di classificazione su ogni prodotto (UNSPSC o ECLASS)
• Apertura nel frame del cliente: header dei frame, cookie e impostazioni di sicurezza
• Unità di misura associate ai codici del cliente
• Importazione degli ordini con cXML OrderRequest (piano Premium)

Supportare entrambi su un unico e-commerce

Molti fornitori si trovano ad avere clienti su entrambi i protocolli. Sviluppare due integrazioni raddoppia il lavoro; un gateway che li supporta entrambi consente a un solo e-commerce di servire tutti i clienti. Con PunchOut Rocket configuri ogni cliente una sola volta nella dashboard, scegli cXML o OCI e il plugin sul tuo e-commerce resta lo stesso.