Segui questa checklist completa per configurare il tuo account Zonos Dashboard e integrare Zonos Checkout nel tuo sito o piattaforma personalizzati.
1
Crea un account Zonos
Per iniziare, contatta il nostro team commerciale per creare un account e firmare un accordo. Una volta firmato l'accordo, riceverai due microdepositi sul tuo conto che dovranno essere verificati.
Invia via email questi importi dei microdepositi ad accounting@zonos.com con l'ID negozio Dashboard (in CC al tuo rappresentante commerciale).
Una volta verificati, i dettagli bancari verranno visualizzati in Dashboard -> Settings -> Billing.
2
Configura le impostazioni di Dashboard e Checkout
Dopo aver creato il tuo account Zonos, dovrai configurare le impostazioni in Dashboard per garantire che Checkout funzioni correttamente con il tuo negozio. Questa sezione copre tutte le configurazioni essenziali di Dashboard.
Collega un conto bancario per ricevere pagamenti in uscita tempestivi da Checkout. I pagamenti in uscita vengono elaborati quotidianamente con un ritardo di 2 giorni dal pagamento acquisito. Per farlo, segui questi passaggi:
Lo script Zonos JS richiede un elenco di domini consentiti per motivi di sicurezza. Questo impedisce a siti non autorizzati di caricare lo script e garantisce che venga eseguito solo sui domini approvati. Senza questa configurazione, lo script restituirà errori di autorizzazione.
In URLs, aggiungi il tuo dominio completo e tutti i sottodomini in cui verrà utilizzato Checkout. Ad esempio, se il tuo dominio è example.com, dovresti aggiungere example.com e test.example.com.
Per quotare la spedizione al checkout, dovrai collegare un corriere di spedizione al tuo account Zonos. Questo ti consentirà di abilitare livelli di servizio di spedizione specifici al checkout.
Per collegare un corriere di spedizione, segui questi passaggi:
Il Paese di origine e il codice HS vengono utilizzati per calcolare dazi e imposte accurati.
Se non fornisci un Paese di origine o un codice HS specifico, utilizzeremo i fallback configurati in Dashboard.
Per impostare il Paese di origine e il codice HS di fallback:
Vai a Dashboard -> Settings -> Shipping -> Catalog.
Per il Paese di origine, seleziona il Paese in cui viene prodotto il maggior numero dei tuoi prodotti.
Per il codice HS, inserisci il codice HS del tuo prodotto più comune. Se non hai un codice HS, vai a Classify in Dashboard e inserisci il nome e la descrizione del tuo prodotto per generare un codice HS accurato.
3
Installa lo snippet Zonos JS
Lo snippet Zonos JS è un'integrazione JavaScript lato client che abilita la funzionalità di checkout globale sul tuo sito. Funge da ponte tra la tua piattaforma ecommerce e i servizi Zonos, gestendo:
Esperienza Checkout: Renderizza l'interfaccia utente del checkout ed elabora i pagamenti.
Servizi di localizzazione: Rileva la posizione del visitatore e gestisce la conversione valutaria.
Integrazione carrello: Si collega al tuo sistema carrello e ordini esistente.
Sicurezza: Valida i domini e autentica le richieste API.
Lo snippet viene caricato in modo asincrono per evitare qualsiasi impatto sulle prestazioni del tuo sito. Si inizializza con le credenziali API del tuo negozio e gestisce in modo sicuro tutte le interazioni lato client. L'implementazione è progettata per essere non invasiva, richiedendo modifiche minime al flusso di checkout esistente.
Di seguito è riportato un esempio completo che include caricamento dello script, inizializzazione e gestione degli eventi da consultare durante l'integrazione di Checkout.
1
Passa gli ID corrispondenti tramite customHTML di Checkout in modo che il relay sappia quale property/pixel utilizzare:
1
Per istruzioni passo passo sull'iframe, il riferimento completo degli eventi (inclusa la mappatura del payload purchase / Purchase) e suggerimenti per il debug, consulta:
Sincronizza il tuo numero account nativo con Dashboard. Docs →
orderAddTrackingNumber
Obbligatoria solo se non stampi etichette in Dashboard. Garantisce che il tracking appaia in Dashboard così Zonos può garantire i calcoli del Landed Cost. Docs →
Necessario per inviare gli ordini Checkout alla tua piattaforma nativa. Docs →
ORDER_STATUS_CHANGED
Mantiene il tuo sistema sincronizzato con Zonos quando gli stati degli ordini cambiano (ad es. evaso, annullato). Docs →
7
Testa la tua integrazione
Prima di andare live con l'integrazione Checkout, è importante testare accuratamente tutti gli aspetti dell'integrazione per garantire un'esperienza cliente fluida. Questo include il test del flusso checkout, dell'elaborazione dei pagamenti, della creazione degli ordini e della funzionalità webhook.
Segui la nostra guida ai test per verificare che l'integrazione funzioni correttamente e per identificare e correggere eventuali problemi prima del lancio in produzione.
Domande comuni
Di seguito alcune domande comuni sul processo di integrazione.
Configura l'esperienza post-acquisto in Dashboard -> Settings -> Checkout settings in Success page type. Sono disponibili tre opzioni:
Show Zonos success page (predefinito, consigliato) — Zonos visualizza una pagina di ringraziamento integrata dopo che l'ordine è stato effettuato. La pagina viene sempre mostrata, anche se l'ordine non riesce a essere importato nel tuo sistema, così l'acquirente riceve sempre una conferma.
Redirect to a success page — Zonos attende su una breve schermata «Order complete» fino alla creazione dell'ordine, quindi reindirizza all'URL di successo configurato con zOrderNumber (e orderId per i carrelli legacy) aggiunti come parametri di query.
Close the checkout modal — Zonos chiude la sua modale una volta acquisito il pagamento. Se configuri anche un URL di successo, Zonos reindirizza a tale URL immediatamente dopo che Stripe raccoglie il pagamento — senza attendere la creazione dell'ordine — e aggiunge zonosCheckoutSessionId come parametro di query. Usa questa opzione quando desideri il passaggio più rapido alla tua pagina di successo.
Quando utilizzi Close the checkout modal con un URL di reindirizzamento, l'ordine potrebbe richiedere alcuni secondi per essere associato alla sessione checkout dopo il reindirizzamento. Leggi zonosCheckoutSessionId dall'URL ed esegui il polling della query GraphQL checkoutSession dal tuo server utilizzando il token credenziale segreto fino a quando l'ordine è pronto. Non chiamare mai questa query dal browser — il token credenziale segreto deve rimanere lato server.
1query getCheckoutSession($id: String!)
2checkoutSession )
3order
4id
Invia la query a https://api.zonos.com/graphql con il token credenziale segreto da Dashboard -> Settings -> Integrations passato come intestazione della richiesta credentialToken.
Sì. Se desideri ricevere notifiche quando viene creato un ordine, in Dashboard nella sezione Email di Checkout settings, puoi inserire l'indirizzo email dei membri del team che devono essere notificati quando un ordine viene creato, spedito o annullato.
Integrazione personalizzata
Integrazione personalizzata
Crea un'integrazione Checkout end-to-end nel tuo sito personalizzato.
Checklist di integrazione
Segui questa checklist completa per configurare il tuo account Zonos Dashboard e integrare Zonos Checkout nel tuo sito o piattaforma personalizzati.
Crea un account Zonos
Per iniziare, contatta il nostro team commerciale per creare un account e firmare un accordo. Una volta firmato l'accordo, riceverai due microdepositi sul tuo conto che dovranno essere verificati.
Invia via email questi importi dei microdepositi ad accounting@zonos.com con l'ID negozio Dashboard (in CC al tuo rappresentante commerciale).
Una volta verificati, i dettagli bancari verranno visualizzati in Dashboard -> Settings -> Billing.
Configura le impostazioni di Dashboard e Checkout
Dopo aver creato il tuo account Zonos, dovrai configurare le impostazioni in Dashboard per garantire che Checkout funzioni correttamente con il tuo negozio. Questa sezione copre tutte le configurazioni essenziali di Dashboard.
Configura i pagamenti in uscita
Collega un conto bancario per ricevere pagamenti in uscita tempestivi da Checkout. I pagamenti in uscita vengono elaborati quotidianamente con un ritardo di 2 giorni dal pagamento acquisito. Per farlo, segui questi passaggi:
Configura i domini consentiti
Lo script Zonos JS richiede un elenco di domini consentiti per motivi di sicurezza. Questo impedisce a siti non autorizzati di caricare lo script e garantisce che venga eseguito solo sui domini approvati. Senza questa configurazione, lo script restituirà errori di autorizzazione.
Per configurarlo:
example.com, dovresti aggiungereexample.cometest.example.com.Personalizza le impostazioni del brand
Configura le impostazioni del brand in Dashboard per adattarle all'aspetto del tuo negozio.
Per farlo, segui questi passaggi:
Per maggiori informazioni sulle impostazioni del brand, consulta la nostra documentazione.
Collega un corriere di spedizione
Per quotare la spedizione al checkout, dovrai collegare un corriere di spedizione al tuo account Zonos. Questo ti consentirà di abilitare livelli di servizio di spedizione specifici al checkout.
Per collegare un corriere di spedizione, segui questi passaggi:
Per maggiori dettagli sulla connessione degli account corriere, consulta la nostra documentazione.
Configura le zone di spedizione
Le zone di spedizione ti consentono di configurare quali corrieri e livelli di servizio sono disponibili per diverse regioni del mondo.
Per configurare le zone di spedizione, segui questi passaggi:
Per maggiori dettagli sulle zone di spedizione, consulta la nostra documentazione.
Configura un Paese di origine e un codice HS di fallback
Il Paese di origine e il codice HS vengono utilizzati per calcolare dazi e imposte accurati.
Se non fornisci un Paese di origine o un codice HS specifico, utilizzeremo i fallback configurati in Dashboard.
Per impostare il Paese di origine e il codice HS di fallback:
Installa lo snippet Zonos JS
Lo snippet Zonos JS è un'integrazione JavaScript lato client che abilita la funzionalità di checkout globale sul tuo sito. Funge da ponte tra la tua piattaforma ecommerce e i servizi Zonos, gestendo:
Lo snippet viene caricato in modo asincrono per evitare qualsiasi impatto sulle prestazioni del tuo sito. Si inizializza con le credenziali API del tuo negozio e gestisce in modo sicuro tutte le interazioni lato client. L'implementazione è progettata per essere non invasiva, richiedendo modifiche minime al flusso di checkout esistente.
Di seguito è riportato un esempio completo che include caricamento dello script, inizializzazione e gestione degli eventi da consultare durante l'integrazione di Checkout.
customHTMLdi Checkout in modo che il relay sappia quale property/pixel utilizzare:Per istruzioni passo passo sull'iframe, il riferimento completo degli eventi (inclusa la mappatura del payload
purchase/Purchase) e suggerimenti per il debug, consulta:Sincronizza tracking e stato ordine in Dashboard
Per sincronizzare gli ordini tra il tuo sistema e Zonos Dashboard, implementa queste chiamate API e webhook:
Mutation obbligatorie
orderUpdateAccountOrderNumberorderAddTrackingNumberWebhook obbligatori
ORDER_CREATEDORDER_STATUS_CHANGEDTesta la tua integrazione
Prima di andare live con l'integrazione Checkout, è importante testare accuratamente tutti gli aspetti dell'integrazione per garantire un'esperienza cliente fluida. Questo include il test del flusso checkout, dell'elaborazione dei pagamenti, della creazione degli ordini e della funzionalità webhook.
Segui la nostra guida ai test per verificare che l'integrazione funzioni correttamente e per identificare e correggere eventuali problemi prima del lancio in produzione.
Domande comuni
Di seguito alcune domande comuni sul processo di integrazione.
Come gestisce Zonos la conferma dell'ordine?
Configura l'esperienza post-acquisto in Dashboard -> Settings -> Checkout settings in Success page type. Sono disponibili tre opzioni:
zOrderNumber(eorderIdper i carrelli legacy) aggiunti come parametri di query.zonosCheckoutSessionIdcome parametro di query. Usa questa opzione quando desideri il passaggio più rapido alla tua pagina di successo.Ricerca dell'ordine da
zonosCheckoutSessionIdQuando utilizzi Close the checkout modal con un URL di reindirizzamento, l'ordine potrebbe richiedere alcuni secondi per essere associato alla sessione checkout dopo il reindirizzamento. Leggi
zonosCheckoutSessionIddall'URL ed esegui il polling della query GraphQLcheckoutSessiondal tuo server utilizzando il token credenziale segreto fino a quando l'ordine è pronto. Non chiamare mai questa query dal browser — il token credenziale segreto deve rimanere lato server.query getCheckoutSession($id: String!)checkoutSession )orderidInvia la query a
https://api.zonos.com/graphqlcon il token credenziale segreto da Dashboard -> Settings -> Integrations passato come intestazione della richiestacredentialToken.Posso ricevere una notifica quando viene creato un ordine?
Sì. Se desideri ricevere notifiche quando viene creato un ordine, in Dashboard nella sezione Email di Checkout settings, puoi inserire l'indirizzo email dei membri del team che devono essere notificati quando un ordine viene creato, spedito o annullato.
Questa pagina è stata utile?