Checkout para Miva

En un plazo de 24 horas después de registrarse, un representante de incorporación dedicado se pondrá en contacto con usted para iniciar un proceso de integración personalizado.

Importante: Los pasos que se enumeran a continuación son solo de referencia y su representante de incorporación le guiará a través de ellos.

1. Descargue el módulo desde la Miva App Store, o solicite el archivo zonos.mvc directamente a Zonos.
2. En su administrador de Miva, vaya a Domain Settings -> Modules -> Add Module, cargue el archivo zonos.mvc y haga clic en Add.

3. Vaya a Settings -> Modules, busque Zonos y haga clic en Install. Confirme que aparezca como Installed.

En Miva, vaya a Users -> API Tokens y haga clic en Add API Token. Configúrelo de la siguiente manera:

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- haga clic en Generate para crear una clave de firma
• Timestamp: Require Timestamp Within 30 seconds

En la siguiente pantalla, habilite Customer Service & Sales para permitir que el token cree y modifique pedidos. Haga clic en Save.

Navegue al módulo de Checkout en Miva yendo a Miva -> Utility Settings -> Zonos, luego complete los siguientes campos:

1. Store ID: Copie su Zonos account number desde Dashboard -> Settings -> Account -> Integrations.
2. Zonos API Key: Su clave de API secreta (nunca la comparta).
3. Zonos Public Key: Su clave pública.
4. Store Currency: La moneda base de su tienda (por ejemplo, USD).
5. Environment: Seleccione Live para producción o Test para pruebas.
6. Checkout Button Selector: Selector CSS para el botón de checkout (ejemplo: a[href*="checkout.html"]).
7. Hidden Selectors: Para ocultar las opciones de pago nacionales y otros detalles que puedan no ser pertinentes para clientes internacionales.
8. Import Orders: Marque para importar automáticamente los pedidos completados de Zonos al administrador de Miva. Esto requiere que los webhooks estén registrados en el siguiente paso.

Haga clic en Update en la esquina superior derecha para guardar antes de continuar.

Los pedidos se importan mediante webhook en el módulo 10.x. Las versiones anteriores del módulo utilizaban en su lugar una URL/endpoint de éxito de pedido.

Después de guardar sus ajustes, haga clic en Register Webhooks. Esto conecta su tienda con Zonos para que los pedidos completados se importen automáticamente, las cancelaciones se sincronicen y las actualizaciones de envío se envíen de vuelta a Miva.

Los webhooks deben registrarse para que funcionen la importación de pedidos, la sincronización de cancelaciones y las actualizaciones de envío. La casilla Import Orders requiere que los webhooks estén registrados.

Desplácese hacia abajo para completar los campos restantes:

1. Miva API Token: El Access Token del token de API que creó en el paso Crear un token de API.
2. Miva API Signature: La Signing Key de la misma entrada de token de API.
3. Image Type: Selecciona qué tamaño de imagen de producto se muestra en el checkout de Zonos (Main funciona para la mayoría de las tiendas).
4. Additional Field Mappings: Opcionalmente, mapee campos personalizados de Miva a atributos/metadatos de Zonos (color, material, tamaño, etc.). Recomendamos mapear HS code si ha configurado códigos HS específicos del producto en sus listados de productos de Miva. Esto no es obligatorio para generar una cotización de aranceles e impuestos, ya que podemos usar los códigos HS específicos del producto que haya ingresado en Catalog o usar su código HS predeterminado. Sin embargo, se recomienda; la precisión de los cálculos de landed cost aumentará considerablemente con productos correctamente clasificados. Para mapear un campo en Miva, cree un campo personalizado para el código HS y luego mapéelo en Utility Settings -> Zonos.

Haga clic en Update para guardar todos los ajustes.

Ahora que ha configurado su cuenta y su módulo, está listo para probar haciendo lo siguiente:

• Probar cotizaciones de envío
• Realizar un pedido de prueba en su sitio
• Probar el flujo de pedidos a través de sus sistemas
• Probar su sitio web

Aprenda a ejecutar estas pruebas. Deberá configurar el campo Environment del módulo en Test mientras realiza las pruebas.

Después de completar las pruebas, ¡está listo para ponerse en marcha! Configure Environment en Live, confirme que sus credenciales de Zonos sean correctas y asegúrese de que los webhooks estén registrados en su tienda en vivo.

1. Vaya a dashboard.zonos.com -> Hello -> Hello Settings.
2. Active Currency behavior.
3. Ingrese el selector CSS que apunta a los elementos de precio de su producto (por ejemplo, .price).

Zonos Hello convertirá y mostrará automáticamente los precios en la moneda local del comprador cuando esto esté habilitado.

Las dimensiones de envío, el país de origen y el código HS configurados en el catálogo de Miva se mapean automáticamente a Zonos y se utilizan para las cotizaciones de landed cost / envío si están completados. No se requiere mapeo adicional para configurarlo.

Si su tienda vende productos configurables en los que todas las variaciones comparten un único SKU, las Product Shipping Rules estándar de Miva almacenan un solo conjunto de dimensiones por producto, por lo que cada configuración se trata como del mismo tamaño sin importar lo que el cliente haya seleccionado.

Miva y Zonos admiten dimensiones a nivel de variante, pero esto requiere configurar cada variante individualmente. Esto puede ser poco práctico para tiendas con cientos o miles de configuraciones que no se corresponden con variantes discretas.

Esta función resuelve ese problema leyendo las dimensiones de cada configuración directamente desde la cesta en el checkout, utilizando la lógica personalizada que su tienda ya tenga implementada para calcularlas -- por ejemplo, extrayendo las dimensiones de la descripción del producto.

Requisitos

• Su tienda ya debe completar columnas de dimensiones personalizadas en los artículos de la cesta cuando se agregan al carrito (esto se gestiona del lado de Miva, fuera del alcance del módulo de Zonos).
• Deberá conocer los nombres exactos de las columnas que está utilizando.

Configuración

Ingrese esos nombres de columna en los tres campos correspondientes del administrador del módulo de Zonos. Déjelos en blanco para recurrir a las Product Shipping Rules estándar -- la función es completamente opcional y no afectará a las tiendas que no la utilicen.

Cuando se crea una etiqueta de envío o se ingresa un número de seguimiento en el Zonos Dashboard, el número de seguimiento y el estado del envío se envían automáticamente al pedido correspondiente en el administrador de Miva. Esto requiere que los webhooks estén registrados (consulte el paso Registrar webhooks anterior).

El seguimiento también se puede ingresar directamente en Miva. Use el cuadro de diálogo Enter Tracking Number en cualquier pedido de Zonos -- el número de seguimiento y el estado del envío se sincronizarán automáticamente de vuelta al Zonos Dashboard.

El registro de depuración es accesible dentro del administrador de Miva, en los ajustes del módulo de Zonos. Registra el ciclo de vida completo de cada evento de pedido que procesa el módulo -- importaciones, sincronizaciones de seguimiento, cancelaciones y solicitudes de cancelación salientes a Zonos -- incluyendo tanto los éxitos como los fallos en línea.

Cada entrada incluye el ID de pedido de Zonos, el ID de pedido de Miva y, cuando corresponde, detalles a nivel de cliente como la respuesta de error de la API de Miva o Zonos. Esto lo convierte en la fuente de información más completa para diagnosticar problemas.

El registro conserva solo las 500 líneas más recientes. Las entradas antiguas no se archivan, así que revíselo con prontitud después de que ocurra un problema -- los eventos anteriores pueden haber sido sobrescritos.

Registro público de errores (no requiere inicio de sesión) 

Hay disponible un segundo registro de acceso público mediante una URL directa -- no requiere inicio de sesión en el administrador de Miva. Registra únicamente errores (sin éxitos) y no contiene PII de clientes ni datos sensibles. Cada entrada tiene como prefijo la versión del módulo (por ejemplo, [v10.09]) para una identificación rápida.

Formato de URL:

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Ejemplo:

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code: El miva_store_code se devuelve en el arreglo de metadatos de la respuesta de la API para todos los pedidos del dashboard.

Todos los reembolsos de pagos deben procesarse directamente a través del dashboard de Zonos. Los botones Refund, Capture y Void en Miva no están disponibles para los pedidos importados de Zonos por diseño. Cualquier reembolso procesado en Zonos no actualizará automáticamente los montos de pago en el pedido correspondiente de Miva -- el pedido de Miva conserva los montos originalmente capturados y no se mantiene sincronizado con la actividad de reembolso en Zonos.

En cuanto a las cancelaciones de pedidos, el comportamiento depende del estado actual del pedido:

• Open (aún no enviado): Cancelarlo en Miva también lo cancelará en Zonos y anulará la autorización de pago. Dado que Zonos no captura el pago hasta que se envía un pedido, al cliente nunca se le cobra realmente y no se requiere un reembolso por separado.
• Shipped o Completed: Cancelar en Miva marcará el pedido de Miva como cancelado, pero Zonos rechazará la cancelación porque el pedido ya ha sido completado y ya no califica para la cancelación automática. En este caso, se agrega una nota visible solo para el administrador en el pedido de Miva -- visible únicamente para el personal de la tienda y nunca para el cliente -- explicando que el pedido debe gestionarse en Zonos. También se envía una notificación por correo electrónico a la dirección de correo principal de la cuenta de la tienda, alertando al comerciante para que tome acción en el dashboard de Zonos, donde puede procesar manualmente cualquier reembolso aplicable.

Síntoma: Los pedidos se completan en Zonos Checkout y aparecen en el dashboard de Zonos, pero no aparece nada en el administrador de Miva.

Causa: Zonos envía un webhook ORDER_CREATED (HTTP POST) al endpoint /mm5/json.mvc de su tienda. En sitios de desarrollo, la seguridad a nivel de servidor a menudo bloquea esta solicitud antes de que llegue a Miva. Causas comunes:

• HTTP Basic Auth -- Si el sitio de desarrollo tiene un aviso de contraseña (Plesk, cPanel, .htaccess, etc.), el webhook es rechazado con un 401 Unauthorized. Incluya en la lista blanca las IPs de Zonos en su configuración de .htaccess o Plesk para que omitan el aviso de autenticación.
• Cloudflare WAF / IP Access Rules -- Si el sitio está detrás de un proxy de Cloudflare, sus reglas de seguridad pueden bloquear el POST antes de que llegue a su servidor. Agregue una regla de WAF para permitir solicitudes POST donde la ruta de la URL contenga /mm5/json.mvc, o incluya en la lista blanca las IPs de Zonos directamente en las IP Access Rules de Cloudflare.
• Lista blanca de IP a nivel de servidor -- Si el sitio de desarrollo restringe el tráfico solo a IPs específicas (algo común en entornos de staging restringidos a IPs de oficina o de la plataforma), las solicitudes de webhook de Zonos se descartan silenciosamente sin respuesta. Agregue todas las IPs de entrega de webhooks de Zonos a la lista blanca de su servidor (Plesk IP Access Restriction Manager, cPanel IP Blocker, o las reglas de seguridad de su firewall/panel de hosting).

IPs de entrega de webhooks de Zonos

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

Esto normalmente solo afecta a sitios de desarrollo/staging -- los sitios de Miva en producción suelen ser públicos y no necesitan lista blanca de IPs. Si no está seguro de cómo configurar esto, contacte a su proveedor de hosting o al soporte de Miva.

La información del producto afecta los aranceles, los impuestos y los costos de envío, por lo que cuanta más información reciba Zonos, más precisa será la cotización. Zonos puede generar una cotización incluso cuando falta parte de esta información.

• Peso, dimensiones, país de origen y código HS: Los valores configurados en las reglas de envío del catálogo de Miva se transfieren automáticamente a Zonos. No se requiere ningún mapeo.
• Códigos HS en un campo personalizado: Si, en cambio, almacena los códigos HS en un campo personalizado de Miva, mapee ese campo en Additional Field Mappings en Utility Settings -> Zonos.
• Valores faltantes: Zonos recurre a los detalles del producto en Catalog o a su código HS predeterminado.

Nota: Cualquier valor que ingrese en Catalog anula el valor enviado desde Miva.

Más información sobre la información de productos por plataforma.

El módulo 10.x importa los pedidos completados de Zonos al administrador de Miva mediante webhook. Marque Import Orders en los ajustes de Zonos y luego haga clic en Register Webhooks. Los webhooks también sincronizan las cancelaciones y envían las actualizaciones de envío de vuelta a Miva. Las versiones anteriores del módulo utilizaban en su lugar una URL de éxito de pedido.

Por lo general, la seguridad a nivel de servidor del sitio de desarrollo está bloqueando el webhook ORDER_CREATED que Zonos envía a /mm5/json.mvc: HTTP Basic Auth, Cloudflare WAF o IP Access Rules, o una lista blanca de IP del servidor. Permita las IPs de entrega de webhooks de Zonos que se enumeran en Solución de problemas: los pedidos no aparecen en Miva en sitios de desarrollo/staging más arriba. Los sitios en producción suelen ser públicos y no se ven afectados.

Procese todos los reembolsos en el dashboard de Zonos. Los botones Refund, Capture y Void de Miva no están disponibles para los pedidos importados de Zonos, y los reembolsos realizados en Zonos no actualizan los montos de pago en el pedido de Miva.

Depende del estado del pedido:

• Open (aún no enviado): El pedido también se cancela en Zonos y se anula la autorización de pago. Al cliente nunca se le cobra, por lo que no se necesita ningún reembolso.
• Shipped o Completed: Zonos rechaza la cancelación. Se agrega una nota visible solo para el administrador en el pedido de Miva y se envía un correo electrónico a la dirección de correo principal de la cuenta de la tienda para que pueda procesar cualquier reembolso en el dashboard de Zonos.

Use el registro de depuración en los ajustes del módulo de Zonos en el administrador de Miva. Registra cada importación de pedido, sincronización de seguimiento y cancelación, con los éxitos y los fallos, y conserva las 500 líneas más recientes. Para ver solo los errores, sin iniciar sesión en el administrador de Miva, use la URL del registro público de errores descrita en Registro de depuración más arriba.