Tilpasset integration

For at komme i gang, bedes du kontakte vores salgsteam for at oprette en konto og underskrive en aftale. Når en aftale er underskrevet, vil du modtage to mikroindskud på din konto, som skal verificeres.

Send venligst disse mikroindskudsbeløb til accounting@zonos.com med dit Dashboard butik ID (CC din salgsrepræsentant).

Når det er verificeret, vil dine bankoplysninger blive vist i Dashboard -> Indstillinger -> Fakturering.

Efter oprettelsen af din Zonos konto, skal du konfigurere indstillinger i Dashboard for at sikre, at Checkout fungerer korrekt med din butik. Denne sektion dækker alle de essentielle Dashboard-konfigurationer.

Opsæt udbetalinger

Forbind en bankkonto for at modtage rettidige udbetalinger fra Checkout. Udbetalinger behandles dagligt med en forsinkelse på 2 dage fra den indfangede betaling. For at gøre dette, følg venligst disse trin:

1. Naviger til Dashboard -> Indstillinger -> Checkout indstillinger .
2. Klik på Tilføj bankkonto
3. Du vil blive ført til en Stripe-portal for at fuldføre opsætningen og give følgende oplysninger:
   • Bankkontooplysninger.
   • Virksomhedens EIN.
   • Social Security Number for en 25% ejer af virksomheden. For flere detaljer om, hvorfor dette er nødvendigt, se Stripes dokumentation.

Bemærk: Hvis du har brug for at opdatere din udbetalingsplan, bedes du kontakte support@zonos.com

Opsæt tilladte domæner

Den Zonos JS-script kræver en liste over tilladte domæner af sikkerhedsmæssige årsager. Dette forhindrer uautoriserede sites i at indlæse scriptet og sikrer, at det kun kører på dine godkendte domæner. Uden denne konfiguration vil scriptet returnere tilladelsesfejl.

For at opsætte dette:

1. Naviger til Dashboard -> Indstillinger -> Checkout indstillinger
2. Under URLs, tilføj dit fulde domæne og eventuelle underdomæner, hvor Checkout vil blive brugt. For eksempel, hvis dit domæne er example.com, bør du tilføje example.com og test.example.com.

Tilpas brandingindstillinger

Konfigurer dine brandingindstillinger i Dashboard for at matche din butiks udseende og følelse.

For at gøre dette, følg venligst disse trin:

1. Naviger til Dashboard -> Indstillinger -> Checkout indstillinger -> Branding
2. Konfigurer følgende indstillinger:
   • Logo.
   • Brand- og accentfarve.
   • Tema, stil og skrifttype.

For mere information om brandingindstillinger, se vores dokumentation.

Forbind en fragtudbyder

For at citere fragt ved checkout, skal du forbinde en fragtudbyder til din Zonos konto. Dette vil give dig mulighed for at aktivere specifikke fragtserviceniveauer ved checkout.

For at forbinde en fragtudbyder, følg venligst disse trin:

1. Naviger til Dashboard -> Indstillinger -> Fragt -> Takster
2. Klik på Tilføj udbyder
3. Følg instruktionerne til opsætning af udbyderen.

For flere detaljer om at forbinde udbyderkonti, se vores dokumentation.

Opsæt fragtzoner

Fragtzoner giver dig mulighed for at konfigurere, hvilke fragtudbydere og serviceniveauer der er tilgængelige for forskellige regioner i verden.

For at opsætte fragtzoner, følg venligst disse trin:

1. Naviger til Dashboard -> Indstillinger -> Fragt -> Lokationer
2. Klik på Ny zone
3. Indtast et zonenavn og vælg de lande, du ønsker at sende til.
4. Vælg den udbyder og serviceniveau, du ønsker at tilbyde.

For flere detaljer om fragtzoner, se vores dokumentation.

Opsæt en fallback oprindelsesland og HS-kode

Oprindelseslandet og HS-koden bruges til at beregne nøjagtige told og skatter.

Hvis du ikke angiver et specifikt oprindelsesland eller HS-kode, vil vi bruge de fallback-indstillinger, der er opsat i Dashboard.

For at indstille dit fallback oprindelsesland og HS-kode:

1. Naviger til Dashboard -> Indstillinger -> Fragt -> Katalog.
2. For oprindelseslandet, vælg det land, hvor størstedelen af dine produkter er fremstillet.
3. For HS-koden, indtast HS-koden for dit mest almindelige produkt. Hvis du ikke har en HS-kode, naviger til Classify i Dashboard og indtast navnet og beskrivelsen af dit produkt for at generere en nøjagtig HS-kode.

Zonos JS-snippet er en klient-side JavaScript-integration, der muliggør global checkout funktionalitet på dit site. Det fungerer som broen mellem din e-handelsplatform og Zonos tjenester, der håndterer:

• Checkout Oplevelse: Gengiver checkout UI og behandler betalinger.
• Placeringstjenester: Registrerer besøgendes placering og håndterer valutakonvertering.
• Kurv Integration: Forbinder med dit eksisterende kurv- og bestillingssystem.
• Sikkerhed: Validerer domæner og autentificerer API-anmodninger.

Snippetet indlæses asynkront for at forhindre enhver indvirkning på dit sites ydeevne. Det initialiseres med din butiks API-legitimationsoplysninger og håndterer alle klient-side interaktioner sikkert. Implementeringen er designet til at være ikke-intrusiv og kræver minimale ændringer i din eksisterende checkout flow.

Nedenfor er et komplet eksempel, der inkluderer scriptindlæsning, initialisering og begivenhedshåndtering til reference, 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>

Bemærk: Erstat pladsholderværdierne (storeId, zonosApiKey, selectors osv.) med dine faktiske værdier fra dit Zonos Dashboard.

Håndtering af browsercache

Vi anbefaler at tilføje et tidsstempel eller en anden unik identifikator til URL'en for at sikre, at scriptet ikke bliver cachet af browseren. Dette vil sikre, at den nyeste version af scriptet altid indlæses. Dette vises i linje 10 i det komplette eksempel.

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

Authenticate the Zonos JS snippet

Når du har indlæst Zonos JS-scriptet, skal du autentificere det ved at sende en offentlig Zonos API-nøgle og butik-ID ind i Zonos.init funktionen. Den offentlige API-nøgle, der bruges til at autentificere Checkout, er designet til at være offentlig, hvilket betyder, at den sikkert kan bruges i frontend-kode uden at afsløre følsomme oplysninger.

For at finde dit butik-ID og API-nøgle, naviger til Dashboard -> Indstillinger -> Integrationer. Sørg for, at du ikke bruger en Secret API-nøgle, da den ikke er designet til at blive brugt i frontend-kode. Dette vises i linje 29 og 30 i det komplette eksempel.

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 påkrævet, når du bruger Checkout.

Hello er ansvarlig for at registrere besøgendes placering, sprog og valuta og vise de relevante oplysninger til dem. Du kan konfigurere alle Hello indstillinger i Dashboard eller i Zonos JS-scriptet. Hvis du allerede har konfigureret Hello i Dashboard, vil scriptet indlæse disse indstillinger og bruge dem. Hvis du angiver nogen værdier i helloSettings-egenskaben i Zonos.init funktionen, vil scriptet bruge disse værdier i stedet som vist nedenfor.

Konfigurer valutakonvertering i Hello i JS Script

Hello bruger CSS-selektorer til at identificere elementer på dit site, der viser valutaoplysninger. Send disse selektorer til helloSettings.currencyElementSelector-egenskaben i Zonos.init funktionen, så Hello kan registrere og vise den korrekte valuta for den internationale shopper.

Du kan bruge enhver gyldig CSS-selektor her, for eksempel #price, .price for at vælge flere forskellige elementer. Dette vises i linje 23 og 24 i det komplette eksempel.

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

Automatisk åbning af Hello ved indlæsning af siden

Som standard vil Hello kun åbne, når besøgende klikker på flagknappen. Hvis du ønsker at åbne Hello automatisk, når siden indlæses, kan du kalde funktionen Zonos.openHelloDialog() efter at Zonos scriptet er indlæst. Dette vises i linje 25 og 26 i det komplette eksempel.

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

Checkout er ansvarlig for at lade kunden indtaste deres forsendelses- og faktureringsoplysninger, beregne landed cost, collect betaling og fuldføre ordren.

Checkout vil dele kontekstuelle data med Hello, såsom besøgendes placering, sprog og valuta. Dette sikrer, at kundens oplevelse er konsistent gennem hele shoppingprocessen.

Du kan konfigurere alle Checkout indstillinger i både Dashboard og Zonos JS-scriptet. Hvis du allerede har konfigureret Checkout i Dashboard, vil scriptet indlæse disse indstillinger og bruge dem. Hvis du angiver nogen værdier i checkoutSettings egenskaben af Zonos.init funktionen, vil scriptet bruge disse værdier i stedet.

Konfigurer 'læg ordre' knappen i JS Script

Zonos JS-scriptet vil automatisk genkende internationale shoppere og lede dem til Checkout flowet. Du skal dog konfigurere 'læg ordre' knappen på din platform til at åbne Checkout når den klikkes. Dette kan gøres ved at videregive en CSS-selektor til checkoutSettings.placeOrderButtonSelector egenskaben af Zonos.init funktionen.

Hvis du har flere knapper, der kan bruges til at lægge en ordre, skal du sørge for at videregive en selektor for hver knap. For eksempel, #placeOrder, .place-order.

Dette vises i linje 21 af det komplette eksempel.

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

Sikkert opret cart-detaljer på serversiden

For at vise cart-detaljerne til kunden skal du oprette en serverside-funktion, der vil kalde Zonos API'et for at oprette en cart, og derefter sende den cart-ID tilbage til din frontend. Dette vil sikre, at cart-detaljerne ikke bliver eksponeret for kunden på en måde, der kan manipuleres.

Dit backend API-opkald vil bruge en hemmelig GraphQL legitimations-token, som er forskellig fra den offentlige token, du bruger til at autentificere Zonos JS-scriptet. Denne token kan hentes i Dashboard -> Indstillinger -> Integrationer. Den hemmelige token skal sendes som en header i dit API-opkald.

Mutation cartCreate accepterer en liste over varer, som skal formateres i henhold til cart item schema.

// 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 at oprette et API-endpoint på din server-side og derefter kalde dette endpoint fra din frontend JS-integration, som er detaljeret i næste trin.

Send kurv-ID til Checkout via frontend

Når du har oprettet en kurv på din server-side, skal du sende kurv-ID'et til Zonos JS-scriptet. Dette kan gøres ved at bruge createCartId callback'en, som er en del af Zonos.init funktionen. Checkout vil derefter sikkert hente kurvdetaljerne fra Zonos når den åbnes, hvilket forhindrer enhver manipulation af kurven. Se kodeeksemplet nedenfor.

Værdien af createCartId kan ikke være en statisk værdi, det skal være en funktion.

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 at synkronisere ordrer mellem dit system og Zonos Dashboard, implementer disse API-opkald og webhooks:

Nødvendige mutationer

Nødvendige webhooks

Før du går live med din Checkout integration, er det vigtigt at teste alle aspekter af integrationen grundigt for at sikre en glat kundeoplevelse. Dette inkluderer test af checkout flow, betalingsbehandling, ordreoprettelse og webhook-funktionalitet.

Følg vores testguide for at verificere, at din integration fungerer korrekt, og for at identificere og løse eventuelle problemer, før du lancerer til produktion.

Nedenfor er nogle almindelige spørgsmål om integrationsprocessen.

Hvordan håndterer Zonos ordrebekræftelse?

Zonos tilbyder en indbygget takkeside, som du kan bruge til ordrebekræftelser. Denne side vil altid blive vist, selvom en ordre ikke lykkes med at importere til dit system, hvilket sikrer, at kunder altid modtager bekræftelse på deres køb.

Kan jeg blive underrettet, når en ordre oprettes?

Ja. Hvis du ønsker at modtage underretninger, når en ordre oprettes, kan du i Dashboard under Email sektionen af Checkout indstillinger indtaste e-mailadressen på de teammedlemmer, der skal underrettes, når en ordre oprettes, sendes eller annulleres.