DOCS

Integração personalizada

Entrar
Agendar uma demonstração
Checkout•
InícioEcommerce global Integração Integrar Checkout Integração personalizada

Integração personalizada

Construa uma integração de Checkout de ponta a ponta em seu site personalizado.

Este guia cobre os aspectos técnicos de completar uma integração completa do Zonos Checkout em seu site ou plataforma personalizada. É destinado a desenvolvedores que estão confortáveis trabalhando com JavaScript e têm experiência em desenvolvimento frontend. Todos os passos são obrigatórios, a menos que indicado de outra forma.

Pré-requisitos


Instale o script JS do Zonos 

Sua integração personalizada precisará incluir o trecho JavaScript do Zonos. Este script é responsável por renderizar a interface do usuário do Checkout, Zonos Hello, processar pagamentos e lidar com a detecção de geo-IP dos visitantes.

1

Instale o trecho JS do Zonos

O script Elements do Zonos está disponível na seguinte URL:

Zonos trecho JS

1
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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:

Zonos trecho de JS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<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',
        () => {
          // Initialize the script here (instructions in next section)
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>
2

Autenticar o trecho de código JS do Zonos

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 trecho de código JS

1
2
3
4
5
6
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
});
3

Definir domínios permitidos

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.

Configurar Zonos Hello 

Depois de configurar o script JS do Zonos, você precisa configurar o Hello para funcionar com seu site. O Hello é responsável por detectar a localização, idioma e moeda do visitante e exibir as informações apropriadas para ele. O Hello é necessário ao usar o Checkout.

Você pode configurar todas as configurações do Hello tanto no Dashboard quanto no script JS do Zonos. Se você já configurou o Hello no Dashboard, o script carregará essas configurações e as usará. Se você especificar quaisquer valores na propriedade helloSettings da função Zonos.init, o script usará esses valores em vez disso.

1

Configurar conversão de moeda

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

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Opcional — Abrir automaticamente Hello ao carregar a página

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 trecho de JS

1
2
3
4
5
6
7
8
9
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Configurar Zonos Checkout 

Uma vez que o Hello tenha sido configurado, você precisa configurar o Checkout para funcionar com o seu site. O Checkout é responsável por permitir que o cliente insira suas informações de envio, calcule o landed cost e complete o pedido.

O Checkout compartilhará dados contextuais com o Hello, como a localização do visitante, idioma e moeda. Isso garante que a experiência do cliente seja consistente em todo o processo de compra.

Você pode configurar todas as configurações do Checkout tanto no Dashboard quanto no script JS do Zonos. Se você já configurou o Checkout no Dashboard, o script carregará essas configurações e as usará. Se você especificar quaisquer valores na propriedade checkoutSettings da função Zonos.init, o script usará esses valores em vez disso.

1

Configurar o botão 'finalizar pedido'

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

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});
2

Crie detalhes do carrinho de forma segura no lado do servidor

Para exibir os detalhes do carrinho ao cliente, você precisa criar uma função no lado do servidor que chamará a API Zonos para criar um carrinho e, em seguida, passar esse ID do carrinho de volta para o seu frontend. Isso garantirá que os detalhes do carrinho não sejam expostos ao cliente de uma forma que possa ser manipulada.

Sua chamada de API no backend usará um token de credencial GraphQL secreto, que é diferente do token público que você usa para autenticar o script JS Zonos. Este token pode ser recuperado em Dashboard -> Settings -> Integrações. O token secreto precisa ser passado como um cabeçalho na sua chamada de API.

A mutação cartCreate aceita uma lista de itens, que deve ser formatada de acordo com o esquema de item do carrinho.

Exemplo de criação de carrinho no lado do servidor

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
// 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
}

Sugerimos criar um endpoint de API no seu lado do servidor e, em seguida, chamar esse endpoint a partir da sua integração JS no frontend, que é detalhada na próxima etapa.

3

Passe o ID do carrinho para Checkout via frontend

Uma vez que você tenha criado um carrinho no seu lado do servidor, você precisa passar o ID do carrinho para o script JS do Zonos. Isso pode ser feito usando o callback createCartId, que faz parte da função Zonos.init. O Checkout então recuperará com segurança os detalhes do carrinho do Zonos quando aberto, prevenindo qualquer adulteração do carrinho.

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // 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
    },
  },
});

Esta página foi útil?

Agendar uma demonstração

Dúvidas?

Obter suporte
© 2025 Zonoszonos.com
Nesta página:
  • Integração personalizada
  • Instale o script JS do Zonos
  • Configurar Zonos Hello
  • Configurar Zonos Checkout