Specifiche di integrazione PunchOut per e-commerce personalizzati

1. Configurazione in PunchOut Rocket

Sito e-commerce

I percorsi degli endpoint vengono aggiunti a Site URL così come sono, quindi devono iniziare con /. Esempio: Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Ordini d’acquisto (sezione 6) e carrelli predefiniti sono inclusi nel piano Premium, compreso nella prova gratuita: il piano li abilita sul sito e la pagina dell’end customer mostra le sezioni Orders e Predefined Carts. Conferme d’ordine e avvisi di spedizione (sezioni 7–8) richiedono anche l’opzione OC & ASN.

End customer / cliente finale

Ogni azienda cliente è un end customer del tuo sito. Oltre alle credenziali del protocollo (identità cXML e shared secret oppure utente e password OCI), questi campi riguardano il tuo negozio:

Il resto delle pagine del sito e dell’end customer funziona come per le altre piattaforme: consulta la documentazione.

2. Endpoint di clonazione

Percorso predefinito: /api/punchout/clone. Chiamato quando un cliente apre il negozio dal sistema di acquisto. Il negozio crea (o riutilizza) un utente clonato da username, associato a questa sessione PunchOut, e restituisce un URL SSO che lo autentica (sezione 3).

Corpo della richiesta

quantity e price sono stringhe: convertile prima dell’uso.

Richiesta: creazione con un articolo selezionato

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-012345",
  "operation": "create",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "selected_item": {
    "supplier_part_id": "X-100",
    "supplier_part_auxiliary_id": "19853"
  }
}

Richiesta: edit, con il carrello da ripristinare

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-67890",
  "operation": "edit",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "cart_items": [
    {"sku": "ABC-001", "product_id": "19852", "quantity": "2", "price": "15.95",
     "description": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Risposta di esito positivo

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url è l’unico campo letto: è obbligatorio e deve essere un URL assoluto http:// o https://. PunchOut Rocket indirizza lì il browser del cliente (tramite il sistema di acquisto per cXML, direttamente per OCI).

Risposte di errore

Qualsiasi stato non 2xx o risposta senza un sso_url valido causa il fallimento del PunchOut: il cliente riceve un errore nel sistema di acquisto. La tua risposta (stato e corpo) viene salvata nel registro della sessione PunchOut, quindi spiega il motivo nel messaggio.

4. Trasferimento del carrello (modulo con invio automatico)

Per un utente PunchOut, il pulsante di checkout non deve avviare il normale processo d’ordine: invia invece il carrello a PunchOut Rocket. Il negozio restituisce una pagina HTML che invia automaticamente un modulo nascosto, preferibilmente con un indicatore di caricamento.

• URL: {gateway_base_url}/start-sso-checkout (gateway_base_url dalla richiesta di clonazione)
• Metodo: POST, application/x-www-form-urlencoded (normale invio di un modulo del browser)
• Nessuna api_key: la sessione è identificata da session_token e end_customer_id.

i parte da 0 e non ha interruzioni: PunchOut Rocket smette di leggere al primo indice mancante. Ricorda di applicare l’escape HTML ai valori.

Esempio di pagina restituita al checkout

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket invia quindi il carrello al sistema di acquisto e termina la sessione. Ogni sessione accetta un solo carrello:

7. Endpoint dello stato degli ordini

Percorso predefinito: /api/punchout/order-status. Chiamato solo per gli end customer con “Send order status updates” attivo, per gli ordini creati tramite la sezione 6: ogni ora per 60 giorni dall’ordine e subito dopo una notifica (sezione 8). Richiede l’opzione OC & ASN. Dalla risposta, PunchOut Rocket invia al sistema di acquisto del cliente:

• una conferma d’ordine (cXML ConfirmationRequest), una sola volta, quando l’ordine viene accettato o annullato;
• un avviso di spedizione (cXML ShipNoticeRequest) per ogni nuova spedizione di un ordine confermato.

PunchOut Rocket ricorda cosa ha inviato: rispondi sempre con lo stato attuale dell’ordine e PunchOut Rocket individua le novità.

Richiesta: order_id è quello restituito dall’endpoint di creazione degli ordini

{"api_key": "site-api-key-abc", "order_id": "100045"}

Risposta di esito positivo

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

La conferma viene inviata una sola volta, la prima volta che l’ordine è processing, shipped o delivered:

• accetta l’intero ordine quando ogni riga del PO è presente per intero;
• altrimenti accetta ogni riga per la quantità presente nell’ordine e rifiuta il resto (articoli rimossi, quantità ridotte). Una quantità superiore al PO viene confermata per la quantità del PO;
• se non resta alcuna riga, non viene inviato nulla: usa cancelled per rifiutare l’ordine.

Le modifiche successive agli articoli non vengono confermate di nuovo: modifica l’ordine prima di accettarlo.

Comunica una spedizione solo dopo la partenza. Le modifiche a una spedizione già notificata non vengono inviate di nuovo. Se il sistema di acquisto rifiuta una conferma o un avviso di spedizione, PunchOut Rocket lo reinvia al controllo successivo e non invia nulla di successivo finché non viene accettato.

9. Controlli prima della messa online

1. Configura il sito (sezione 1) e inserisci la stessa chiave API nel tuo negozio.
2. Crea un end customer e imposta il suo “E-commerce User to Clone”.
3. Fai clic su “Update from e-commerce” nel suo Category Mapping e associa le categorie; imposta un Default UNSPSC.
4. Prova un PunchOut con il modulo di test cXML nel pannello amministrativo: create, poi edit con un carrello, quindi restituisci il carrello.
5. Per gli ordini d’acquisto (piano Premium): invia un OrderRequest di test e verifica l’ordine nel negozio.
6. Per gli aggiornamenti di stato (opzione OC & ASN): attiva “Send order status updates” sull’end customer, fai passare l’ordine di test attraverso i tuoi stati e verifica che il sistema del cliente riceva la conferma e gli avvisi di spedizione.

Ricorda:

• Gli utenti PunchOut non devono completare un checkout nel tuo negozio: il carrello torna al sistema di acquisto (sezione 4) e l’ordine arriva in seguito tramite la sezione 6.
• Gli ordini ricevuti tramite la sezione 6 sono già approvati dal sistema di acquisto del cliente: non richiedono un pagamento online.

Ti serve un cliente di test o una revisione dell’implementazione? Parla con i nostri sviluppatori, oppure affida lo sviluppo a noi con Go-Live Assist.