Integração personalizada

Para começar, entre em contato com nossa equipe de vendas para criar uma conta e assinar um contrato. Depois de assinar o contrato, você receberá dois microdepósitos em sua conta que precisam ser verificados.

Envie por e-mail os valores desses microdepósitos para accounting@zonos.com com o ID da sua loja no Dashboard (envie uma cópia para seu representante de vendas).

Após a verificação, seus detalhes bancários serão exibidos em Dashboard -> Configurações -> Faturamento.

Após criar sua conta do Zonos, você precisará configurar as configurações no Dashboard para garantir que o Checkout funcione corretamente com sua loja. Esta seção abrange todas as configurações essenciais do Dashboard.

Configurar pagamentos

Conecte uma conta bancária para receber pagamentos oportunos do Checkout. Os pagamentos são processados diariamente com um atraso de 2 dias a partir do pagamento capturado. Para fazer isso, siga estas etapas:

1. Acesse Dashboard -> Configurações -> Configurações do Checkout.
2. Clique em Adicionar conta bancária
3. Você será direcionado para um portal da Stripe para concluir a configuração e fornecer as seguintes informações:
   • Informações da conta bancária.
   • EIN da empresa.
   • Número de Seguro Social de um proprietário da empresa de 25%. Para mais detalhes sobre por que isso é necessário, consulte a documentação da Stripe.

Observação: Se precisar atualizar seu cronograma de pagamentos, entre em contato com support@zonos.com

Configurar domínios permitidos

O script JS do Zonos requer uma lista de domínios permitidos por motivos de segurança. Isso impede que sites não autorizados carreguem o script e garante que ele seja executado apenas em seus domínios aprovados. Sem essa configuração, o script retornará erros de permissão.

Para configurar isso:

1. Acesse Dashboard -> Configurações -> Configurações do Checkout
2. Em URLs, adicione seu domínio completo e quaisquer subdomínios onde o Checkout será usado. Por exemplo, se seu domínio for exemplo.com, você deve adicionar exemplo.com e teste.exemplo.com.

Personalizar configurações de marca

Configure suas configurações de marca no Dashboard para combinar com a aparência de sua loja.

Para fazer isso, siga estas etapas:

1. Acesse Dashboard -> Configurações -> Configurações do Checkout -> Marca
2. Configure as seguintes configurações:
   • Logotipo.
   • Cor da marca e de destaque.
   • Tema, Estilo e Fonte.

Para mais informações sobre as configurações de marca, consulte nossa documentação.

Conectar um transportador de envio

Para cotar o envio no checkout, você precisará conectar um transportador de envio à sua conta do Zonos. Isso permitirá que você habilite níveis de serviço de envio específicos no checkout.

Para conectar um transportador de envio, siga estas etapas:

1. Acesse Dashboard -> Configurações -> Envio -> Tarifas
2. Clique em Adicionar transportador
3. Siga as instruções de configuração do transportador.

Para mais detalhes sobre a conexão de contas de transportadoras, consulte nossa documentação.

Configurar zonas de envio

As zonas de envio permitem que você configure quais transportadoras e níveis de serviço de envio estão disponíveis para diferentes regiões do mundo.

Para configurar zonas de envio, siga estas etapas:

1. Acesse Dashboard -> Configurações -> Envio -> Locais
2. Clique em Nova zona
3. Insira um nome de zona e selecione os países para os quais deseja enviar.
4. Selecione a transportadora e o nível de serviço que deseja oferecer.

Para mais detalhes sobre zonas de envio, consulte nossa documentação.

Configurar um país de origem e código HS de fallback

O país de origem e o código HS são usados para calcular impostos e taxas com precisão.

Se você não fornecer um país de origem específico ou código HS, usaremos os fallbacks configurados no Dashboard.

Para configurar seu país de origem e código HS de fallback:

1. Acesse Dashboard -> Configurações -> Envio -> Catálogo.
2. Para o país de origem, selecione o país onde a maioria de seus produtos é fabricada.
3. Para o código HS, insira o código HS do seu produto mais comum. Se você não tiver um código HS, acesse Classify no Dashboard e insira o nome e a descrição do seu produto para gerar um código HS preciso.

O trecho de JS do Zonos é uma integração de JavaScript do lado do cliente que permite a funcionalidade global de checkout em seu site. Ele serve como a ponte entre sua plataforma de comércio eletrônico e os serviços do Zonos, lidando com:

• Experiência de Checkout: Renderiza a interface do checkout e processa pagamentos.
• Serviços de Localização: Detecta a localização do visitante e gerencia a conversão de moeda.
• Integração de Carrinho: Conecta-se ao seu carrinho existente e sistema de pedidos.
• Segurança: Valida domínios e autentica solicitações de API.

O trecho é carregado de forma assíncrona para evitar qualquer impacto no desempenho do seu site. Ele é inicializado com as credenciais da API da sua loja e lida com todas as interações do lado do cliente de forma segura. A implementação é projetada para ser não intrusiva, exigindo alterações mínimas no fluxo de checkout existente.

Abaixo está um exemplo completo que inclui o carregamento do script, inicialização e tratamento de eventos para referência ao integrar o 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>

Nota: Substitua os valores de espaço reservado (storeId, zonosApiKey, selectors, etc.) pelos seus valores reais do seu Zonos Dashboard.

Manipulando o cache do navegador

Recomendamos anexar um carimbo de data/hora ou outro identificador exclusivo à 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. Isso é mostrado na linha 10 do exemplo completo.

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

Autentique o Zonos snippet JS

Uma vez que você tenha carregado o script JS do Zonos, você precisa autenticá-lo passando uma chave pública da API do Zonos e o ID da loja na função Zonos.init. A chave pública da API usada para autenticar o Checkout é projetada para ser publicável, o que significa que pode ser usada com segurança no código do frontend sem expor informações sensíveis.

Para encontrar seu ID da loja e chave da API, navegue até Dashboard -> Configurações -> Integrações. Certifique-se de não usar uma chave da API secreta, pois não é projetada para ser usada no código do frontend. Isso é mostrado nas linhas 29 e 30 do exemplo completo.

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 é necessário ao usar Checkout.

Hello é responsável por detectar a localização, idioma e moeda do visitante, e exibir as informações apropriadas para ele. Você pode configurar todas as configurações do Hello no Dashboard ou no script JS do Zonos. Se você já configurou 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 dos anteriores, conforme mostrado abaixo.

Configurar conversão de moeda em Hello no Script JS

Hello usa seletores CSS para identificar elementos em seu site que exibem informações de moeda. Passe esses seletores para a propriedade helloSettings.currencyElementSelector da função Zonos.init para que Hello possa detectar e exibir a moeda correta do comprador internacional.

Você pode usar qualquer seletor CSS válido aqui, por exemplo #price, .price para selecionar vários elementos diferentes. Isso é mostrado nas linhas 23 e 24 do exemplo completo.

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

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 você deseja abrir automaticamente Hello quando a página carregar, pode chamar a função Zonos.openHelloDialog() assim que o script Zonos tiver sido carregado. Isso é mostrado nas linhas 25 e 26 do exemplo completo.

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

Checkout é responsável por permitir que o cliente insira suas informações de envio e cobrança, calcule landed cost, collect pagamento e complete o pedido.

Checkout compartilhará dados contextuais com 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.

Configurar o botão 'fazer pedido' no Script JS

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 'fazer pedido' em 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 fazer um pedido, certifique-se de passar um seletor para cada botão. Por exemplo, #placeOrder, .place-order.

Isso é mostrado na linha 21 do exemplo completo.

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

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 do 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 maneira que possa ser manipulada.

Sua chamada de API de 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 -> Configurações -> Integrações. O token secreto precisa ser passado como um cabeçalho em sua chamada de API.

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

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

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 de Zonos. Isso pode ser feito usando o callback createCartId, que faz parte da função Zonos.init. Checkout então recuperará com segurança os detalhes do carrinho de Zonos quando aberto, prevenindo qualquer adulteração do carrinho. Veja o exemplo de código abaixo.

O valor de createCartId não pode ser um valor estático, deve ser uma função.

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

Para sincronizar pedidos entre seu sistema e o Zonos Dashboard, implemente essas chamadas de API e webhooks:

Mutations Necessárias

Webhooks Necessários

Antes de entrar em operação com sua integração do Checkout, é importante testar minuciosamente todos os aspectos da integração para garantir uma experiência suave para o cliente. Isso inclui testar o fluxo de checkout, processamento de pagamentos, criação de pedidos e funcionalidade de webhook.

Consulte nosso guia de testes para verificar se sua integração está funcionando corretamente e para identificar e corrigir quaisquer problemas antes de lançar em produção.

Abaixo estão algumas perguntas comuns sobre o processo de integração.

Como o Zonos lida com a confirmação de pedidos?

Zonos fornece uma página de agradecimento integrada que você pode usar para confirmações de pedidos. Esta página sempre será exibida, mesmo que um pedido falhe ao ser importado para seu sistema, garantindo que os clientes sempre recebam a confirmação de sua compra.

Posso ser notificado quando um pedido é criado?

Sim. Se você deseja receber notificações quando um pedido é criado, no Dashboard, na seção Email das configurações do Checkout, você pode inserir o endereço de e-mail dos membros da equipe que devem ser notificados quando um pedido é criado, enviado ou cancelado.