VibeFox Blue Express 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 Blue Express (solo para tarifas en tiempo real): las tarifas en tiempo real requieren una cuenta de comercio electrónico de Blue Express y su clave de API (x-api-key). Solicítala a Blue Express: developers.bluex.cl o gpo.integraciones@bx.cl. El servicio que uses (EX, PY o MD) debe estar habilitado en tu contrato con Blue Express. Si solo usas precios fijos, no necesitas clave de API.
Regiones chilenas: para una tarifa en tiempo real, la dirección de entrega debe tener una región chilena. Si tu tienda no tiene regiones para Chile, el módulo puede añadirlas por ti (consulta Configuración).
Puntos de recogida: el mapa de Blue Express se carga desde widget-pudo.blue.cl en el navegador del cliente.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 carga, haz clic en Configure, o busca VibeFox Blue Express en la lista de módulos más tarde y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página de Configure y haz clic en Activate (ver Clave de licencia).
4. Introduce la clave de API, el servicio, el código de distrito de origen (por ejemplo SCL), el tipo de cambio a CLP si la moneda de tu tienda no es CLP y los precios fijos (por ejemplo CL=4500). Activa Pickup point carrier si quieres ofrecer la recogida en puntos de Blue Express. Haz clic en Save. Consulta Configuración.
Al instalarse, el módulo crea dos transportistas: Blue Express (entrega a domicilio, con el texto de tiempo de entrega Home delivery, activado) y Blue Express pickup point (con el texto de tiempo de entrega Pickup at a Blue Express point, desactivado hasta que lo actives). Ambos están asignados a la zona de Chile y a todos los grupos de clientes. Puedes cambiar las zonas, los grupos de clientes, el tiempo de entrega, el logotipo y los límites de tamaño en Shipping > Carriers. No configures precios allí: el precio siempre viene del módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Blue Express > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cada guardado también borra las tarifas de Blue Express y los datos de comunas en caché. En la parte superior de la página aparecen advertencias sobre los ajustes que ocultarían los transportistas o la tarifa en tiempo real: sin clave de API, moneda de la tienda distinta de CLP sin tipo de cambio, tabla de precios fijos vacía, sin regiones para Chile, una unidad de peso o de dimensiones de la tienda que el módulo no conoce (los pesos se leen entonces como kg y las dimensiones como cm), o un transportista eliminado. Los valores no válidos se rechazan con un error y no se guarda nada: un nombre de transportista vacío o no válido, un nombre de más de 64 caracteres, un número negativo o no válido, o Min weight (kg) mayor que Max weight (kg). Las condiciones y los precios que se describen a continuación se aplican a ambos transportistas.
General
Enable/Disable: activa o desactiva el transportista de entrega a domicilio. Es el mismo interruptor que el estado del transportista en Shipping > Carriers.
Name: el nombre del transportista que se muestra en la finalización de compra para la entrega a domicilio. Por defecto: Blue Express. Obligatorio, como máximo 64 caracteres.
Tax status: None (no tax on shipping) o Taxable con una de tus reglas de impuesto. Las tarifas de Blue Express incluyen IVA. Elige None si PrestaShop no debe añadir impuestos encima. Se aplica a ambos transportistas.
Pickup at Blue Express points (PUDO)
Pickup point carrier: ofrece la entrega en un punto de Blue Express elegido por el cliente, como segundo transportista junto a la entrega a domicilio. Desactivado por defecto. Es el mismo interruptor que el estado del transportista Blue Express pickup point en Shipping > Carriers.
Pickup point name: el nombre del transportista que se muestra en la finalización de compra para la recogida en un punto de Blue Express. Por defecto: Blue Express pickup point. Obligatorio, como máximo 64 caracteres.
Blue Express API (necesaria para las tarifas en tiempo real)
API key: tu clave de API de Blue Express (cabecera x-api-key). Sin ella solo se usan los precios fijos. Después de guardar, el campo queda vacío y muestra A key is saved - leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla. Marca Remove the saved API key y guarda para eliminarla.
Service: el servicio de Blue Express que se usa para la tarifa: Express (EX) (por defecto), Prioritario (PY) o SameDay (MD). Debe estar habilitado en tu contrato con Blue Express.
Origin district code: el código de distrito de Blue Express del lugar desde el que envías, por ejemplo SCL para Santiago (por defecto). Consúltalo con Blue Express si no estás seguro.
CLP per 1 unit of store currency: cuando la moneda predeterminada de tu tienda no es CLP, la etiqueta lo muestra, por ejemplo CLP per 1 EUR. Los precios de Blue Express están en pesos chilenos (CLP). Introduce cuántos CLP vale una unidad de la moneda predeterminada de tu tienda, por ejemplo 1050. Sin este valor no se usan las tarifas en tiempo real. Se ignora si la moneda de la tienda es CLP.
Price
Rate source: cómo se calcula el precio. La tarifa en tiempo real necesita una dirección chilena con región y comuna (ciudad). Los errores se escriben en el registro y nunca se muestran al cliente.
Fixed prices: una línea por país en el formato COUNTRY_CODE=PRICE, en la moneda predeterminada de tu tienda, sin impuestos, por ejemplo CL=4500 en una tienda en CLP o CL=4.50 en una tienda en EUR. Se aceptan la coma y el punto como separador decimal. Las líneas no válidas se ignoran y aparecen en una advertencia al guardar. Un país sin línea no tiene precio fijo, así que los transportistas se ocultan para él cuando se necesita el precio fijo. Los precios fijos pueden usarse para cualquier país.
Fixed price per: Order cobra el precio una sola vez. Item (price x quantity) lo multiplica por el número de artículos del carrito. Esto se aplica solo al precio fijo. La tarifa de la API siempre es para el envío completo.
Conditions
Min weight (kg): oculta los transportistas cuando el carrito pesa menos. 0 significa sin límite.
Max weight (kg): oculta los transportistas cuando el carrito pesa más. Por defecto: 100. 0 significa sin límite; un campo vacío significa 100 kg. Min weight (kg) no puede ser mayor que Max weight (kg).
Minimum order subtotal: muestra los transportistas solo a partir de este subtotal del carrito (moneda de la tienda, después de descuentos, sin impuestos). Déjalo vacío para mostrarlos siempre.
Free shipping
Free shipping: activa el envío gratuito a partir de un subtotal del carrito.
Free from subtotal: el subtotal del carrito (moneda de la tienda, después de descuentos, sin impuestos) a partir del cual el envío es gratuito. Se usa solo cuando Free shipping está activado.
Availability without shipping zones
Ignore shipping zones: ofrece ambos transportistas en todas las zonas. Los países se limitan entonces con la lista siguiente. Las zonas creadas después también se añaden. Cuando lo desactives de nuevo, los transportistas recuperan las zonas que tenían antes.
Countries: los países de destino para ese modo. Déjalo vacío para usar todos los países a los que envías. Solo se usa con Ignore shipping zones.
Advanced
Debug log: registra las solicitudes y las decisiones en logs/vfd_blex_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores de la API siempre se registran. La clave de API y las direcciones de los clientes nunca se registran. Desactiva el registro cuando termines.
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 borran los ajustes y los transportistas. Los puntos de recogida guardados en los pedidos se conservan.
Chilean regions (se muestra solo cuando tu tienda no tiene regiones chilenas utilizables)
Blue Express necesita la región de una dirección chilena (RM, VS, etc.) para la tarifa en tiempo real. PrestaShop no incluye las regiones chilenas por defecto. Haz clic en Add Chilean regions para añadir las 16 regiones chilenas como estados de Chile, con los códigos que usa Blue Express, y para mostrar el campo de región en el formulario de direcciones chilenas. Las regiones que ya tengas, por código o por nombre, no se añaden dos veces. No se cambia nada hasta que hagas clic en el botón. También puedes añadirlas tú mismo en International > Locations > States con los códigos RM, VS, etc.
Cómo funciona en la finalización de compra
En el paso de envío, PrestaShop pide al módulo el precio de cada transportista de Blue Express. Solo cuentan los productos físicos: los productos virtuales no añaden peso y no se incluyen en el subtotal. El módulo comprueba Countries (con Ignore shipping zones), el peso del carrito y el Minimum order subtotal. Si se aplica el envío gratuito, el precio es 0 y no se envía ninguna solicitud a Blue Express.
Para una tarifa en tiempo real, la dirección debe estar en Chile, con región y ciudad (comuna). El módulo primero pide a Blue Express que reconozca la comuna y después solicita el precio del servicio, el distrito de origen, el destino y los paquetes. Cada producto se envía con su peso y sus dimensiones convertidos a kg y cm. Los productos sin peso o tamaño se envían como 0,01 kg, 10 x 10 x 10 cm. El valor declarado se envía en CLP. El precio en CLP se convierte a la moneda predeterminada de tu tienda y después se muestra en la moneda del carrito del cliente.
Las tarifas se guardan en caché durante 1 hora y los datos de comunas durante 12 horas. Una llamada fallida a la API se recuerda durante 5 minutos, y el tiempo de espera es de 10 segundos, para que una API lenta o no disponible no ralentice cada actualización de la finalización de compra. Los errores de la API nunca se muestran al cliente: el transportista se oculta o, en el modo con precio fijo de respaldo, se usa el precio fijo. El motivo se escribe en el registro.
Si editas un 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 no crea envíos ni etiquetas en Blue Express, no asigna números de seguimiento y no muestra actualizaciones de seguimiento. Crea el envío en tu cuenta de Blue Express. No hay tablas de tarifas regionales por comuna: usa la tarifa de la API de Blue Express o un precio fijo por país. Las tarifas en tiempo real funcionan solo para Chile.
Puntos de recogida
Cuando el cliente selecciona Blue Express pickup point en el paso de entrega, aparece debajo un recuadro con el botón Choose pickup point. El botón abre el mapa oficial de Blue Express, donde el cliente elige un punto. El punto elegido se muestra con su nombre y su dirección, y el botón cambia a Change pickup point. El punto se guarda en el carrito y la tarifa se recalcula con el precio de recogida (PUDO) de Blue Express. Si el precio cambia, la página se recarga para mostrarlo. Hasta que se elija un punto, el transportista muestra el precio del paquete de entrega a domicilio.
El cliente no puede continuar sin un punto: Please choose a Blue Express pickup point. La tienda lo comprueba cuando el cliente hace clic en Continue en el paso de entrega. Un código de punto mal formado se rechaza con The selected Blue Express pickup point is not valid. Please choose it again on the map., y la elección anterior se mantiene.
Al realizar el pedido, el punto se guarda en él con su código de agencia de Blue Express, su nombre y su dirección. En la página de pedido del administrador se muestra en el bloque Blue Express pickup point. Haz clic en Edit para elegir otro punto con Choose on the Blue Express map o para introducir a mano el Agency code, el Name y la Address, y después haz clic en Save pickup point. El cambio se registra como un mensaje privado del pedido. Cambiar el punto solo requiere permisos de edición de pedidos, no acceso a las páginas de Módulos. El cliente ve el punto en la página de confirmación del pedido, en la página de detalle del pedido y en el correo de confirmación del pedido, junto al nombre del transportista. El nuevo correo de pedido a la tienda (del módulo Mail alerts) también muestra el código de agencia. Los pedidos existentes conservan los datos de su punto de recogida.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Blue Express es el primer bloque de Modules > Module Manager > VibeFox Blue Express > Configure, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-shipping-blue-express 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 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 de liberar un 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 dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su dominio. Libera el dominio en tu cuenta de vibefox.net.
Sin una clave activa, los transportistas de Blue Express no se muestran a los clientes en la finalización de compra y no se calcula ninguna tarifa. La tienda 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 a la semana. No hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Blue Express no aparece en la finalización de compra: comprueba que la licencia esté activa y que Enable/Disable (o Pickup point carrier) 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. Lee las advertencias de la parte superior de la página del módulo. Revisa los límites de peso, el Minimum order subtotal y que Fixed prices tenga una línea para el país si usas precios fijos o la alternativa. Los productos también pueden limitarse a ciertos transportistas en la página del producto.
Las tarifas en tiempo real no aparecen: con Blue Express API only, los transportistas se ocultan cuando no hay tarifa. Activa Debug log, recarga la finalización de compra y mira el campo Log en la página del módulo. Motivos habituales: no hay clave de API, la moneda de la tienda no es CLP sin tipo de cambio, falta la región o la comuna en la dirección, Blue Express no reconoce la comuna o hay un error de la API (por ejemplo HTTP 401 o 403 cuando se rechaza la clave de API). Con Blue Express API, fixed price if the API gives no rate, los clientes siguen recibiendo el precio fijo mientras corriges el problema.
Las direcciones chilenas no tienen región: la página muestra una advertencia sobre las regiones que faltan. Haz clic en Add Chilean regions en la página del módulo. Los clientes cuyas direcciones se guardaron sin región deben editar la dirección y elegir la región.
Se añade impuesto encima de la tarifa de Blue Express: las tarifas de Blue Express incluyen IVA. Pon Tax status en None (no tax on shipping).
El mapa no se abre: el mapa se carga desde widget-pudo.blue.cl en el navegador del cliente, así que esta dirección debe ser accesible y no estar bloqueada en tu sitio.
Las tarifas parecen desactualizadas después de un cambio: haz clic en Save en la página del módulo. Esto borra las tarifas y los datos de comunas en caché.
La página indica que falta un transportista de Blue Express: el transportista se eliminó en Shipping > Carriers. Restablece el módulo en Modules > Module Manager para volver a crearlo. El restablecimiento conserva tus ajustes y el estado de los transportistas.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Blue Express y elige Uninstall. La clave de licencia, el estado de la licencia y las tarifas en caché siempre se eliminan. Si Remove data on uninstall está activado, se eliminan ambos transportistas (los pedidos conservan su historial), los ajustes, el registro y los puntos de recogida que no estén vinculados a un pedido. Si está desactivado, los transportistas solo se desactivan y se conservan todos los ajustes. Al volver a instalar el módulo, los transportistas se restauran con el estado que tenían antes. Los puntos de recogida guardados en los pedidos nunca se eliminan.
Blue Express es una marca comercial de su respectivo titular. Este módulo no está afiliado a Blue Express ni cuenta con su aprobación.