Tích hợp tùy chỉnh

Để bắt đầu, vui lòng liên hệ với đội ngũ bán hàng của chúng tôi để tạo tài khoản và ký hợp đồng. Sau khi hợp đồng được ký, bạn sẽ nhận được hai khoản tiền gửi nhỏ vào tài khoản của bạn cần được xác minh.

Vui lòng gửi email các khoản tiền gửi nhỏ này đến accounting@zonos.com với ID cửa hàng Dashboard của bạn (CC đại diện bán hàng của bạn).

Sau khi được xác minh, thông tin ngân hàng của bạn sẽ hiển thị trong Dashboard -> Cài đặt -> Thanh toán.

Sau khi tạo tài khoản Zonos, bạn sẽ cần cấu hình cài đặt trong Dashboard để đảm bảo Checkout hoạt động đúng cách với cửa hàng của bạn. Phần này bao gồm tất cả các cấu hình cần thiết trong Dashboard.

Thiết lập thanh toán

Kết nối một tài khoản ngân hàng để nhận thanh toán kịp thời từ Checkout. Thanh toán được xử lý hàng ngày trong vòng 2 ngày kể từ khi thanh toán được ghi nhận. Để thực hiện điều này, vui lòng làm theo các bước sau:

1. Điều hướng đến Dashboard -> Cài đặt -> cài đặt Checkout.
2. Nhấp vào Thêm tài khoản ngân hàng
3. Bạn sẽ được chuyển đến cổng thông tin Stripe để hoàn tất thiết lập và cung cấp các thông tin sau:
   • Thông tin tài khoản ngân hàng.
   • Số EIN của công ty.
   • Số An sinh xã hội của một chủ sở hữu công ty 25%. Để biết thêm chi tiết về lý do tại sao điều này là cần thiết, xem tài liệu của Stripe tại đây.

Lưu ý: Nếu bạn cần cập nhật lịch trình thanh toán của mình, vui lòng liên hệ với support@zonos.com

Thiết lập miền được phép

Kịch bản JS của Zonos yêu cầu một danh sách các miền được phép vì lý do bảo mật. Điều này ngăn chặn các trang không được ủy quyền tải kịch bản và đảm bảo nó chỉ chạy trên các miền đã được phê duyệt của bạn. Nếu không có cấu hình này, kịch bản sẽ trả về lỗi quyền truy cập.

Để thiết lập điều này:

1. Điều hướng đến Dashboard -> Cài đặt -> cài đặt Checkout
2. Dưới URLs, thêm miền đầy đủ của bạn và bất kỳ miền phụ nào mà Checkout sẽ được sử dụng. Ví dụ, nếu miền của bạn là example.com, bạn nên thêm example.com và test.example.com.

Tùy chỉnh cài đặt thương hiệu

Cấu hình cài đặt thương hiệu của bạn trong Dashboard để phù hợp với giao diện và cảm nhận của cửa hàng bạn.

Để thực hiện điều này, vui lòng làm theo các bước sau:

1. Điều hướng đến Dashboard -> Cài đặt -> cài đặt Checkout -> Thương hiệu
2. Cấu hình các cài đặt sau:
   • Logo.
   • Màu sắc thương hiệu và màu sắc nhấn.
   • Chủ đề, Kiểu và Phông chữ.

Để biết thêm thông tin về cài đặt thương hiệu, xem tài liệu của chúng tôi tại đây.

Kết nối một nhà vận chuyển

Để báo giá vận chuyển tại checkout, bạn sẽ cần kết nối một nhà vận chuyển với tài khoản Zonos của bạn. Điều này sẽ cho phép bạn kích hoạt các cấp độ dịch vụ vận chuyển cụ thể tại checkout.

Để kết nối một nhà vận chuyển, vui lòng làm theo các bước sau:

1. Điều hướng đến Dashboard -> Cài đặt -> Vận chuyển -> Giá
2. Nhấp vào Thêm nhà vận chuyển
3. Làm theo hướng dẫn thiết lập nhà vận chuyển.

Để biết thêm chi tiết về việc kết nối tài khoản nhà vận chuyển, xem tài liệu của chúng tôi tại đây.

Thiết lập khu vực vận chuyển

Khu vực vận chuyển cho phép bạn cấu hình các nhà vận chuyển và cấp độ dịch vụ nào có sẵn cho các khu vực khác nhau trên thế giới.

Để thiết lập khu vực vận chuyển, vui lòng làm theo các bước sau:

1. Điều hướng đến Dashboard -> Cài đặt -> Vận chuyển -> Địa điểm
2. Nhấp vào Khu vực mới
3. Nhập tên khu vực và chọn các quốc gia bạn muốn vận chuyển đến.
4. Chọn nhà vận chuyển và cấp độ dịch vụ bạn muốn cung cấp.

Để biết thêm chi tiết về khu vực vận chuyển, xem tài liệu của chúng tôi tại đây.

Thiết lập quốc gia xuất xứ dự phòng và mã HS

Quốc gia xuất xứ và mã HS được sử dụng để tính toán chính xác thuế và phí.

Nếu bạn không cung cấp một quốc gia xuất xứ hoặc mã HS cụ thể, chúng tôi sẽ sử dụng các giá trị dự phòng được thiết lập trong Dashboard.

Để thiết lập Quốc gia Xuất xứ và mã HS dự phòng của bạn:

1. Điều hướng đến Dashboard -> Cài đặt -> Vận chuyển -> Danh mục.
2. Đối với quốc gia xuất xứ, chọn quốc gia nơi phần lớn sản phẩm của bạn được sản xuất.
3. Đối với mã HS, nhập mã HS của sản phẩm phổ biến nhất của bạn. Nếu bạn không có mã HS, hãy điều hướng đến Classify trong Dashboard và nhập tên và mô tả sản phẩm của bạn để tạo mã HS chính xác.

Đoạn mã JS của Zonos là một tích hợp JavaScript phía khách hàng cho phép chức năng checkout toàn cầu trên trang web của bạn. Nó hoạt động như cầu nối giữa nền tảng thương mại điện tử của bạn và các dịch vụ của Zonos, xử lý:

• Trải nghiệm Checkout: Hiển thị giao diện checkout và xử lý thanh toán.
• Dịch vụ vị trí: Phát hiện vị trí của khách truy cập và quản lý chuyển đổi tiền tệ.
• Tích hợp giỏ hàng: Kết nối với giỏ hàng và hệ thống đơn hàng hiện có của bạn.
• Bảo mật: Xác thực miền và xác thực các yêu cầu API.

Đoạn mã được tải không đồng bộ để ngăn chặn bất kỳ tác động nào đến hiệu suất của trang web của bạn. Nó khởi tạo với thông tin xác thực API của cửa hàng bạn và xử lý tất cả các tương tác phía khách hàng một cách an toàn. Việc triển khai được thiết kế không gây cản trở, yêu cầu thay đổi tối thiểu đối với quy trình checkout hiện có của bạn.

Dưới đây là một ví dụ hoàn chỉnh bao gồm việc tải kịch bản, khởi tạo và xử lý sự kiện để tham khảo khi tích hợp 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>

Lưu ý: Thay thế các giá trị giữ chỗ (storeId, zonosApiKey, selectors, v.v.) bằng các giá trị thực tế của bạn từ bảng điều khiển Zonos.

Xử lý bộ nhớ cache của trình duyệt

Chúng tôi khuyên bạn nên thêm một dấu thời gian hoặc một định danh duy nhất khác vào URL để đảm bảo rằng kịch bản không bị bộ nhớ cache bởi trình duyệt. Điều này sẽ đảm bảo rằng phiên bản mới nhất của kịch bản luôn được tải. Điều này được thể hiện trong dòng 10 của ví dụ hoàn chỉnh.

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

Xác thực đoạn mã JS của Zonos

Sau khi bạn đã tải đoạn mã JS của Zonos, bạn cần xác thực nó bằng cách truyền một khóa API công khai Zonos và ID cửa hàng vào hàm Zonos.init. Khóa API công khai được sử dụng để xác thực Checkout được thiết kế để có thể công khai, có nghĩa là nó có thể được sử dụng an toàn trong mã frontend mà không làm lộ bất kỳ thông tin nhạy cảm nào.

Để tìm ID cửa hàng và khóa API của bạn, hãy điều hướng đến Dashboard -> Settings -> Integrations. Đảm bảo rằng bạn không sử dụng Secret API key, vì nó không được thiết kế để sử dụng trong mã frontend. Điều này được thể hiện trong các dòng 29 và 30 của ví dụ hoàn chỉnh.

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 là cần thiết khi sử dụng Checkout.

Hello có trách nhiệm phát hiện vị trí, ngôn ngữ và tiền tệ của khách truy cập, và hiển thị thông tin phù hợp cho họ. Bạn có thể cấu hình tất cả các cài đặt Hello trong Dashboard hoặc trong script JS của Zonos. Nếu bạn đã cấu hình Hello trong Dashboard, script sẽ tải các cài đặt đó và sử dụng chúng. Nếu bạn chỉ định bất kỳ giá trị nào trong thuộc tính helloSettings của hàm Zonos.init, script sẽ sử dụng các giá trị đó thay thế như được hiển thị bên dưới.

Cấu hình chuyển đổi tiền tệ trong Hello trong Script JS

Hello sử dụng các bộ chọn CSS để xác định các phần tử trên trang web của bạn hiển thị thông tin tiền tệ. Chuyển các bộ chọn này vào thuộc tính helloSettings.currencyElementSelector của hàm Zonos.init để Hello có thể phát hiện và hiển thị đúng tiền tệ của người mua sắm quốc tế.

Bạn có thể sử dụng bất kỳ bộ chọn CSS hợp lệ nào ở đây, ví dụ #price, .price để chọn nhiều phần tử khác nhau. Điều này được hiển thị trong dòng 23 và 24 của ví dụ hoàn chỉnh.

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

Tự động mở Hello khi tải trang

Theo mặc định, Hello chỉ mở khi người truy cập nhấp vào nút cờ. Nếu bạn muốn tự động mở Hello khi trang tải, bạn có thể gọi hàm Zonos.openHelloDialog() ngay sau khi script Zonos đã được tải. Điều này được thể hiện trong dòng 25 và 26 của ví dụ hoàn chỉnh.

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

Checkout chịu trách nhiệm cho phép khách hàng nhập thông tin giao hàng và thanh toán, tính toán landed cost, collect thanh toán, và hoàn tất đơn hàng.

Checkout sẽ chia sẻ dữ liệu ngữ cảnh với Hello, chẳng hạn như vị trí của khách truy cập, ngôn ngữ và tiền tệ. Điều này đảm bảo rằng trải nghiệm của khách hàng là nhất quán trong toàn bộ quá trình mua sắm.

Bạn có thể cấu hình tất cả các cài đặt của Checkout trong cả Dashboard và tập lệnh JS của Zonos. Nếu bạn đã cấu hình Checkout trong Dashboard, tập lệnh sẽ tải các cài đặt đó và sử dụng chúng. Nếu bạn chỉ định bất kỳ giá trị nào trong thuộc tính checkoutSettings của hàm Zonos.init, tập lệnh sẽ sử dụng những giá trị đó thay thế.

Cấu hình nút 'đặt hàng' trong Tập lệnh JS

Tập lệnh JS của Zonos sẽ tự động nhận diện người mua sắm quốc tế và hướng dẫn họ đến quy trình Checkout. Tuy nhiên, bạn sẽ cần cấu hình nút 'đặt hàng' trên nền tảng của bạn để mở Checkout khi được nhấp. Điều này có thể được thực hiện bằng cách truyền một bộ chọn CSS vào thuộc tính checkoutSettings.placeOrderButtonSelector của hàm Zonos.init.

Nếu bạn có nhiều nút có thể được sử dụng để đặt hàng, hãy đảm bảo truyền vào một bộ chọn cho mỗi nút. Ví dụ, #placeOrder, .place-order.

Điều này được hiển thị trong dòng 21 của ví dụ hoàn chỉnh.

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

Tạo chi tiết giỏ hàng một cách an toàn trên máy chủ

Để hiển thị chi tiết giỏ hàng cho khách hàng, bạn cần tạo một hàm trên máy chủ sẽ gọi API Zonos để tạo một giỏ hàng, và sau đó truyền ID giỏ hàng đó trở lại giao diện người dùng của bạn. Điều này sẽ đảm bảo rằng chi tiết giỏ hàng không bị lộ ra cho khách hàng theo cách có thể bị thao túng.

Cuộc gọi API phía backend của bạn sẽ sử dụng một mã thông báo xác thực GraphQL bí mật, khác với mã thông báo công khai mà bạn sử dụng để xác thực tập lệnh JS Zonos. Mã thông báo này có thể được lấy trong Dashboard -> Settings -> Integrations. Mã thông báo bí mật cần được truyền dưới dạng tiêu đề trong cuộc gọi API của bạn.

Biến thể cartCreate chấp nhận một danh sách các mặt hàng, mà nên được định dạng theo lược đồ mặt hàng giỏ hàng.

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

Chúng tôi đề xuất tạo một điểm cuối API trên máy chủ của bạn và sau đó gọi điểm cuối đó từ tích hợp JS phía frontend của bạn, điều này được chi tiết trong bước tiếp theo.

Truyền ID giỏ hàng đến Checkout qua frontend

Khi bạn đã tạo một giỏ hàng trên máy chủ của mình, bạn cần truyền ID giỏ hàng đến tập lệnh JS của Zonos. Điều này có thể được thực hiện bằng cách sử dụng callback createCartId, là một phần của hàm Zonos.init. Checkout sẽ sau đó an toàn lấy thông tin giỏ hàng từ Zonos khi được mở, ngăn chặn bất kỳ sự can thiệp nào với giỏ hàng. Xem ví dụ mã dưới đây.

Giá trị của createCartId không thể là một giá trị tĩnh, nó phải là một hàm.

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

Để đồng bộ hóa đơn hàng giữa hệ thống của bạn và Zonos Dashboard, hãy triển khai các cuộc gọi API và webhook sau:

Các biến đổi cần thiết

Các webhook cần thiết

Trước khi chính thức ra mắt tích hợp Checkout của bạn, điều quan trọng là phải kiểm tra kỹ lưỡng tất cả các khía cạnh của tích hợp để đảm bảo trải nghiệm khách hàng suôn sẻ. Điều này bao gồm việc kiểm tra quy trình checkout, xử lý thanh toán, tạo đơn hàng và chức năng webhook.

Theo dõi hướng dẫn kiểm tra của chúng tôi để xác minh rằng tích hợp của bạn đang hoạt động chính xác và để xác định và khắc phục bất kỳ vấn đề nào trước khi ra mắt sản xuất.

Dưới đây là một số câu hỏi thường gặp về quy trình tích hợp.

Zonos xử lý xác nhận đơn hàng như thế nào?

Zonos cung cấp một trang cảm ơn tích hợp sẵn mà bạn có thể sử dụng cho các xác nhận đơn hàng. Trang này sẽ luôn được hiển thị, ngay cả khi một đơn hàng không được nhập vào hệ thống của bạn, đảm bảo rằng khách hàng luôn nhận được xác nhận về việc mua hàng của họ.

Tôi có thể được thông báo khi một đơn hàng được tạo không?

Có. Nếu bạn muốn nhận thông báo khi một đơn hàng được tạo, trong Dashboard dưới phần Email của cài đặt Checkout, bạn có thể nhập địa chỉ email của các thành viên trong nhóm mà nên được thông báo khi một đơn hàng được tạo, đã được gửi hoặc đã bị hủy.