Özel entegrasyon

Başlamak için, bir hesap oluşturmak ve bir anlaşma imzalamak için lütfen satış ekibimizle iletişime geçin. Anlaşma imzalandıktan sonra, hesabınıza doğrulanması gereken iki mikro para yatırma işlemi alacaksınız.

Lütfen bu mikro para yatırma miktarlarını Dashboard mağaza kimliğinizle birlikte accounting@zonos.com adresine e-posta ile gönderin (satış temsilcinizi CC'leyin).

Doğrulandıktan sonra, banka bilgileriniz Dashboard -> Ayarlar -> Faturalama bölümünde görüntülenecektir.

Zonos hesabınızı oluşturduktan sonra, Checkout'un mağazanızla düzgün çalışmasını sağlamak için Dashboard'da ayarları yapılandırmanız gerekecek. Bu bölüm, tüm temel Dashboard yapılandırmalarını kapsar.

Ödemeleri ayarlayın

Checkout'tan zamanında ödeme almak için bir banka hesabı bağlayın. Ödemeler, alınan ödemeden 2 gün sonra günlük olarak işlenir. Bunu yapmak için lütfen şu adımları izleyin:

1. Dashboard -> Ayarlar -> Checkout ayarları bölümüne gidin.
2. Banka hesabı ekle'ye tıklayın
3. Kurulumu tamamlamak ve aşağıdaki bilgileri sağlamak için bir Stripe portalına yönlendirileceksiniz:
   • Banka hesap bilgileri.
   • Şirket EIN.
   • %25 şirket sahibinin Sosyal Güvenlik Numarası. Bunun neden gerekli olduğu hakkında daha fazla bilgi için Stripe'ın belgelerine bakın.

Not: Ödeme planınızı güncellemeniz gerekiyorsa, lütfen support@zonos.com adresine başvurun.

İzin verilen alan adlarını ayarlayın

Zonos JS betiği, güvenlik amacıyla izin verilen alan adlarının bir listesini gerektirir. Bu, yetkisiz sitelerin betiği yüklemesini engeller ve yalnızca onaylı alan adlarınızda çalışmasını sağlar. Bu yapılandırma olmadan, betik izin hataları döndürecektir.

Bunu ayarlamak için:

1. Dashboard -> Ayarlar -> Checkout ayarları bölümüne gidin
2. URL'ler altında, Checkout'un kullanılacağı tam alan adınızı ve alt alan adlarınızı ekleyin. Örneğin, alan adınız example.com ise, example.com ve test.example.com eklemelisiniz.

Marka ayarlarını özelleştirin

Mağazanızın görünümüne ve hissine uygun olacak şekilde Dashboard'da marka ayarlarınızı yapılandırın.

Bunu yapmak için lütfen şu adımları izleyin:

1. Dashboard -> Ayarlar -> Checkout ayarları -> Marka bölümüne gidin
2. Aşağıdaki ayarları yapılandırın:
   • Logo.
   • Marka ve vurgu rengi.
   • Tema, Stil ve Yazı Tipi.

Marka ayarları hakkında daha fazla bilgi için belgelerimize bakın.

Bir nakliye taşıyıcısı bağlayın

checkout'ta nakliye teklifi vermek için Zonos hesabınıza bir nakliye taşıyıcısı bağlamanız gerekecek. Bu, checkout'ta belirli nakliye hizmet seviyelerini etkinleştirmenizi sağlar.

Bir nakliye taşıyıcısı bağlamak için lütfen şu adımları izleyin:

1. Dashboard -> Ayarlar -> Nakliye -> Fiyatlar bölümüne gidin
2. Taşıyıcı ekle'ye tıklayın
3. Taşıyıcı kurulum talimatlarını izleyin.

Taşıyıcı hesaplarını bağlama hakkında daha fazla bilgi için belgelerimize bakın.

Nakliye bölgelerini ayarlayın

Nakliye bölgeleri, dünyanın farklı bölgeleri için hangi nakliye taşıyıcılarının ve hizmet seviyelerinin mevcut olduğunu yapılandırmanıza olanak tanır.

Nakliye bölgelerini ayarlamak için lütfen şu adımları izleyin:

1. Dashboard -> Ayarlar -> Nakliye -> Konumlar bölümüne gidin
2. Yeni bölge'ye tıklayın
3. Bir bölge adı girin ve gönderim yapmak istediğiniz ülkeleri seçin.
4. Sunmak istediğiniz taşıyıcıyı ve hizmet seviyesini seçin.

Nakliye bölgeleri hakkında daha fazla bilgi için belgelerimize bakın.

Yedek menşe ülkesini ve HS kodunu ayarlayın

Menşe ülkesi ve HS kodu, doğru gümrük vergileri ve vergileri hesaplamak için kullanılır.

Belirli bir menşe ülkesi veya HS kodu sağlamazsanız, Dashboard'da ayarlanan yedekler kullanılacaktır.

Yedek Menşe Ülkenizi ve HS kodunuzu ayarlamak için:

1. Dashboard -> Ayarlar -> Nakliye -> Katalog bölümüne gidin.
2. Menşe ülkesi için, ürünlerinizin çoğunluğunun üretildiği ülkeyi seçin.
3. HS kodu için, en yaygın ürününüzün HS kodunu girin. Bir HS kodunuz yoksa, Dashboard'da Classify bölümüne gidin ve ürününüzün adını ve açıklamasını girerek doğru bir HS kodu oluşturun.

Zonos JS kod parçası, sitenizde küresel checkout işlevselliğini etkinleştiren istemci tarafı bir JavaScript entegrasyonudur. E-ticaret platformunuz ile Zonos hizmetleri arasında köprü görevi görür ve aşağıdaki işlemleri gerçekleştirir:

• Checkout Deneyimi: checkout kullanıcı arayüzünü oluşturur ve ödemeleri işler.
• Konum Hizmetleri: Ziyaretçi konumunu algılar ve para birimi dönüşümünü yönetir.
• Sepet Entegrasyonu: Mevcut sepet ve sipariş sisteminizle bağlantı kurar.
• Güvenlik: Alan adlarını doğrular ve API isteklerini kimlik doğrulaması yapar.

Kod parçası, sitenizin performansını etkilememek için eşzamansız olarak yüklenir. Mağazanızın API kimlik bilgileriyle başlatılır ve tüm istemci tarafı etkileşimlerini güvenli bir şekilde yönetir. Uygulama, mevcut checkout akışınıza minimal değişiklik gerektirecek şekilde tasarlanmıştır.

Aşağıda, Checkout entegrasyonu sırasında referans alabileceğiniz, betik yükleme, başlatma ve olay işleme içeren eksiksiz bir örnek bulunmaktadır.

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

Not: Yer tutucu değerleri (storeId, zonosApiKey, selectors, vb.) Zonos Gösterge Panelinizden gerçek değerlerinizle değiştirin.

Tarayıcı önbelleklemesini yönetme

Tarayıcının scripti önbelleğe almadığından emin olmak için URL'ye bir zaman damgası veya başka bir benzersiz tanımlayıcı eklemenizi öneririz. Bu, scriptin her zaman en son sürümünün yüklenmesini sağlayacaktır. Bu, tam örneğin 10. satırında gösterilmektedir.

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

Zonos JS parçasını doğrulayın

Zonos JS betiğini yükledikten sonra, bir genel Zonos API anahtarı ve mağaza kimliğini Zonos.init fonksiyonuna geçirerek doğrulamanız gerekir. Checkout'ı doğrulamak için kullanılan genel API anahtarı, hassas bilgileri açığa çıkarmadan ön uç kodunda güvenle kullanılabilecek şekilde tasarlanmıştır.

Mağaza kimliğinizi ve API anahtarınızı bulmak için Dashboard -> Settings -> Integrations yolunu izleyin. Ön uç kodunda kullanılmak üzere tasarlanmamış olan Secret API key kullanmadığınızdan emin olun. Bu, tam örneğin 29. ve 30. satırlarında gösterilmektedir.

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 Checkout kullanırken gereklidir.

Hello ziyaretçinin konumunu, dilini ve para birimini tespit etmekten ve onlara uygun bilgileri göstermekten sorumludur. Tüm Hello ayarlarını Dashboard'da veya Zonos JS scriptinde yapılandırabilirsiniz. Eğer Hello'yu Dashboard'da zaten yapılandırdıysanız, script bu ayarları yükleyecek ve kullanacaktır. Zonos.init fonksiyonunun helloSettings özelliğinde herhangi bir değer belirtirseniz, script aşağıda gösterildiği gibi bu değerleri kullanacaktır.

Hello'da para birimi dönüşümünü JS Scriptinde yapılandırın

Hello para birimi bilgilerini gösteren sitenizdeki öğeleri tanımlamak için CSS seçicilerini kullanır. Zonos'nun uluslararası alışverişçinin doğru para birimini tespit edip göstermesi için bu seçicileri Hello.init fonksiyonunun helloSettings.currencyElementSelector özelliğine iletin.

Burada herhangi bir geçerli CSS seçicisini kullanabilirsiniz, örneğin #price, .price birden fazla farklı öğeyi seçmek için. Bu, tam örneğin 23. ve 24. satırlarında gösterilmektedir.

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

Sayfa yüklendiğinde Hello otomatik olarak aç

Varsayılan olarak, Hello yalnızca ziyaretçi bayrak butonuna tıkladığında açılacaktır. Sayfa yüklendiğinde Hello'yı otomatik olarak açmak istiyorsanız, Zonos betiği yüklendikten sonra Zonos.openHelloDialog() fonksiyonunu çağırabilirsiniz. Bu, tam örneğin 25. ve 26. satırında gösterilmektedir.

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

Checkout müşteri için gönderim ve faturalama bilgilerini girmesine, landed cost hesaplamasına, collect ödemesini almasına ve siparişi tamamlamasına olanak tanır.

Checkout ziyaretçinin konumu, dili ve para birimi gibi bağlamsal verileri Hello ile paylaşacaktır. Bu, müşterinin deneyiminin alışveriş süreci boyunca tutarlı olmasını sağlar.

Tüm Checkout ayarlarını hem Dashboard'da hem de Zonos JS scriptinde yapılandırabilirsiniz. Eğer Checkout'ı Dashboard'da zaten yapılandırdıysanız, script bu ayarları yükleyecek ve kullanacaktır. Zonos.init fonksiyonunun checkoutSettings özelliğinde herhangi bir değer belirtirseniz, script bu değerleri kullanacaktır.

JS Script'te 'siparişi ver' butonunu yapılandırın

Zonos JS scripti uluslararası alışveriş yapanları otomatik olarak tanıyacak ve onları Checkout akışına yönlendirecektir. Ancak, tıklandığında Checkout'ı açmak için platformunuzda 'siparişi ver' butonunu yapılandırmanız gerekecektir. Bu, Zonos.init fonksiyonunun checkoutSettings.placeOrderButtonSelector özelliğine bir CSS seçici geçirerek yapılabilir.

Birden fazla sipariş verme butonunuz varsa, her buton için bir seçici geçirdiğinizden emin olun. Örneğin, #placeOrder, .place-order.

Bu, tam örneğin 21. satırında gösterilmektedir.

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

Güvenli bir şekilde sunucu tarafında sepet detayları oluşturma

Müşteriye sepet detaylarını gösterebilmek için, Zonos API'sini çağıracak bir sunucu tarafı fonksiyonu oluşturmanız ve ardından bu sepet ID'sini ön yüzünüze geri iletmeniz gerekmektedir. Bu, sepet detaylarının müşteriye manipüle edilebilecek bir şekilde açığa çıkmamasını sağlayacaktır.

Arka uç API çağrınız, Zonos JS scriptini kimlik doğrulamak için kullandığınız genel token'dan farklı olan gizli bir GraphQL kimlik bilgisi token'ı kullanacaktır. Bu token, Dashboard -> Settings -> Integrations bölümünden alınabilir. Gizli token, API çağrınızda bir başlık olarak iletilmelidir.

cartCreate mutasyonu, sepet öğesi şemasına göre formatlanmış bir öğe listesi kabul eder.

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

Önerimiz, sunucu tarafınızda bir API uç noktası oluşturmak ve ardından bu uç noktasını ön uç JS entegrasyonunuzdan çağırmaktır; bu, bir sonraki adımda ayrıntılı olarak açıklanmıştır.

Sepet ID'sini Checkout'a ön uç aracılığıyla geçirin

Sunucu tarafınızda bir sepet oluşturduktan sonra, sepet ID'sini Zonos JS betiğine geçirmeniz gerekir. Bu, Zonos.init fonksiyonunun bir parçası olan createCartId geri çağrısını kullanarak yapılabilir. Checkout açıldığında, sepet detaylarını Zonos'dan güvenli bir şekilde alacak ve sepetin değiştirilmesini önleyecektir. Aşağıdaki kod örneğine bakın.

createCartId değerinin statik bir değer olmaması gerekir, bir fonksiyon olmalıdır.

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

Siparişlerinizi sisteminiz ile Zonos Dashboard arasında senkronize etmek için bu API çağrılarını ve webhook'ları uygulayın:

Gerekli Mutasyonlar

Gerekli Webhook'lar

Checkout entegrasyonunuzla canlıya geçmeden önce, entegrasyonun tüm yönlerini kapsamlı bir şekilde test etmek önemlidir. Bu, checkout akışını, ödeme işlemlerini, sipariş oluşturmayı ve webhook işlevselliğini test etmeyi içerir.

Entegrasyonunuzun doğru çalıştığını doğrulamak ve üretime geçmeden önce herhangi bir sorunu tanımlayıp düzeltmek için test kılavuzumuzu takip edin.

Aşağıda entegrasyon süreciyle ilgili bazı sıkça sorulan sorular bulunmaktadır.

Zonos sipariş onayını nasıl yönetir?

Zonos sipariş onayları için kullanabileceğiniz yerleşik bir teşekkür sayfası sağlar. Bu sayfa, bir sipariş sisteminize aktarılmayı başaramasa bile her zaman gösterilecektir, böylece müşterilerin her zaman satın alımlarının onayını almasını sağlar.

Bir sipariş oluşturulduğunda bildirim alabilir miyim?

Evet. Bir sipariş oluşturulduğunda bildirim almak istiyorsanız, Dashboard'da Checkout ayarları bölümündeki E-posta kısmına, bir sipariş oluşturulduğunda, gönderildiğinde veya iptal edildiğinde bildirim alması gereken ekip üyelerinin e-posta adreslerini girebilirsiniz.