Integración personalizada

El script de Elementos de Zonos está disponible en la siguiente URL:

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

Manejo de la caché del navegador

También recomendamos típicamente agregar una marca de tiempo u otro identificador único a la URL para asegurar que el script no sea almacenado en caché por el navegador. Esto garantizará que siempre se cargue la última versión del script. Por ejemplo:

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

Una vez que hayas cargado el script de JS de Zonos, necesitas autenticarlo pasando una Zonos API key y el ID de la tienda al interior de la función Zonos.init. Las claves API utilizadas para autenticar Checkout están diseñadas para ser publicables, lo que significa que se pueden utilizar de forma segura en el código frontend sin exponer información sensible.

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 asegurarse de que el script JS de Zonos solo se cargue en sitios permitidos, filtramos las solicitudes basándonos en una lista de "dominios permitidos". Esta lista se configura en el Dashboard. Sin esta configuración, el script JS de Zonos devolverá errores de permiso en lugar de cargarse correctamente.

Para actualizar sus dominios permitidos:

1. Vaya a Dashboard -> Configuración -> Configuración de Checkout.
2. En la sección Dominios permitidos, agregue el/los dominio(s) donde integrará Checkout.
3. Haga clic en Guardar.

Hello utiliza selectores CSS para identificar elementos en su sitio que muestran información de moneda. Necesitará pasar estos selectores a la propiedad helloSettings.currencyElementSelector de la función Zonos.init.

Puede usar cualquier selector CSS válido aquí, por ejemplo #price, .price para seleccionar múltiples elementos diferentes.

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

Hello tiene la capacidad de verificar artículos restringidos mientras el comprador navega y evitar que se agreguen al carrito. Para que esto funcione, Hello necesita conocer información adicional sobre el artículo, como el nombre y la descripción, así como el "botón de agregar al carrito". Puede pasar selectores CSS a Hello para permitirle extraer esta información de la página.

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

De forma predeterminada, Hello solo se abrirá cuando el visitante haga clic en el botón de la bandera. Si desea abrir automáticamente Hello al cargar la página, puede llamar a la función Zonos.openHelloDialog() una vez que se haya cargado el script de Zonos.

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

Zonos.openHelloDialog();

El script de Zonos JS reconocerá automáticamente a los compradores internacionales y los dirigirá al flujo de Checkout. Sin embargo, necesitarás configurar el botón 'realizar pedido' en tu plataforma para que abra Checkout cuando se haga clic. Esto se puede hacer pasando un selector CSS a la propiedad checkoutSettings.placeOrderButtonSelector de la función Zonos.init.

Si tienes múltiples botones que se pueden usar para realizar un pedido, asegúrate de pasar un selector que coincida con todos ellos. Por ejemplo, #placeOrder, .place-order coincidirá tanto con #placeOrder como con .place-order.

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

La devolución de llamada buildCartDetail es responsable de devolver los detalles del carrito en un formato que la interfaz de Checkout pueda entender y mostrar. Esta función se llama tan pronto como el cliente llega a la página de checkout, asegurando que los detalles del carrito se muestren con precisión en la primera página de Checkout. Tenga en cuenta que esto no se utiliza para cálculos, eso se maneja en el siguiente paso.

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

Esquema de artículo del carrito

La función buildCartDetail debe devolver un array de artículos del carrito. A continuación se muestra una tabla que detalla la estructura de cada objeto CartItem:

La función buildLandedCost se encarga de calcular de forma segura el landed cost. Se invoca después de que el cliente ingresa su información de envío. Esta función calcula las tarifas de envío y otros costos necesarios, que luego se muestran en la página siguiente de Checkout.

Es importante que manejes la lógica de cálculo del landed cost en el lado del servidor, ya que esta es la única forma de garantizar que los detalles del carrito no se expongan al navegador del cliente. Si estás utilizando una arquitectura sin servidor, puedes usar una función sin servidor para manejar el cálculo del landed cost. La función buildLandedCost simplemente debe llamar a la función/API sin servidor y devolver el resultado.

En el lado del servidor, puedes usar la API de Zonos Checkout para calcular el landed cost utilizando la siguiente solicitud POST. Necesitarás pasar la clave API que has estado utilizando para el script JS de Zonos en el encabezado 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
    },
  },
});