Barra de envío gratuito (dffreeshipbar) — Guía completa

Guía completa del módulo dffreeshipbar para PrestaShop 8 y 9: instalación, umbrales por país y por estado, filtrado por transportista, posiciones de visualización, multitienda y resolución de problemas. Todas las reglas de resolución están documentadas, casos límite incluidos.

Descripción general

dffreeshipbar muestra una barra de progreso que indica al cliente cuánto le falta gastar para disfrutar del envío gratuito. Cuando se alcanza el umbral, el mensaje pasa a una confirmación.

El módulo funciona con sus propios umbrales, almacenados en sus propias tablas. En ningún momento consulta la variable nativa PS_SHIPPING_FREE_PRICE: puede dejarla a 0 y gestionar su envío gratuito mediante rangos de transportista sin conflicto alguno.

La particularidad del módulo es su resolución territorial de dos niveles. Un umbral puede definirse a nivel de país, pero también a nivel de estado de PrestaShop — lo que permite tratar de forma distinta territorios vinculados administrativamente a un mismo país, como los departamentos de ultramar vinculados a la Francia metropolitana.

Requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 como mínimo (8.0 a 8.3 compatibles)
• Tema Classic, Hummingbird o cualquier tema personalizado que invoque los hooks estándar
• Acceso de administrador al back office

Instalación

1. En el back office, ir a Módulos → Gestor de módulos → Subir un módulo.
2. Subir el archivo dffreeshipbar-2.1.0.zip.
3. Hacer clic en Instalar y luego en Configurar.

Al instalarse, el módulo crea dos tablas y registra sus hooks:

• PREFIX_dffreeshipbar_country — umbrales a nivel de país, con una columna id_shop.
• PREFIX_dffreeshipbar_state — umbrales a nivel de estado, con una columna id_shop.

Hooks registrados: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Ajustes generales

La pantalla de configuración se encuentra en Módulos → DataFirefly – Barra de envío gratuito → Configurar. Consta de tres paneles: ajustes generales, reglas de transportista y umbrales por territorio.

Umbral global de reserva

Dos ajustes vinculados:

• Usar un umbral global por defecto: en posición No, la barra solo aparece en los territorios configurados explícitamente. En posición Sí, todo territorio no configurado recibe el importe indicado debajo.
• Umbral global por defecto: el importe aplicado como último recurso.

Deje la reserva desactivada si su envío gratuito solo cubre unos pocos destinos. Actívela si es universal y las excepciones son escasas.

Base de cálculo

• Comparar totales con impuestos: determina si el total del carrito se evalúa con o sin impuestos. Debe coincidir con la base que usan sus rangos de transportista; de lo contrario, la barra y el proceso de compra no coincidirán.
• Incluir las reglas de carrito en el total: cuando está activo, los descuentos se deducen antes de comparar con el umbral. Un carrito de 70 € con un vale de 10 € se evalúa entonces en 60 €.

El total evaluado corresponde a una llamada nativa:

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Los gastos de envío y el envoltorio de regalo nunca cuentan para el progreso.

Requerir una dirección de entrega

Mientras el cliente no introduzca una dirección, el destino es solo una estimación y el estado se desconoce. Tres modos:

• Nunca: la barra se muestra desde la navegación por el catálogo, según el país estimado.
• Para países con estados (recomendado): la barra permanece visible en todas partes salvo en los países cuyos estados puedan aplicar condiciones distintas. Un visitante estimado en Bélgica ve la barra; uno estimado en Francia solo la ve tras introducir una dirección, ya que su estado determinará el umbral real.
• Siempre: nada mientras no exista una dirección en el carrito.

Posiciones y apariencia

• Mostrar en la parte superior de la página: banner visible en todo el sitio.
• Mostrar en el carrito y en la compra: bloque mostrado en el momento de la decisión.
• Activar la animación: rayas animadas mientras la barra progresa. La animación se desactiva automáticamente para los visitantes que activan prefers-reduced-motion.
• Cuatro colores: fondo, barra, texto y mensaje de éxito.

Para una colocación libre en su tema, el módulo implementa WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Umbrales por territorio

Es el núcleo del módulo. La tabla enumera todos los países activos de la tienda y, bajo cada país que tenga estados, sus estados con sangría.

Orden de resolución

Para una dirección de entrega dada, el módulo busca en este orden y se detiene en la primera coincidencia:

1. El estado de la dirección, si existe una regla para él.
2. El país de la dirección, si existe una regla para él.
3. El umbral global de reserva, si está activado.

Si ninguno de estos tres pasos produce un importe, la barra no se muestra.

Casilla e importe: dos efectos distintos

Es el punto más importante de la configuración y el que más se malinterpreta:

• Casilla desmarcada → la barra queda oculta para ese territorio. No hereda ni del país padre ni del umbral global. La resolución se detiene ahí.
• Casilla marcada, importe vacío → la regla se elimina y el territorio hereda del nivel superior.
• Casilla marcada, importe indicado → se aplica ese importe.

Ejemplo: solo península

Caso habitual de una tienda francesa que ofrece el envío gratuito a 65 € en la Francia metropolitana y Córcega, pero no en ultramar:

• Francia: casilla marcada, importe 65.
• Córcega: casilla marcada, importe vacío — hereda los 65 € de Francia.
• Guadalupe, Martinica, Guayana Francesa, Reunión, Mayotte: casillas desmarcadas. Sin barra en estos destinos.
• Umbral global de reserva: desactivado, para que ningún otro país reciba una barra por accidente.

Un cliente de Guadalupe nunca verá la promesa de envío gratuito, aunque su dirección pertenezca al país «Francia» en PrestaShop.

Filtro y búsqueda

El campo de búsqueda filtra países y estados por nombre. La casilla Mostrar solo los territorios configurados reduce la tabla a las filas que ya tienen una regla — útil en una tienda abierta a cien países.

Los dos botones de guardado son independientes: Guardar países y Guardar estados.

Reglas de transportista

Si su envío gratuito solo lo conceden algunos transportistas, restrinja la visualización en consecuencia. Tres modos:

• Todos los transportistas: sin filtrado.
• Mostrar solo para los transportistas marcados abajo: lista blanca.
• Ocultar para los transportistas marcados abajo: lista negra.

Antes de seleccionar transportista

El transportista no se conoce hasta el paso de entrega. El ajuste Antes de seleccionar transportista decide qué ocurre antes de ese momento:

• Mostrar: la barra aparece en el catálogo y el carrito, y desaparece si el cliente elige un transportista excluido.
• Ocultar: la barra solo aparece una vez seleccionado un transportista elegible.

Actualización en tiempo real

La barra se recalcula en el servidor y se refresca sin recargar la página en cada evento del carrito: añadir, eliminar, cambiar cantidad, modificar dirección, cambiar de paso en el proceso de compra.

El script escucha los eventos de PrestaShop updatedCart, updateCart, updatedAddressForm, changedCheckoutStep y updateDeliveryForm. Puede provocar un refresco manual desde su propio código:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

Es el servidor quien decide la visibilidad: si el territorio o el transportista dejan de cumplir, la barra se retira del DOM en lugar de quedarse con un valor obsoleto.

Multitienda

Los umbrales se almacenan con una columna id_shop. Cada tienda tiene por tanto sus propias reglas de país y estado, independientes entre sí.

Para configurar una tienda concreta, seleccione su contexto en la parte superior del back office antes de abrir la pantalla de configuración. El panel de umbrales muestra el nombre de la tienda actual como recordatorio.

Traducciones

El módulo se entrega traducido al español, francés, inglés, alemán, italiano y polaco.

Para adaptar los textos visibles por el cliente, ir a Internacional → Traducciones, seleccionar «Traducciones de módulos», elegir dffreeshipbar y el idioma, y buscar el dominio Modules.Dffreeshipbar.Shop. Cadenas disponibles:

• «¡Solo le faltan %amount% para el envío gratuito!» — carrito en curso.
• «Envío gratuito a partir de %amount%.» — carrito vacío.
• «¡Enhorabuena! Su pedido disfruta de envío gratuito.» — umbral alcanzado.

El testigo %amount% se sustituye por el importe formateado según la moneda y la configuración regional activas. Consérvelo en sus traducciones.

Actualización desde la versión 1.0

La actualización es automática al reemplazar el ZIP. Los scripts de actualización realizan lo siguiente:

• Creación de la tabla de estados.
• Renombrado de la columna active a enabled en la tabla de países. Sus umbrales existentes se conservan.
• El umbral global de reserva se activa si tenía uno en la 1.0, para no modificar lo que ven sus clientes.
• El modo de exigencia de dirección se ajusta a Nunca, que corresponde al comportamiento de la versión 1.0. Cámbielo al modo recomendado cuando lo decida.

Resolución de problemas

La barra no aparece en ninguna parte

1. ¿Está activado el módulo? (interruptor Activar el módulo).
2. ¿Ha configurado al menos un territorio o activado el umbral global de reserva? Sin uno u otro, la barra nunca aparece.
3. ¿Está el modo de exigencia de dirección en Siempre mientras prueba sin dirección de entrega?
4. ¿Están activadas las posiciones? (banner y/o carrito).
5. ¿Invoca su tema los hooks utilizados? Compruébelo en Módulos → Posiciones. En un tema personalizado, use el widget.

La barra aparece donde no debería

El caso típico es un territorio que hereda cuando debería estar excluido. Compruebe que la casilla del territorio esté realmente desmarcada, y no solo que se haya vaciado su importe — ambas acciones tienen efectos opuestos.

El umbral mostrado no coincide con la compra

• Compruebe que Comparar totales con impuestos coincide con la base de sus rangos de transportista.
• Compruebe el ajuste de reglas de carrito: un carrito con descuento puede caer por debajo del umbral.
• El módulo no lee sus rangos de transportista. Si modificó un rango, traslade el nuevo valor al módulo.

La barra no se actualiza tras añadir al carrito

El refresco se apoya en los eventos JavaScript de PrestaShop. Algunos temas o módulos de carrito de terceros no los emiten. Dos comprobaciones:

• ¿Señala la consola del navegador un error JavaScript en otro recurso? Un error bloqueante previo impide que se instale la escucha.
• ¿Emite realmente su módulo de carrito ajax prestashop.emit('updatedCart')? Si no, lance dffreeshipbar:refresh desde su código.

Las reglas de transportista parecen ignoradas

Compruebe que el transportista seleccionado es el que cree: tras un cambio de tarifa, PrestaShop crea un transportista nuevo. El módulo sigue la referencia, así que la regla debería seguirla también — pero si el transportista se recreó desde cero en lugar de editarse, su referencia es nueva y hay que volver a marcarlo.

Desinstalación

Ir a Módulos → Gestor de módulos → DataFirefly – Barra de envío gratuito → Desinstalar. La desinstalación elimina las dos tablas de umbrales y todas las claves de configuración con el prefijo DFFREESHIPBAR_.

FAQ rápida

• ¿Lee el módulo PS_SHIPPING_FREE_PRICE? Nunca. Puede dejarla a 0 y gestionar su envío gratuito con rangos de transportista.
• ¿Lee el módulo mis rangos de transportista para deducir el umbral? No. Los umbrales se introducen manualmente. Una sincronización automática desde los rangos es posible como desarrollo específico.
• Mi envío gratuito también depende del peso. ¿Está contemplado? No, el módulo solo mide un importe. Una condición de peso es un desarrollo específico.
• ¿Puedo mostrar la barra fuera de las posiciones propuestas? Sí, mediante {widget name='dffreeshipbar'} en cualquier plantilla.
• ¿Funciona el módulo con el tema Hummingbird? Sí. Los hooks displayNavFullWidth y displayCheckoutSummaryTop están registrados para él, y el widget cubre las colocaciones personalizadas.
• ¿Son independientes los umbrales por tienda? Sí, cada fila lleva un id_shop.

Soporte y actualizaciones

El módulo incluye 12 meses de actualizaciones y soporte desde la fecha de compra. Soporte por email en francés o inglés, respuesta en 24 horas hábiles.

Para cualquier duda o incidencia, contactar con el soporte de DataFirefly indicando:

• Versión de PrestaShop y de PHP
• Versión del módulo instalada
• Tema utilizado
• Territorio y transportista implicados en el comportamiento observado
• Comportamiento observado frente al esperado