Integración personalizada

Para comenzar, por favor contacta a nuestro equipo de ventas para crear una cuenta y firmar un acuerdo. Una vez que se firme un acuerdo, recibirás dos micro depósitos en tu cuenta que deben ser verificados.

Por favor, envía estos montos de micro depósitos a accounting@zonos.com con tu ID de tienda de Dashboard (CC a tu representante de ventas).

Una vez verificado, tus detalles bancarios se mostrarán en Dashboard -> Configuraciones -> Facturación.

Después de crear tu cuenta de Zonos, necesitarás configurar las configuraciones en Dashboard para asegurar que Checkout funcione correctamente con tu tienda. Esta sección cubre todas las configuraciones esenciales de Dashboard.

Configura los pagos

Conecta una cuenta bancaria para recibir pagos puntuales de Checkout. Los pagos se procesan diariamente con un retraso de 2 días desde el pago capturado. Para hacer esto, sigue estos pasos:

1. Navega a Dashboard -> Configuraciones -> Configuraciones de Checkout.
2. Haz clic en Agregar cuenta bancaria
3. Serás llevado a un portal de Stripe para completar la configuración y proporcionar la siguiente información:
   • Información de la cuenta bancaria.
   • EIN de la empresa.
   • Número de Seguro Social de un propietario de la empresa del 25%. Para más detalles sobre por qué se requiere esto, consulta la documentación de Stripe.

Nota: Si necesitas actualizar tu programación de pagos, por favor contacta a support@zonos.com

Configura los dominios permitidos

El script JS de Zonos requiere una lista de dominios permitidos por razones de seguridad. Esto previene que sitios no autorizados carguen el script y asegura que solo se ejecute en tus dominios aprobados. Sin esta configuración, el script devolverá errores de permiso.

Para configurar esto:

1. Navega a Dashboard -> Configuraciones -> Configuraciones de Checkout
2. Bajo URLs, agrega tu dominio completo y cualquier subdominio donde se utilizará Checkout. Por ejemplo, si tu dominio es example.com, deberías agregar example.com y test.example.com.

Personaliza las configuraciones de marca

Configura tus ajustes de marca en Dashboard para que coincidan con la apariencia y sensación de tu tienda.

Para hacer esto, sigue estos pasos:

1. Navega a Dashboard -> Configuraciones -> Configuraciones de Checkout -> Marca
2. Configura los siguientes ajustes:
   • Logo.
   • Color de marca y acento.
   • Tema, Estilo y Fuente.

Para más información sobre las configuraciones de marca, consulta nuestra documentación.

Conecta un transportista de envío

Para cotizar el envío en checkout, necesitarás conectar un transportista de envío a tu cuenta de Zonos. Esto te permitirá habilitar niveles de servicio de envío específicos en checkout.

Para conectar un transportista de envío, sigue estos pasos:

1. Navega a Dashboard -> Configuraciones -> Envío -> Tarifas
2. Haz clic en Agregar transportista
3. Sigue las instrucciones de configuración del transportista.

Para más detalles sobre cómo conectar cuentas de transportistas, consulta nuestra documentación.

Configura zonas de envío

Las zonas de envío te permiten configurar qué transportistas de envío y niveles de servicio están disponibles para diferentes regiones del mundo.

Para configurar zonas de envío, sigue estos pasos:

1. Navega a Dashboard -> Configuraciones -> Envío -> Ubicaciones
2. Haz clic en Nueva zona
3. Ingresa un nombre de zona y selecciona los países a los que deseas enviar.
4. Selecciona el transportista y el nivel de servicio que deseas ofrecer.

Para más detalles sobre zonas de envío, consulta nuestra documentación.

Configura un país de origen y código HS de respaldo

El país de origen y el código HS se utilizan para calcular los derechos e impuestos precisos.

Si no proporcionas un país de origen específico o un código HS, utilizaremos los respaldos configurados en Dashboard.

Para establecer tu país de origen y código HS de respaldo:

1. Navega a Dashboard -> Configuraciones -> Envío -> Catálogo.
2. Para el país de origen, selecciona el país donde se fabrican la mayoría de tus productos.
3. Para el código HS, ingresa el código HS de tu producto más común. Si no tienes un código HS, navega a Classify en Dashboard e ingresa el nombre y la descripción de tu producto para generar un código HS preciso.

El fragmento JS de Zonos es una integración de JavaScript del lado del cliente que habilita la funcionalidad global de checkout en tu sitio. Sirve como el puente entre tu plataforma de ecommerce y los servicios de Zonos, manejando:

• Experiencia de Checkout: Renderiza la interfaz de usuario de checkout y procesa pagos.
• Servicios de ubicación: Detecta la ubicación del visitante y gestiona la conversión de moneda.
• Integración del carrito: Se conecta con tu carrito y sistema de pedidos existentes.
• Seguridad: Valida dominios y autentica solicitudes de API.

El fragmento se carga de manera asíncrona para evitar cualquier impacto en el rendimiento de tu sitio. Se inicializa con las credenciales de API de tu tienda y maneja todas las interacciones del lado del cliente de manera segura. La implementación está diseñada para ser no intrusiva, requiriendo cambios mínimos en tu flujo existente de checkout.

A continuación se muestra un ejemplo completo que incluye la carga del script, la inicialización y el manejo de eventos para referencia al integrar 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: Reemplace los valores de marcador de posición (storeId, zonosApiKey, selectors, etc.) con sus valores reales de su Zonos Dashboard.

Manejo de la caché del navegador

Recomendamos agregar un sello de tiempo u otro identificador único a la URL para asegurarnos de que el script no sea almacenado en caché por el navegador. Esto garantizará que siempre se cargue la versión más reciente del script. Esto se muestra en la línea 10 del ejemplo completo.

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

Autenticar el Zonos fragmento de JS

Una vez que hayas cargado el script de Zonos, necesitas autenticarlo pasando una clave pública de Zonos API y el ID de la tienda en la función Zonos.init. La clave pública de API utilizada para autenticar Checkout está diseñada para ser publicable, lo que significa que se puede usar de manera segura en el código del frontend sin exponer información sensible.

Para encontrar tu ID de tienda y clave de API, navega a Dashboard -> Settings -> Integraciones. Asegúrate de no usar una clave de API secreta, ya que no está diseñada para ser utilizada en el código del frontend. Esto se muestra en las líneas 29 y 30 del ejemplo 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 es necesario al usar Checkout.

Hello es responsable de detectar la ubicación, el idioma y la moneda del visitante, y mostrarles la información adecuada. Puedes configurar todos los ajustes de Hello en el Dashboard o en el script JS de Zonos. Si ya has configurado Hello en el Dashboard, el script cargará esos ajustes y los utilizará. Si especificas algún valor en la propiedad helloSettings de la función Zonos.init, el script utilizará esos valores en su lugar, como se muestra a continuación.

Configurar la conversión de moneda en Hello en el script JS

Hello utiliza selectores CSS para identificar elementos en tu sitio que muestran información de moneda. Pasa estos selectores a la propiedad helloSettings.currencyElementSelector de la función Zonos.init para que Hello pueda detectar y mostrar la moneda correcta del comprador internacional.

Puedes usar cualquier selector CSS válido aquí, por ejemplo #price, .price para seleccionar múltiples elementos diferentes. Esto se muestra en las líneas 23 y 24 del ejemplo completo.

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

Abrir automáticamente Hello al cargar la página

Por defecto, Hello solo se abrirá cuando el visitante haga clic en el botón de la bandera. Si desea abrir automáticamente Hello cuando se carga la página, puede llamar a la función Zonos.openHelloDialog() una vez que se haya cargado el script de Zonos. Esto se muestra en las líneas 25 y 26 del ejemplo completo.

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

Checkout es responsable de permitir que el cliente ingrese su información de envío y facturación, calcule landed cost, collect el pago y complete el pedido.

Checkout compartirá datos contextuales con Hello, como la ubicación, el idioma y la moneda del visitante. Esto asegura que la experiencia del cliente sea consistente a lo largo de todo el proceso de compra.

Puedes configurar todas las opciones de Checkout tanto en el Dashboard como en el script JS de Zonos. Si ya has configurado Checkout en el Dashboard, el script cargará esas configuraciones y las utilizará. Si especificas algún valor en la propiedad checkoutSettings de la función Zonos.init, el script utilizará esos valores en su lugar.

Configurar el botón 'realizar pedido' en el script JS

El script JS de Zonos 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 abrir 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 para cada botón. Por ejemplo, #placeOrder, .place-order.

Esto se muestra en la línea 21 del ejemplo completo.

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

Crear detalles del carrito de manera 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.

// 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, evitando cualquier manipulación del carrito. Vea el ejemplo de código a continuación.

El valor de createCartId no puede ser un valor estático, debe ser una función.

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 tu sistema y el Zonos Dashboard, implementa estas llamadas a la API y webhooks:

Mutaciones Requeridas

Webhooks Requeridos

Antes de poner en marcha tu integración de Checkout, es importante probar a fondo todos los aspectos de la integración para garantizar una experiencia fluida para el cliente. Esto incluye probar el flujo de checkout, el procesamiento de pagos, la creación de pedidos y la funcionalidad de los webhooks.

Sigue nuestra guía de pruebas para verificar que tu integración esté funcionando correctamente e identificar y solucionar cualquier problema antes de lanzar a producción.

A continuación se presentan algunas preguntas comunes sobre el proceso de integración.

¿Cómo maneja Zonos la confirmación de pedidos?

Zonos proporciona una página de agradecimiento incorporada que puedes usar para las confirmaciones de pedidos. Esta página siempre se mostrará, incluso si un pedido no se importa a tu sistema, asegurando que los clientes siempre reciban confirmación de su compra.

¿Puedo ser notificado cuando se crea un pedido?

Sí. Si deseas recibir notificaciones cuando se crea un pedido, en el Dashboard bajo la sección Email de configuración de Checkout, puedes ingresar la dirección de correo electrónico de los miembros del equipo que deben ser notificados cuando se crea, envía o cancela un pedido.