Niestandardowa integracja

Aby rozpocząć, prosimy o kontakt z naszym zespołem sprzedaży w celu utworzenia konta i podpisania umowy. Po podpisaniu umowy otrzymasz dwa mikropłatności na swoje konto, które muszą zostać zweryfikowane.

Proszę wysłać te kwoty mikropłatności na adres accounting@zonos.com z identyfikatorem swojego sklepu Dashboard (CC swojego przedstawiciela handlowego).

Po weryfikacji szczegóły bankowe będą wyświetlane w Dashboard -> Ustawienia -> Fakturowanie.

Po utworzeniu konta Zonos będziesz musiał skonfigurować ustawienia w Dashboard, aby zapewnić prawidłowe działanie Checkout w Twoim sklepie. Ta sekcja obejmuje wszystkie niezbędne konfiguracje Dashboard.

Skonfiguruj wypłaty

Połącz konto bankowe, aby otrzymywać terminowe wypłaty z Checkout. Wypłaty są przetwarzane codziennie z 2-dniowym opóźnieniem od zrealizowanej płatności. Aby to zrobić, postępuj zgodnie z tymi krokami:

1. Przejdź do Dashboard -> Ustawienia -> ustawienia Checkout.
2. Kliknij Dodaj konto bankowe
3. Zostaniesz przeniesiony do portalu Stripe, aby zakończyć konfigurację i podać następujące informacje:
   • Informacje o koncie bankowym.
   • Numer EIN firmy.
   • Numer ubezpieczenia społecznego właściciela firmy posiadającego 25%. Aby uzyskać więcej informacji na temat tego, dlaczego jest to wymagane, zobacz dokumentację Stripe tutaj.

Uwaga: Jeśli musisz zaktualizować harmonogram wypłat, skontaktuj się z support@zonos.com

Skonfiguruj dozwolone domeny

Skrypt JS Zonos wymaga listy dozwolonych domen w celach bezpieczeństwa. Zapobiega to ładowaniu skryptu przez nieautoryzowane witryny i zapewnia, że działa tylko na zatwierdzonych domenach. Bez tej konfiguracji skrypt zwróci błędy uprawnień.

Aby to skonfigurować:

1. Przejdź do Dashboard -> Ustawienia -> ustawienia Checkout
2. W sekcji URL dodaj swoją pełną domenę oraz wszelkie subdomeny, na których będzie używany Checkout. Na przykład, jeśli Twoja domena to example.com, powinieneś dodać example.com oraz test.example.com.

Dostosuj ustawienia marki

Skonfiguruj ustawienia marki w Dashboard, aby dopasować je do wyglądu i stylu Twojego sklepu.

Aby to zrobić, postępuj zgodnie z tymi krokami:

1. Przejdź do Dashboard -> Ustawienia -> ustawienia Checkout -> Marka
2. Skonfiguruj następujące ustawienia:
   • Logo.
   • Kolor marki i akcentu.
   • Motyw, styl i czcionka.

Aby uzyskać więcej informacji na temat ustawień marki, zobacz naszą dokumentację.

Połącz przewoźnika

Aby wycenić przesyłkę w checkout, będziesz musiał połączyć przewoźnika z kontem Zonos. Umożliwi to włączenie określonych poziomów usług wysyłkowych w checkout.

Aby połączyć przewoźnika, postępuj zgodnie z tymi krokami:

1. Przejdź do Dashboard -> Ustawienia -> Wysyłka -> Stawki
2. Kliknij Dodaj przewoźnika
3. Postępuj zgodnie z instrukcjami konfiguracji przewoźnika.

Aby uzyskać więcej informacji na temat łączenia kont przewoźników, zobacz naszą dokumentację.

Skonfiguruj strefy wysyłkowe

Strefy wysyłkowe pozwalają skonfigurować, które przewoźnicy i poziomy usług są dostępne dla różnych regionów świata.

Aby skonfigurować strefy wysyłkowe, postępuj zgodnie z tymi krokami:

1. Przejdź do Dashboard -> Ustawienia -> Wysyłka -> Lokalizacje
2. Kliknij Nowa strefa
3. Wprowadź nazwę strefy i wybierz kraje, do których chcesz wysyłać.
4. Wybierz przewoźnika i poziom usługi, który chcesz oferować.

Aby uzyskać więcej informacji na temat stref wysyłkowych, zobacz naszą dokumentację.

Skonfiguruj kraj pochodzenia i kod HS jako zapasowe

Kraj pochodzenia i kod HS są używane do obliczania dokładnych ceł i podatków.

Jeśli nie podasz konkretnego kraju pochodzenia lub kodu HS, użyjemy zapasów skonfigurowanych w Dashboard.

Aby ustawić zapasowy kraj pochodzenia i kod HS:

1. Przejdź do Dashboard -> Ustawienia -> Wysyłka -> Katalog.
2. Dla kraju pochodzenia wybierz kraj, w którym większość Twoich produktów jest produkowana.
3. Dla kodu HS wprowadź kod HS swojego najczęściej sprzedawanego produktu. Jeśli nie masz kodu HS, przejdź do Classify w Dashboard i wprowadź nazwę oraz opis swojego produktu, aby wygenerować dokładny kod HS.

Fragment JS Zonos to integracja JavaScript po stronie klienta, która umożliwia globalną funkcjonalność checkout na Twojej stronie. Służy jako most między Twoją platformą e-commerce a usługami Zonos, obsługując:

• Doświadczenie Checkout: Renderuje interfejs użytkownika checkout i przetwarza płatności.
• Usługi lokalizacyjne: Wykrywa lokalizację odwiedzającego i zarządza konwersją walut.
• Integracja koszyka: Łączy się z istniejącym koszykiem i systemem zamówień.
• Bezpieczeństwo: Weryfikuje domeny i autoryzuje żądania API.

Fragment ładowany jest asynchronicznie, aby nie wpływać na wydajność Twojej strony. Inicjalizuje się z danymi uwierzytelniającymi API Twojego sklepu i obsługuje wszystkie interakcje po stronie klienta w sposób bezpieczny. Implementacja została zaprojektowana tak, aby była nieinwazyjna, wymagając minimalnych zmian w istniejącym przepływie checkout.

Poniżej znajduje się kompletny przykład, który obejmuje ładowanie skryptu, inicjalizację i obsługę zdarzeń, do którego możesz się odwołać podczas integracji 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>

Uwaga: Zastąp wartości zastępcze (storeId, zonosApiKey, selektory itp.) swoimi rzeczywistymi wartościami z panelu Zonos.

Obsługa pamięci podręcznej przeglądarki

Zalecamy dodanie znacznika czasu lub innego unikalnego identyfikatora do adresu URL, aby upewnić się, że skrypt nie jest buforowany przez przeglądarkę. Zapewni to, że zawsze ładowana jest najnowsza wersja skryptu. Jest to pokazane w linii 10 pełnego przykładu.

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

Uwierzytelnij Zonos fragment JS

Po załadowaniu skryptu Zonos JS, musisz go uwierzytelnić, przekazując publiczny Zonos klucz API i identyfikator sklepu do funkcji Zonos.init. Publiczny klucz API używany do uwierzytelniania Checkout jest zaprojektowany jako publikowalny, co oznacza, że może być bezpiecznie używany w kodzie frontendowym bez ujawniania jakichkolwiek wrażliwych informacji.

Aby znaleźć swój identyfikator sklepu i klucz API, przejdź do Dashboard -> Ustawienia -> Integracje. Upewnij się, że nie używasz Tajnego klucza API, ponieważ nie jest on przeznaczony do użycia w kodzie frontendowym. Jest to pokazane w liniach 29 i 30 pełnego przykładu.

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 jest wymagany podczas korzystania z Checkout.

Hello odpowiada za wykrywanie lokalizacji, języka i waluty odwiedzającego oraz wyświetlanie odpowiednich informacji. Możesz skonfigurować wszystkie ustawienia Hello w Dashboard lub w skrypcie JS Zonos. Jeśli już skonfigurowałeś Hello w Dashboard, skrypt załaduje te ustawienia i je wykorzysta. Jeśli określisz jakiekolwiek wartości w właściwości helloSettings funkcji Zonos.init, skrypt użyje tych wartości zamiast jak pokazano poniżej.

Skonfiguruj konwersję walut w Hello w skrypcie JS

Hello używa selektorów CSS do identyfikacji elementów na Twojej stronie, które wyświetlają informacje o walucie. Przekaż te selektory do właściwości helloSettings.currencyElementSelector funkcji Zonos.init, aby Hello mogło wykryć i wyświetlić poprawną walutę międzynarodowego kupującego.

Możesz użyć dowolnego ważnego selektora CSS tutaj, na przykład #price, .price, aby wybrać wiele różnych elementów. Jest to pokazane w liniach 23 i 24 pełnego przykładu.

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

Automatyczne otwieranie Hello przy ładowaniu strony

Domyślnie Hello otworzy się tylko wtedy, gdy odwiedzający kliknie przycisk flagi. Jeśli chcesz automatycznie otworzyć Hello po załadowaniu strony, możesz wywołać funkcję Zonos.openHelloDialog(), gdy skrypt Zonos zostanie załadowany. Jest to pokazane w liniach 25 i 26 pełnego przykładu.

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

Checkout odpowiada za umożliwienie klientowi wprowadzenia informacji o wysyłce i płatności, obliczenie landed cost, collect płatności oraz zakończenie zamówienia.

Checkout będzie dzielić się danymi kontekstowymi z Hello, takimi jak lokalizacja odwiedzającego, język i waluta. Zapewnia to, że doświadczenie klienta jest spójne w całym procesie zakupowym.

Możesz skonfigurować wszystkie ustawienia Checkout zarówno w Dashboard, jak i w skrypcie Zonos JS. Jeśli już skonfigurowałeś Checkout w Dashboard, skrypt załaduje te ustawienia i je wykorzysta. Jeśli określisz jakiekolwiek wartości w właściwości checkoutSettings funkcji Zonos.init, skrypt użyje tych wartości zamiast.

Skonfiguruj przycisk 'złóż zamówienie' w skrypcie JS

Skrypt Zonos JS automatycznie rozpozna międzynarodowych kupujących i skieruje ich do procesu Checkout. Jednak będziesz musiał skonfigurować przycisk 'złóż zamówienie' na swojej platformie, aby otwierał Checkout po kliknięciu. Można to zrobić, przekazując selektor CSS do właściwości checkoutSettings.placeOrderButtonSelector funkcji Zonos.init.

Jeśli masz wiele przycisków, które mogą być używane do składania zamówienia, upewnij się, że przekazujesz selektor dla każdego przycisku. Na przykład, #placeOrder, .place-order.

Jest to pokazane w linii 21 pełnego przykładu.

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

Bezpieczne tworzenie szczegółów koszyka po stronie serwera

Aby wyświetlić szczegóły koszyka klientowi, musisz stworzyć funkcję po stronie serwera, która wywoła API Zonos w celu utworzenia koszyka, a następnie przekaże ten identyfikator koszyka z powrotem do twojego frontend. Zapewni to, że szczegóły koszyka nie będą ujawnione klientowi w sposób, który można by manipulować.

Twoje wywołanie API w backendzie będzie używać tajnego tokena uwierzytelniającego GraphQL, który różni się od publicznego tokena, którego używasz do uwierzytelnienia skryptu JS Zonos. Ten token można uzyskać w Dashboard -> Settings -> Integracje. Tajny token musi być przekazany jako nagłówek w twoim wywołaniu API.

Mutacja cartCreate akceptuje listę przedmiotów, które powinny być sformatowane zgodnie z schematem przedmiotu koszyka.

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

Sugerujemy utworzenie punktu końcowego API na serwerze, a następnie wywołanie tego punktu końcowego z integracji JS na froncie, co jest szczegółowo opisane w następnym kroku.

Przekaż identyfikator koszyka do Checkout za pomocą frontendu

Gdy utworzysz koszyk na swoim serwerze, musisz przekazać identyfikator koszyka do skryptu JS Zonos. Można to zrobić, używając funkcji zwrotnej createCartId, która jest częścią funkcji Zonos.init. Checkout następnie bezpiecznie pobierze szczegóły koszyka z Zonos po otwarciu, zapobiegając jakimkolwiek manipulacjom z koszykiem. Zobacz przykład kodu poniżej.

Wartość createCartId nie może być wartością statyczną, musi być funkcją.

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

Aby zsynchronizować zamówienia między Twoim systemem a Zonos Dashboard, zaimplementuj te wywołania API i webhooki:

Wymagane mutacje

Wymagane webhooki

Przed uruchomieniem integracji Checkout ważne jest, aby dokładnie przetestować wszystkie aspekty integracji, aby zapewnić płynne doświadczenie klienta. Obejmuje to testowanie przepływu checkout, przetwarzania płatności, tworzenia zamówień i funkcjonalności webhooków.

Postępuj zgodnie z naszym przewodnikiem testowania, aby zweryfikować, że Twoja integracja działa poprawnie i zidentyfikować oraz naprawić wszelkie problemy przed uruchomieniem w produkcji.

Poniżej znajdują się niektóre często zadawane pytania dotyczące procesu integracji.

Jak Zonos obsługuje potwierdzenie zamówienia?

Zonos zapewnia wbudowaną stronę z podziękowaniami, którą możesz wykorzystać do potwierdzeń zamówień. Ta strona zawsze będzie wyświetlana, nawet jeśli zamówienie nie uda się zaimportować do Twojego systemu, zapewniając, że klienci zawsze otrzymują potwierdzenie zakupu.

Czy mogę być powiadamiany, gdy zamówienie zostanie utworzone?

Tak. Jeśli chcesz otrzymywać powiadomienia, gdy zamówienie zostanie utworzone, w Dashboard w sekcji Email ustawień Checkout możesz wpisać adres e-mail członków zespołu, którzy powinni być powiadamiani, gdy zamówienie zostanie utworzone, wysłane lub anulowane.