Documentazione di PunchOut Rocket

Specifiche Integrazione Ecommerce Personalizzata

Questo documento descrive cosa deve fornire l’implementazione ecommerce personalizzata per poter essere configurata nei campi admin:

“Custom Clone Endpoint”
“Custom Categories Endpoint”

Inoltre descrive:

Comportamento Autologin / SSO
Form auto-post (reinvio del carrello al middleware)

Contiene i verbi HTTP richiesti, i parametri, i significati dei parametri e i valori possibili, le risposte attese (successo ed errore) ed esempi concreti.

1) Custom Clone Endpoint (scopo)
Utilizzato dal middleware per:

Creare un nuovo ordine/sessione sul negozio remoto (flusso “create”), oppure
Modificare/popolare un ordine/carrello esistente (flusso EDIT) L’endpoint deve restituire:
Un URL SSO che effettua il login dell’acquirente con un token monouso nel sito remoto, dove l’utente può essere reindirizzato al carrello se si tratta del flusso EDIT e il carrello è popolato, può essere reindirizzato al prodotto selezionato (nel caso venga comunicato durante il flusso “create”), altrimenti viene reindirizzato alla homepage

Percorso URL consigliato (esempio):

POST https://your-store.example.com/api/punchout/clone

Verbo HTTP

POST (obbligatorio). Usa il body JSON (application/json). Il middleware chiamerà POST.

Body della richiesta (JSON)
Campi base (sempre presenti)

- username (string) — username nell’ecommerce dell’utente da clonare per generare un nuovo utente associato alla sessione punchout.
- api_key (string) — chiave API che deve corrispondere a quella impostata in Punchout Rocket per l’ecommerce corrente
- end_customer_id (integer) – identificatore del cliente finale nel middleware Punchout Rocket per l’ecommerce per la richiesta punchout corrente
- session_token (string) — Buyer Cookie univoco in caso di CXML o UUID univoco o simile in caso di OCI
- operation (string) — “create” o “edit” o “inspect” in caso di CXML, “create” in caso di OCI. In caso di “edit” o “inspect” potrebbe essere passata una lista di articoli del carrello
- gateway_base_url (string) — URL del Middleware dove il carrello dovrà essere successivamente inviato

Aggiunte specifiche del protocollo

Se il protocollo risolto è CXML, possono essere aggiunti questi campi aggiuntivi:

selected_item (object) — identificazione del prodotto a cui l’utente dovrebbe essere reindirizzato opzionale in caso di operazione “create”:

supplier_part_id (string) — identificatore dello SKU (codice prodotto) nell’ecommerce (se presente)
supplier_part_auxiliary_id (string) — identificatore dell’ID prodotto nell’ecommerce (se presente)

Esempio: json

{  
  "selected_item":  
  {  
  "supplier_part_id": "ABC-001",  
  "supplier_part_auxiliary_id": "19852"  
  }  
}

cart_items (array) — la lista degli articoli del carrello da aggiungere nuovamente al carrello della sessione corrente Ogni elemento in cart_items contiene tipicamente:

sku (string) — identificatore dello SKU (codice prodotto) nell’ecommerce (se presente)
product_id (string) — identificatore dell’ID prodotto nell’ecommerce (se presente)
quantity (integer) – quantità dell’articolo nel carrello
price (numero decimale con punto come separatore decimale) – prezzo unitario dell’articolo nel carrello. Tieni presente che verrà aggiornato al prezzo corrente quando l’utente verrà reindirizzato al carrello
description (string) – descrizione del prodotto
currency (string) — codice valuta ISO 4217

Esempio payload (create, CXML, selected item presente)

{
  "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"
  }
}

Esempio payload (edit, CXML, carrello popolato)

{
  "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/e di successo
Opzione A — Fornire un URL SSO diretto (JSON) – HTTP 200 – Content-Type: application/json – Body:

{
  "status":"ok",
  "sso_url":"https://your-store.example.com/sso?token=eyJ…"
}

Comportamento: Il middleware reindirizzerà l’acquirente a sso_url (GET) e lo invierà alla piattaforma di procurement in caso di CXML o direttamente in caso di OCI. Il negozio remoto deve consumare il token, effettuare il login dell’utente, quindi:

Se l’azione è “edit” o “inspect”: il sito remoto dovrebbe leggere le informazioni del carrello e popolare il carrello in modo che l’utente arrivi nel negozio nella pagina del carrello con gli articoli già nel carrello con le quantità corrispondenti.

Se l’azione è “create”: il sito remoto dovrebbe reindirizzare all’articolo selezionato se passato e trovato, altrimenti semplicemente arrivare sulla vetrina

Risposte di errore
HTTP 400 — Richiesta non valida (campi obbligatori mancanti) json

{  
  "status":"error",  
  "error_code":"invalid_request",  
  "message":"Missing field: action"  
}

HTTP 422 — Impossibile costruire SSO (es. identità acquirente mancante) json

{  
  "status":"error",  
  "error_code":"sso_unavailable",  
  "message":"Cannot generate SSO token for this user"  
}

HTTP 500 — Errore interno json

{  
  "status":"error",  
  "error_code":"internal_error"  
}

2) Comportamento Autologin / SSO (come effettuare il login dell’acquirente e popolare il carrello)
Quando si risponde con sso_url, il negozio dovrebbe:

Consumare il token (in modo che non possa essere utilizzato due volte) ed effettuare il login dell’acquirente con l’utente clonato.
Dopo il login:
- Se l’azione è “edit”:
  - Popolare il carrello dell’utente con i prodotti esatti e le quantità fornite come articoli del carrello.
  - Reindirizzare l’utente alla pagina carrello/checkout dove può modificare prima del checkout.
- Se l’azione è “create”:
  - Opzionalmente reindirizzare al prodotto specificato come selected item. Se il middleware non ha fornito alcun selected item o se non viene più trovato nell’ecommerce, portare l’utente alla home del negozio.

Sicurezza:

Usa solo HTTPS.

I token devono essere monouso.

3) Form auto-post (reinvio del carrello al middleware)
Quando il negozio deve inviare il carrello/conferma carrello al middleware (dopo il login SSO aggiungendo prodotti al carrello o modificando) quando l’utente clicca sul pulsante (normalmente nel carrello) che dovrebbe avviare il checkout del carrello e invece in caso di utenti clonati di sessioni punchout dovrebbe inviare un form POST (content-type: application/x-www-form-urlencoded) all’URL del middleware comunicato nella richiesta all’endpoint di clonazione nel percorso relativo “/start-sso-checkout”. L’UX preferita: il negozio serve una pagina HTML che mostra un loader che auto-invia un form nascosto all’endpoint del middleware (questo rende l’SSO trasparente).

Campi del form attesi dal middleware:

session_token (string) — token di sessione ricevuto dall’ecommerce durante la richiesta di clone
end_customer_id (integer) — identificazione del cliente finale ricevuta dall’ecommerce durante la richiesta di clone
Per ogni articolo del carrello dovremmo avere un form data a indice zero ad esempio con chiave products[0][product_id] per l’ID prodotto del primo articolo nel carrello. Per ogni articolo nel carrello la lista dei campi è
- sku (string) — identificatore dello SKU (codice prodotto) nell’ecommerce (se presente)
- product_id (string) — identificatore dell’ID prodotto nell’ecommerce (se presente)
- description (string) — descrizione del prodotto
- quantity (integer) — quantità del prodotto nel carrello
- price (numero decimale con punto come separatore decimale) — Prezzo unitario
- currency (string) — codice valuta ISO 4217
- manufacturer_name (string) – produttore del prodotto
- category_ids (string) — lista, separata da virgola, di ID interi di categoria nell’ecommerce delle categorie a cui il prodotto appartiene direttamente (foglia nella struttura ad albero delle categorie normalmente)

Esempio di form HTML auto-post (il negozio lo restituisce al browser dell’utente e lo auto-invia al middleware):

Comportamento:

Il browser invia automaticamente a middleware_callback.

Il middleware riceve il carrello e continua il suo flusso di lavoro aggiungendo codici di categoria (es. UNSPSC) calcolati abbinando le categorie dell’ecommerce con i codici di categoria rimappati.

4) Custom Categories Endpoint (scopo)
Utilizzato dal middleware/admin per recuperare le categorie dal negozio remoto per consentire la mappatura con codici di categoria standard (es. UNSPSC).

Percorso URL consigliato (esempio):

POST https://your-store.example.com/api/punchout/categories

Verbo HTTP

POST (obbligatorio). Parametri query opzionali consentiti (vedi sotto).

Parametri query

api_key (string) — chiave API che deve corrispondere a quella impostata in Punchout Rocket per l’ecommerce corrente

Risposta di successo
HTTP 200
Content-Type: application/json
Body:

{
  "status":"ok",
  "categories":[
  {"id":1345,"name":"Office Supplies","parent_id":0},
  {"id":1847,"name":"Pens","parent_id":1345},
     {"id":2345,"name":"Electronics","parent_id":0}
  ]
}

Semantica:

id (integer) — identificatore univoco (normalmente ID intero della categoria nella tabella delle categorie nell’ecommerce) della categoria, che successivamente il middleware utilizzerà durante l’invio del carrello al sistema di procurement con categorie rimappate (es. codice UNSPSC).

name (string) — nome visualizzato

parent_id (integer) — identificatore univoco (normalmente ID intero della categoria nella tabella delle categorie nell’ecommerce) della categoria padre della categoria corrente. Normalmente “0” se non ha un genitore

Risposte di errore:

HTTP 400 — query non valida

HTTP 500 — errore interno

Esempio richiesta: GET /api/punchout/categories?api_key=site-api-key-abc

Esempio risposta:

{
  "status":"ok",
  "categories":[
  {"id":1345,"name":"Office Supplies","parent_id":0},
  {"id":1847,"name":"Pens","parent_id":1345},
     {"id":2345,"name":"Electronics","parent_id":0}
  ]
}

5) Note e suggerimenti per l’implementazione

Usa sempre HTTPS.

Usa token SSO monouso.

Quando invii le righe del carrello, mantieni l’ordine degli indici (sku[], product_id[], quantity[], unit_price[], extended_price[], categories[]). Il middleware abbinerà gli articoli per indice.

Specifiche Integrazione Ecommerce Personalizzata

Contatti

Azienda