Aangepaste integratie

Om te beginnen, neem alstublieft contact op met ons verkoopteam om een account aan te maken en een overeenkomst te ondertekenen. Zodra een overeenkomst is ondertekend, ontvangt u twee micro-deposits op uw account die moeten worden geverifieerd.

Stuur deze micro-depositbedragen per e-mail naar accounting@zonos.com met uw Dashboard-winkel-ID (CC uw verkoopvertegenwoordiger).

Zodra geverifieerd, worden uw bankgegevens weergegeven in Dashboard -> Instellingen -> Facturering.

Nadat u uw Zonos account heeft aangemaakt, moet u instellingen in het Dashboard configureren om ervoor te zorgen dat Checkout goed werkt met uw winkel. Deze sectie behandelt alle essentiële Dashboard-configuraties.

Stel uitbetalingen in

Verbind een bankrekening om tijdige uitbetalingen van Checkout te ontvangen. Uitbetalingen worden dagelijks verwerkt met een vertraging van 2 dagen vanaf de vastgelegde betaling. Volg deze stappen:

1. Navigeer naar Dashboard -> Instellingen -> Checkout instellingen .
2. Klik op Voeg bankrekening toe
3. U wordt naar een Stripe-portaal geleid om de installatie te voltooien en de volgende informatie te verstrekken:
   • Bankrekeninginformatie.
   • Bedrijf EIN.
   • Burgerservicenummer van een 25% eigenaar van het bedrijf. Voor meer details over waarom dit vereist is, zie de documentatie van Stripe.

Opmerking: Als u uw uitbetalingsschema moet bijwerken, neem dan contact op met support@zonos.com

Stel toegestane domeinen in

Het Zonos JS-script vereist een lijst van toegestane domeinen voor beveiligingsdoeleinden. Dit voorkomt dat ongeautoriseerde sites het script laden en zorgt ervoor dat het alleen op uw goedgekeurde domeinen draait. Zonder deze configuratie retourneert het script toestemmingsfouten.

Om dit in te stellen:

1. Navigeer naar Dashboard -> Instellingen -> Checkout instellingen
2. Voeg onder URLs uw volledige domein en eventuele subdomeinen toe waar Checkout zal worden gebruikt. Bijvoorbeeld, als uw domein example.com is, moet u example.com en test.example.com toevoegen.

Pas brandinginstellingen aan

Configureer uw brandinginstellingen in het Dashboard om overeen te komen met de uitstraling van uw winkel.

Volg deze stappen:

1. Navigeer naar Dashboard -> Instellingen -> Checkout instellingen -> Branding
2. Configureer de volgende instellingen:
   • Logo.
   • Merken en accentkleur.
   • Thema, stijl en lettertype.

Voor meer informatie over brandinginstellingen, zie onze documentatie.

Verbind een verzendcarrier

Om verzendkosten bij checkout te quoten, moet u een verzendcarrier aan uw Zonos account koppelen. Dit stelt u in staat om specifieke verzendservice-niveaus bij checkout in te schakelen.

Volg deze stappen om een verzendcarrier te verbinden:

1. Navigeer naar Dashboard -> Instellingen -> Verzending -> Tarief
2. Klik op Voeg carrier toe
3. Volg de instructies voor het instellen van de carrier.

Voor meer details over het verbinden van carrier-accounts, zie onze documentatie.

Stel verzendzones in

Verzendzones stellen u in staat om te configureren welke verzendcarriers en serviceniveaus beschikbaar zijn voor verschillende regio's van de wereld.

Volg deze stappen om verzendzones in te stellen:

1. Navigeer naar Dashboard -> Instellingen -> Verzending -> Locaties
2. Klik op Nieuwe zone
3. Voer een zonenaam in en selecteer de landen waar u naartoe wilt verzenden.
4. Selecteer de carrier en het serviceniveau dat u wilt aanbieden.

Voor meer details over verzendzones, zie onze documentatie.

Stel een fallback land van oorsprong en HS-code in

Het land van oorsprong en de HS-code worden gebruikt om nauwkeurige douanerechten en belastingen te berekenen.

Als u geen specifiek land van oorsprong of HS-code opgeeft, gebruiken we de fallback-instellingen die in het Dashboard zijn ingesteld.

Om uw fallback land van oorsprong en HS-code in te stellen:

1. Navigeer naar Dashboard -> Instellingen -> Verzending -> Catalogus.
2. Voor het land van oorsprong selecteert u het land waar de meeste van uw producten zijn vervaardigd.
3. Voor de HS-code voert u de HS-code van uw meest voorkomende product in. Als u geen HS-code heeft, navigeer dan naar Classify in het Dashboard en voer de naam en beschrijving van uw product in om een nauwkeurige HS-code te genereren.

De Zonos JS-snippet is een client-side JavaScript-integratie die wereldwijde checkout functionaliteit op uw site mogelijk maakt. Het fungeert als de brug tussen uw e-commerceplatform en Zonos-diensten, en behandelt:

• Checkout Ervaring: Weergave van de checkout UI en verwerking van betalingen.
• Locatiediensten: Detecteert de locatie van de bezoeker en beheert valutaconversie.
• Winkelwagentje-integratie: Verbindt met uw bestaande winkelwagentje en ordersysteem.
• Beveiliging: Valideert domeinen en authenticatie van API-aanvragen.

De snippet wordt asynchroon geladen om enige impact op de prestaties van uw site te voorkomen. Het initialiseert met de API-gegevens van uw winkel en behandelt alle client-side interacties veilig. De implementatie is ontworpen om niet-intrusief te zijn, met minimale wijzigingen aan uw bestaande checkout flow.

Hieronder staat een compleet voorbeeld dat het laden van scripts, initialisatie en gebeurtenisafhandeling omvat om naar te verwijzen bij het integreren van 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>

Opmerking: Vervang de tijdelijke waarden (storeId, zonosApiKey, selectors, enz.) door uw werkelijke waarden van uw Zonos Dashboard.

Omgaan met browsercaching

We raden aan om een tijdstempel of een andere unieke identifier aan de URL toe te voegen om ervoor te zorgen dat het script niet door de browser wordt gecached. Dit zorgt ervoor dat de nieuwste versie van het script altijd wordt geladen. Dit wordt weergegeven in regel 10 van het complete voorbeeld.

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

Authenticate the Zonos JS snippet

Zodra je het Zonos JS-script hebt geladen, moet je het authentiseren door een openbare Zonos API-sleutel en winkel-ID door te geven aan de Zonos.init functie. De openbare API-sleutel die wordt gebruikt om Checkout te authentiseren, is ontworpen om publiceerbaar te zijn, wat betekent dat deze veilig kan worden gebruikt in frontendcode zonder gevoelige informatie bloot te stellen.

Om je winkel-ID en API-sleutel te vinden, navigeer je naar Dashboard -> Instellingen -> Integraties. Zorg ervoor dat je geen Geheime API-sleutel gebruikt, aangezien deze niet is ontworpen om in frontendcode te worden gebruikt. Dit wordt weergegeven in regels 29 en 30 van het volledige voorbeeld.

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 is vereist bij het gebruik van Checkout.

Hello is verantwoordelijk voor het detecteren van de locatie, taal en valuta van de bezoeker, en het weergeven van de juiste informatie aan hen. Je kunt alle Hello instellingen configureren in het Dashboard of in het Zonos JS-script. Als je Hello al in het Dashboard hebt geconfigureerd, zal het script die instellingen laden en gebruiken. Als je waarden opgeeft in de helloSettings eigenschap van de Zonos.init functie, zal het script die waarden in plaats daarvan gebruiken, zoals hieronder weergegeven.

Configureer valutaconversie in Hello in JS-script

Hello gebruikt CSS-selectors om elementen op je site te identificeren die valutainformatie weergeven. Geef deze selectors door aan de helloSettings.currencyElementSelector eigenschap van de Zonos.init functie, zodat Hello de juiste valuta van de internationale shopper kan detecteren en weergeven.

Je kunt hier elke geldige CSS-selector gebruiken, bijvoorbeeld #price, .price om meerdere verschillende elementen te selecteren. Dit wordt weergegeven in regels 23 en 24 van het complete voorbeeld.

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

Automatisch Hello openen bij het laden van de pagina

Standaard zal Hello alleen openen wanneer de bezoeker op de vlagknop klikt. Als u Hello automatisch wilt openen wanneer de pagina laadt, kunt u de Zonos.openHelloDialog() functie aanroepen zodra het Zonos script is geladen. Dit wordt weergegeven in regels 25 en 26 van het volledige voorbeeld.

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

Checkout is verantwoordelijk voor het toestaan van de klant om hun verzend- en factuurinformatie in te voeren, landed cost te berekenen, collect betaling te innen en de bestelling te voltooien.

Checkout zal contextuele gegevens delen met Hello, zoals de locatie, taal en valuta van de bezoeker. Dit zorgt ervoor dat de ervaring van de klant consistent is gedurende het hele winkelproces.

Je kunt alle instellingen van Checkout configureren in zowel het Dashboard als het Zonos JS-script. Als je Checkout al in het Dashboard hebt geconfigureerd, zal het script die instellingen laden en gebruiken. Als je waarden opgeeft in de checkoutSettings eigenschap van de Zonos.init functie, zal het script die waarden in plaats daarvan gebruiken.

Configureer de 'plaats bestelling' knop in JS Script

Het Zonos JS-script zal automatisch internationale shoppers herkennen en hen naar de Checkout flow leiden. Je moet echter de 'plaats bestelling' knop op jouw platform configureren om Checkout te openen wanneer erop geklikt wordt. Dit kan gedaan worden door een CSS-selector door te geven aan de checkoutSettings.placeOrderButtonSelector eigenschap van de Zonos.init functie.

Als je meerdere knoppen hebt die gebruikt kunnen worden om een bestelling te plaatsen, zorg er dan voor dat je een selector voor elke knop doorgeeft. Bijvoorbeeld, #placeOrder, .place-order.

Dit wordt getoond in regel 21 van het complete voorbeeld.

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

Beveiligd cartdetails aanmaken op de serverzijde

Om de cartdetails aan de klant weer te geven, moet je een server-side functie maken die de Zonos API aanroept om een cart aan te maken, en vervolgens die cart-ID teruggeeft aan je frontend. Dit zorgt ervoor dat cartdetails niet op een manier aan de klant worden blootgesteld die kan worden gemanipuleerd.

Je backend API-aanroep gebruikt een geheim GraphQL-credentialtoken, dat verschilt van het publieke token dat je gebruikt om het Zonos JS-script te authenticeren. Dit token kan worden opgehaald in Dashboard -> Instellingen -> Integraties. Het geheime token moet als een header in je API-aanroep worden doorgegeven.

De cartCreate mutatie accepteert een lijst van items, die moet worden geformatteerd volgens het 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
}

We raden aan om een API-eindpunt op uw serverzijde te creëren en dat eindpunt vervolgens aan te roepen vanuit uw frontend JS-integratie, wat in de volgende stap wordt toegelicht.

Geef cart ID door aan Checkout via frontend

Zodra u een cart op uw serverzijde heeft aangemaakt, moet u de cart ID doorgeven aan het Zonos JS-script. Dit kan worden gedaan door de createCartId callback te gebruiken, die deel uitmaakt van de Zonos.init functie. Checkout zal vervolgens veilig de cartgegevens ophalen van Zonos wanneer deze wordt geopend, waardoor elke manipulatie van de cart wordt voorkomen. Zie het codevoorbeeld hieronder.

De waarde van de createCartId kan geen statische waarde zijn, het moet een functie zijn.

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

Om bestellingen tussen uw systeem en Zonos Dashboard te synchroniseren, implementeer deze API-aanroepen en webhooks:

Vereiste Mutaties

Vereiste Webhooks

Voordat u live gaat met uw Checkout integratie, is het belangrijk om alle aspecten van de integratie grondig te testen om een soepele klantervaring te waarborgen. Dit omvat het testen van de checkout flow, betalingsverwerking, ordercreatie en webhookfunctionaliteit.

Volg onze testgids om te verifiëren dat uw integratie correct werkt en om eventuele problemen te identificeren en op te lossen voordat u naar productie gaat.

Hieronder staan enkele veelgestelde vragen over het integratieproces.

Hoe gaat Zonos om met orderbevestiging?

Zonos biedt een ingebouwde bedankpagina die u kunt gebruiken voor orderbevestigingen. Deze pagina wordt altijd weergegeven, zelfs als een bestelling niet in uw systeem kan worden geïmporteerd, zodat klanten altijd bevestiging van hun aankoop ontvangen.

Kan ik een melding ontvangen wanneer een bestelling is aangemaakt?

Ja. Als u meldingen wilt ontvangen wanneer een bestelling is aangemaakt, kunt u in Dashboard onder de E-mail sectie van Checkout instellingen het e-mailadres invoeren van de teamleden die op de hoogte moeten worden gesteld wanneer een bestelling is aangemaakt, verzonden of geannuleerd.