Tilpasset integrasjon

For å komme i gang, vennligst kontakt vårt salgsteam for å opprette en konto og signere en avtale. Når en avtale er signert, vil du motta to mikroinnskudd på kontoen din som må verifiseres.

Vennligst send disse mikroinnskuddsbeløpene til accounting@zonos.com med din Dashboard-butikk-ID (CC din salgsrepresentant).

Når det er verifisert, vil bankdetaljene dine vises i Dashboard -> Innstillinger -> Fakturering.

Etter å ha opprettet din Zonos konto, må du konfigurere innstillinger i Dashboard for å sikre at Checkout fungerer som det skal med butikken din. Denne seksjonen dekker alle essensielle Dashboard-konfigurasjoner.

Sett opp utbetalinger

Koble en bankkonto for å motta tidsriktige utbetalinger fra Checkout. Utbetalinger behandles daglig med en 2-dagers forsinkelse fra den registrerte betalingen. For å gjøre dette, vennligst følg disse trinnene:

1. Naviger til Dashboard -> Innstillinger -> Checkout innstillinger .
2. Klikk Legg til bankkonto
3. Du vil bli tatt til en Stripe-portalen for å fullføre oppsettet og gi følgende informasjon:
   • Bankkontoinformasjon.
   • Selskapets EIN.
   • Personnummer til en 25% eier av selskapet. For mer informasjon om hvorfor dette er nødvendig, se Stripes dokumentasjon.

Merk: Hvis du trenger å oppdatere utbetalingsplanen din, vennligst kontakt support@zonos.com

Sett opp tillatte domener

Den Zonos JS-skriptet krever en liste over tillatte domener av sikkerhetsgrunner. Dette forhindrer uautoriserte nettsteder fra å laste inn skriptet og sikrer at det kun kjører på dine godkjente domener. Uten denne konfigurasjonen vil skriptet returnere tillatelsesfeil.

For å sette dette opp:

1. Naviger til Dashboard -> Innstillinger -> Checkout innstillinger
2. Under URL-er, legg til ditt fulle domene og eventuelle underdomener der Checkout vil bli brukt. For eksempel, hvis domenet ditt er example.com, bør du legge til example.com og test.example.com.

Tilpass merkevareinnstillinger

Konfigurer merkevareinnstillingene dine i Dashboard for å matche utseendet og følelsen til butikken din.

For å gjøre dette, vennligst følg disse trinnene:

1. Naviger til Dashboard -> Innstillinger -> Checkout innstillinger -> Merkevare
2. Konfigurer følgende innstillinger:
   • Logo.
   • Merke- og aksentfarge.
   • Tema, stil og skrifttype.

For mer informasjon om merkevareinnstillinger, se vår dokumentasjon.

Koble til en fraktleverandør

For å gi fraktpriser ved checkout, må du koble til en fraktleverandør til din Zonos konto. Dette vil tillate deg å aktivere spesifikke frakttjenestenivåer ved checkout.

For å koble til en fraktleverandør, vennligst følg disse trinnene:

1. Naviger til Dashboard -> Innstillinger -> Frakt -> Priser
2. Klikk Legg til leverandør
3. Følg instruksjonene for oppsett av leverandøren.

For mer informasjon om å koble til leverandørkontoer, se vår dokumentasjon.

Sett opp fraktsoner

Fraktsoner lar deg konfigurere hvilke fraktleverandører og tjenestenivåer som er tilgjengelige for forskjellige regioner i verden.

For å sette opp fraktsoner, vennligst følg disse trinnene:

1. Naviger til Dashboard -> Innstillinger -> Frakt -> Steder
2. Klikk Ny sone
3. Skriv inn et sonenavn og velg landene du ønsker å sende til.
4. Velg leverandøren og tjenestenivået du ønsker å tilby.

For mer informasjon om fraktsoner, se vår dokumentasjon.

Sett opp et fallback-land for opprinnelse og HS-kode

Opprinnelseslandet og HS-koden brukes til å beregne nøyaktige avgifter og skatter.

Hvis du ikke oppgir et spesifikt opprinnelsesland eller HS-kode, vil vi bruke fallbackene som er satt opp i Dashboard.

For å sette ditt fallback-land for opprinnelse og HS-kode:

1. Naviger til Dashboard -> Innstillinger -> Frakt -> Katalog.
2. For opprinnelseslandet, velg landet der flertallet av produktene dine er produsert.
3. For HS-koden, skriv inn HS-koden for ditt mest vanlige produkt. Hvis du ikke har en HS-kode, naviger til Classify i Dashboard og skriv inn navnet og beskrivelsen av produktet ditt for å generere en nøyaktig HS-kode.

Zonos JS-snippet er en klient-side JavaScript-integrasjon som muliggjør global checkout funksjonalitet på nettstedet ditt. Det fungerer som broen mellom din e-handelsplattform og Zonos-tjenester, og håndterer:

• Checkout Opplevelse: Viser checkout UI og behandler betalinger.
• Stedstjenester: Oppdager besøkendes plassering og håndterer valutakonvertering.
• Handlekurvintegrasjon: Koble til din eksisterende handlekurv og bestillingssystem.
• Sikkerhet: Validerer domener og autentiserer API-forespørsel.

Snippets lastes inn asynkront for å forhindre noen innvirkning på nettstedets ytelse. Det initialiseres med butikkens API-legitimasjon og håndterer alle klient-side interaksjoner sikkert. Implementeringen er designet for å være ikke-invasiv, og krever minimale endringer i din eksisterende checkout flyt.

Nedenfor er et komplett eksempel som inkluderer skriptlasting, initialisering og hendelseshåndtering for referanse når du integrerer 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>

Merk: Erstatt plassholderverdiene (storeId, zonosApiKey, selectors, osv.) med dine faktiske verdier fra din Zonos Dashboard.

Håndtering av nettleserbuffer

Vi anbefaler å legge til et tidsstempel eller en annen unik identifikator til URL-en for å sikre at skriptet ikke blir bufret av nettleseren. Dette vil sikre at den nyeste versjonen av skriptet alltid lastes. Dette vises i linje 10 av det komplette eksemplet.

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

Autentiser Zonos JS-snippetet

Når du har lastet inn Zonos JS-skriptet, må du autentisere det ved å sende en offentlig Zonos API-nøkkel og butikk-ID inn i Zonos.init funksjonen. Den offentlige API-nøkkelen som brukes til å autentisere Checkout er designet for å være publiserbar, noe som betyr at den trygt kan brukes i frontend-kode uten å eksponere sensitiv informasjon.

For å finne butikk-ID-en og API-nøkkelen din, naviger til Dashboard -> Innstillinger -> Integrasjoner. Sørg for at du ikke bruker en Hemmelig API-nøkkel, da den ikke er designet for å brukes i frontend-kode. Dette vises i linje 29 og 30 av det komplette eksempelet.

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 er nødvendig når du bruker Checkout.

Hello er ansvarlig for å oppdage besøkendes plassering, språk og valuta, og vise den passende informasjonen til dem. Du kan konfigurere alle Hello innstillinger i Dashboard eller i Zonos JS-skriptet. Hvis du allerede har konfigurert Hello i Dashboard, vil skriptet laste disse innstillingene og bruke dem. Hvis du spesifiserer noen verdier i helloSettings-egenskapen til Zonos.init-funksjonen, vil skriptet bruke disse verdiene i stedet som vist nedenfor.

Konfigurer valutakonvertering i Hello i JS-skript

Hello bruker CSS-selektorer for å identifisere elementer på nettstedet ditt som viser valutainformasjon. Send disse selektorene til helloSettings.currencyElementSelector-egenskapen til Zonos.init-funksjonen slik at Hello kan oppdage og vise riktig valuta for den internasjonale kunden.

Du kan bruke hvilken som helst gyldig CSS-selektor her, for eksempel #price, .price for å velge flere forskjellige elementer. Dette vises i linje 23 og 24 av det komplette eksemplet.

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

Automatisk åpning av Hello ved sideinnlasting

Som standard vil Hello kun åpne når besøkende klikker på flaggknappen. Hvis du ønsker å automatisk åpne Hello når siden lastes, kan du kalle Zonos.openHelloDialog()-funksjonen når Zonos-skriptet har lastet. Dette vises i linje 25 og 26 av det komplette eksemplet.

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

Checkout er ansvarlig for å la kunden angi sin frakt- og faktureringsinformasjon, beregne landed cost, collect betaling, og fullføre bestillingen.

Checkout vil dele kontekstuell data med Hello, som for eksempel besøkendes plassering, språk og valuta. Dette sikrer at kundens opplevelse er konsistent gjennom hele handleprosessen.

Du kan konfigurere alle Checkout innstillinger både i Dashboard og i Zonos JS-skriptet. Hvis du allerede har konfigurert Checkout i Dashboard, vil skriptet laste disse innstillingene og bruke dem. Hvis du spesifiserer noen verdier i checkoutSettings-egenskapen til Zonos.init-funksjonen, vil skriptet bruke disse verdiene i stedet.

Konfigurer 'legg inn bestilling'-knappen i JS-skript

Zonos JS-skriptet vil automatisk gjenkjenne internasjonale kunder og lede dem til Checkout-flyten. Du må imidlertid konfigurere 'legg inn bestilling'-knappen på plattformen din for å åpne Checkout når den klikkes. Dette kan gjøres ved å sende en CSS-velger til checkoutSettings.placeOrderButtonSelector-egenskapen til Zonos.init-funksjonen.

Hvis du har flere knapper som kan brukes til å legge inn en bestilling, må du sørge for å sende inn en velger for hver knapp. For eksempel, #placeOrder, .place-order.

Dette vises i linje 21 av det komplette eksemplet.

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

Sikkert oppretting av handlekurvdetaljer på serversiden

For å vise handlekurvdetaljene til kunden, må du opprette en funksjon på serversiden som vil kalle Zonos API-et for å opprette en handlekurv, og deretter sende tilbake den handlekurv-ID-en til frontend. Dette vil sikre at handlekurvdetaljene ikke blir eksponert for kunden på en måte som kan manipuleres.

API-anropet ditt på backend vil bruke en hemmelig GraphQL-legitimasjonstoken, som er forskjellig fra den offentlige tokenen som du bruker for å autentisere Zonos JS-skriptet. Denne tokenen kan hentes i Dashboard -> Innstillinger -> Integrasjoner. Den hemmelige tokenen må sendes som en header i API-anropet ditt.

cartCreate mutasjonen aksepterer en liste over varer, som bør formateres i henhold til handlekurvvare-skjemaet.

// 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
}

Vi foreslår å opprette et API-endepunkt på server-siden din og deretter kalle dette endepunktet fra frontend JS-integrasjonen din, som er detaljert i neste steg.

Send handlekurv-ID til Checkout via frontend

Når du har opprettet en handlekurv på server-siden din, må du sende handlekurv-ID-en til Zonos JS-skriptet. Dette kan gjøres ved å bruke createCartId tilbakeringingsfunksjonen som er en del av Zonos.init-funksjonen. Checkout vil deretter sikkert hente handlekurvdetaljene fra Zonos når den åpnes, noe som forhindrer enhver manipulering med handlekurven. Se kodeeksempelet nedenfor.

Verdien av createCartId kan ikke være en statisk verdi, den må være en funksjon.

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
    },
  },
});

For å synkronisere ordre mellom systemet ditt og Zonos Dashboard, implementer disse API-kallene og webhookene:

Nødvendige mutasjoner

Nødvendige webhooker

Før du går live med din Checkout integrasjon, er det viktig å grundig teste alle aspekter av integrasjonen for å sikre en smidig kundeopplevelse. Dette inkluderer testing av checkout flyten, betalingsbehandling, ordreopprettelse og webhook-funksjonalitet.

Følg vår testguide for å verifisere at integrasjonen din fungerer korrekt og for å identifisere og fikse eventuelle problemer før lansering til produksjon.

Nedenfor er noen vanlige spørsmål om integrasjonsprosessen.

Hvordan håndterer Zonos ordrebekreftelse?

Zonos tilbyr en innebygd takk-siden som du kan bruke for ordrebekreftelser. Denne siden vil alltid bli vist, selv om en ordre ikke klarer å importeres til systemet ditt, og sikrer at kundene alltid mottar bekreftelse på kjøpet sitt.

Kan jeg bli varslet når en ordre opprettes?

Ja. Hvis du ønsker å motta varsler når en ordre opprettes, kan du i Dashboard under E-post-seksjonen av Checkout innstillinger angi e-postadressen til teammedlemmene som skal varsles når en ordre opprettes, sendes eller kanselleres.