VibeFox Mercado Envios for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Cuenta de Mercado Pago (solo para tarifas en tiempo real): las tarifas en tiempo real provienen 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 token de acceso de producción (empieza por APP_USR-): en Mercado Pago Developers, abre tu aplicación y sus credenciales de producción. No hay botón de inicio de sesión: pegas el token en la configuración de la extensión. 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
La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_mercado_envios-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_mercado_envios.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.
OpenCart 3
1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_mercado_envios-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del Installer, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Mercado Envios y haz clic en Install (el botón verde +).
3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración.
4. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Edit y haz clic en Activate (véase Clave de licencia).
5. Para las tarifas en tiempo real, pega el token de acceso, elige el país de Mercado Envios y, si la moneda predeterminada de tu tienda no es ARS, BRL o MXN, el tipo de cambio. Opcionalmente, rellena Country prices y Fallback cost (se usan sin tarifas en tiempo real). Activa Enable Mercado Envios shipping y haz clic en Save.
OpenCart 4
1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_mercado_envios.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.
2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.
3. Ve a Extensions > Extensions y elige el tipo de extensión Shipping. Busca VibeFox Mercado Envios, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y los ajustes como en los pasos 4 y 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.
Después de instalar, el método está desactivado hasta que actives Enable Mercado Envios shipping y guardes. Si vuelves a instalar la extensión tras desinstalarla, se usan de nuevo los ajustes que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit. Las secciones aparecen a la izquierda. Un único botón Save guarda toda la página sin recargarla. Cada guardado también borra las tarifas en tiempo real en caché de Mercado Envios y el último error de la API. Solo los usuarios administradores con permiso de modificación para esta extensión pueden guardar los ajustes.
Las advertencias de la sección General (y después de cada guardado) muestran problemas de configuración: falta el tipo de cambio, no hay token de acceso ni precio (en ese caso el método nunca se muestra), el último error de la API de Mercado Envios con su fecha, y una unidad de peso o de longitud de la tienda que la extensión no reconoce (entonces se interpreta como kg o cm). Si Name está vacío o tiene más de 64 caracteres, Exchange rate no es un número positivo, otro campo numérico no es un número igual o mayor que 0, o Min weight es mayor que Max weight, la página muestra un error y no se guarda nada.
General
El cliente ve una única tarifa de Mercado Envios. Puedes limitar el método a una zona geográfica o a países en Availability. Estos ajustes se aplican a todas las zonas.
Enable Mercado Envios shipping: muestra u oculta Mercado Envios en la finalización de compra. Predeterminado: desactivado.
Name: el nombre del método de envío que ven los clientes en el carrito y en la finalización de compra. Predeterminado: Mercado Envios. Obligatorio, 64 caracteres como máximo.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Mercado Envios cotiza precios finales. No tax los muestra tal como se cotizan; una clase de impuesto añade encima el impuesto de envío de tu tienda.
Sort order: la posición de Mercado Envios entre los métodos de envío de la finalización de compra. Un número entero.
API de Mercado Envios (tarifas en tiempo real) (sin token solo se usan los precios de abajo)
Access token: tu token de acceso 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 para cambiarlo.
Remove the saved access token: actívalo y guarda para eliminar el token guardado. En ese caso solo se usan los precios de abajo. En cambio, un token escrito arriba sustituye al guardado.
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 cuando 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 las 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 token de acceso, para destinos fuera del país de Mercado Envios y cuando la API no da ninguna tarifa (una solicitud fallida se reintenta tras 5 minutos). 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 botón de eliminar para borrar 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 método en ese caso.
Calculation type: Per order (predeterminado) 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 peso de cada producto y lo multiplica por su cantidad. Si un producto no obtiene precio, el método se oculta. Las tarifas en tiempo real de Mercado Envios siempre se refieren a todo el paquete.
Disponibilidad
Min weight (kg): el peso mínimo del carrito para que aparezca este método. 0 significa sin límite (predeterminado).
Max weight (kg): oculta el método cuando el carrito pese más. Predeterminado: 25. Vacío significa 25 kg; 0 significa sin límite.
Minimum subtotal: muestra el método solo cuando el subtotal de los productos que requieren envío (después del cupón y antes de impuestos) sea al menos este importe. Déjalo vacío para mostrarlo siempre.
Geo zone: ofrece Mercado Envios solo para direcciones de esta zona geográfica. All zones (predeterminado) significa sin límite. La zona geográfica no se comprueba cuando Ignore shipping zones está activado. Las zonas geográficas se gestionan en System > Localisation > Geo Zones.
Ignore shipping zones: ofrece el método para los países indicados abajo, sin importar la zona geográfica seleccionada.
Countries: los países de destino para ese modo. Déjalo vacío para todos los países activados de la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Envío gratuito
Free shipping from: el subtotal de los productos que requieren envío (después del cupón y antes de impuestos) a partir del cual este método es gratuito. En ese caso no se hace ninguna solicitud a la API. Déjalo vacío para desactivarlo.
Avanzado
Debug log: escribe las solicitudes a la API y el cálculo de tarifas en storage/logs/vfd_mrcv_debug.log.php (en OpenCart 4, system/storage/logs/vfd_mrcv_debug.log.php). El archivo no se puede leer desde la web. Los errores siempre se registran, incluso con esta opción desactivada. El token de acceso y las direcciones de los clientes nunca se registran. Cuando el archivo llega a 5 MB, se traslada a vfd_mrcv_debug.old.log.php y se inicia un registro nuevo.
Log: muestra el tamaño y las últimas entradas del registro de depuración. Haz clic en Clear log para vaciarlo.
Remove data on uninstall: si está activado, al desinstalar la extensión se borran los ajustes y el registro. Si está desactivado (predeterminado), se conservan para una nueva instalación. Las tarifas en caché siempre se eliminan. Los datos de Mercado Envios de los pedidos realizados siempre se conservan como historial de pedidos.
Importar / Exportar
Export: haz clic en Download JSON para guardar los ajustes como archivo JSON. El token de acceso no se exporta.
Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes, por ejemplo en otra tienda. Los valores se comprueban igual que en un guardado normal. El token de acceso guardado se conserva.
Cómo funciona en la finalización de compra
Cuando OpenCart muestra los métodos de envío, pide a la extensión el precio de Mercado Envios. Si hay una Geo zone definida y la dirección está fuera de ella, no se ofrece Mercado Envios (salvo que Ignore shipping zones esté activado; en ese caso decide Countries). Solo cuentan los productos con Requires Shipping en Yes: los demás no añaden peso y no se incluyen en el subtotal. Después, la extensión comprueba el peso del carrito y el subtotal mínimo. El subtotal es el precio de los productos que requieren envío, después del descuento del cupón y antes de impuestos. Los certificados de regalo, los puntos de recompensa y el crédito de la tienda no se tienen en cuenta. 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 (4 dígitos en Argentina, también de un CPA como C1425ABC; 8 dígitos en Brasil; 5 dígitos en México), la extensión describe el carrito como un único paquete: el mayor ancho y largo de los productos, la suma de las alturas de todos los productos y el peso total en gramos. Los pesos y las dimensiones de los productos se convierten desde sus clases de peso y de longitud de OpenCart. Cada lado y el peso se elevan a los mínimos de Mercado Envios del país, de modo que los productos sin dimensiones ni peso también obtienen 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, se redondea a sus decimales y se muestra en la moneda del cliente con el impuesto de la Tax class seleccionada.
Cada cotización se guarda en caché durante hasta 1 hora (no más que la duración de la caché de OpenCart), para que el mismo carrito no dispare una nueva solicitud. Una cotización fallida no se repite durante 5 minutos. Si no se puede contactar con Mercado Pago, rechaza el token, limita las solicitudes o responde en otra moneda, todas las cotizaciones 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 *), y si no, el coste alternativo. Si no hay precio, el método se oculta. El cliente nunca ve un error de la API.
En OpenCart 4 el cliente hace clic en Choose en el bloque del método de envío de la página de finalización de compra y elige Mercado Envios en la ventana Shipping method options. El método funciona igual que en OpenCart 3.
La extensión 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 único 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 un pedido se realiza con una tarifa en tiempo real de Mercado Envios, la extensión guarda el nombre del servicio, el tiempo estimado de entrega en días y la tarifa en tiempo real. En Sales > Orders, la página del pedido muestra un bloque Mercado Envios con Mercado Envios service, Estimated delivery y Live rate (excl. tax). El bloque se muestra incluso si el método se desactiva más tarde. Un cliente registrado ve Mercado Envios service y Estimated delivery debajo del método de envío en la página de pedido de su cuenta, y las mismas líneas se añaden al correo electrónico del nuevo pedido. Los pedidos realizados con un precio de tabla o con el coste alternativo no tienen servicio. Los pedidos existentes no se ven afectados por cambios posteriores de tarifas.
En OpenCart 4, el bloque Mercado Envios se muestra encima de History. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza cada vez que el cliente vuelve a confirmar: el servicio guardado se actualiza con él, y se elimina cuando el cliente cambia a otro método de envío o cuando el pedido recibe un precio de tabla o el coste alternativo.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Mercado Envios es el primer bloque de Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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: opencart-shipping-mercado-envios y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con permiso de modificación para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (se incluyen inglés y ruso).
Si no se acepta la clave, 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. Tras cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Quitar 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 método de envío de Mercado Envios no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. Un usuario administrador que haya iniciado sesión en el administrador en el mismo navegador sigue viendo el método en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método se oculta a todos. Tras abrir una vez la página Edit, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados.
Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del administrador o la página Edit: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Desinstalar la extensión 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. Revisa Geo zone, o activa Ignore shipping zones y revisa Countries. Revisa las advertencias de la página de la extensión, los límites de peso y Minimum subtotal. El método necesita un precio: un token de acceso válido para direcciones del país de Mercado Envios, o Country prices o Fallback cost. Comprueba que los productos tengan Requires Shipping en Yes.
Las tarifas en tiempo real no aparecen: activa Debug log, recarga la finalización de compra y mira el campo Log de la página de la extensión. 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 no hay opción de Mercado Envios para la dirección.
HTTP 401 o 403 en las advertencias: el token de acceso no es válido o ha caducado. Copia de nuevo el Access Token de producción desde Mercado Pago Developers.
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.
Moneda de 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 de la extensión. Esto borra las tarifas en caché.
La página muestra "Warning: You do not have permission to modify VibeFox Mercado Envios!": es posible que el grupo de usuarios administradores solo pueda ver los ajustes. Da al grupo el permiso de modificación para extension/shipping/vfd_mercado_envios (OpenCart 3) o extension/vfd_mercado_envios/shipping/vfd_mercado_envios (OpenCart 4) en System > Users > User Groups.
Para desarrolladores: la dirección de la API de Mercado Envios se puede sustituir con el ajuste vfd_mrcv_api_url (para pruebas); no tiene campo en la página de configuración.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox Mercado Envios. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable Mercado Envios shipping, Sort order, Tax class y Geo zone. Las tarifas en caché y el último error de la API siempre se eliminan. Si Remove data on uninstall está activado, también se borran los demás ajustes y el registro de depuración. Si está desactivado, se conservan y se vuelven a usar cuando vuelvas a instalar la extensión. Los datos de Mercado Envios de los pedidos realizados siempre se conservan, y los pedidos existentes mantienen su método de envío y su coste.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Mercado Envios en la lista de extensiones instaladas y, después, en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.
Mercado Envios y Mercado Pago son marcas comerciales de sus respectivos propietarios. Esta extensión no está afiliada ni respaldada por Mercado Envios ni por Mercado Pago.