dffreegift — Regalo por umbral del carrito — Guía completa

Guía completa del módulo dffreegift para PrestaShop 8 y 9: instalación, configuración, mecánica interna (CartRule nativo), personalización, resolución de problemas y desinstalación. Cada paso viene acompañado de una explicación conceptual y los parámetros exactos a usar en producción.

Visión general

dffreegift añade automáticamente un producto regalo al carrito en cuanto se alcanza un umbral configurado, y lo retira si el carrito baja de nuevo por debajo. La mecánica se apoya íntegramente en el sistema nativo CartRule de PrestaShop (campo gift_product): el módulo nunca manipula directamente los precios de los productos, no crea SpecificPrice temporales y no inyecta nada en los hooks de cálculo de precios. Resultado: compatibilidad completa con sus otras promociones, códigos de descuento, impuestos y multidivisa.

El módulo también muestra un bloque de progreso en la página del carrito con el mensaje «Añada X € para recibir su regalo», una barra coloreada que se rellena a medida que se acerca el umbral, y una animación al cruzarlo.

Requisitos

• PrestaShop 8.0 a 9.x (probado en 8.0, 8.1, 8.2, 9.0)
• PHP 8.1 mínimo (8.2 y 8.3 soportadas)
• Un producto activo en su catálogo que hará de regalo (producto simple o con combinaciones)
• Acceso de administrador al back office de PrestaShop

Instalación

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

Durante la instalación, el módulo realiza las siguientes operaciones en segundo plano:

• Registro de 5 hooks: actionCartSave, actionObjectCartRuleDeleteBefore, displayShoppingCart, displayCartExtraProductActions, displayHeader.
• Escritura de los valores de configuración por defecto (umbral 50 €, cálculo con impuestos, sin envío, verificación de stock activada).
• Creación de una CartRule «fantasma» con un código único del tipo DFFREEGIFT_A7B3F2D9, visible en Catálogo → Descuentos → Reglas de carrito.

Configuración

La pantalla de configuración está en Módulos → DataFirefly Free Gift → Configurar. Todos los parámetros están agrupados en un único formulario.

Activar el módulo

El switch Activar el módulo actúa como interruptor maestro. En posición No, el módulo sigue instalado pero no hace nada: sin auto-añadido, sin bloque frontal, sin cálculo de umbral. Útil para desactivar temporalmente la oferta (fin de una operación estacional por ejemplo) sin perder la configuración.

Producto regalo y combinación

Dos campos a rellenar en orden:

1. ID del producto regalo: introduzca el ID de PrestaShop del producto a regalar. El ID se encuentra en Catálogo → Productos (columna ID). Tras guardar por primera vez, el nombre del producto se muestra como ayuda bajo el campo para confirmación.
2. Combinación: lista desplegable con las combinaciones disponibles del producto. Se rellena automáticamente después de guardar el ID del producto. Elija una combinación específica (por ejemplo «Talla M, color negro») o deje en — Sin combinación — para un producto simple.

Umbral de activación

El campo Umbral de activación define el importe del carrito a partir del cual se añade el regalo. Dos parámetros asociados definen la base de cálculo:

• Cálculo con impuestos: si está activado, el total incluye todos los impuestos aplicados al carrito. Si está desactivado, el umbral se compara con el total sin impuestos. La mayoría de tiendas B2C funcionan con impuestos incluidos; las B2B suelen razonar en base sin impuestos.
• Incluir gastos de envío: si está activado, se añaden los gastos de envío estimados al total antes de la comparación. En la práctica, se activa raramente ya que los gastos de envío no siempre están calculados en el momento en que el cliente consulta su carrito (sin transportista elegido = 0 €).

En el fondo, el total evaluado corresponde a una llamada nativa de PrestaShop:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Esto garantiza que el valor usado para la comparación es estrictamente idéntico al mostrado en el resumen del carrito de PrestaShop.

Verificación del stock

El switch Verificar el stock del regalo (activado por defecto) suspende el auto-añadido si el producto regalo no está disponible. El control respeta la estrategia out of stock configurada globalmente en PrestaShop:

• Si el producto está marcado como «permitir pedidos sin stock», el auto-añadido sigue activo incluso con cantidad 0.
• Si el producto rechaza los pedidos sin stock, el auto-añadido se suspende cuando la cantidad llega a 0.

Restricción por grupos de clientes

La cuadrícula Grupos de clientes elegibles lista todos los grupos de la tienda con una casilla por grupo. Dos comportamientos:

• Ninguna casilla marcada: todos los clientes son elegibles, incluidos los visitantes no identificados (siempre que el grupo por defecto PS_UNIDENTIFIED_GROUP no esté excluido, comportamiento por defecto).
• Una o varias casillas marcadas: solo los clientes miembros de al menos un grupo marcado ven el bloque de progreso y se benefician del auto-añadido.

Casos de uso típicos:

• Regalo reservado al grupo «Profesionales» para clientela B2B.
• Regalo reservado al grupo «VIP» para un programa de fidelización.
• Regalo ofrecido a todos excepto a los revendedores (marcar todos los grupos salvo el de revendedores).

Opciones de visualización

Dos switches independientes controlan la apariencia del bloque frontal:

• Mostrar mensaje de progreso: activa o desactiva completamente el bloque en la página del carrito. En No, el auto-añadido sigue funcionando pero no aparece ningún mensaje del lado del cliente (útil si quiere controlar la visualización desde su propio tema).
• Mostrar barra de progreso: activa o desactiva la barra coloreada bajo el mensaje. El mensaje de texto sigue visible.

Cómo funciona técnicamente

La CartRule fantasma

En lugar de manipular los precios de los productos, dffreegift usa el mecanismo nativo de regalo de PrestaShop vía CartRule. En la instalación se crea una regla con las siguientes propiedades:

• code = DFFREEGIFT_A7B3F2D9 (sufijo generado aleatoriamente en la instalación)
• gift_product = 0 (actualizado en cada guardado de configuración)
• gift_product_attribute = 0 (actualizado en cada guardado de configuración)
• quantity = 999.999 y quantity_per_user = 999.999 (prácticamente ilimitado)
• date_from = ahora, date_to = +50 años
• active = 1, sin código, sin reducción, sin restricción de producto ni categoría

Cuando se alcanza el umbral, el módulo asocia esta regla al carrito mediante Cart::addCartRule($id). PrestaShop se encarga del resto:

• Inserta una línea de carrito con gift = 1 y price = 0.
• La muestra en el resumen del carrito con un badge «Regalo».
• La contempla en el momento de la conversión en pedido.
• Snapshot en el histórico de pedidos (el regalo sigue visible incluso si cambia el producto regalo más tarde).

Cuando el carrito baja del umbral, el módulo desasocia la regla mediante Cart::removeCartRule($id). La línea del regalo se retira en la misma petición.

Hooks utilizados

• actionCartSave: hook principal. Se llama en cada guardado del carrito (añadido, modificación, retirada, login del cliente con fusión de carrito). El módulo calcula el total y decide asociar o desasociar la regla. Un flag estático self::$syncing evita la recursión si la asociación de la regla dispara a su vez un guardado.
• actionObjectCartRuleDeleteBefore: auto-reparación. Si un administrador elimina manualmente la regla fantasma desde Catálogo → Descuentos, este hook detecta la eliminación y reinicia el ID en la configuración. La próxima sincronización recreará una regla limpia.
• displayHeader: registra el CSS y el JS del frontal (views/css/dffreegift.css y views/js/dffreegift.js).
• displayShoppingCart: renderiza el bloque de progreso en la página del carrito.
• displayCartExtraProductActions: reservado para futuras mejoras (badge en la línea del regalo).

Cálculo del umbral

En cada llamada a syncCartGift(), el módulo verifica en orden:

1. ¿El módulo está activo? (si no, se sale)
2. ¿El cliente es elegible según los grupos configurados? (si no, se desasocia si estaba asociado)
3. ¿El producto regalo es válido (existe, activo, con stock si la verificación está activada)? (si no, se desasocia)
4. Cálculo del total según con/sin impuestos y con/sin envío.
5. Comparación con el umbral con tolerancia de redondeo de 0,001 €.
6. Asociar la regla si se alcanza el umbral y aún no está asociada. Desasociar si está por debajo y estaba asociada.

Bloque de progreso del frontal

El bloque se muestra automáticamente en la página del carrito, entre el resumen de productos y el total. Dos estados visuales:

• Pendiente (umbral no alcanzado): fondo gris claro, mensaje «Añada X,XX € para recibir su regalo», barra naranja que se rellena a medida que se acerca el umbral.
• Objetivo alcanzado (umbral cruzado): fondo verde claro, mensaje «¡Regalo añadido a su carrito!», barra completamente rellena en verde. Se activa una animación pulse en la transición de pendiente a alcanzado.

Personalizar los colores

Los colores están definidos en views/css/dffreegift.css. Para personalizarlos sin modificar el módulo (lo que sobrescribiría los cambios en cada actualización), sobrecargue las clases en el CSS de su tema:

.dffreegift-progress {
    border-color: #su-color;
    background: #su-fondo;
}
.dffreegift-progress--reached {
    background: #su-verde-claro;
    border-color: #su-verde;
}
.dffreegift-progress__bar-fill {
    background: linear-gradient(90deg, #color1, #color2);
}

Personalizar los textos

Los textos mostrados al cliente son traducibles mediante el mecanismo estándar de PrestaShop. Vaya a Internacional → Traducciones, elija «Traducciones de módulos», seleccione dffreegift y el idioma, y busque el dominio Modules.Dffreegift.Shop. Cadenas disponibles:

• «Añada %amount% para recibir su regalo» — mensaje pendiente (%amount% se sustituye automáticamente por el importe restante formateado según divisa y locale).
• «¡Regalo añadido a su carrito!» — mensaje de objetivo alcanzado.
• «Progreso hacia el regalo» — etiqueta ARIA de la barra (leída por los lectores de pantalla).

Coexistencia con otras promociones

Como el regalo se añade mediante una CartRule nativa, coexiste normalmente con cualquier otra CartRule. Comportamientos esperados:

• Otros códigos de descuento de cliente (descuento porcentual, importe fijo, envío gratuito): se aplican con normalidad en paralelo al regalo. El regalo no consume el descuento, y viceversa.
• Otra regla con gift_product configurada en otro sitio: PrestaShop las trata como reglas independientes y añade los dos regalos. Atención si acumula varios módulos de regalo.
• Regla con product_restriction que excluye el producto regalo: gana la regla que restringe. El regalo no se añade si otra regla activa lo excluye explícitamente.
• Regla con cart_rule_restriction: si otra regla prohíbe el uso de la nuestra por restricción cruzada, el auto-añadido queda bloqueado (comportamiento nativo de PrestaShop).

Multi-tienda

El módulo funciona con la configuración multi-tienda de PrestaShop en el contexto de tienda por defecto. Las configuraciones (umbral, producto regalo, opciones) se almacenan mediante Configuration::updateValue, que respeta el contexto de tienda actual. La CartRule creada en la instalación queda asociada a la tienda activa en ese momento.

Para un despliegue multi-tienda con regalos distintos por tienda, actualmente hay que instalar y configurar el módulo en cada contexto de tienda por separado. Contacte con el soporte para una variante con scoping explícito por id_shop.

Resolución de problemas

El regalo no se añade al carrito

Verificar en orden:

1. ¿El módulo está bien activado? (Módulos → Configurar → switch Activar el módulo).
2. ¿El producto regalo es válido? (ID correcto, producto activo, con stock si la verificación de stock está activada).
3. ¿El cliente está en un grupo autorizado? (si ha restringido por grupos, un visitante no identificado que no esté en ningún grupo autorizado no verá nada).
4. ¿Se alcanza realmente el umbral? Recalcule manualmente el total según sus parámetros (con/sin impuestos, con/sin envío).
5. ¿Existe y está activa la CartRule fantasma? Vaya a Catálogo → Descuentos → Reglas de carrito y busque DFFREEGIFT_.

El bloque de progreso no aparece en la página del carrito

Causas frecuentes:

• El switch Mostrar mensaje de progreso está en No.
• El cliente no es elegible según los grupos configurados.
• El producto regalo no es válido (no existe, inactivo, o sin stock con la verificación activada).
• Su tema personalizado no invoca el hook displayShoppingCart. Compruébelo con el comando grep -r "displayShoppingCart" themes/su-tema/ o en Módulos → Posiciones.

La CartRule ha desaparecido del back office

Si alguien eliminó la regla desde Catálogo → Descuentos, el hook actionObjectCartRuleDeleteBefore detectó la eliminación y reinició la configuración. En la próxima sincronización del carrito (por tanto, en el siguiente añadido de producto por un cliente), se crea una nueva regla automáticamente con un nuevo código DFFREEGIFT_xxxxxxxx.

Para forzar la regeneración inmediatamente sin esperar a un cliente:

1. Ir a Módulos → DataFirefly Free Gift → Desactivar.
2. Luego Activar de nuevo. Esto recrea una regla limpia.

Errores en los logs de PrestaShop

El módulo registra las excepciones en Parámetros avanzados → Logs con el prefijo [dffreegift]. Un mensaje típico en caso de problema:

[dffreegift] actionCartSave error: <descripción del error>

Estos errores nunca interrumpen el funcionamiento del carrito — son puramente informativos. En caso de log recurrente, envíe el mensaje completo al soporte.

El umbral parece mal calculado

El cálculo depende estrictamente de sus parámetros Cálculo con impuestos e Incluir gastos de envío. Para verificar lo que devuelve PrestaShop:

• Con impuestos + sin envío: corresponde al Subtotal productos (con impuestos) mostrado en el resumen del carrito.
• Con impuestos + con envío: corresponde al Total (con impuestos) (productos + envío si hay transportista seleccionado).
• Sin impuestos + sin envío: corresponde al Subtotal productos (sin impuestos).
• Sin impuestos + con envío: corresponde al Total (sin impuestos) (productos + envío sin impuestos).

Si detecta una discrepancia, compare con la línea exacta del resumen del carrito — la mayoría de veces la diferencia viene de un envío que aún no se ha calculado (el cliente no ha elegido transportista, luego el envío es 0 €).

Desinstalación

Ir a Módulos → Gestor de módulos → DataFirefly Free Gift → Desinstalar. La desinstalación elimina:

• La CartRule fantasma y todas sus asociaciones a carritos (los carritos en curso perderán su regalo automáticamente).
• Todas las claves de configuración con el prefijo DFFREEGIFT_.

FAQ rápida

• ¿Aparece el regalo en el mini-carrito del header? No, únicamente en la página del carrito (hook displayShoppingCart). El mini-carrito lo gestiona cada tema de forma distinta y sería necesaria una integración específica por tema. Bajo petición al soporte.
• ¿Puedo ofrecer varios regalos con varios umbrales (ej. regalo A a 50 €, regalo B a 100 €)? No, la versión 1.0.0 gestiona un solo regalo con un solo umbral. Para varios niveles, contactar con el soporte.
• ¿Se incluye el regalo en los reembolsos? Como cualquier producto regalo nativo de PrestaShop, el regalo aparece en el pedido con precio 0. En caso de reembolso parcial, el regalo se mantiene en el pedido sin impacto financiero.
• ¿Puedo modificar directamente el archivo dffreegift.php? Técnicamente sí (código fuente no ofuscado), pero las actualizaciones oficiales sobrescribirán sus cambios. Crear un módulo override para cualquier personalización profunda.

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 pregunta o incidencia, contacte con el soporte DataFirefly indicando:

• Versión de PrestaShop (visible en Parámetros avanzados → Información)
• Versión de PHP
• Versión del módulo dffreegift instalado
• Descripción del comportamiento observado vs. comportamiento esperado
• Extracto de los logs de PrestaShop si procede ([dffreegift])