Индивидуальная интеграция

Чтобы начать, пожалуйста, свяжитесь с нашей командой продаж, чтобы создать учетную запись и подписать соглашение. После подписания соглашения вы получите два микро-депозита на свой счет, которые необходимо будет подтвердить.

Пожалуйста, отправьте эти суммы микро-депозитов на accounting@zonos.com с вашим идентификатором магазина Dashboard (копия вашему менеджеру по продажам).

После подтверждения ваши банковские реквизиты будут отображаться в Dashboard -> Настройки -> Биллинг.

После создания учетной записи Zonos вам необходимо настроить параметры в Dashboard, чтобы гарантировать правильную работу Checkout с вашим магазином. Этот раздел охватывает все основные конфигурации Dashboard.

Настройка выплат

Подключите банковский счет, чтобы получать своевременные выплаты от Checkout. Выплаты обрабатываются ежедневно с задержкой в 2 дня с момента получения платежа. Для этого выполните следующие шаги:

1. Перейдите в Dashboard -> Настройки -> настройки Checkout.
2. Нажмите Добавить банковский счет
3. Вы будете перенаправлены в портал Stripe для завершения настройки и предоставления следующей информации:
   • Информация о банковском счете.
   • EIN компании.
   • Номер социального страхования владельца компании с долей 25%. Для получения дополнительной информации о том, почему это требуется, смотрите документацию Stripe.

Примечание: Если вам нужно обновить график выплат, пожалуйста, свяжитесь с support@zonos.com

Настройка разрешенных доменов

JS-скрипт Zonos требует список разрешенных доменов для обеспечения безопасности. Это предотвращает загрузку скрипта на несанкционированных сайтах и гарантирует, что он работает только на ваших одобренных доменах. Без этой конфигурации скрипт будет возвращать ошибки разрешения.

Чтобы настроить это:

1. Перейдите в Dashboard -> Настройки -> настройки Checkout
2. В разделе URLs добавьте ваш полный домен и любые поддомены, на которых будет использоваться Checkout. Например, если ваш домен example.com, вы должны добавить example.com и test.example.com.

Настройка параметров брендинга

Настройте параметры брендинга в Dashboard, чтобы они соответствовали внешнему виду вашего магазина.

Для этого выполните следующие шаги:

1. Перейдите в Dashboard -> Настройки -> настройки Checkout -> Брендинг
2. Настройте следующие параметры:
   • Логотип.
   • Цвета бренда и акцента.
   • Тема, стиль и шрифт.

Для получения дополнительной информации о параметрах брендинга смотрите нашу документацию.

Подключение службы доставки

Чтобы рассчитать стоимость доставки на checkout, вам необходимо подключить службу доставки к вашей учетной записи Zonos. Это позволит вам включить определенные уровни обслуживания доставки на checkout.

Чтобы подключить службу доставки, выполните следующие шаги:

1. Перейдите в Dashboard -> Настройки -> Доставка -> Тарифы
2. Нажмите Добавить перевозчика
3. Следуйте инструкциям по настройке перевозчика.

Для получения дополнительной информации о подключении учетных записей перевозчиков смотрите нашу документацию.

Настройка зон доставки

Зоны доставки позволяют вам настроить, какие службы доставки и уровни обслуживания доступны для различных регионов мира.

Чтобы настроить зоны доставки, выполните следующие шаги:

1. Перейдите в Dashboard -> Настройки -> Доставка -> Локации
2. Нажмите Новая зона
3. Введите название зоны и выберите страны, в которые вы хотите отправлять.
4. Выберите перевозчика и уровень обслуживания, который вы хотите предложить.

Для получения дополнительной информации о зонах доставки смотрите нашу документацию.

Настройка страны происхождения и кода HS по умолчанию

Страна происхождения и код HS используются для расчета точных пошлин и налогов.

Если вы не укажете конкретную страну происхождения или код HS, мы будем использовать значения по умолчанию, установленные в Dashboard.

Чтобы установить страну происхождения и код HS по умолчанию:

1. Перейдите в Dashboard -> Настройки -> Доставка -> Каталог.
2. Для страны происхождения выберите страну, в которой производится большинство ваших продуктов.
3. Для кода HS введите код HS вашего самого распространенного продукта. Если у вас нет кода HS, перейдите к Classify в Dashboard и введите название и описание вашего продукта, чтобы сгенерировать точный код HS.

JS-скрипт Zonos — это интеграция JavaScript на стороне клиента, которая обеспечивает глобальную функциональность checkout на вашем сайте. Он служит мостом между вашей платформой электронной коммерции и услугами Zonos, обрабатывая:

• Опыт Checkout: Отображает интерфейс checkout и обрабатывает платежи.
• Службы местоположения: Определяет местоположение посетителя и управляет конверсией валюты.
• Интеграция корзины: Подключается к вашей существующей корзине и системе заказов.
• Безопасность: Проверяет домены и аутентифицирует API-запросы.

Скрипт загружается асинхронно, чтобы предотвратить любое влияние на производительность вашего сайта. Он инициализируется с использованием учетных данных API вашего магазина и безопасно обрабатывает все взаимодействия на стороне клиента. Реализация разработана так, чтобы быть ненавязчивой, требуя минимальных изменений в вашем существующем процессе checkout.

Ниже приведен полный пример, который включает загрузку скрипта, инициализацию и обработку событий для справки при интеграции 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>

Примечание: Замените значения-заполнители (storeId, zonosApiKey, selectors и т. д.) на ваши реальные значения из вашей Zonos панели управления.

Обработка кэширования браузера

Мы рекомендуем добавлять временную метку или другой уникальный идентификатор к URL, чтобы гарантировать, что скрипт не кэшируется браузером. Это обеспечит загрузку последней версии скрипта. Это показано в строке 10 полного примера.

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

Аутентификация Zonos JS фрагмента

После загрузки скрипта Zonos вам необходимо аутентифицировать его, передав публичный Zonos API ключ и идентификатор магазина в функцию Zonos.init. Публичный API ключ, используемый для аутентификации Checkout, предназначен для публикации, что означает, что его можно безопасно использовать в коде фронтенда, не раскрывая никакой конфиденциальной информации.

Чтобы найти ваш идентификатор магазина и API ключ, перейдите в Dashboard -> Settings -> Integrations. Убедитесь, что вы не используете Secret API key, так как он не предназначен для использования в коде фронтенда. Это показано в строках 29 и 30 полного примера.

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.

Hello отвечает за определение местоположения, языка и валюты посетителя, а также за отображение соответствующей информации. Вы можете настроить все настройки Hello в Dashboard или в JS-скрипте Zonos. Если вы уже настроили Hello в Dashboard, скрипт загрузит эти настройки и использует их. Если вы укажете какие-либо значения в свойстве helloSettings функции Zonos.init, скрипт будет использовать эти значения вместо указанных ниже.

Настройка конверсии валюты в Hello в JS-скрипте

Hello использует CSS-селекторы для определения элементов на вашем сайте, которые отображают информацию о валюте. Передайте эти селекторы в свойство helloSettings.currencyElementSelector функции Zonos.init, чтобы Hello мог определить и отобразить правильную валюту международного покупателя.

Вы можете использовать любой действительный CSS-селектор здесь, например #price, .price, чтобы выбрать несколько различных элементов. Это показано в строках 23 и 24 полного примера.

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

Автоматически открывать Hello при загрузке страницы

По умолчанию Hello будет открываться только при нажатии посетителем на кнопку флага. Если вы хотите автоматически открыть Hello при загрузке страницы, вы можете вызвать функцию Zonos.openHelloDialog(), как только скрипт Zonos будет загружен. Это показано в строках 25 и 26 полного примера.

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

Checkout отвечает за то, чтобы клиент мог ввести свою информацию для доставки и выставления счета, рассчитать landed cost, collect оплату и завершить заказ.

Checkout будет делиться контекстными данными с Hello, такими как местоположение посетителя, язык и валюта. Это гарантирует, что опыт клиента будет последовательным на протяжении всего процесса покупок.

Вы можете настроить все параметры Checkout как в Dashboard, так и в скрипте Zonos JS. Если вы уже настроили Checkout в Dashboard, скрипт загрузит эти настройки и использует их. Если вы укажете какие-либо значения в свойстве checkoutSettings функции Zonos.init, скрипт будет использовать эти значения вместо.

Настройка кнопки 'разместить заказ' в JS Script

Скрипт Zonos JS автоматически распознает международных покупателей и направляет их в поток Checkout. Однако вам нужно будет настроить кнопку 'разместить заказ' на вашей платформе, чтобы она открывала Checkout при нажатии. Это можно сделать, передав CSS-селектор в свойство checkoutSettings.placeOrderButtonSelector функции Zonos.init.

Если у вас есть несколько кнопок, которые могут использоваться для размещения заказа, убедитесь, что вы передали селектор для каждой кнопки. Например, #placeOrder, .place-order.

Это показано в строке 21 полного примера.

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

Безопасное создание деталей корзины на стороне сервера

Чтобы отобразить детали корзины клиенту, вам необходимо создать серверную функцию, которая будет вызывать API Zonos для создания корзины, а затем передавать этот идентификатор корзины обратно на ваш фронтенд. Это обеспечит защиту деталей корзины от раскрытия клиенту таким образом, чтобы их можно было манипулировать.

Ваш вызов API на стороне сервера будет использовать секретный токен учетных данных GraphQL, который отличается от публичного токена, который вы используете для аутентификации JS-скрипта Zonos. Этот токен можно получить в Dashboard -> Settings -> Integrations. Секретный токен необходимо передать в заголовке вашего вызова API.

Мутация cartCreate принимает список элементов, который должен быть отформатирован в соответствии с схемой элемента корзины.

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

Мы предлагаем создать конечную точку API на вашей стороне сервера, а затем вызывать эту конечную точку из вашей интеграции JS на стороне клиента, что подробно описано на следующем шаге.

Передача идентификатора корзины в Checkout через фронтенд

После того как вы создали корзину на стороне сервера, вам необходимо передать идентификатор корзины в JS-скрипт Zonos. Это можно сделать, используя обратный вызов createCartId, который является частью функции Zonos.init. Checkout затем безопасно получит детали корзины из Zonos при открытии, предотвращая любое вмешательство в корзину. См. пример кода ниже.

Значение createCartId не может быть статическим значением, это должна быть функция.

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

Чтобы синхронизировать заказы между вашей системой и Zonos Dashboard, реализуйте эти API вызовы и вебхуки:

Обязательные мутации

Обязательные вебхуки

Перед тем как запустить вашу интеграцию Checkout, важно тщательно протестировать все аспекты интеграции, чтобы обеспечить плавный опыт для клиентов. Это включает в себя тестирование процесса checkout, обработки платежей, создания заказов и функциональности вебхуков.

Следуйте нашему руководству по тестированию, чтобы убедиться, что ваша интеграция работает правильно, и выявить и исправить любые проблемы перед запуском в продукцию.

Ниже приведены некоторые часто задаваемые вопросы о процессе интеграции.

Как Zonos обрабатывает подтверждение заказа?

Zonos предоставляет встроенную страницу благодарности, которую вы можете использовать для подтверждений заказов. Эта страница всегда будет отображаться, даже если заказ не удается импортировать в вашу систему, что гарантирует, что клиенты всегда получают подтверждение своей покупки.

Могу ли я получать уведомления, когда заказ создан?

Да. Если вы хотите получать уведомления, когда заказ создан, в Dashboard в разделе Email настроек Checkout вы можете ввести адреса электронной почты членов команды, которые должны получать уведомления, когда заказ создан, отправлен или отменен.