Integração personalizada

O script de Elementos do Zonos está disponível no seguinte URL:

<script src="https://js.zonos.com/dist/scripts/loadZonos.js" />

Lidar com o cache do navegador

Também costumamos recomendar anexar um carimbo de data/hora ou outro identificador único à URL para garantir que o script não seja armazenado em cache pelo navegador. Isso garantirá que a versão mais recente do script seja sempre carregada. Por exemplo:

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://js.zonos.com/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://js.zonos.com/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
      script.addEventListener(
        'load',
        () => {
          // Initialize the script here (instructions in next section)
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>

Depois de carregar o script JS do Zonos, você precisa autenticá-lo passando uma Zonos chave de API e ID da loja para a função Zonos.init. As chaves de API usadas para autenticar o Checkout são projetadas para serem publicáveis, o que significa que podem ser usadas com segurança no código frontend sem expor informações sensíveis.

Zonos.init({
  // ... other fields
  zonosApiKey: 'API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Para garantir que o script JS do Zonos seja carregado apenas em sites permitidos, filtramos as solicitações com base em uma lista de "domínios permitidos". Esta lista é configurada no Dashboard. Sem essa configuração, o script JS do Zonos retornará erros de permissão em vez de carregar corretamente.

Para atualizar seus domínios permitidos:

1. Vá para Dashboard -> Configurações -> Configurações do Checkout.
2. Na seção Domínios permitidos, adicione o(s) domínio(s) onde você integrará o Checkout.
3. Clique em Salvar.

O Hello usa seletores CSS para identificar elementos em seu site que exibem informações de moeda. Você precisará passar esses seletores para a propriedade helloSettings.currencyElementSelector da função Zonos.init.

Você pode usar qualquer seletor CSS válido aqui, por exemplo #price, .price para selecionar vários elementos diferentes.

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

Hello tem a capacidade de verificar itens restritos enquanto o comprador navega e impedi-los de serem adicionados ao carrinho. Para que isso funcione, Hello precisa saber informações adicionais sobre o item, como o nome e a descrição, bem como o "botão adicionar ao carrinho". Você pode passar seletores CSS para Hello para permitir que ele raspe essas informações da página.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    productAddToCartElementSelector: '.add-to-cart',
    productDescriptionElementSelector: '.description',
    productPriceElementSelector: '.price',
    productTitleElementSelector: '.title',
  },
});

Por padrão, Hello só será aberto quando o visitante clicar no botão da bandeira. Se deseja abrir automaticamente Hello ao carregar a página, pode chamar a função Zonos.openHelloDialog() assim que o script do Zonos tiver carregado.

Zonos.init({
  // ... other fields
});

Zonos.openHelloDialog();

O script JS do Zonos reconhecerá automaticamente os compradores internacionais e os direcionará para o fluxo do Checkout. No entanto, você precisará configurar o botão 'finalizar pedido' na sua plataforma para abrir o Checkout quando clicado. Isso pode ser feito passando um seletor CSS para a propriedade checkoutSettings.placeOrderButtonSelector da função Zonos.init.

Se você tiver vários botões que podem ser usados para finalizar um pedido, certifique-se de passar um seletor que corresponda a todos eles. Por exemplo, #placeOrder, .place-order corresponderá tanto a #placeOrder quanto a .place-order.

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

A função buildCartDetail é responsável por retornar os detalhes do carrinho em um formato que a interface do Checkout possa entender e exibir. Esta função é chamada assim que o cliente chega à página de checkout, garantindo que os detalhes do carrinho sejam exibidos com precisão na primeira página do Checkout. Por favor, note que isso não é usado para cálculos - isso é tratado no próximo passo.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildCartDetail: async () => {
      // ... Your existing buildCartDetail implementation
      // This should return cart details for UI display
    },
  },
});

Esquema do item do carrinho

A função buildCartDetail deve retornar uma matriz de itens do carrinho. Abaixo está uma tabela detalhando a estrutura de cada objeto CartItem:

A função buildLandedCost lida com o cálculo seguro do landed cost. Ela é invocada após o cliente inserir suas informações de envio. Esta função calcula as taxas de envio e outros custos necessários, que são então exibidos na página subsequente do Checkout.

É importante que você lide com a lógica de cálculo do landed cost no lado do servidor, pois esta é a única maneira de garantir que os detalhes do carrinho não sejam expostos ao navegador do cliente. Se você estiver usando uma arquitetura serverless, pode usar uma função serverless para lidar com o cálculo do landed cost. A função buildLandedCost deve simplesmente chamar a função serverless/ponto de extremidade da API e retornar o resultado.

No lado do servidor, você pode usar a API do Zonos Checkout para calcular o landed cost usando a seguinte solicitação POST. Você precisará passar a chave da API que tem usado para o script JS do Zonos no cabeçalho credentialToken.

https://v1.route.js.zonos.com/api/zonos-elements/calculate-landed-cost

{
  "billingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  },
  "billingContact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "checkoutSessionId": "xyz789",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "items": [
    {
      "amount": 150,
      "currencyCode": "USD",
      "name": "Product Name",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  }
}

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // This should return the landed cost calculation
    },
  },
});