Instala el script JS de Zonos
Tu integración personalizada necesitará incluir el fragmento de JavaScript de Zonos. Este script es responsable de renderizar la interfaz de usuario de Checkout, Zonos Hello, manejar el procesamiento de pagos y gestionar la detección de geo-IP de los visitantes.
Instala el fragmento JS de Zonos
El script de Elementos de Zonos está disponible en la siguiente URL:
Zonos fragmento JS
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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:
Zonos Fragmento de JS
<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>
Autenticar el fragmento de JS de Zonos
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
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
});
Configurar dominios permitidos
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:
- Vaya a Dashboard -> Configuración -> Configuración de Checkout.
- En la sección Dominios permitidos, agregue el/los dominio(s) donde integrará Checkout.
- Haga clic en Guardar.
Configurar Zonos Hello
Una vez que haya configurado el script JS de Zonos, necesita configurar Hello para que funcione con su sitio. Hello es responsable de detectar la ubicación, el idioma y la moneda del visitante, y mostrarles la información adecuada. Hello es necesario cuando se utiliza Checkout.
Puede configurar todos los ajustes de Hello tanto en el Dashboard como en el script JS de Zonos. Si ya ha configurado Hello en el Dashboard, el script cargará esos ajustes y los usará. Si especifica algún valor en la propiedad helloSettings de la función Zonos.init, el script usará esos valores en su lugar.
Configurar la conversión de moneda
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 JS snippet
Zonos.init({
// ... other fields
helloSettings: {
// ... other fields
currencyElementSelector: '#price, .price', // Replace with your actual selector
},
});
Opcional — Abrir automáticamente Hello al cargar la página
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 Fragmento de JS
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
Configurar Zonos Checkout
Una vez que Hello ha sido configurado, necesitas configurar Checkout para que funcione con tu sitio. Checkout es responsable de permitir que el cliente ingrese su información de envío, calcule el landed cost y complete el pedido.
Checkout compartirá datos contextuales con Hello, como la ubicación del visitante, el idioma y la moneda. Esto asegura que la experiencia del cliente sea consistente en todo el proceso de compra.
Puedes configurar todos los ajustes de Checkout tanto en el Dashboard como en el script de Zonos JS. Si ya has configurado Checkout en el Dashboard, el script cargará esos ajustes y los usará. Si especificas algún valor en la propiedad checkoutSettings de la función Zonos.init, el script usará esos valores en su lugar.
Configurar el botón 'realizar pedido'
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 JS snippet
Zonos.init({
// ... other fields
checkoutSettings: {
// ... other fields
placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
},
});
Crear detalles del carrito de forma segura en el lado del servidor
Para mostrar los detalles del carrito al cliente, necesitas crear una función del lado del servidor que llame a la API de Zonos para crear un carrito, y luego pasar ese ID de carrito de vuelta a tu frontend. Esto asegurará que los detalles del carrito no se expongan al cliente de una manera que pueda ser manipulada.
Tu llamada a la API del backend utilizará un token de credencial GraphQL secreto, que es diferente del token público que usas para autenticar el script JS de Zonos. Este token se puede recuperar en Dashboard -> Settings -> Integraciones. El token secreto debe ser pasado como un encabezado en tu llamada a la API.
La mutación cartCreate acepta una lista de artículos, que deben estar formateados de acuerdo con el esquema de artículo del carrito.
Ejemplo de creación de carrito del lado del servidor
// 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 crear un endpoint de API en su servidor y luego llamar a ese endpoint desde su integración de JS en el frontend, lo cual se detalla en el siguiente paso.
Pasar el ID del carrito a Checkout a través del frontend
Una vez que haya creado un carrito en su servidor, necesita pasar el ID del carrito al script JS de Zonos. Esto se puede hacer utilizando el callback createCartId que es parte de la función Zonos.init. Checkout luego recuperará de manera segura los detalles del carrito de Zonos cuando se abra, previniendo cualquier manipulación del carrito.
Zonos fragmento de JS
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
},
},
});
Integración personalizada
Construye una integración de Checkout de extremo a extremo en tu sitio personalizado.
Esta guía cubre los aspectos técnicos de completar una integración completa de Zonos Checkout en tu sitio o plataforma personalizada. Está destinada a desarrolladores que se sientan cómodos trabajando con JavaScript y tengan experiencia en desarrollo frontend. Todos los pasos son obligatorios a menos que se indique lo contrario.
Requisitos previos