Integrasi kustom

Untuk memulai, silakan hubungi tim penjualan kami untuk membuat akun dan menandatangani perjanjian. Setelah perjanjian ditandatangani, Anda akan menerima dua setoran mikro di akun Anda yang perlu diverifikasi.

Silakan kirimkan jumlah setoran mikro ini ke accounting@zonos.com dengan ID toko Dashboard Anda (CC perwakilan penjualan Anda).

Setelah diverifikasi, detail perbankan Anda akan ditampilkan di Dashboard -> Pengaturan -> Penagihan.

Setelah membuat akun Zonos, Anda perlu mengonfigurasi pengaturan di Dashboard untuk memastikan Checkout berfungsi dengan baik di toko Anda. Bagian ini mencakup semua konfigurasi Dashboard yang penting.

Atur pembayaran

Hubungkan rekening bank untuk menerima pembayaran tepat waktu dari Checkout. Pembayaran diproses setiap hari dengan penundaan 2 hari dari pembayaran yang diterima. Untuk melakukan ini, silakan ikuti langkah-langkah berikut:

1. Navigasikan ke Dashboard -> Pengaturan -> pengaturan Checkout .
2. Klik Tambahkan rekening bank
3. Anda akan dibawa ke portal Stripe untuk menyelesaikan pengaturan dan memberikan informasi berikut:
   • Informasi rekening bank.
   • EIN perusahaan.
   • Nomor Jaminan Sosial pemilik perusahaan 25%. Untuk informasi lebih lanjut tentang mengapa ini diperlukan, lihat dokumentasi Stripe.

Catatan: Jika Anda perlu memperbarui jadwal pembayaran Anda, silakan hubungi support@zonos.com

Atur domain yang diizinkan

Skrip JS Zonos memerlukan daftar domain yang diizinkan untuk tujuan keamanan. Ini mencegah situs yang tidak sah memuat skrip dan memastikan hanya berjalan di domain yang disetujui. Tanpa konfigurasi ini, skrip akan mengembalikan kesalahan izin.

Untuk mengatur ini:

1. Navigasikan ke Dashboard -> Pengaturan -> pengaturan Checkout
2. Di bawah URL, tambahkan domain lengkap Anda dan subdomain mana pun di mana Checkout akan digunakan. Misalnya, jika domain Anda adalah example.com, Anda harus menambahkan example.com dan test.example.com.

Sesuaikan pengaturan merek

Konfigurasikan pengaturan merek Anda di Dashboard agar sesuai dengan tampilan dan nuansa toko Anda.

Untuk melakukan ini, silakan ikuti langkah-langkah berikut:

1. Navigasikan ke Dashboard -> Pengaturan -> pengaturan Checkout -> Merek
2. Konfigurasikan pengaturan berikut:
   • Logo.
   • Warna merek dan aksen.
   • Tema, Gaya, dan Font.

Untuk informasi lebih lanjut tentang pengaturan merek, lihat dokumentasi kami.

Hubungkan penyedia pengiriman

Untuk mengutip pengiriman di checkout, Anda perlu menghubungkan penyedia pengiriman ke akun Zonos Anda. Ini akan memungkinkan Anda untuk mengaktifkan tingkat layanan pengiriman tertentu di checkout.

Untuk menghubungkan penyedia pengiriman, silakan ikuti langkah-langkah berikut:

1. Navigasikan ke Dashboard -> Pengaturan -> Pengiriman -> Tarif
2. Klik Tambahkan penyedia
3. Ikuti instruksi pengaturan penyedia.

Untuk informasi lebih lanjut tentang menghubungkan akun penyedia, lihat dokumentasi kami.

Atur zona pengiriman

Zona pengiriman memungkinkan Anda mengonfigurasi penyedia pengiriman dan tingkat layanan mana yang tersedia untuk berbagai wilayah di dunia.

Untuk mengatur zona pengiriman, silakan ikuti langkah-langkah berikut:

1. Navigasikan ke Dashboard -> Pengaturan -> Pengiriman -> Lokasi
2. Klik Zona baru
3. Masukkan nama zona dan pilih negara yang ingin Anda kirimkan.
4. Pilih penyedia dan tingkat layanan yang ingin Anda tawarkan.

Untuk informasi lebih lanjut tentang zona pengiriman, lihat dokumentasi kami.

Atur negara asal cadangan dan kode HS

Negara asal dan kode HS digunakan untuk menghitung bea dan pajak yang akurat.

Jika Anda tidak memberikan negara asal atau kode HS tertentu, kami akan menggunakan cadangan yang diatur di Dashboard.

Untuk mengatur Negara Asal dan kode HS cadangan Anda:

1. Navigasikan ke Dashboard -> Pengaturan -> Pengiriman -> Katalog.
2. Untuk negara asal, pilih negara di mana sebagian besar produk Anda diproduksi.
3. Untuk kode HS, masukkan kode HS produk Anda yang paling umum. Jika Anda tidak memiliki kode HS, navigasikan ke Classify di Dashboard dan masukkan nama serta deskripsi produk Anda untuk menghasilkan kode HS yang akurat.

Cuplikan JS Zonos adalah integrasi JavaScript sisi klien yang memungkinkan fungsionalitas global checkout di situs Anda. Ini berfungsi sebagai jembatan antara platform ecommerce Anda dan layanan Zonos, menangani:

• Pengalaman Checkout: Menampilkan UI checkout dan memproses pembayaran.
• Layanan Lokasi: Mendeteksi lokasi pengunjung dan mengelola konversi mata uang.
• Integrasi Keranjang: Terhubung dengan keranjang dan sistem pesanan yang ada.
• Keamanan: Memvalidasi domain dan mengautentikasi permintaan API.

Cuplikan ini dimuat secara asinkron untuk mencegah dampak pada kinerja situs Anda. Ini diinisialisasi dengan kredensial API toko Anda dan menangani semua interaksi sisi klien dengan aman. Implementasinya dirancang agar tidak mengganggu, memerlukan perubahan minimal pada alur checkout yang ada.

Berikut adalah contoh lengkap yang mencakup pemuatan skrip, inisialisasi, dan penanganan acara untuk referensi saat mengintegrasikan 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>

Catatan: Gantilah nilai placeholder (storeId, zonosApiKey, selectors, dll.) dengan nilai aktual Anda dari dasbor Zonos Anda.

Menangani caching browser

Kami merekomendasikan untuk menambahkan cap waktu atau pengidentifikasi unik lainnya ke URL untuk memastikan bahwa skrip tidak di-cache oleh browser. Ini akan memastikan bahwa versi terbaru dari skrip selalu dimuat. Ini ditunjukkan pada baris 10 dari contoh lengkap.

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

Autentikasi Zonos JS snippet

Setelah Anda memuat skrip JS Zonos, Anda perlu mengautentikasinya dengan memasukkan kunci API publik Zonos dan ID toko ke dalam fungsi Zonos.init. Kunci API publik yang digunakan untuk mengautentikasi Checkout dirancang untuk dapat dipublikasikan, yang berarti dapat digunakan dengan aman dalam kode frontend tanpa mengekspos informasi sensitif.

Untuk menemukan ID toko dan kunci API Anda, navigasikan ke Dashboard -> Settings -> Integrasi. Pastikan Anda tidak menggunakan Kunci API Rahasia, karena tidak dirancang untuk digunakan dalam kode frontend. Ini ditunjukkan pada baris 29 dan 30 dari contoh lengkap.

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 diperlukan saat menggunakan Checkout.

Hello bertanggung jawab untuk mendeteksi lokasi, bahasa, dan mata uang pengunjung, serta menampilkan informasi yang sesuai kepada mereka. Anda dapat mengonfigurasi semua pengaturan Hello di Dashboard atau dalam skrip JS Zonos. Jika Anda telah mengonfigurasi Hello di Dashboard, skrip akan memuat pengaturan tersebut dan menggunakannya. Jika Anda menentukan nilai apa pun dalam properti helloSettings dari fungsi Zonos.init, skrip akan menggunakan nilai tersebut sebagai pengganti seperti yang ditunjukkan di bawah ini.

Konfigurasi konversi mata uang di Hello dalam Skrip JS

Hello menggunakan pemilih CSS untuk mengidentifikasi elemen di situs Anda yang menampilkan informasi mata uang. Kirimkan pemilih ini ke properti helloSettings.currencyElementSelector dari fungsi Zonos.init sehingga Hello dapat mendeteksi dan menampilkan mata uang yang benar dari pembeli internasional.

Anda dapat menggunakan pemilih CSS yang valid di sini, misalnya #price, .price untuk memilih beberapa elemen yang berbeda. Ini ditunjukkan pada baris 23 dan 24 dari contoh lengkap.

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

Secara otomatis membuka Hello saat halaman dimuat

Secara default, Hello hanya akan terbuka ketika pengunjung mengklik tombol bendera. Jika Anda ingin secara otomatis membuka Hello saat halaman dimuat, Anda dapat memanggil fungsi Zonos.openHelloDialog() setelah skrip Zonos dimuat. Ini ditunjukkan pada baris 25 dan 26 dari contoh lengkap.

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

Checkout bertanggung jawab untuk memungkinkan pelanggan memasukkan informasi pengiriman dan penagihan mereka, menghitung landed cost, collect pembayaran, dan menyelesaikan pesanan.

Checkout akan berbagi data kontekstual dengan Hello, seperti lokasi pengunjung, bahasa, dan mata uang. Ini memastikan bahwa pengalaman pelanggan konsisten di seluruh proses belanja.

Anda dapat mengonfigurasi semua pengaturan Checkout di Dashboard dan skrip JS Zonos. Jika Anda telah mengonfigurasi Checkout di Dashboard, skrip akan memuat pengaturan tersebut dan menggunakannya. Jika Anda menentukan nilai apa pun dalam properti checkoutSettings dari fungsi Zonos.init, skrip akan menggunakan nilai tersebut sebagai gantinya.

Konfigurasi tombol 'tempatkan pesanan' dalam Skrip JS

Skrip JS Zonos akan secara otomatis mengenali pembeli internasional dan mengarahkan mereka ke alur Checkout. Namun, Anda perlu mengonfigurasi tombol 'tempatkan pesanan' di platform Anda untuk membuka Checkout saat diklik. Ini dapat dilakukan dengan mengirimkan pemilih CSS ke properti checkoutSettings.placeOrderButtonSelector dari fungsi Zonos.init.

Jika Anda memiliki beberapa tombol yang dapat digunakan untuk melakukan pemesanan, pastikan untuk mengirimkan pemilih untuk setiap tombol. Misalnya, #placeOrder, .place-order.

Ini ditunjukkan di baris 21 dari contoh lengkap.

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

Dengan Aman Membuat Detail Keranjang di Sisi Server

Untuk menampilkan detail keranjang kepada pelanggan, Anda perlu membuat fungsi sisi server yang akan memanggil API Zonos untuk membuat keranjang, dan kemudian mengirimkan ID keranjang tersebut kembali ke frontend Anda. Ini akan memastikan bahwa detail keranjang tidak diekspos kepada pelanggan dengan cara yang dapat dimanipulasi.

Panggilan API backend Anda akan menggunakan token kredensial GraphQL rahasia, yang berbeda dari token publik yang Anda gunakan untuk mengautentikasi skrip JS Zonos. Token ini dapat diambil di Dashboard -> Settings -> Integrasi. Token rahasia perlu dikirim sebagai header dalam panggilan API Anda.

Mutasi cartCreate menerima daftar item, yang harus diformat sesuai dengan skema item keranjang.

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

Kami menyarankan untuk membuat endpoint API di sisi server Anda dan kemudian memanggil endpoint tersebut dari integrasi JS frontend Anda, yang dijelaskan di langkah berikutnya.

Kirim ID keranjang ke Checkout melalui frontend

Setelah Anda membuat keranjang di sisi server Anda, Anda perlu mengirimkan ID keranjang ke skrip JS Zonos. Ini dapat dilakukan dengan menggunakan callback createCartId yang merupakan bagian dari fungsi Zonos.init. Checkout kemudian akan dengan aman mengambil detail keranjang dari Zonos saat dibuka, mencegah adanya manipulasi pada keranjang. Lihat contoh kode di bawah ini.

Nilai dari createCartId tidak dapat berupa nilai statis, itu harus berupa fungsi.

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

Untuk menyinkronkan pesanan antara sistem Anda dan Zonos Dashboard, terapkan panggilan API dan webhook berikut:

Mutasi yang Diperlukan

Webhook yang Diperlukan

Sebelum meluncurkan integrasi Checkout Anda, penting untuk menguji semua aspek integrasi secara menyeluruh untuk memastikan pengalaman pelanggan yang lancar. Ini termasuk menguji alur checkout, pemrosesan pembayaran, pembuatan pesanan, dan fungsionalitas webhook.

Ikuti panduan pengujian kami untuk memverifikasi bahwa integrasi Anda berfungsi dengan benar dan untuk mengidentifikasi serta memperbaiki masalah sebelum diluncurkan ke produksi.

Berikut adalah beberapa pertanyaan umum tentang proses integrasi.

Bagaimana Zonos menangani konfirmasi pesanan?

Zonos menyediakan halaman terima kasih bawaan yang dapat Anda gunakan untuk konfirmasi pesanan. Halaman ini akan selalu ditampilkan, bahkan jika pesanan gagal diimpor ke sistem Anda, memastikan bahwa pelanggan selalu menerima konfirmasi pembelian mereka.

Bisakah saya diberi tahu ketika pesanan dibuat?

Ya. Jika Anda ingin menerima notifikasi ketika pesanan dibuat, di Dashboard di bawah bagian Email dari pengaturan Checkout, Anda dapat memasukkan alamat email anggota tim yang harus diberi tahu ketika pesanan dibuat, dikirim, atau dibatalkan.