VibeFox iMile for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Tarifa de iMile: los precios acordados con el equipo comercial de iMile. Los introduces en la tabla de precios en la moneda predeterminada de tu tienda.
Cuenta de 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 junto con tu Customer ID). Para un cliente de prueba, regístrate en el portal para desarrolladores de iMile (developer.imile.com). Las claves de producción las facilita 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
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 iMile 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. Introduce tus precios de iMile en la Price table. Opcionalmente, rellena la sección Live rates (API) y activa Live estimate (consulta Configuración). Haz clic en Save.
Al instalar, el módulo crea el transportista iMile con el texto de plazo de entrega Courier delivery. El transportista se asigna a todas las zonas y a todos los grupos de clientes. 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 definas 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 iMile > Configure. Se aplican a todas las zonas del transportista. Cada sección tiene su propio botón Save, que guarda la página completa. Cada guardado también borra las estimaciones de iMile en caché y los tokens de acceso.
Si Live estimate está activado pero no puede funcionar, aparecen advertencias encima de los ajustes: 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 otros países. También aparece una advertencia cuando el módulo no reconoce la unidad de peso de la tienda: en ese caso, los pesos de los productos se toman como kilogramos, así que configura la unidad en International > Localization (Local units). Al guardar, el módulo comprueba que Method title sea válido (64 caracteres como máximo), que los campos de importe y de peso sean números iguales o mayores que 0, que Minimum weight no sea mayor que Maximum weight y que exista la regla de impuesto. Si no, muestra un error y no guarda nada.
General
Enable iMile: activa o desactiva el transportista. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Method title: el nombre del transportista que se muestra en el carrito y en la finalización de compra. Predeterminado: iMile. Obligatorio.
Tarifas en tiempo real (API) (opcional)
Si iMile no devuelve ninguna estimación (sin claves, sin ciudad introducida todavía, error, tiempo de espera o sin tipo de cambio), se usa la tabla de precios.
Live estimate: actívala para obtener el coste de envío de iMile. Predeterminado: 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 devuelven precios de prueba.
Customer ID: el código de cliente (customerId) que emite iMile, por ejemplo C2102192601. Al borrarlo, también se borra la Secret key guardada.
Secret key: la clave secreta (clave de API) que emite iMile junto con el Customer ID. Firma las solicitudes. Después de guardar, el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.
Signature: cómo se firman las solicitudes.
Ship-from country: el país desde el que envías. Por defecto es el país de tu tienda (Shop country). La lista solo contiene los países para los que el módulo 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). Déjala vacía para usar la ciudad de la tienda indicada en Shop Parameters > Contact > Stores.
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). El servicio Express debe estar habilitado para tu cuenta y tu 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 calcula las estimaciones en la moneda del país de destino. Introduce 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". Se acepta un punto o una coma como separador decimal. No hace falta 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. Las líneas no válidas se eliminan al guardar.
Precios (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 icono de papelera para eliminar una. Elige * All other countries para una fila que cubra todos los países que no tienen 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 con 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". Al guardar se eliminan las filas sin ningún precio y los precios negativos. Solo se conserva una fila por país.
Price for countries not in the table: un precio en la moneda predeterminada de la tienda. Se usa cuando la tabla no tiene fila para el país de destino (y no hay fila *), o cuando la fila no tiene precio para ese peso. Déjalo vacío para ocultar el transportista en ese caso.
Price applies: cómo se cobra el precio de la tabla.
La misma opción se aplica a la estimación en tiempo real: por pedido envía un solo paquete con todo el carrito; por artículo pide una estimación para 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 y las dimensiones de los productos se convierten de las unidades de tu tienda a kilogramos y centímetros.
Condiciones
Minimum weight: oculta el transportista cuando el carrito pese menos, en kg. 0 significa sin límite.
Maximum weight: oculta el transportista cuando el carrito pese más, en kg. Predeterminado: 30. 0 significa sin límite.
Minimum order amount: muestra el transportista solo cuando el subtotal del carrito (después de descuentos, antes de impuestos) alcance este importe. Déjalo vacío para mostrarlo siempre.
Free shipping from: el subtotal del carrito (después de descuentos, antes de impuestos) a partir del cual la entrega con iMile es gratuita. Déjalo vacío para no ofrecer nunca envío gratuito.
Tax: la regla de impuesto del transportista, o No tax. Elige No tax si los precios de la tabla y las estimaciones de iMile ya incluyen el IVA.
Disponibilidad sin zonas de envío
Ignore shipping zones: ofrece iMile para los países indicados abajo, sea cual sea la zona que coincida. Al guardar, el transportista se añade a todas las zonas, y las zonas creadas después también lo reciben. Al desactivar la opción, se eliminan esas zonas añadidas y el transportista recupera las zonas que tenía antes.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países activos. Este campo solo se usa cuando Ignore shipping zones está activado.
Avanzado
Debug log: escribe los cálculos de tarifas en logs/vfd_imle_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir 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. Desactívalo cuando termines.
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 el módulo se borran los ajustes de iMile, el transportista, las estimaciones 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 iMile. Solo cuentan los productos físicos: los productos virtuales no suman peso y no se incluyen en el importe del pedido. El módulo comprueba primero las condiciones: países permitidos (cuando Ignore shipping zones está activado), peso del carrito e importe mínimo del pedido. 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, el módulo envía a iMile el país, la provincia y la ciudad de origen, el país, el estado, 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 prepagada, así que no se incluyen las tasas de contrareembolso. La 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 consulta a iMile durante 2 minutos; tras 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 ofrece una estimación utilizable (claves sin configurar, ciudad aún no introducida, ciudad desconocida, error, tiempo de espera o sin tipo de cambio), el cliente no ve ningún error y se usa el precio de la tabla. Si la tabla tampoco tiene precio, el transportista se oculta. El motivo se escribe en el registro. El precio se calcula en tu moneda predeterminada y después se muestra en la moneda del carrito del cliente.
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 de iMile, no imprime etiquetas AWB, no solicita recogidas, no hace seguimiento de paquetes, no concilia los importes contra reembolso ni ofrece puntos de recogida y taquillas. Usa el portal de iMile para los envíos.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox iMile es el primer bloque de Modules > Module Manager > VibeFox iMile > Configure, encima de los ajustes. Introduce 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-imile y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 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, 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. 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 transportista iMile no se muestra a los clientes en la finalización de compra y no se calcula ninguna tarifa. El front office 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 requieren 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 por 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
iMile no aparece en la finalización de compra: comprueba que la licencia está activa y que Enable iMile está activado. En Shipping > Carriers, comprueba que el transportista cubre la zona del país del cliente y el grupo del cliente, o activa Ignore shipping zones y revisa Countries. Revisa los límites de peso y Minimum order amount. Comprueba que el país o * tiene una fila en la Price table, o que Price for countries not in the table está definido. Los productos también pueden estar limitados a ciertos transportistas en la página del producto.
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 revisa el campo Log en la página del módulo. Motivos habituales: Live estimate está desactivado, faltan las claves, el cliente aún no ha introducido una ciudad, iMile no reconoce la ortografía de la ciudad, los productos no tienen peso, no hay tipo de cambio para la moneda de destino, o hay un error de la API. Revisa también las advertencias encima de los ajustes.
"sign is invalid" en el registro: comprueba la Secret key y luego prueba con Signature = SimpleKey.
Las claves son rechazadas: comprueba 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 asignarlos con el hook actionVfdImileLiveRequest, y los códigos de país con el hook actionVfdImileLiveCountryCode.
Los precios están en la moneda equivocada: 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 en No tax.
Las estimaciones parecen desactualizadas tras un cambio: haz clic en Save en la página del módulo. Esto borra las estimaciones de iMile en caché.
La página indica que no se encuentra el transportista iMile: 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 iMile y elige Uninstall. La clave de licencia y el estado de la licencia siempre se eliminan.Las estimaciones en caché y los tokens de acceso siempre se eliminan. Si Remove data on uninstall está activado, el transportista se elimina (los pedidos conservan su historial) y se borran los ajustes y el registro. Si está desactivado, el transportista solo se desactiva y se conservan todos los ajustes. Al volver a instalar el módulo se restaura el estado que tenía el transportista antes.
iMile es una marca comercial de su respectivo propietario. Este módulo no está afiliado a iMile ni cuenta con su respaldo.