Benutzerdefinierte Integration

Um zu beginnen, kontaktieren Sie bitte unser Verkaufsteam, um ein Konto zu erstellen und eine Vereinbarung zu unterzeichnen. Sobald eine Vereinbarung unterzeichnet ist, erhalten Sie zwei Mikrodeposits auf Ihr Konto, die verifiziert werden müssen.

Bitte senden Sie diese Mikrodepositbeträge an accounting@zonos.com mit Ihrer Dashboard-Shop-ID (CC an Ihren Vertriebsmitarbeiter).

Sobald die Verifizierung abgeschlossen ist, werden Ihre Bankdaten in Dashboard -> Einstellungen -> Abrechnung angezeigt.

Nachdem Sie Ihr Zonos-Konto erstellt haben, müssen Sie die Einstellungen im Dashboard konfigurieren, um sicherzustellen, dass Checkout ordnungsgemäß mit Ihrem Shop funktioniert. Dieser Abschnitt behandelt alle wesentlichen Dashboard-Konfigurationen.

Richten Sie Auszahlungen ein

Verbinden Sie ein Bankkonto, um rechtzeitige Auszahlungen von Checkout zu erhalten. Auszahlungen werden täglich mit einer Verzögerung von 2 Tagen nach der erfassten Zahlung verarbeitet. Gehen Sie dazu bitte wie folgt vor:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Checkout-Einstellungen.
2. Klicken Sie auf Bankkonto hinzufügen
3. Sie werden zu einem Stripe-Portal weitergeleitet, um die Einrichtung abzuschließen und die folgenden Informationen bereitzustellen:
   • Bankkontoinformationen.
   • Unternehmens-EIN.
   • Sozialversicherungsnummer eines 25%-Eigentümers des Unternehmens. Weitere Informationen dazu, warum dies erforderlich ist, finden Sie in Stripes Dokumentation.

Hinweis: Wenn Sie Ihren Auszahlungstermin aktualisieren müssen, kontaktieren Sie bitte support@zonos.com

Richten Sie erlaubte Domains ein

Das Zonos JS-Skript benötigt eine Liste erlaubter Domains aus Sicherheitsgründen. Dies verhindert, dass unbefugte Websites das Skript laden, und stellt sicher, dass es nur auf Ihren genehmigten Domains ausgeführt wird. Ohne diese Konfiguration gibt das Skript Berechtigungsfehler zurück.

Um dies einzurichten:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Checkout-Einstellungen
2. Fügen Sie unter URLs Ihre vollständige Domain und alle Subdomains hinzu, auf denen Checkout verwendet wird. Wenn Ihre Domain beispielsweise example.com ist, sollten Sie example.com und test.example.com hinzufügen.

Passen Sie die Branding-Einstellungen an

Konfigurieren Sie Ihre Branding-Einstellungen im Dashboard, um das Erscheinungsbild Ihres Shops anzupassen.

Gehen Sie dazu bitte wie folgt vor:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Checkout-Einstellungen -> Branding
2. Konfigurieren Sie die folgenden Einstellungen:
   • Logo.
   • Marken- und Akzentfarbe.
   • Thema, Stil und Schriftart.

Für weitere Informationen zu den Branding-Einstellungen siehe unsere Dokumentation.

Verbinden Sie einen Versanddienstleister

Um Versandkosten bei checkout zu berechnen, müssen Sie einen Versanddienstleister mit Ihrem Zonos-Konto verbinden. Dadurch können Sie spezifische Versanddienstleistungsstufen bei checkout aktivieren.

Um einen Versanddienstleister zu verbinden, gehen Sie bitte wie folgt vor:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Versand -> Tarife
2. Klicken Sie auf Carrier hinzufügen
3. Befolgen Sie die Anweisungen zur Einrichtung des Carriers.

Für weitere Details zur Verbindung von Carrier-Konten siehe unsere Dokumentation.

Richten Sie Versandzonen ein

Versandzonen ermöglichen es Ihnen, zu konfigurieren, welche Versanddienstleister und Dienstleistungsstufen für verschiedene Regionen der Welt verfügbar sind.

Um Versandzonen einzurichten, gehen Sie bitte wie folgt vor:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Versand -> Standorte
2. Klicken Sie auf Neue Zone
3. Geben Sie einen Zonnennamen ein und wählen Sie die Länder aus, in die Sie versenden möchten.
4. Wählen Sie den Carrier und die Dienstleistungsstufe aus, die Sie anbieten möchten.

Für weitere Details zu Versandzonen siehe unsere Dokumentation.

Richten Sie ein Fallback-Land des Ursprungs und HS-Code ein

Das Ursprungsland und der HS-Code werden verwendet, um genaue Zölle und Steuern zu berechnen.

Wenn Sie kein spezifisches Ursprungsland oder HS-Code angeben, verwenden wir die im Dashboard festgelegten Fallbacks.

Um Ihr Fallback-Ursprungsland und HS-Code festzulegen:

1. Navigieren Sie zu Dashboard -> Einstellungen -> Versand -> Katalog.
2. Wählen Sie für das Ursprungsland das Land aus, in dem die Mehrheit Ihrer Produkte hergestellt wird.
3. Geben Sie für den HS-Code den HS-Code Ihres häufigsten Produkts ein. Wenn Sie keinen HS-Code haben, navigieren Sie zu Classify im Dashboard und geben Sie den Namen und die Beschreibung Ihres Produkts ein, um einen genauen HS-Code zu generieren.

Der Zonos JS-Snippet ist eine clientseitige JavaScript-Integration, die globale checkout-Funktionalität auf Ihrer Website ermöglicht. Er dient als Brücke zwischen Ihrer E-Commerce-Plattform und den Zonos-Diensten und verarbeitet:

• Checkout-Erlebnis: Rendert die checkout-UI und verarbeitet Zahlungen.
• Standortdienste: Erkennt den Standort des Besuchers und verwaltet die Währungsumrechnung.
• Warenkorb-Integration: Verbindet sich mit Ihrem bestehenden Warenkorb- und Bestellsystem.
• Sicherheit: Validiert Domains und authentifiziert API-Anfragen.

Der Snippet wird asynchron geladen, um jegliche Auswirkungen auf die Leistung Ihrer Website zu vermeiden. Er wird mit den API-Anmeldeinformationen Ihres Shops initialisiert und verarbeitet alle clientseitigen Interaktionen sicher. Die Implementierung ist so konzipiert, dass sie nicht störend ist und minimale Änderungen an Ihrem bestehenden checkout-Ablauf erfordert.

Nachfolgend finden Sie ein vollständiges Beispiel, das das Laden des Skripts, die Initialisierung und die Ereignisbehandlung umfasst, auf das Sie sich bei der Integration von Checkout beziehen können.

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

Hinweis: Ersetzen Sie die Platzhalterwerte (storeId, zonosApiKey, selectors usw.) durch Ihre tatsächlichen Werte aus Ihrem Zonos Dashboard.

Umgang mit dem Browser-Cache

Wir empfehlen, einen Zeitstempel oder einen anderen eindeutigen Identifikator an die URL anzuhängen, um sicherzustellen, dass das Skript nicht vom Browser zwischengespeichert wird. Dies stellt sicher, dass immer die neueste Version des Skripts geladen wird. Dies wird in Zeile 10 des vollständigen Beispiels gezeigt.

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

Authentifizieren Sie den Zonos JS-Snippet

Sobald Sie das Zonos JS-Skript geladen haben, müssen Sie es authentifizieren, indem Sie einen öffentlichen Zonos API-Schlüssel und die Store-ID in die Zonos.init-Funktion übergeben. Der öffentliche API-Schlüssel, der zur Authentifizierung von Checkout verwendet wird, ist so konzipiert, dass er veröffentlicht werden kann, was bedeutet, dass er sicher im Frontend-Code verwendet werden kann, ohne sensible Informationen offenzulegen.

Um Ihre Store-ID und den API-Schlüssel zu finden, navigieren Sie zu Dashboard -> Einstellungen -> Integrationen. Stellen Sie sicher, dass Sie keinen Secret API-Schlüssel verwenden, da dieser nicht für die Verwendung im Frontend-Code vorgesehen ist. Dies wird in den Zeilen 29 und 30 des vollständigen Beispiels gezeigt.

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 ist erforderlich, wenn Sie Checkout verwenden.

Hello ist dafür verantwortlich, den Standort, die Sprache und die Währung des Besuchers zu erkennen und die entsprechenden Informationen anzuzeigen. Sie können alle Hello-Einstellungen im Dashboard oder im Zonos-JS-Skript konfigurieren. Wenn Sie Hello bereits im Dashboard konfiguriert haben, lädt das Skript diese Einstellungen und verwendet sie. Wenn Sie Werte in der helloSettings-Eigenschaft der Zonos.init-Funktion angeben, verwendet das Skript stattdessen diese Werte, wie unten gezeigt.

Konfigurieren Sie die Währungsumrechnung in Hello im JS-Skript

Hello verwendet CSS-Selektoren, um Elemente auf Ihrer Website zu identifizieren, die Währungsinformationen anzeigen. Übergeben Sie diese Selektoren an die helloSettings.currencyElementSelector-Eigenschaft der Zonos.init-Funktion, damit Hello die richtige Währung des internationalen Käufers erkennen und anzeigen kann.

Sie können hier jeden gültigen CSS-Selektor verwenden, zum Beispiel #price, .price, um mehrere verschiedene Elemente auszuwählen. Dies wird in den Zeilen 23 und 24 des vollständigen Beispiels gezeigt.

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

Automatisch Hello beim Laden der Seite öffnen

Standardmäßig wird Hello nur geöffnet, wenn der Besucher auf die Flaggen-Schaltfläche klickt. Wenn Sie Hello automatisch öffnen möchten, wenn die Seite geladen wird, können Sie die Funktion Zonos.openHelloDialog() aufrufen, sobald das Skript Zonos geladen wurde. Dies wird in den Zeilen 25 und 26 des vollständigen Beispiels gezeigt.

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

Checkout ist dafür verantwortlich, dem Kunden die Eingabe seiner Versand- und Rechnungsinformationen zu ermöglichen, landed cost zu berechnen, collect Zahlungen zu akzeptieren und die Bestellung abzuschließen.

Checkout wird kontextuelle Daten mit Hello teilen, wie z.B. den Standort, die Sprache und die Währung des Besuchers. Dies stellt sicher, dass die Erfahrung des Kunden während des gesamten Einkaufsprozesses konsistent ist.

Sie können alle Einstellungen von Checkout sowohl im Dashboard als auch im Zonos JS-Skript konfigurieren. Wenn Sie Checkout bereits im Dashboard konfiguriert haben, lädt das Skript diese Einstellungen und verwendet sie. Wenn Sie Werte in der checkoutSettings-Eigenschaft der Zonos.init-Funktion angeben, verwendet das Skript stattdessen diese Werte.

Konfigurieren Sie die 'Bestellung aufgeben'-Schaltfläche im JS-Skript

Das Zonos JS-Skript erkennt automatisch internationale Käufer und leitet sie zum Checkout-Prozess. Sie müssen jedoch die 'Bestellung aufgeben'-Schaltfläche auf Ihrer Plattform so konfigurieren, dass sie Checkout öffnet, wenn sie angeklickt wird. Dies kann erreicht werden, indem ein CSS-Selektor an die checkoutSettings.placeOrderButtonSelector-Eigenschaft der Zonos.init-Funktion übergeben wird.

Wenn Sie mehrere Schaltflächen haben, die verwendet werden können, um eine Bestellung aufzugeben, stellen Sie sicher, dass Sie einen Selektor für jede Schaltfläche übergeben. Zum Beispiel #placeOrder, .place-order.

Dies wird in Zeile 21 des vollständigen Beispiels gezeigt.

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

Sicheres Erstellen von Warenkorbdaten auf der Serverseite

Um die Warenkorbdaten dem Kunden anzuzeigen, müssen Sie eine serverseitige Funktion erstellen, die die Zonos API aufruft, um einen Warenkorb zu erstellen, und dann diese Warenkorb-ID an Ihr Frontend zurückgibt. Dies stellt sicher, dass die Warenkorbdaten dem Kunden nicht in einer Weise angezeigt werden, die manipuliert werden kann.

Ihr Backend-API-Aufruf verwendet ein geheimes GraphQL-Anmeldeinformationstoken, das sich von dem öffentlichen Token unterscheidet, das Sie zur Authentifizierung des Zonos JS-Skripts verwenden. Dieses Token kann in Dashboard -> Einstellungen -> Integrationen abgerufen werden. Das geheime Token muss als Header in Ihrem API-Aufruf übergeben werden.

Die cartCreate-Mutation akzeptiert eine Liste von Artikeln, die gemäß dem Warenkorb-Artikel-Schema formatiert sein sollte.

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

Wir empfehlen, einen API-Endpunkt auf Ihrer Server-Seite zu erstellen und diesen Endpunkt dann von Ihrer Frontend-JS-Integration aus aufzurufen, was im nächsten Schritt detailliert beschrieben wird.

Übergeben Sie die Warenkorb-ID an Checkout über das Frontend

Sobald Sie einen Warenkorb auf Ihrer Server-Seite erstellt haben, müssen Sie die Warenkorb-ID an das Zonos JS-Skript übergeben. Dies kann durch die Verwendung des createCartId-Callbacks erfolgen, das Teil der Zonos.init-Funktion ist. Checkout wird dann sicher die Warenkorbdaten von Zonos abrufen, wenn es geöffnet wird, um eine Manipulation des Warenkorbs zu verhindern. Siehe das Codebeispiel unten.

Der Wert von createCartId kann kein statischer Wert sein, es muss eine Funktion sein.

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

Um Bestellungen zwischen Ihrem System und dem Zonos Dashboard zu synchronisieren, implementieren Sie diese API-Aufrufe und Webhooks:

Erforderliche Mutationen

Erforderliche Webhooks

Bevor Sie mit Ihrer Checkout Integration live gehen, ist es wichtig, alle Aspekte der Integration gründlich zu testen, um ein reibungsloses Kundenerlebnis zu gewährleisten. Dazu gehört das Testen des checkout Ablaufs, der Zahlungsabwicklung, der Bestellerstellung und der Webhook-Funktionalität.

Folgen Sie unserem Testleitfaden, um zu überprüfen, ob Ihre Integration korrekt funktioniert und um Probleme zu identifizieren und zu beheben, bevor Sie in die Produktion gehen.

Im Folgenden finden Sie einige häufige Fragen zum Integrationsprozess.

Wie geht Zonos mit der Bestellbestätigung um?

Zonos bietet eine integrierte Dankeschön-Seite, die Sie für Bestellbestätigungen verwenden können. Diese Seite wird immer angezeigt, selbst wenn eine Bestellung nicht in Ihr System importiert werden kann, sodass Kunden immer eine Bestätigung ihres Kaufs erhalten.

Kann ich benachrichtigt werden, wenn eine Bestellung erstellt wird?

Ja. Wenn Sie Benachrichtigungen erhalten möchten, wenn eine Bestellung erstellt wird, können Sie im Dashboard im Abschnitt E-Mail der Checkout Einstellungen die E-Mail-Adresse der Teammitglieder eingeben, die benachrichtigt werden sollen, wenn eine Bestellung erstellt, versendet oder storniert wird.