VibeFox iMile for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado con la versión 3.0.5.0) u OpenCart 4.0.2 o posterior (probado con la versión 4.1.0.3).
PHP: 8.0 o posterior.
Tarifa de iMile: los precios que acordaste con el equipo de ventas de iMile. Los introduces en la tabla de precios en la moneda predeterminada de tu tienda.
Cuenta de la API de iMile (solo para la estimación en tiempo real): la estimación en tiempo real usa la OpenAPI de iMile "Estimated order delivery costs". Necesitas un Customer ID y una Secret key (la clave de API que iMile emite con tu Customer ID). Para un cliente de prueba, regístrate en el portal de desarrolladores de iMile (developer.imile.com). Las claves de producción las proporciona tu gestor de cuenta de iMile. Si solo usas la tabla de precios, no necesitas claves de API.
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 para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 vfd_imile-oc3-(version).ocmod.zip y el paquete de OpenCart 4 vfd_imile.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 área de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_imile-oc3-(version).ocmod.zip. La extensión no añade modificaciones OCMOD, así que no necesitas actualizar Extensions > Modifications. En lugar del instalador, también 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 iMile 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 ajustes.
4. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia en la parte superior de la página Edit y haz clic en Activate (consulta Clave de licencia).
5. Introduce tus precios de iMile en la Price table. Opcionalmente, rellena la sección Live rates (API) y activa Live estimate (consulta Configuración). Activa Enable iMile y haz clic en Save.
OpenCart 4
1. En el área de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo vfd_imile.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 iMile, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).
4. Introduce tu clave de licencia y los ajustes como en los pasos 4 y 5 para OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.
Tras la instalación, el método está desactivado hasta que actives Enable iMile y guardes. Si vuelves a instalar la extensión después de desinstalarla, se usan de nuevo los ajustes de iMile que conservaste.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Shipping > VibeFox iMile > Edit. Las secciones aparecen en la parte izquierda. Un botón Save guarda toda la página sin recargarla. Cada guardado también borra las estimaciones de iMile en caché y los tokens de acceso. Solo los usuarios administradores con el permiso de modificación para esta extensión pueden guardar los ajustes.
Al guardar, la extensión comprueba que Method title sea válido (64 caracteres como máximo, sin los caracteres < > ; = # { }), que los campos de precio, importe y peso sean números de 0 o más, que Minimum weight (kg) no sea mayor que Maximum weight (kg), que Sort order sea un número entero y que la clase de impuesto y la zona geográfica existan. En caso contrario, muestra un error y no guarda nada.
Aparecen advertencias sobre los ajustes (y de nuevo tras un guardado) cuando Live estimate está activado pero no puede funcionar: el Customer ID o la Secret key están vacíos, falta la ciudad o el país de origen (o el país no es un mercado de iMile), no hay tipos de cambio, o la tabla de precios está vacía y no hay precio para los demás países. También aparece una advertencia cuando la tienda no tiene una clase de peso en kilogramos y la unidad de la clase de peso predeterminada no es reconocida por la extensión: los pesos de los productos se toman entonces como kilogramos, así que añade una clase de peso kg en System > Localisation > Weight Classes.
General
Los ajustes se aplican a todas las zonas geográficas. Puedes limitar el método a una zona geográfica en Conditions, o activar Ignore shipping zones en Countries para limitarlo a una lista de países.
Enable iMile: muestra u oculta iMile en la finalización de compra. Por defecto: desactivado.
Method title: el nombre del método de envío que ve el cliente en el carrito y en la finalización de compra. Por defecto: iMile. Obligatorio.
Sort order: la posición de iMile entre los métodos de envío en la finalización de compra. Un número entero.
Live rates (API) (opcional)
Si iMile no devuelve ninguna estimación (sin claves, sin ciudad introducida todavía, error, tiempo de espera, sin tipo de cambio), se usa la tabla de precios.
Live estimate: actívalo para obtener el coste de envío de iMile. Por defecto: desactivado. Con la estimación en tiempo real desactivada, no se envía nada a iMile durante la finalización de compra.
Environment: Production (openapi.imile.com) (predeterminado) o Test (test-openapi.52imile.cn). Las claves de prueba solo funcionan con el servidor de pruebas y dan precios de prueba.
Customer ID: el código de cliente (customerId) emitido por iMile, por ejemplo C2102192601. Al borrarlo también se borra la Secret key guardada.
Secret key: la clave secreta (clave de API) emitida por iMile junto con el Customer ID. Firma las solicitudes. Tras guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla.
Signature: cómo se firman las solicitudes.
Ship-from country: el país desde el que envías. La primera opción, Store country, usa el país de tu tienda. La lista contiene solo los países para los que la extensión tiene códigos de país de iMile.
Ship-from city: la ciudad desde la que se envían tus paquetes, escrita como en la lista de ciudades de iMile (por ejemplo Dubai, Riyadh). Es obligatoria para las estimaciones en tiempo real: OpenCart no tiene una ciudad de la tienda, así que sin este campo solo se usa la tabla de precios.
Ship-from province: opcional, por ejemplo Dubai o Riyadh Province.
iMile service: el tipo de pedido que se envía a iMile: Delivery order (100) (predeterminado) o Express order (1100). Express debe estar habilitado para tu cuenta y país.
Goods category: el tipo de mercancía que se envía a iMile: Normal goods (predeterminado), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents o Parcel.
Exchange rates: iMile estima en la moneda del país de destino. Escribe una línea por moneda con el precio de 1 unidad en la moneda predeterminada de tu tienda, por ejemplo "AED = 0.25" o "SAR = 0.24". No se necesita un tipo de cambio para la propia moneda de la tienda. Sin tipo de cambio, las estimaciones en esa moneda no se usan y se utiliza la tabla de precios. El mismo tipo de cambio convierte el valor del carrito declarado a iMile.
Prices (se usan cuando la estimación en tiempo real está desactivada y como alternativa cuando iMile no devuelve ninguna estimación)
Introduce tu tarifa de iMile en la moneda predeterminada de la tienda, sin impuestos. Si está en AED, SAR u otra moneda, conviértela antes.
Price table: una fila por país de destino. Haz clic en Add country para añadir una fila y en el botón × para quitarla. Elige * All other countries para una fila que cubra todos los países sin fila propia. Cada fila tiene un Base price y columnas de peso opcionales: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg y XL >5 kg. Una columna de peso vacía (o 0) usa el precio base. Un precio base de 0 significa envío gratuito a ese país. Se aceptan tanto "9.99" como "9,99".
Price for countries not in the table: un precio en la moneda predeterminada de la tienda. Se usa cuando la tabla no tiene una fila para el país de destino (y no hay fila *), o la fila no tiene precio para ese peso. Déjalo vacío para ocultar el método en ese caso.
Price applies: cómo se cobra el precio.
La misma elección se aplica a la estimación en tiempo real: por pedido envía un paquete con todo el carrito; por artículo pide una estimación por cada paquete distinto y la multiplica por el número de unidades. Si el carrito tiene más de 5 paquetes distintos, se usa la tabla de precios.
Los pesos de los productos se convierten de su clase de peso de OpenCart a kilogramos, y las dimensiones de su clase de longitud a centímetros.
Conditions
Minimum weight (kg): oculta el método por debajo de este peso del carrito. 0 significa sin límite (predeterminado).
Maximum weight (kg): oculta el método por encima de este peso del carrito. Por defecto: 30. 0 significa sin límite. Si dejas el campo vacío, se usan 30 kg.
Minimum order amount: muestra el método solo cuando el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) alcanza este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal de los productos que necesitan envío (después del cupón, antes de impuestos) a partir del cual el envío con iMile es gratuito. Déjalo vacío para no ofrecer nunca envío gratuito.
Tax class: la clase de impuesto del coste de envío, o No tax (predeterminado). Elige No tax si los precios de la tabla y las estimaciones de iMile ya incluyen el IVA.
Geo zone: ofrece iMile 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.
Countries
Ignore shipping zones: cuando está activado, no se comprueba la Geo zone y iMile se ofrece para los países indicados abajo. Cuando está desactivado (predeterminado), solo se aplica la Geo zone.
Countries: los países de destino permitidos. Déjalo vacío para permitir todos los países habilitados en la tienda. Este campo solo se usa cuando Ignore shipping zones está activado.
Advanced
Debug log: escribe los cálculos de tarifas en storage/logs/vfd_imle_debug.log.php (en OpenCart 4, system/storage/logs/vfd_imle_debug.log.php). El archivo no se puede leer desde la web. No se registran claves ni direcciones de clientes. Las solicitudes fallidas a iMile siempre se registran, incluso con el registro de depuración desactivado. Desactiva el registro cuando termines. Cuando el archivo llega a 5 MB, se mueve a vfd_imle_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: cuando está activado, al desinstalar la extensión se borran los ajustes de iMile y el registro. Cuando está desactivado (predeterminado), los ajustes se conservan para una nueva instalación. Las estimaciones en caché y los tokens de acceso siempre se borran.
Import / Export
Export: haz clic en Download JSON para guardar los ajustes como un archivo JSON. La Secret key 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. La Secret key guardada 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 iMile. Si se ha definido una Geo zone, Ignore shipping zones está desactivado y la dirección está fuera de la zona geográfica, iMile no se ofrece. Solo cuentan los productos con Requires Shipping en Yes: los demás productos no suman peso ni se incluyen en el importe del pedido. A continuación, la extensión comprueba las condiciones: países permitidos (cuando Ignore shipping zones está activado), peso del carrito e importe mínimo del pedido. El importe del pedido es el precio de los productos que necesitan 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 iMile.
Con la estimación en tiempo real activada, la extensión envía a iMile el país, la provincia y la ciudad de origen, el país, la región, la ciudad y el código postal de destino, el peso del carrito en kg, el tamaño en cm³ (a partir de las dimensiones de los productos), el valor del carrito, el servicio de iMile y la categoría de mercancía. La estimación siempre se solicita como prepago, así que las tarifas de pago contra reembolso no se incluyen. Una estimación en tiempo real solo se solicita después de que el cliente haya introducido una dirección de entrega con ciudad, y solo cuando todos los productos del carrito tienen peso.
Cada respuesta se guarda en caché durante 1 hora. Una solicitud fallida se guarda en caché durante 5 minutos. Tras un tiempo de espera o un error del servidor, no se vuelve a consultar a iMile durante 2 minutos; tras unas claves rechazadas, durante 5 minutos, para que la finalización de compra no espere a iMile en cada actualización. El tiempo de espera de la API es de 12 segundos. Un token de acceso caducado se renueva automáticamente.
La estimación se convierte a la moneda predeterminada de la tienda con tus tipos de cambio. Si iMile no da una estimación utilizable (claves no configuradas, ciudad aún no introducida, ciudad desconocida, error, tiempo de espera, sin tipo de cambio), el cliente no ve ningún error y se usa el precio de la tabla. Si la tabla tampoco tiene un precio, el método se oculta. El motivo se escribe en el registro. El precio se calcula en tu moneda predeterminada, se redondea a sus decimales y se muestra al cliente en su moneda con el impuesto de la Tax class seleccionada.
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 iMile 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 de iMile, no imprime etiquetas AWB, no solicita recogidas, no hace el seguimiento de paquetes, no concilia los pagos contra reembolso ni ofrece puntos de recogida ni taquillas. No añade nada a los pedidos: el pedido muestra el nombre del método y el coste de envío como cualquier otro método de envío de OpenCart. Usa el portal de iMile para los envíos.
Clave de licencia
La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox iMile es el primero en la página Extensions > Extensions > Shipping > VibeFox iMile > Edit, por encima de los ajustes. Introduce 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-shipping-imile y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso de modificación de la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (se incluyen inglés y ruso).
Si la clave no se acepta, 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, 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 iMile 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 área de administración 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. Después de abrir la página Edit una vez, 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 después de introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Al desinstalar la extensión, la clave de licencia y el estado de la licencia siempre se eliminan.
Solución de problemas
iMile no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable iMile esté activado. Revisa Geo zone, Ignore shipping zones y Countries, los límites de peso y Minimum order amount. Comprueba que el país o * All other countries tenga una fila en la Price table, o que Price for countries not in the table esté definido. Comprueba que los productos tengan Requires Shipping en Yes.
Se muestra el precio de la tabla en lugar de la estimación de iMile: activa Debug log, recarga la finalización de compra y mira el campo Log en la página de la extensión. Motivos habituales: Live estimate está desactivado, faltan las claves, Ship-from city está vacío, el cliente todavía no ha introducido una ciudad, iMile no reconoce la escritura de la ciudad, los productos no tienen peso, no hay tipo de cambio para la moneda de destino, o un error de la API. Revisa también las advertencias sobre los ajustes.
"sign is invalid" en el registro: revisa la Secret key y luego prueba con Signature = SimpleKey.
Las claves se rechazan: revisa el Customer ID, la Secret key y el Environment. Las claves de prueba solo funcionan con el servidor de pruebas.
Los nombres de ciudad no coinciden: los nombres de ciudad deben coincidir con la lista de ciudades de iMile. Los desarrolladores pueden cambiar la solicitud con el evento de OpenCart vfd_imile/live_request, y los códigos de país con el evento vfd_imile/live_country_code.
Los precios están en la moneda incorrecta: la tabla de precios está en la moneda predeterminada de la tienda. Convierte una tarifa en AED, SAR o MXN al introducirla. Las estimaciones en tiempo real se convierten con Exchange rates.
El impuesto se cobra dos veces en el envío: si tus precios ya incluyen el IVA, pon Tax class en No tax.
Las estimaciones parecen desactualizadas tras un cambio: haz clic en Save en la página de la extensión. Esto borra las estimaciones de iMile en caché.
La página indica "Warning: You do not have permission to modify VibeFox iMile!": tu grupo de usuarios de administración puede solo ver los ajustes. Concede al grupo el permiso de modificación para extension/shipping/vfd_imile (OpenCart 3) o extension/vfd_imile/shipping/vfd_imile (OpenCart 4) en System > Users > User Groups.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Shipping y haz clic en Uninstall (el botón rojo −) junto a VibeFox iMile. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre restablece Enable iMile, Sort order, Tax class y Geo zone. Las estimaciones en caché y los tokens de acceso siempre se eliminan. Si Remove data on uninstall está activado, los ajustes de iMile y el registro de depuración también se borran. Si está desactivado, los demás ajustes se conservan y se usan de nuevo al volver a instalar la extensión. 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, haz clic en Uninstall (el botón naranja −) junto a VibeFox iMile en la lista de extensiones instaladas y luego en Delete (el botón rojo con forma de papelera) para eliminar el paquete subido.
iMile es una marca comercial de su titular. Esta extensión no está afiliada a iMile ni cuenta con su respaldo.