Integrazione personalizzata

Per iniziare, ti preghiamo di contattare il nostro team di vendita per creare un account e firmare un accordo. Una volta firmato l'accordo, riceverai due micro depositi nel tuo account che devono essere verificati.

Ti preghiamo di inviare questi importi di micro deposito a accounting@zonos.com con il tuo ID negozio Dashboard (CC il tuo rappresentante di vendita).

Una volta verificati, i tuoi dettagli bancari verranno visualizzati in Dashboard -> Impostazioni -> Fatturazione.

Dopo aver creato il tuo account Zonos, dovrai configurare le impostazioni nel Dashboard per garantire che Checkout funzioni correttamente con il tuo negozio. Questa sezione copre tutte le configurazioni essenziali del Dashboard.

Configura i pagamenti

Collega un conto bancario per ricevere pagamenti tempestivi da Checkout. I pagamenti vengono elaborati quotidianamente con un ritardo di 2 giorni dal pagamento catturato. Per fare ciò, segui questi passaggi:

1. Naviga su Dashboard -> Impostazioni -> impostazioni Checkout.
2. Clicca su Aggiungi conto bancario
3. Verrai reindirizzato a un portale Stripe per completare la configurazione e fornire le seguenti informazioni:
   • Informazioni sul conto bancario.
   • EIN dell'azienda.
   • Numero di previdenza sociale di un proprietario dell'azienda al 25%. Per ulteriori dettagli su perché questo è richiesto, consulta la documentazione di Stripe.

Nota: Se hai bisogno di aggiornare il tuo programma di pagamento, ti preghiamo di contattare support@zonos.com

Configura i domini consentiti

Lo script JS di Zonos 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 tuoi domini approvati. Senza questa configurazione, lo script restituirà errori di autorizzazione.

Per configurarlo:

1. Naviga su Dashboard -> Impostazioni -> impostazioni Checkout
2. Sotto URL, aggiungi il tuo dominio completo e eventuali 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 marchio

Configura le impostazioni del tuo marchio nel Dashboard per adattarle all'aspetto e alla sensazione del tuo negozio.

Per fare ciò, segui questi passaggi:

1. Naviga su Dashboard -> Impostazioni -> impostazioni Checkout -> Branding
2. Configura le seguenti impostazioni:
   • Logo.
   • Colore del marchio e colore di accento.
   • Tema, Stile e Font.

Per ulteriori informazioni sulle impostazioni del marchio, consulta la nostra documentazione.

Collega un corriere di spedizione

Per quotare la spedizione in checkout, dovrai collegare un corriere di spedizione al tuo account Zonos. Questo ti permetterà di abilitare specifici livelli di servizio di spedizione in checkout.

Per collegare un corriere di spedizione, segui questi passaggi:

1. Naviga su Dashboard -> Impostazioni -> Spedizione -> Tariffe
2. Clicca su Aggiungi corriere
3. Segui le istruzioni per la configurazione del corriere.

Per ulteriori dettagli su come collegare gli account dei corrieri, consulta la nostra documentazione.

Configura le zone di spedizione

Le zone di spedizione ti consentono di configurare quali corrieri di spedizione e livelli di servizio sono disponibili per diverse regioni del mondo.

Per configurare le zone di spedizione, segui questi passaggi:

1. Naviga su Dashboard -> Impostazioni -> Spedizione -> Località
2. Clicca su Nuova zona
3. Inserisci un nome per la zona e seleziona i paesi a cui desideri spedire.
4. Seleziona il corriere e il livello di servizio che desideri offrire.

Per ulteriori dettagli sulle zone di spedizione, consulta la nostra documentazione.

Configura un paese di origine di riserva e codice HS

Il paese di origine e il codice HS vengono utilizzati per calcolare dazi e tasse accurati.

Se non fornisci un paese di origine specifico o un codice HS, utilizzeremo i fallback impostati nel Dashboard.

Per impostare il tuo Paese di Origine di riserva e codice HS:

1. Naviga su Dashboard -> Impostazioni -> Spedizione -> Catalogo.
2. Per il paese di origine, seleziona il paese in cui viene fabbricata la maggior parte dei tuoi prodotti.
3. Per il codice HS, inserisci il codice HS del tuo prodotto più comune. Se non hai un codice HS, naviga su Classify nel Dashboard e inserisci il nome e la descrizione del tuo prodotto per generare un codice HS accurato.

Il frammento JS di Zonos è un'integrazione JavaScript lato client che abilita la funzionalità globale di checkout sul tuo sito. Funziona come ponte tra la tua piattaforma ecommerce e i servizi di Zonos, gestendo:

• Esperienza Checkout: Rende l'interfaccia utente di checkout e gestisce i pagamenti.
• Servizi di localizzazione: Rileva la posizione dei visitatori e gestisce la conversione della valuta.
• Integrazione del carrello: Si collega al tuo carrello e sistema ordini esistenti.
• Sicurezza: Valida i domini e autentica le richieste API.

Il frammento viene caricato in modo asincrono per prevenire qualsiasi impatto sulle prestazioni del tuo sito. Si inizializza con le credenziali API del tuo negozio e gestisce tutte le interazioni lato client in modo sicuro. L'implementazione è progettata per essere non intrusiva, richiedendo modifiche minime al tuo flusso di checkout esistente.

Di seguito è riportato un esempio completo che include il caricamento dello script, l'inizializzazione e la gestione degli eventi da utilizzare come riferimento durante l'integrazione di Checkout.

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

      script.addEventListener('load', () => {
        window.Zonos.init({
          checkoutSettings: {
            createCartId: async () => {
              // Replace with your server-side cart creation logic
              return {
                cartId: 'cart_73e707c0-c161-4c37-9581-4da1b1115777',
              };
            },
            placeOrderButtonSelector: '#placeOrder, .place-order', // Replace with your actual selector(s)
          },
          helloSettings: {
            currencyElementSelector: '.price',
            onInitSuccess: () => {
              Zonos.openHelloDialog();
            },
          },
          storeId: 7744, // Replace with your actual store ID
          zonosApiKey: 'credential_live_7a128f4e-f192-4232-8992-94dd09eb4437', // Replace with your actual API key
        });
      });

      document.head.appendChild(script);
    }
  })();
</script>

Nota: Sostituisci i valori segnaposto (storeId, zonosApiKey, selectors, ecc.) con i tuoi valori reali dal tuo Zonos Dashboard.

Gestione della cache del browser

Ti consigliamo di aggiungere un timestamp o un altro identificatore unico all'URL per garantire che lo script non venga memorizzato nella cache dal browser. Questo garantirà che l'ultima versione dello script venga sempre caricata. Questo è mostrato nella riga 10 dell'esempio completo.

      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

Autenticare il Zonos JS snippet

Una volta caricato lo script JS di Zonos, è necessario autenticare passando una chiave API pubblica di Zonos e l'ID del negozio nella funzione Zonos.init. La chiave API pubblica utilizzata per autenticare Checkout è progettata per essere pubblicabile, il che significa che può essere utilizzata in modo sicuro nel codice frontend senza esporre informazioni sensibili.

Per trovare il tuo ID negozio e la chiave API, naviga su Dashboard -> Impostazioni -> Integrazioni. Assicurati di non utilizzare una chiave API segreta, poiché non è progettata per essere utilizzata nel codice frontend. Questo è mostrato nelle righe 29 e 30 dell'esempio completo.

Zonos.init({
  // ... other fields
  zonosApiKey: 'Your API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'Your STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Hello è necessario quando si utilizza Checkout.

Hello è responsabile della rilevazione della posizione, della lingua e della valuta del visitatore, e della visualizzazione delle informazioni appropriate per loro. Puoi configurare tutte le impostazioni di Hello nel Dashboard o nello script JS di Zonos. Se hai già configurato Hello nel Dashboard, lo script caricherà quelle impostazioni e le utilizzerà. Se specifichi dei valori nella proprietà helloSettings della funzione Zonos.init, lo script utilizzerà quei valori invece, come mostrato di seguito.

Configura la conversione di valuta in Hello nello script JS

Hello utilizza i selettori CSS per identificare gli elementi sul tuo sito che visualizzano informazioni sulla valuta. Passa questi selettori alla proprietà helloSettings.currencyElementSelector della funzione Zonos.init in modo che Hello possa rilevare e visualizzare la valuta corretta dello shopper internazionale.

Puoi utilizzare qualsiasi selettore CSS valido qui, ad esempio #price, .price per selezionare più elementi diversi. Questo è mostrato nelle righe 23 e 24 dell'esempio completo.

Zonos.init({
  // ... other fields
  helloSettings: {
    currencyElementSelector: '.price', // Replace with your actual selector
  },
  // ... other fields
});

Aprire automaticamente Hello al caricamento della pagina

Per impostazione predefinita, Hello si aprirà solo quando il visitatore fa clic sul pulsante della bandiera. Se desideri aprire automaticamente Hello quando la pagina si carica, puoi chiamare la funzione Zonos.openHelloDialog() una volta che lo script Zonos è stato caricato. Questo è mostrato nelle righe 25 e 26 dell'esempio completo.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Checkout è responsabile per consentire al cliente di inserire le proprie informazioni di spedizione e fatturazione, calcolare landed cost, collect pagamento e completare l'ordine.

Checkout condividerà dati contestuali con Hello, come la posizione del visitatore, la lingua e la valuta. Questo assicura che l'esperienza del cliente sia coerente durante l'intero processo di acquisto.

Puoi configurare tutte le impostazioni di Checkout sia nel Dashboard che nello script JS di Zonos. Se hai già configurato Checkout nel Dashboard, lo script caricherà quelle impostazioni e le utilizzerà. Se specifichi dei valori nella proprietà checkoutSettings della funzione Zonos.init, lo script utilizzerà quei valori invece.

Configura il pulsante 'effettua ordine' nello script JS

Lo script JS di Zonos riconoscerà automaticamente gli acquirenti internazionali e li dirigerà al flusso di Checkout. Tuttavia, dovrai configurare il pulsante 'effettua ordine' sulla tua piattaforma per aprire Checkout quando viene cliccato. Questo può essere fatto passando un selettore CSS alla proprietà checkoutSettings.placeOrderButtonSelector della funzione Zonos.init.

Se hai più pulsanti che possono essere utilizzati per effettuare un ordine, assicurati di passare un selettore per ciascun pulsante. Ad esempio, #placeOrder, .place-order.

Questo è mostrato nella riga 21 dell'esempio completo.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

Crea in modo sicuro i dettagli del carrello sul lato server

Per visualizzare i dettagli del carrello al cliente, è necessario creare una funzione sul lato server che chiamerà l'API Zonos per creare un carrello e poi restituire quell'ID del carrello al tuo frontend. Questo garantirà che i dettagli del carrello non siano esposti al cliente in un modo che possa essere manipolato.

La tua chiamata API backend utilizzerà un token di credenziale GraphQL segreto, che è diverso dal token pubblico che utilizzi per autenticare lo script JS di Zonos. Questo token può essere recuperato in Dashboard -> Impostazioni -> Integrazioni. Il token segreto deve essere passato come intestazione nella tua chiamata API.

La mutazione cartCreate accetta un elenco di articoli, che devono essere formattati secondo lo schema dell'articolo del carrello.

// Create new cart from serverside
async function createCart() {
  /**
   * Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
   * */
  const graphql = JSON.stringify({
    query: `
mutation cartCreate($input: CartCreateInput!){
  cartCreate(input: $input) {
    id
    adjustments {
      amount
      currencyCode
      description
      productId
      sku
      type
    }
    items {
      id
      name
      amount
      currencyCode
      quantity
      sku
      description
      metadata {
        key
        value
      }
    }
    metadata {
      key
      value
    }
  }
}`,
    variables: {
      /**
       * input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
       */
      input: {
        /**
         * Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
         */
        adjustments: [
          {
            amount: -10,
            currencyCode: 'USD',
            /**
             * Enum value: https://zonos.com/developer/types/CartAdjustmentType
             */
            type: 'CART_TOTAL',
          },
        ],
        /**
         * Cart item input: https://zonos.com/developer/types/ItemInput
         */
        items: [
          {
            name: 'Item 1',
            amount: 150.99,
            currencyCode: 'USD',
            description: 'Item 1 description',
            quantity: 2,
          },
        ],
        /**
         * Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
         */
        metadata: [
          {
            key: 'key1',
            value: 'value1',
          },
        ],
      },
    },
  });

  const response = await fetch('https://api.zonos.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      credentialToken: 'credential_live_xxxxxxxxx', // Replace with your actual SECRET credential token (found in Dashboard)
    },
    body: graphql,
  });

  const { data } = await response.json();
  return data.cartCreate.id; // Return the cart ID to your frontend
}

Suggeriamo di creare un endpoint API sul lato server e poi chiamare quell'endpoint dalla tua integrazione JS frontend, che è dettagliata nel passaggio successivo.

Passa l'ID del carrello a Checkout tramite frontend

Una volta che hai creato un carrello sul lato server, devi passare l'ID del carrello allo script JS di Zonos. Questo può essere fatto utilizzando il callback createCartId che fa parte della funzione Zonos.init. Checkout recupererà quindi in modo sicuro i dettagli del carrello da Zonos quando aperto, prevenendo qualsiasi manomissione del carrello. Vedi l'esempio di codice qui sotto.

Il valore di createCartId non può essere un valore statico, deve essere una funzione.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch('https://api.merchant.com/api/get-cart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});

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

Mutazioni richieste

Webhook richiesti

Prima di andare live con la tua integrazione di Checkout, è importante testare a fondo tutti gli aspetti dell'integrazione per garantire un'esperienza cliente fluida. Questo include il test del flusso di checkout, l'elaborazione dei pagamenti, la creazione degli ordini e la funzionalità dei webhook.

Segui la nostra guida ai test per verificare che la tua integrazione funzioni correttamente e per identificare e risolvere eventuali problemi prima del lancio in produzione.

Di seguito sono riportate alcune domande comuni sul processo di integrazione.

Come gestisce Zonos la conferma degli ordini?

Zonos fornisce una pagina di ringraziamento integrata che puoi utilizzare per le conferme degli ordini. Questa pagina verrà sempre mostrata, anche se un ordine non riesce a essere importato nel tuo sistema, garantendo che i clienti ricevano sempre conferma del loro acquisto.

Posso essere avvisato quando viene creato un ordine?

Sì. Se desideri ricevere notifiche quando viene creato un ordine, nel Dashboard sotto la sezione Email delle impostazioni di Checkout, puoi inserire l'indirizzo email dei membri del team che dovrebbero essere avvisati quando un ordine viene creato, spedito o annullato.