Documentazione PunchOut Rocket

1. Introduzione

Questa guida ti accompagna nella configurazione di PunchOut Rocket, dall’account alla prima sessione PunchOut, per collegare il tuo e-commerce ai sistemi di eProcurement dei clienti.

PunchOut Rocket è un gateway SaaS che collega il tuo e-commerce WooCommerce, Magento 2, PrestaShop, nopCommerce o personalizzato a sistemi di acquisto come SAP Ariba, Coupa e Jaggaer, tramite cXML o OCI. Il cliente avvia un PunchOut dal proprio sistema di acquisto, acquista nel tuo e-commerce con i prezzi contrattuali e restituisce il carrello per creare una richiesta d’acquisto.

La guida copre cinque aree:

1. Gestione dell’account: registrazione, dashboard, profilo e dati di fatturazione, autenticazione a due fattori e recupero password.
2. Configurazione del sito e-commerce: il tuo e-commerce, piano e abbonamento, impostazioni di connessione e funzionalità del piano.
3. Configurazione degli end customer: un end customer per ogni azienda cliente, con i relativi carrelli predefiniti e l’importazione ordini.
4. Configurazione del plugin sulla tua piattaforma e-commerce.
5. Test e monitoraggio: sessioni di test, registri di comunicazione e registri degli ordini.

Le ultime sezioni spiegano frame, cookie e reverse proxy e come risolvere i problemi più comuni. Per i protocolli, leggi cXML e OCI; trovi ogni termine nel glossario.

2. Gestione dell’account

2.1 Registrazione e primo accesso

1. Vai su platform.punchoutrocket.com e fai clic su Register.
2. Inserisci il nome, i dati aziendali e di fatturazione: Paese, indirizzo, città, CAP, provincia o Stato e partita IVA. Le aziende italiane inseriscono anche il codice SDI o l’indirizzo PEC.
3. Inserisci l’indirizzo email e una password sicura, poi fai clic su Create Account.
4. Effettua l’accesso: si apre la Dashboard.

La prova gratuita di 30 giorni inizia con il tuo account e non richiede carta di credito. Durante la prova sono attive tutte le funzionalità, comprese quelle Premium (carrelli predefiniti e importazione ordini).

2.2 La Dashboard

• Key metrics: il numero di siti e-commerce e di end customer configurati.
• System overview: il passaggio di configurazione successivo. Quando il sito e il primo end customer sono pronti, il pannello mostra You’re All Set!
• System info: gli ambienti, i protocolli e le piattaforme supportati.
• Quick Actions: Test OCI PunchOut e Test CXML PunchOut aprono le pagine di test (vedere la sezione 6.1).

2.3 Gestione del profilo e dei dati di fatturazione

Apri My Account › My Profile dalla barra laterale sinistra.

• User information: puoi modificare nome, cognome e password. L’indirizzo email è il nome utente e non può essere modificato.
• Company information: ragione sociale, partita IVA, indirizzo, città, CAP e provincia o Stato. Questi dati compaiono sulle fatture. Le aziende italiane devono inserire il codice SDI o l’indirizzo PEC.
• Country: il Paese determina il trattamento IVA delle fatture (l’IVA italiana si applica solo alle aziende italiane). Una volta impostato, può essere modificato solo dal nostro team di assistenza.

Fai clic su Save per applicare le modifiche. I nuovi dati di fatturazione vengono inviati anche al sistema di pagamento e si applicano dalla fattura successiva.

2.4 Autenticazione a due fattori via email (facoltativa)

L’autenticazione a due fattori è facoltativa e consigliata. Quando è attiva, ogni accesso richiede un codice monouso a 6 cifre inviato all’indirizzo email registrato.

• Accesso con 2FA: inserisci email e password, apri l’email con il codice, digitalo nella pagina Enter One-time Code e fai clic su Verify. I codici scadono dopo 5 minuti: se un codice scade, effettua nuovamente l’accesso per riceverne uno nuovo.
• Attivazione: dall’avviso di sicurezza nella Dashboard (Enable 2FA in My Profile) oppure da My Profile, seleziona Enable OTP login verification nella sezione Two-Factor Authentication e fai clic su Save. Si applica dall’accesso successivo.
• Disattivazione: in My Profile, deseleziona la stessa casella e fai clic su Save.

Prima di attivarla, verifica di poter accedere alla tua casella email. Se il codice tarda ad arrivare, controlla la cartella spam.

2.5 Password dimenticata

1. Nella pagina di accesso, fai clic su Forgot your password?
2. Inserisci l’indirizzo email del tuo account e conferma.
3. Apri l’email ricevuta e fai clic sul link di reimpostazione. Il link è valido per 4 ore.
4. Inserisci la nuova password. Riceverai anche un’email di conferma della modifica.

3. Configurazione del sito e-commerce

Aggiungi il tuo e-commerce, scegli un piano e completa le impostazioni di connessione.

3.1 Aggiunta del sito e-commerce

Nel pannello Get Started della Dashboard, fai clic su + Add Your First E-commerce Site (oppure My Account › My E-commerce Sites › Add E-commerce Site) e compila:

• Site Name: un’etichetta interna, ad esempio “E-commerce B2B della mia azienda”. Determina anche l’indirizzo del reverse proxy.
• Site URL: l’indirizzo completo del tuo e-commerce, incluso https://.
• E-commerce Platform: scegli la tua piattaforma dall’elenco, ad esempio WooCommerce.
• Le credenziali di connessione per la tua piattaforma (vedere 3.4).

Fai clic su Save.

3.2 Scelta del piano e sottoscrizione

La pagina del sito mostra i giorni di prova rimanenti e lo stato dell’abbonamento. Sono disponibili due piani: Standard e Premium, che aggiunge l’importazione degli ordini d’acquisto e i carrelli predefiniti.

1. Nella sezione Subscription Details, fai clic su Subscribe · Standard o Subscribe · Premium.
2. Inserisci i dati di pagamento nella pagina di pagamento sicura Stripe.
3. Quando il pagamento è confermato, fai clic su Back to Site Settings.

Se sottoscrivi Standard, le funzionalità Premium vengono disattivate al termine della prova: i carrelli predefiniti vengono conservati, ma non sono più proposti ai clienti. Premium li mantiene attiva.

Se abbiamo concordato un prezzo personalizzato, la pagina del sito propone invece un unico piano Custom. Piani e pacchetti clienti sono nella pagina dei prezzi.

3.3 Modifica del piano o gestione dell’abbonamento

Con un abbonamento attivo pagato con carta, la pagina del sito mostra:

• Upgrade to Premium: una finestra mostra l’importo dovuto oggi (la differenza proporzionale fino alla data di rinnovo, più IVA), la carta su cui verrà effettuato l’addebito, il prezzo dal rinnovo successivo e le funzionalità sbloccate. Fai clic su Pay and upgrade: le funzionalità sono attive immediatamente.
• Downgrade to Standard: la finestra mostra il credito per il periodo Premium non utilizzato, detratto dalla fattura successiva, e le funzionalità disattivate immediatamente. Oggi non viene addebitato nulla.
• Manage your subscription: apre il portale clienti sicuro Stripe, dove puoi vedere il piano e la prossima data di pagamento, cambiare il metodo di pagamento, aggiornare i dati di fatturazione, scaricare le fatture o annullare l’abbonamento.

3.4 Completamento delle impostazioni del sito

Alcune impostazioni dipendono dalla piattaforma; queste sono comuni a tutti i siti:

• Use Reverse Proxy: attivo per impostazione predefinita. Durante le sessioni PunchOut l’e-commerce viene servito tramite PunchOut Rocket, evitando i blocchi dei frame e dei cookie dei sistemi di acquisto senza modifiche al tuo server. Vedere la sezione 7.
• Reverse Proxy URL: di sola lettura, generato dal Site Name. È il punto di ingresso delle sessioni PunchOut; non devi impostarlo.
• DUNS number and ANID (Ariba Network ID): identificativi cXML facoltativi. Inseriscili se il cliente li richiede: vengono restituiti con il carrello.
• API credentials: memorizzate in forma crittografata. Dopo il salvataggio sono visibili solo gli ultimi 4 caratteri. Se lasci vuoto un campo password, il valore salvato viene mantenuto. Le nuove password devono contenere almeno 10 caratteri.

WordPress / WooCommerce

• API Username: l’utente WordPress usato da PunchOut Rocket per la REST API.
• API Password: la password per le applicazioni di quell’utente, creata nel profilo utente come descritto nella documentazione WordPress sulle password per le applicazioni.

Magento 2 / Adobe Commerce

• API Username: l’utente amministratore Magento usato per la REST API.
• API Password: la password di quell’utente amministratore.

nopCommerce, PrestaShop 8+ e piattaforme personalizzate

• API Key: fai clic su Generate per creare una chiave segreta univoca, copiala e incollala nelle impostazioni del plugin PunchOut Rocket (o nell’integrazione personalizzata). Dopo il salvataggio sono visibili solo gli ultimi 4 caratteri.
• Per un e-commerce personalizzato, l’integrazione è descritta nelle specifiche di integrazione.

3.5 Funzionalità del piano

La sezione Features della pagina del sito mostra le funzionalità incluse nel piano o nella prova gratuita:

• Predefined carts: puoi preparare carrelli già pronti per ogni end customer e i clienti possono inviarli al proprio sistema di acquisto con un clic (vedere 4.5).
• OrderRequest: il sito accetta gli ordini d’acquisto cXML dei clienti e crea gli ordini corrispondenti nel tuo e-commerce (vedere 4.6).

Le funzionalità dipendono dal piano e non possono essere modificate qui: le configuri per ogni end customer.

Non hai tempo per configurarlo personalmente? Go-Live Assist: il nostro team configura la connessione per te.

4. Configurazione degli end customer

Un end customer è una delle tue aziende clienti, che apre il tuo catalogo dal proprio sistema di acquisto. Ogni end customer ha le proprie impostazioni di connessione.

4.1 Creazione di un nuovo end customer

Nella pagina di modifica del sito, trova Associated End Customers e fai clic su + Add End Customer. Puoi anche usare My Account › My End Customers.

4.2 Impostazioni generali

• Name: un’etichetta per l’azienda cliente.
• Email: un’email di contatto per questo cliente (facoltativa).
• E-commerce User to Clone: l’email o il nome utente di un utente dedicato nel tuo e-commerce. Ruolo e permessi definiscono catalogo e prezzi visibili al cliente: durante il PunchOut, PunchOut Rocket apre l’e-commerce con la sessione di questo utente.
• Ecommerce Site: il sito da cui acquista questo cliente.
• Protocol: cXML o OCI, secondo i requisiti del sistema del cliente.
• Default UNSPSC: il codice di classificazione inviato per i prodotti la cui categoria non ha un codice associato.
• Default Lead Time: il tempo di consegna stimato in giorni, inviato con ogni articolo del carrello.
• EA Override and BX Override: sostituiscono le unità di misura predefinite (EA per pezzo, BX per scatola) con i codici attesi dal sistema del cliente, ad esempio PCE.

4.3 Configurazione del protocollo (cXML e OCI)

Inserisci le credenziali fornite dall’ufficio acquisti del cliente. Devono corrispondere esattamente a quelle del sistema del cliente.

• cXML: From Identity, Sender Identity, Shared Secret, campi extrinsic facoltativi e CXML URL da fornire al cliente come URL di configurazione PunchOut.
• OCI: i parametri di accesso chiave-valore, inclusi nome utente e password, eventuali campi facoltativi da restituire con il carrello e OCI URL da fornire al cliente.

Dove trovare questi valori per ciascun sistema: SAP Ariba, Coupa, Jaggaer, SAP tramite OCI.

4.4 Mappatura delle categorie

1. Fai clic su Update from e-commerce per importare l’albero delle categorie.
2. Inserisci il codice UNSPSC corrispondente per ogni categoria, dove possibile.

Con le categorie mappate il sistema del cliente riceve dati prodotto più dettagliati e può approvare e analizzare correttamente gli acquisti. Consulta categorie PunchOut e UNSPSC.

4.5 Carrelli predefiniti Premium

Un carrello predefinito è un elenco di prodotti già pronto per un end customer, ad esempio il rifornimento mensile di un ufficio. All’inizio di una sessione PunchOut il cliente può inviarlo al sistema di acquisto con un clic, senza navigare nell’e-commerce.

La sezione viene mostrata quando il piano (o la prova gratuita) include i carrelli predefiniti. Salva prima l’end customer, poi:

1. Fai clic su Add cart.
2. Inserisci il cart name e, se desideri, una description: il cliente vede entrambi.
3. Imposta facoltativamente Expires on: dopo quella data il carrello non viene più proposto. Lascia il campo vuoto per un carrello senza scadenza.
4. Aggiungi i prodotti, uno per riga: SKU, Description, Quantity, Unit price e, facoltativamente, il codice UNSPSC. Il totale viene calcolato durante la compilazione.
5. Aggiungi facoltativamente un’image del prodotto a ogni riga tramite il pulsante immagine (PNG, JPEG, GIF o WebP, fino a 5 MB).
6. Fai clic su Save sul carrello. Ogni carrello viene salvato separatamente.

Importazione delle righe da Excel

• Fai clic su Download template per ottenere un file .xlsx di esempio.
• Compilalo con le colonne SKU, Description, Quantity, Unit price e UNSPSC (SKU e Description sono obbligatorie), poi fai clic su Import from Excel: le righe vengono aggiunte al carrello.
• Viene letto solo il primo foglio, fino a 1.000 righe. Sono riconosciuti anche i nomi di colonna italiani (Codice, Descrizione, Quantità, Prezzo).

Cosa vede il cliente

Quando il cliente avvia un PunchOut (una nuova sessione, non la modifica di un carrello esistente) e ha almeno un carrello valido, prima dell’e-commerce si apre una pagina di selezione:

• il cliente può cercare i carrelli per nome, descrizione o SKU del prodotto;
• Show items elenca i prodotti con immagine, SKU, quantità e prezzo;
• Use this cart invia il carrello direttamente al sistema di acquisto, come se il cliente avesse eseguito il checkout nell’e-commerce;
• Continue to the e-commerce apre il tuo e-commerce come sempre.

Il link della pagina di selezione è valido per 8 ore dall’avvio della sessione.

4.6 Importazione ordini con cXML OrderRequest Premium

Con OrderRequest, gli ordini d’acquisto approvati nel sistema di acquisto del cliente arrivano nel tuo e-commerce come normali ordini. Non devi inserirli manualmente.

La sezione Order request Integration dell’end customer mostra:

• Order request URL: l’indirizzo da fornire al cliente per gli ordini d’acquisto. È lo stesso per ogni end customer del sito: ogni ordine viene associato all’end customer tramite la sua From identity cXML.
• Shipping Method e Payment Method: i metodi usati per gli ordini creati nel tuo e-commerce.

Per Magento e PrestaShop compila entrambi i metodi per importare gli ordini. Per un negozio personalizzato, entrambi vengono passati al tuo endpoint di creazione degli ordini: consulta le specifiche di integrazione.

Fai clic su Check Logs nella stessa sezione per vedere gli ordini ricevuti (vedere 6.3).

Non hai tempo per configurarlo personalmente? Go-Live Assist: il nostro team configura la connessione per te.

5. Configurazione del plugin sulla tua piattaforma e-commerce

1. Scarica e installa il plugin PunchOut Rocket per la tua piattaforma.
2. Apri la pagina delle impostazioni del plugin nell’amministrazione dell’e-commerce (in Magento, nelle impostazioni Sales).
3. Inserisci i dati di connessione della sezione 3.4 e salva.

Il tuo e-commerce è ora pronto a ricevere richieste PunchOut.

• WooCommerce: la connessione usa il nome utente API e la password per le applicazioni inseriti nelle impostazioni del sito (3.4). La pagina del plugin conferma quando PunchOut Rocket è configurato e pronto all’uso.
• Magento 2: le impostazioni dell’estensione si trovano in Stores › Configuration › Sales › Punchout Rocket, nel gruppo Gateway.
• nopCommerce e PrestaShop: incolla la chiave API generata nelle impostazioni del sito (3.4) nella configurazione del plugin o del modulo e salva.

Le versioni supportate sono nella pagina della compatibilità. Il tuo e-commerce deve essere servito tramite HTTPS.

Non hai tempo per configurarlo personalmente? Go-Live Assist: il nostro team configura la connessione per te.

6. Test e monitoraggio

6.1 Test di una sessione PunchOut

Prima di fornire gli URL al cliente, puoi simulare il suo sistema di acquisto:

1. Nella Dashboard, sotto Quick Actions, fai clic su Test CXML PunchOut o Test OCI PunchOut.
2. Cerca e seleziona il tuo Ecommerce Site, poi l’End Customer: le credenziali vengono compilate dalla relativa configurazione.
3. Invia la richiesta di test: l’e-commerce si apre come per il cliente e puoi aggiungere prodotti e restituire il carrello.

6.2 Registri di comunicazione

1. Apri la pagina di configurazione dell’end customer.
2. In Protocol Configuration, fai clic su Check Logs.

Il registro elenca ogni sessione PunchOut con orario, indirizzo IP e browser. Per ogni sessione puoi aprire i messaggi scambiati: richiesta di configurazione dal sistema di acquisto, risposta di configurazione, carrello dal tuo e-commerce e carrello restituito al cliente. È la prima cosa da verificare quando una connessione non funziona.

6.3 Registri degli ordini Premium

Nella sezione Order request Integration dell’end customer, fai clic su Check Logs. Per ogni ordine d’acquisto vedi l’orario, il numero d’ordine d’acquisto, l’esito, il numero dell’ordine creato nell’e-commerce, l’ordine ricevuto dal sistema di acquisto e la risposta inviata.

7. Frame, sistemi di acquisto e reverse proxy

Perché i sistemi di acquisto usano i frame

SAP Ariba, Coupa, Jaggaer e altri sistemi aprono spesso l’e-commerce del fornitore in un frame, così il cliente non esce mai dal sistema di acquisto. Questo crea due problemi nel browser:

• frame-ancestors: la Content Security Policy dell’e-commerce non consente al portale acquisti di mostrarlo in un frame, che resta quindi vuoto.
• Cookie SameSite: il browser rifiuta i cookie dell’e-commerce nel frame, così il cliente perde l’accesso o il carrello.

Come il reverse proxy risolve il problema

1. Il cliente seleziona PunchOut nel sistema di acquisto, che invia una richiesta cXML o OCI.
2. PunchOut Rocket serve le pagine del tuo e-commerce sotto il proprio dominio, così il browser vede un’unica origine attendibile.
3. I cookie sono di prima parte, quindi le regole SameSite non li bloccano.
4. Il cliente acquista come sempre e il carrello torna al sistema di acquisto tramite cXML o OCI.

Non devi modificare la configurazione del server.

Disattiva i plugin di ottimizzazione che incorporano i file

I plugin di minificazione come Autoptimize possono incorporare CSS o JavaScript come URI di dati Base64. Quando il proxy riscrive gli URL, questi file non funzionano più: il layout appare errato o gli script smettono di funzionare.

• Soluzione: prima di collegarti, disattiva la minificazione HTML, l’unione di CSS e JS e l’incorporamento delle risorse. Ad esempio: Autoptimize, le opzioni “Combine files” di WP Rocket, la minificazione HTML di LiteSpeed Cache. I plugin di cache delle pagine che non modificano gli URL delle risorse sono generalmente compatibili.
• Come verificare: cerca nel sorgente della pagina data:text/css;base64, o data:application/javascript;base64,.

Disattivazione del reverse proxy (avanzato)

Il proxy è attivo per impostazione predefinita e consigliamo di mantenerlo attivo. Se lo disattivi, il sistema del cliente apre direttamente il tuo server e devi configurare:

• un header Content-Security-Policy: frame-ancestors che autorizza il dominio del portale acquisti;
• SameSite=None; Secure sui cookie di sessione e di accesso.

Queste impostazioni variano per ciascun sistema di acquisto e devono essere aggiornate per ogni nuovo dominio del portale. Nella maggior parte dei pannelli di hosting si trovano nelle impostazioni degli header del server e dei cookie. Dettagli nella guida all’errore iframe.

8. Risoluzione dei problemi

Il problema persiste? Scrivi a support@punchoutrocket.com indicando il nome dell’end customer e l’orario della sessione riportato nel registro.