VibeFox Mercado Envios for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Cuenta de Mercado Pago (solo para tarifas en tiempo real): las tarifas en tiempo real proceden de la calculadora de Mercado Envios de tu cuenta de Mercado Pago en Argentina, Brasil o México. Mercado Envios debe estar activado en la cuenta. Los paquetes se cotizan desde la dirección de envío configurada en esa cuenta. Necesitas el Access Token de producción (empieza por APP_USR-): en el panel de desarrolladores de Mercado Pago, abre tu aplicación y sus credenciales de producción. No hay botón de inicio de sesión: pegas el token en los ajustes del módulo. Si solo usas precios por país, no necesitas una cuenta de Mercado Pago.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

1. En el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Mercado Envios en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).

4. Para las tarifas en tiempo real, pega el Access Token, elige el país de Mercado Envios y, si la moneda predeterminada de tu tienda no es ARS, BRL ni MXN, el tipo de cambio. Opcionalmente, rellena Country prices y Fallback cost (se usan sin tarifas en tiempo real). Haz clic en Save.

Al instalarse, el módulo crea el transportista Mercado Envios con el texto del plazo de entrega Mercado Envios delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes, sin regla de impuestos. Puedes cambiar las zonas, los grupos de clientes, el plazo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre procede del módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Mercado Envios > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de Mercado Envios en caché y el último error de la API.

Las advertencias en la parte superior de la página muestran problemas de configuración: falta el tipo de cambio, no hay Access Token ni precio, el último error de la API de Mercado Envios con su fecha, y una unidad de peso o de dimensiones de la tienda que el módulo no conoce (en ese caso se interpreta como kg o cm). Si se eliminó el transportista, la sección General dice The Mercado Envios carrier was not found — reset the module to create it again.

General

Añade las zonas de tus clientes al transportista de Mercado Envios en Shipping > Carriers, o usa Ignore shipping zones más abajo. Estos ajustes se aplican a todas las zonas.

Enable Mercado Envios shipping: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.

Name: el nombre del transportista que ven los clientes en la finalización de compra. Predeterminado: Mercado Envios. Obligatorio, de 64 caracteres como máximo.

Tax: la regla de impuestos del transportista, o No tax (predeterminado). Mercado Envios cotiza precios finales. No tax los muestra tal como se cotizan; una regla de impuestos añade encima tu impuesto de envío.

API de Mercado Envios (tarifas en tiempo real) (sin token solo se usan los precios de abajo)

Access token: tu Access Token de producción de Mercado Pago (APP_USR-...). Solo se envía a api.mercadopago.com y nunca se registra. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para dejar de usar tarifas en tiempo real, marca Remove the saved access token (only the prices below are used then) y guarda.

Mercado Envios country: el país de tu cuenta de Mercado Pago: Argentina (ARS) (predeterminado), Brazil (BRL) o Mexico (MXN). Las tarifas en tiempo real solo se solicitan para destinos de este país y se cotizan en su moneda.

Exchange rate: solo es necesario si la moneda predeterminada de tu tienda es distinta de la moneda de Mercado Envios: el precio de 1 ARS, BRL o MXN en tu moneda predeterminada, por ejemplo 0.001. Sin él no se usan tarifas en tiempo real. Debe ser un número positivo. Se aceptan tanto el punto como la coma como separador decimal.

Precios sin tarifas en tiempo real

Estos precios se usan cuando no hay Access Token, para destinos fuera del país de Mercado Envios y cuando la API no devuelve ninguna tarifa. Están en la moneda predeterminada de tu tienda, sin impuestos.

Country prices: una tabla de países de destino y precios. Haz clic en Add country para añadir una fila y en el icono de la papelera para eliminar una. Elige * All other countries para todos los países que no tengan fila propia. Price es el precio del país. Las columnas XS (hasta 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) y XL (más de 5 kg) lo sustituyen para ese peso del carrito. Una columna vacía o con 0 usa Price. Un Price de 0 significa envío gratuito a ese país. Se aceptan tanto 9.99 como 9,99. Los valores que no son números se notifican tras guardar y se borran. Las filas sin ningún precio se eliminan al guardar.

Fallback cost: se usa cuando ni la API ni Country prices dan un precio. Déjalo vacío para ocultar el transportista en ese caso.

Calculation type: Per order cobra el precio una sola vez. Per item (each item priced by its own weight x quantity) busca en Country prices (o en el Fallback cost) el precio del peso de cada producto y lo multiplica por su cantidad. Si un producto no tiene precio, el transportista se oculta. Las tarifas en tiempo real de Mercado Envios siempre son para el paquete completo.

Disponibilidad

Min weight: el peso mínimo del carrito en kg para que aparezca este transportista. 0 significa sin límite.

Max weight: oculta el transportista cuando el carrito pesa más, en kg. Vacío significa 25 kg, 0 significa sin límite. Un Min weight mayor que Max weight se rechaza al guardar.

Minimum subtotal: muestra el transportista solo cuando el subtotal del carrito (después de descuentos y antes de impuestos) sea al menos este importe. Déjalo vacío para mostrarlo siempre.

Ignore shipping zones: ofrece el transportista para los países indicados abajo sin configurar sus zonas. Al guardar, el transportista se añade a todas las zonas, y también a las zonas que se creen después. Al desactivar la opción se eliminan las zonas que añadió, y el transportista conserva sus propias zonas.

Countries: los países de destino para ese modo. Déjalo vacío para todos los países activos de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.

Envío gratuito

Free shipping from: el subtotal del carrito (después de descuentos y antes de impuestos) a partir del cual este transportista es gratuito. En ese caso no se hace ninguna solicitud a la API. Déjalo vacío para desactivarlo.

Avanzado

Debug log: registra las solicitudes a la API y el cálculo de tarifas en logs/vfd_mrcv_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso con esta opción desactivada. El Access Token y las direcciones de los clientes nunca se registran.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Remove data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes, el transportista, las tarifas en caché y los registros. Si está desactivado, todo se conserva para una reinstalación.

Cómo funciona en la finalización de compra

En el paso de envío, PrestaShop pide al módulo el precio de Mercado Envios. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el subtotal. El módulo comprueba primero las condiciones: países permitidos (con Ignore shipping zones), peso del carrito y subtotal mínimo. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Mercado Envios.

Para un destino en el país de Mercado Envios con un código postal válido, el módulo describe el carrito como un solo paquete: la mayor anchura y longitud de los productos, la suma de las alturas de todos los productos y el peso total en gramos. Cada lado y el peso se elevan a los mínimos de Mercado Envios del país, de modo que los productos sin dimensiones o peso también obtienen una tarifa. El valor del carrito se envía como precio del artículo en la moneda de Mercado Envios. La opción más barata devuelta por Mercado Envios se convierte a la moneda predeterminada de tu tienda y después se muestra en la moneda del carrito del cliente.

Cada cotización se guarda en caché durante 1 hora, así que el mismo carrito no provoca una nueva solicitud. Una cotización fallida no se repite durante 5 minutos. Si no se puede contactar con Mercado Pago, si rechaza el token o si limita las solicitudes, todas las tarifas en tiempo real se pausan durante 5 minutos, para que la finalización de compra no espere a la API en cada actualización. El tiempo de espera de la API es de 10 segundos.

En su lugar se usan los precios sin tarifas en tiempo real cuando no hay token, el destino está fuera del país de Mercado Envios, falta el código postal o no es válido, falta el tipo de cambio, el paquete pesa más que el límite de Mercado Envios del país (25 kg en Argentina, 15 kg en Brasil, 30 kg en México), o Mercado Envios devuelve un error o ninguna opción para la dirección. Se usa la fila del país (o la fila *); si no existe, el coste alternativo. Si no hay precio, el transportista se oculta. El cliente nunca ve un error de la API.

Si editas el transportista en Shipping > Carriers después de que tenga pedidos, PrestaShop lo guarda como una nueva versión del transportista. El módulo sigue la nueva versión automáticamente.

El módulo solo calcula tarifas. No crea envíos, no imprime etiquetas ni hace seguimiento de paquetes. Crea el envío en tu cuenta de Mercado Libre o de Mercado Pago. Muestra un solo precio, la opción más barata de Mercado Envios, no una elección entre todas las opciones, y no tiene selector de punto de recogida (agencia).

Pedidos

Cuando se realiza un pedido con una tarifa en tiempo real de Mercado Envios, el módulo guarda el nombre del servicio, el plazo de entrega estimado en días y la tarifa en tiempo real. En el back office, la página del pedido muestra un bloque Mercado Envios con Mercado Envios service, Estimated delivery y Live rate (excl. tax). El cliente ve Mercado Envios service y Estimated delivery en la página de detalles del pedido de su cuenta. Los pedidos existentes no se ven afectados por cambios posteriores de tarifas.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Mercado Envios es el primer bloque de Modules > Module Manager > VibeFox Mercado Envios > Configure, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-mercado-envios y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).

Si la clave no es aceptada, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, el transportista de Mercado Envios no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el transportista también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Mercado Envios no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable Mercado Envios shipping esté activado. En Shipping > Carriers, comprueba que el transportista cubra la zona del país del cliente y el grupo del cliente (o activa Ignore shipping zones y revisa Countries). Revisa las advertencias de la parte superior de la página del módulo, los límites de peso y Minimum subtotal. El transportista necesita un precio: un Access Token válido para direcciones del país de Mercado Envios, o Country prices o Fallback cost. Además, los productos pueden estar limitados a ciertos transportistas en la página del producto.

No aparecen tarifas en tiempo real: activa Debug log, recarga la finalización de compra y mira el campo Log de la página del módulo. Motivos habituales: no hay token, un destino fuera del país de Mercado Envios, un código postal que falta o no es válido, falta el Exchange rate, un paquete que supera el límite de peso o ninguna opción de Mercado Envios para la dirección.

HTTP 401 o 403 en las advertencias: el Access Token no es válido o ha caducado. Copia de nuevo el Access Token de producción desde el panel de desarrolladores de Mercado Pago.

Mercado Envios respondió en otra moneda: el país de la cuenta no coincide con Mercado Envios country. Elige el país de tu cuenta de Mercado Pago.

¿En qué moneda están los precios? Country prices, Fallback cost y los umbrales están en la moneda predeterminada de tu tienda. Las tarifas en tiempo real llegan en la moneda de tu cuenta de Mercado Pago y se convierten con Exchange rate cuando la tienda usa otra moneda predeterminada.

Las tarifas parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Así se borran las tarifas en caché.

La página indica que no se encontró el transportista de Mercado Envios: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Mercado Envios y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan. Las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial), y se eliminan los ajustes, el registro y los datos de servicio guardados de los pedidos. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes y los datos de servicio de los pedidos. Al volver a instalar el módulo, el transportista recupera su estado anterior a la desinstalación.

Mercado Envios y Mercado Pago son marcas comerciales de sus respectivos titulares. Este módulo no está afiliado ni cuenta con el respaldo de Mercado Envios ni de Mercado Pago.