Smart Offers — Documentación completa

Smart Offers es un módulo PrestaShop 8 que permite crear ofertas 1+1, packs al por mayor, packs multi-producto y ofertas de elección, con añadido automático de los productos regalo al carrito y presentación cuidada en la ficha de producto.

Visión general

Smart Offers cubre los cuatro formatos de ofertas agrupadas más utilizados en e-commerce en un solo módulo, sin configuración compleja. El motor evalúa el carrito en cada modificación, añade automáticamente los productos regalo en cuanto se cumplen las condiciones y crea una regla de carrito que hace esas unidades gratuitas — la experiencia del cliente es inmediata y legible.

Instalación

1. Descargue el archivo dfoffers-vX.Y.Z.zip desde su área de cliente DataFirefly
2. En el back office de PrestaShop, vaya a Módulos → Administrador de módulos
3. Haga clic en el botón Subir un módulo en la parte superior
4. Arrastre y suelte el archivo ZIP o haga clic para seleccionarlo
5. La instalación es automática: las tablas se crean, los hooks se registran y aparece una nueva pestaña Catálogo → Ofertas agrupadas en el menú

Los cuatro tipos de ofertas

1+1 sobre el mismo producto

El formato viral del buy-one-get-one: el cliente compra una unidad de un producto y recibe otra unidad del mismo producto de regalo. Configura:

• Un solo producto (utilizado como activador y como recompensa)
• La cantidad a comprar para activar la oferta (generalmente 1)
• La cantidad de regalo (generalmente 1)

Ejemplo típico: «Por 1 par de calcetines comprado, el segundo es gratis.» Cuando el cliente añade el par a su carrito, el motor añade automáticamente un segundo y aplica un descuento igual al precio unitario.

Compra X, recibe Y de regalo (productos diferentes)

Formato de bundle: varios productos activadores distintos deben estar presentes en el carrito para que se active la oferta, y entonces se regalan uno o varios productos diferentes. Configura:

• La lista de productos activadores con sus cantidades respectivas
• La lista de productos regalo con sus cantidades respectivas

Ejemplo típico: «Compra una crema de día y un sérum juntos, recibe una muestra de mascarilla de regalo.» El motor verifica que todos los activadores estén presentes antes de activar la oferta.

Elección de variantes

Formato de composición libre: defines un conjunto de productos o variantes candidatas entre las cuales el cliente compone su lote. El motor identifica automáticamente las unidades más baratas del carrito como las unidades de regalo, lo que corresponde a la interpretación comercial estándar del buy-N-get-M.

• La lista de productos o variantes candidatas
• El número de unidades a comprar en este conjunto
• El número de unidades de regalo (las más baratas)

Ejemplo típico: «3 camisetas compradas de nuestra selección, la más barata es gratis.» El cliente compone su lote, el motor no toca su carrito sino que aplica un descuento sobre las unidades más baratas.

Pack al por mayor

Formato B2B y liquidación de stock: por cada lote de X unidades compradas de un producto, el cliente recibe Y unidades gratuitas de otro producto. Configura:

• El producto activador con la cantidad de palier (por ejemplo 10)
• El producto regalo con la cantidad ofrecida (por ejemplo 20)

Ejemplo típico: «Por 10 botellas de vino compradas, 2 copas de regalo.» Práctico para proveedores que quieren impulsar un producto complementario o liquidar stock durmiente vinculándolo a un producto que se vende bien.

Crear su primera oferta

Desde el back office, vaya a Catálogo → Ofertas agrupadas y haga clic en Nueva oferta.

Paso 1: elegir el tipo

Cuatro tarjetas visuales le presentan los tipos disponibles con una breve descripción. Haga clic en la que corresponda a su operación comercial. El formulario se adapta automáticamente y solo muestra los campos relevantes para ese tipo.

Paso 2: nombrar y etiquetar la oferta

Complete:

• Nombre de la oferta (obligatorio): lo que verá el cliente en el banner. Disponible en cinco idiomas.
• Texto del badge (opcional, máx 64 caracteres): mensaje corto que se muestra en la pill en la parte superior del banner (por ejemplo, 1+1 GRATIS, OFERTA ESPECIAL, BLACK FRIDAY).
• Color del badge: seis presets DataFirefly disponibles más un selector de color libre. El color se utiliza tanto para el banner de la ficha de producto COMO para la etiqueta de regalo del lado del carrito.

Paso 3: añadir productos activadores

Haga clic en Añadir un producto activador. Se abre una modal de búsqueda con un campo que consulta su catálogo en directo (búsqueda con debounce de 250 ms tras la última pulsación). Escriba un nombre, una referencia o un EAN; los resultados aparecen inmediatamente.

Haga clic en un producto para añadirlo. Si el producto tiene variantes, aparecen como botones bajo el resultado — haga clic en la que le interesa para añadirla directamente. Indique la cantidad requerida en el campo a la derecha de la fila.

Paso 4: añadir productos de regalo

Mismo procedimiento para los productos de regalo. Esta sección está oculta para el tipo Elección de variantes, ya que las variantes sirven como candidatos Y como recompensas.

Paso 5: reglas específicas

• Acumulable: si se activa, la oferta se aplica varias veces por cada lote activador. Sin acumulación, la oferta se aplica una sola vez sin importar el número de unidades. Desactivado por defecto para proteger sus márgenes.
• Para el tipo Elección de variantes, aparecen dos campos adicionales: cuántas unidades debe comprar el cliente y cuántas son de regalo.

Paso 6: activación

• Fechas de validez: deje vacío para una oferta permanente. Indique la fecha de inicio o de fin para automatizar la activación.
• Prioridad: si varias ofertas pueden aplicarse simultáneamente, la de prioridad más baja se evalúa primero.
• Estado: interruptor on/off, activado por defecto. Útil para desactivar temporalmente una oferta sin eliminarla.

Paso 7: tiendas (si multi-tienda)

Marque las tiendas en las que debe estar disponible la oferta. No marcar ninguna equivale a activar la oferta en todas las tiendas.

Cómo funciona el motor de añadido automático

El motor se engancha al hook PrestaShop actionCartSave y se ejecuta en cada modificación del carrito (añadido, eliminación, cambio de cantidad, fusión al iniciar sesión).

1. Recupera todas las ofertas activas para la tienda actual
2. Para cada oferta, calcula la cantidad pagada de cada producto activador (cantidad total del carrito menos lo que el motor ya ha añadido automáticamente en una evaluación anterior)
3. Evalúa si se cumplen las condiciones de la oferta
4. Si es así, añade los productos de regalo faltantes al carrito a través de Cart::updateQty
5. Crea o actualiza una regla de carrito (CartRule) con un descuento fijo IVA incluido igual al valor de las unidades de regalo
6. Registra en la tabla ps_dfoffers_cart_auto las unidades que ha añadido, para distinguirlas de las unidades que el cliente añadió él mismo

Revocación limpia

Si el cliente quita un producto activador o reduce su cantidad por debajo del umbral, el motor reevalúa la oferta en el siguiente actionCartSave. Si la condición ya no se cumple, retira las unidades que había añadido automáticamente (sin tocar las unidades que el cliente añadió él mismo gracias al tracking) y elimina la regla de carrito asociada.

Visualización en la ficha de producto

En cada ficha de producto activadora, un banner con degradado se muestra a través del hook displayProductAdditionalInfo. Contiene:

• Un badge pill blanco con icono de regalo, conteniendo el texto del badge
• El título de la oferta
• Un mensaje dinámico que depende del tipo de oferta («Añade 1 producto, recibe 1 gratis», «Por 10 unidades compradas, 20 unidades de regalo», etc.)
• Una cuadrícula con las miniaturas clicables de los productos involucrados, separados en dos grupos Compra / Recibe gratis con un separador SVG circular entre ellos

El color del banner reutiliza el del badge configurado en la oferta. La presentación es responsive: en móvil, los dos grupos se apilan verticalmente y el separador rota para apuntar hacia abajo.

Visualización en el carrito

Desde la versión 1.1.0, dos indicadores distintos ayudan al cliente a identificar los productos de regalo en su carrito.

Etiqueta de regalo en cada línea

En cada línea del carrito que contiene unidades añadidas automáticamente por una oferta, aparece una pequeña etiqueta coloreada 🎁 ×N gratis junto a las acciones de la línea. El color reutiliza el del badge de la oferta, y la etiqueta indica cuántas unidades de esta línea son gratuitas (útil cuando una parte de la cantidad está pagada y la otra ofrecida, por ejemplo en un 1+1 mismo producto).

Pie de carrito detallado

En la parte inferior de la cuadrícula de productos, un bloque verde resume las ofertas activadas en el carrito. Para cada oferta, el bloque muestra:

• El nombre de la oferta y su texto de badge (en pill coloreada)
• La lista de productos ofrecidos por esta oferta, en forma de chips visuales con miniatura redonda, nombre y cantidad
• Cada chip es clicable y enlaza a la ficha del producto de regalo

El cliente puede así verificar de un vistazo lo que ha obtenido gratuitamente y gracias a qué operación comercial.

Casos particulares y comportamientos

Por qué el 1+1 sobre el mismo producto se trata específicamente

Cuando el producto activador también es el producto de regalo, muchos módulos de ofertas agrupadas del mercado cometen el error de identificar la unidad pagada del cliente como si ya fuera la unidad ofrecida, y aplican el descuento sobre esa unidad — al final, el cliente paga cero por una unidad en lugar de pagar por una y recibir una segunda gratis.

Smart Offers maneja este caso con una lógica precisa: la cantidad objetivo en el carrito vale cantidad pagada por el cliente + cantidad de regalo. Cuando el cliente añade una unidad, el motor añade una segunda para que el carrito contenga dos unidades, y el descuento se aplica solo sobre la segunda unidad. El cliente paga por tanto el precio de una unidad para tener dos en su carrito.

Acumulación de lotes (opción stackable)

Sin acumulación, la oferta se aplica una sola vez sin importar el número de lotes activadores presentes en el carrito. Si el cliente compra 5 unidades de un producto con una oferta 1+1 y stackable desactivado, recibirá 1 unidad de regalo (no 5).

Con la acumulación activada, el motor multiplica el número de lotes de recompensa por el número entero de lotes activadores presentes. Para la misma oferta 1+1 con stackable activado y 5 unidades en el carrito, el cliente recibirá 5 unidades de regalo (carrito final: 10 unidades, 5 pagadas).

Stock e indisponibilidad

El añadido de los productos de regalo al carrito pasa por Cart::updateQty, que respeta las reglas de stock nativas de PrestaShop. Si un producto de regalo está sin stock y la tienda no permite el pedido sin stock, el añadido falla silenciosamente y el descuento no se aplica — la condición queda lista para activarse en cuanto haya stock disponible.

Múltiples ofertas simultáneas en un mismo carrito

Cada oferta genera su propia regla de carrito con partial_use activado. Esto permite apilar varias ofertas concurrentes en un mismo carrito sin conflicto, y sigue siendo compatible con los códigos de descuento clásicos que sus clientes pueden introducir.

Arquitectura técnica

Hooks utilizados

• displayProductAdditionalInfo: banner en la ficha de producto
• displayShoppingCartFooter: pie detallado en la página del carrito
• displayCartExtraProductActions: etiqueta de regalo en cada línea del carrito
• actionCartSave: motor de evaluación y añadido automático
• actionFrontControllerSetMedia y actionAdminControllerSetMedia: inyección de CSS y JS
• actionObjectProductDeleteAfter: limpieza automática de ofertas que hacen referencia a un producto eliminado

Tablas añadidas

• ps_dfoffers_offer: configuración de cada oferta (tipo, fechas, prioridad, acumulación)
• ps_dfoffers_offer_lang: nombre, badge y descripción traducidos por idioma
• ps_dfoffers_trigger: productos activadores de cada oferta
• ps_dfoffers_reward: productos de regalo de cada oferta
• ps_dfoffers_shop: asociación oferta / tienda en multi-tienda
• ps_dfoffers_cart_auto: tracking de las unidades añadidas automáticamente por carrito y por oferta, con el identificador de la regla de carrito generada

Todas las tablas utilizan el prefijo configurado en su instalación PrestaShop (ps_ por defecto).

Sobrescribir plantillas en su tema

El CSS del módulo está aislado bajo el prefijo .dfoffers- para evitar conflictos con su hoja de estilo. Si desea modificar la presentación, copie las plantillas desde /modules/dfoffers/views/templates/hook/ hacia /themes/su-tema/modules/dfoffers/views/templates/hook/ y personalícelas. Tres plantillas están disponibles:

• product-banner.tpl: banner en la ficha de producto
• cart-offer.tpl: bloque resumen en el pie del carrito
• cart-line-gift.tpl: etiqueta de regalo inline en las líneas del carrito

Actualización del módulo

Para actualizar a una nueva versión, simplemente suba el nuevo ZIP desde el Administrador de módulos. PrestaShop detecta el cambio de versión en config.xml y ejecuta automáticamente los scripts de actualización presentes en /upgrade/upgrade-X.Y.Z.php, que se encargan por ejemplo de registrar nuevos hooks añadidos entre versiones.

Solución de problemas

Los productos de regalo no se añaden al carrito

1. Vacíe la caché de PrestaShop en Parámetros avanzados → Rendimiento
2. Verifique que el hook actionCartSave contiene el módulo en Diseño → Posiciones
3. Verifique que el producto de regalo está disponible (no agotado si los pedidos sin stock están prohibidos, no desactivado, asignado a la tienda actual)
4. Consulte Parámetros avanzados → Logs buscando dfoffers: el motor traza su ejecución en cada modificación del carrito

El descuento no se aplica a pesar del añadido del producto

Verifique en los logs la línea checkValidity que sigue a la creación de la regla de carrito. PrestaShop indica con precisión por qué se rechaza una regla (agotado, restricción de cliente, divisa diferente, etc.).

La etiqueta de regalo no aparece en las líneas del carrito

Verifique que su tema implementa correctamente el hook displayCartExtraProductActions en cart-detailed-product-line.tpl. Los temas Classic y la mayoría de temas comerciales lo contienen. Si utiliza un tema personalizado que no lo implementa, añada la siguiente línea en su archivo cart-detailed-product-line.tpl al nivel deseado:

{hook h='displayCartExtraProductActions' product=$product}

Preguntas frecuentes

¿El módulo es compatible con PrestaShop 9?

No, la versión 1.x cubre únicamente PrestaShop 8.0 a 8.99. Una versión 2.x compatible con PrestaShop 9 está planificada por separado debido a los cambios importantes en la API de controladores en PS 9.

¿Cuál es el impacto en el rendimiento?

El motor ejecuta una consulta SQL por oferta activa en la tienda, luego evalúa las condiciones en memoria. En un catálogo con una decena de ofertas activas, la evaluación completa tarda en promedio menos de cincuenta milisegundos.

¿Puedo utilizar el módulo con un tema headless?

El motor de añadido automático es independiente del tema y funciona para cualquier frontal que pase por Cart::updateQty o la API REST de PrestaShop. El banner de ficha de producto y la etiqueta de regalo del carrito son hooks Smarty nativos que necesitan un tema clásico para mostrarse. Para un front headless, puede exponer los datos a través de una API custom que consulte directamente ps_dfoffers_offer y ps_dfoffers_cart_auto.

¿El módulo gestiona múltiples divisas?

Sí. La regla de carrito generada para cada oferta utiliza la divisa del carrito actual. Si el cliente cambia de divisa, la regla se regenera con el valor correcto en el siguiente actionCartSave.