Integrazione personalizzata

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 a 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.

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:

1. Vai a Dashboard -> Settings -> Checkout settings .
2. Fai clic su Add bank account
3. Verrai reindirizzato a un portale Stripe per completare la configurazione e fornire le seguenti informazioni:
   • Informazioni sul conto bancario.
   • EIN dell'azienda.
   • Social Security Number di un titolare dell'azienda al 25%. Per maggiori dettagli sul motivo per cui è richiesto, consulta la documentazione di Stripe.

Nota: Se devi aggiornare il programma dei pagamenti in uscita, contatta support@zonos.com

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:

1. Vai a Dashboard -> Settings -> Checkout settings
2. 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.

Personalizza le impostazioni del brand 

Configura le impostazioni del brand in Dashboard per adattarle all'aspetto del tuo negozio.

Per farlo, segui questi passaggi:

1. Vai a Dashboard -> Settings -> Checkout settings -> Branding
2. Configura le seguenti impostazioni:
   • Logo.
   • Colore del brand e colore di accento.
   • Tema, stile e font.

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:

1. Vai a Dashboard -> Settings -> Shipping -> Rates
2. Fai clic su Add carrier
3. Segui le istruzioni di configurazione del corriere.

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:

1. Vai a Dashboard -> Settings -> Shipping -> Locations
2. Fai clic su New zone
3. Inserisci un nome per la zona e seleziona i Paesi verso cui desideri spedire.
4. Seleziona il corriere e il livello di servizio che desideri offrire.

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:

1. Vai a Dashboard -> Settings -> Shipping -> Catalog.
2. Per il Paese di origine, seleziona il Paese in cui viene prodotto il maggior numero dei tuoi prodotti.
3. 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.

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.

4. Passa gli ID corrispondenti tramite customHTML di 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:

• Google Analytics 4 per iframe Checkout
• Facebook Pixel per iframe Checkout

Per sincronizzare gli ordini tra il tuo sistema e Zonos Dashboard, implementa queste chiamate API e webhook:

Mutation obbligatorie 

Webhook obbligatori 

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.

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:

• 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.

Ricerca dell'ordine da zonosCheckoutSessionId 

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.

Invia la query a https://api.zonos.com/graphql con il token credenziale segreto da Dashboard -> Settings -> Integrations passato come intestazione della richiesta credentialToken.

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.