Ofertas por cantidad y badges promo: documentación
Configura las promociones por cantidad y las etiquetas promocionales en PrestaShop 8 y 9: seis tipos de oferta, entre ellos el descuento por tramos, segmentación, precios negociados, etiqueta, bloque de ofertas, carrito y diagnóstico.
Instalación
El módulo se instala como cualquier otro módulo de PrestaShop, desde el back office o por FTP.
- En Módulos y luego Gestor de módulos, haz clic en Subir un módulo y suelta el archivo
dfquantitydeal.zip. - Por FTP, descomprime el archivo en la carpeta
/modules/de tu tienda e instala DataFirefly – Ofertas por cantidad y etiquetas promocionales desde el gestor de módulos. - Vacía la caché en Parámetros Avanzados y luego Rendimiento.
La instalación crea ocho tablas con el prefijo ps_df_quantity_deal, engancha el módulo a nueve hooks, crea el hook displayDfQdBadge y añade la pestaña Ofertas por cantidad al menú Catálogo.
El módulo no instala ningún override de clase ni de controlador. La desinstalación elimina las tablas, las claves de configuración y la pestaña.
Idiomas del módulo
El francés es el idioma de origen del módulo. Las traducciones se incluyen en la carpeta translations/ para inglés, italiano, español, alemán, neerlandés, polaco y portugués.
- El back office se muestra en el idioma del empleado conectado.
- Los textos que ve el cliente (frases del bloque de ofertas, incentivos del carrito, botones) siguen el idioma de la tienda.
- La pestaña del menú adopta el nombre traducido en cada idioma instalado.
- Mientras el nombre del descuento del carrito conserve su valor por defecto, se muestra traducido en el idioma del cliente. Si lo personalizas en los ajustes generales, tu texto se usa en todos los idiomas.
Para ajustar una formulación, ve a Internacional y luego Traducciones, tipo Traducciones de módulos instalados, módulo dfquantitydeal.
Ajustes generales
El botón Configurar de la ficha del módulo abre los ajustes que se aplican a todas las ofertas.
- Activar el módulo: desactiva la visualización de las etiquetas y el cálculo de los descuentos sin desinstalar.
- Etiquetas en los listados: muestra la etiqueta en las miniaturas de las páginas de categoría, los resultados de búsqueda y los bloques de productos.
- Etiqueta en la ficha de producto: interruptor independiente, por si prefieres mostrar la etiqueta solo en los listados.
- Tabla de ofertas en la ficha de producto: muestra el bloque que lista las ofertas aplicables al producto.
- Detalle de las ofertas en el carrito: muestra el importe aportado por cada oferta.
- Ubicación del detalle de las ofertas: acordeón bajo la línea Descuento(s) (por defecto), encima de la línea Envío, bajo el total del carrito con IVA incluido, o bajo la lista de productos.
- Etiqueta y precio tachado en las líneas del carrito: en cada línea afectada, muestra la etiqueta de la oferta, tacha el precio inicial y muestra debajo el precio rebajado.
- Ocultar el cupón de descuento automático: quita del resumen la línea del cupón generado por el módulo, ya incluida en la línea Descuento(s). Así el cliente no puede eliminar un descuento que se recalcula en cada modificación del carrito.
- Animar a completar el lote en el carrito: muestra un recuadro cuando solo faltan unos pocos artículos para activar una oferta.
- Calcular los descuentos con IVA incluido: activado, la regla de carrito lleva un importe con IVA incluido. Desactivado, el importe es sin IVA y PrestaShop aplica el IVA según tus reglas.
- Nombre del descuento del carrito: texto mostrado en la línea de descuento del carrito y del pedido.
- Tamaño de fuente de la etiqueta (px): 13 por defecto.
- Método de visualización de las etiquetas: automático (inserción mediante el script front), manual (solo mediante el hook
displayDfQdBadge) o ambos. - Ubicación de las ofertas en la ficha de producto: consulta la sección dedicada más abajo.
- Selector CSS personalizado y Posición respecto al selector: solo se usan con la ubicación «Selector CSS personalizado».
Diagnóstico
La página de configuración muestra un panel Diagnóstico encima de los ajustes. Indica si el módulo está activado, si cada hook necesario existe en la base de datos y si el módulo está enganchado a él, el número de ofertas activas hoy y el número de ofertas asociadas a la tienda actual.
El enlace Probar el endpoint de las etiquetas abre el controlador front que proporciona las etiquetas. Una respuesta JSON confirma que responde. Un error 404 indica que hay que vaciar la caché y regenerar las URL amigables.
Al abrir la página de configuración, los hooks que faltan se enganchan automáticamente, lo que corrige la mayoría de las instalaciones hechas antes de una actualización.
Crear una oferta
Abre Catálogo y luego Ofertas por cantidad, y haz clic en Nueva oferta. El formulario se reparte en tres pestañas.
Pestaña Oferta
- Nombre de la oferta: campo traducido, usado en el listado del back office y en el bloque de ofertas de la ficha de producto.
- Tipo de oferta: las seis mecánicas descritas más abajo. El formulario oculta los campos que no aplican al tipo elegido.
- Cantidad comprada (X) y Cantidad gratis (Y): para el tipo X comprados + Y gratis, y solo X para el precio por lote.
- Posición del artículo rebajado (N): 2 para «el 2.º al -25 %», 3 para «el 3.º al -50 %».
- Valor del descuento: porcentaje, importe del descuento o precio fijo según el tipo. El nombre del campo cambia automáticamente.
- Tramos de descuento: solo para el descuento por tramos. Una tabla en la que cada fila asocia una cantidad mínima a un porcentaje. El botón Añadir un tramo crea una fila y la papelera la elimina. Cada tramo debe ofrecer un descuento mayor que el anterior.
- Productos ya rebajados: solo para el descuento por tramos. Acumular aplica el tramo sobre el precio ya rebajado, No acumular conserva el mejor de los dos descuentos. Consulta la sección dedicada más abajo.
- Oferta repetible: activada, la oferta se aplica tantas veces como lo permita la cantidad (12 artículos activan dos veces una oferta 4+2). Desactivada, solo se aplica una vez por carrito. Campo oculto para el descuento por tramos, que siempre se aplica a toda la cantidad.
- Agrupación de cantidades: por producto, por combinación, o mix and match.
- Prioridad: los valores más bajos se aplican primero.
- Activar la oferta: equivale al interruptor de activación del listado.
Pestaña Condiciones
- Alcance: todo el catálogo, productos seleccionados, categorías seleccionadas o marcas seleccionadas. El campo de selección correspondiente aparece según tu elección.
- Productos incluidos: escribe al menos dos caracteres para lanzar la búsqueda. Cubre el nombre, la referencia y el ID. Haz clic en un resultado para añadirlo a la lista.
- Categorías incluidas: árbol de categorías con casillas. Un producto vinculado a cualquiera de las categorías marcadas activa la oferta.
- Marcas incluidas: lista de fabricantes de la tienda.
- Grupos de clientes: deja todo sin marcar para aplicar la oferta a todos los grupos, visitantes incluidos.
- Excluir los productos ya en promoción: los productos con un precio específico quedan fuera del cálculo.
- Excluir a los clientes con un precio específico: un cliente cuya cuenta o cuyo grupo por defecto tenga un precio específico en el producto no recibe ni el descuento ni la etiqueta. Consulta la sección dedicada más abajo.
- Fecha de inicio y Fecha de fin: déjalas vacías para una oferta permanente. Una fecha sin hora se completa con 00:00:00 para el inicio y 23:59:59 para el fin.
- Tiendas: solo visible si el modo multitienda está activo.
Pestaña Etiqueta y visualización
- Texto de la etiqueta: campo traducido. Déjalo vacío para una generación automática a partir de los valores de la oferta.
- Color de fondo y Color del texto: selectores de color, rojo y blanco por defecto.
- Forma: cuadrado, esquinas redondeadas, píldora, cinta diagonal, pastilla redonda.
- Posición en la miniatura: arriba a la izquierda, arriba a la derecha, abajo a la izquierda, abajo a la derecha, o en línea (bajo el precio).
- Mostrar en los listados, Mostrar en la ficha de producto, Mostrar en la tabla de ofertas: tres interruptores por oferta, además de los ajustes globales.
- Descripción de la oferta: texto enriquecido traducido, mostrado en el bloque de ofertas de la ficha de producto.
Los seis tipos de oferta
X comprados + Y gratis
El formato clásico del 2+1, 3+1 o 4+2. El motor reparte las unidades elegibles del carrito en lotes de X más Y. Por cada lote completo, las Y unidades más baratas son gratis.
Ejemplo: oferta 4+2, seis artículos a 4,49 € en el carrito. Un lote completo, dos unidades gratis, descuento de 8,98 €. Con solo cinco artículos ningún lote está completo y el descuento es nulo.
El N.º a -X %
El motor reparte las unidades en lotes de N. En cada lote, la unidad de posición N recibe el porcentaje de descuento. Como las unidades se ordenan por precio descendente, el artículo rebajado es el más barato del lote.
Ejemplo: oferta «el 2.º al -25 %», cuatro artículos a 20 €. Dos lotes de dos, dos artículos rebajados 5 €, descuento total de 10 €.
El N.º con un descuento fijo
Mismo reparto, pero el descuento es un importe fijo. Queda limitado al precio del artículo: un descuento de 30 € sobre un artículo de 8 € da 8 € de descuento, no 30 €.
El N.º a precio fijo
El artículo de posición N baja al precio que fijes. El descuento corresponde a la diferencia. Para «el 2.º a 1 €» sobre dos artículos de 12 €, el descuento es de 11 €.
Precio por lote
Por cada lote de X unidades, el total baja al precio que anuncias. En una oferta 3 por 10 € con seis artículos a 5 €, el motor forma dos lotes y aplica 10 € de descuento en total.
Descuento por tramos
Defines umbrales de cantidad, cada uno con su porcentaje. El tramo más alto alcanzado se aplica a cada artículo de la oferta, no solo al último.
Ejemplo: tramos -5 % desde 2 artículos y -10 % desde 3. Un artículo: sin descuento. Dos artículos de 10 € y 20 €: 1,50 € de descuento (5 % de 30 €). Cuatro artículos por 50 €: 5 € de descuento, es decir -10 % sobre los cuatro.
Para alcanzar un tramo con productos distintos, una categoría entera por ejemplo, elige la agrupación Mix and match. Con la agrupación Por producto, cada referencia debe alcanzar el tramo por sí misma. El descuento por tramos no es repetible: siempre se aplica a toda la cantidad.
Una regla de precios de catálogo nativa de PrestaShop también puede hacer tramos, pero cuenta las cantidades producto por producto. No sabe sumar dos referencias distintas de una misma categoría.
Qué artículo se regala
El motor ordena las unidades elegibles por precio descendente y aplica la ventaja a las más baratas de cada lote. Es la regla que usa la gran distribución y la que espera el cliente.
En un lote 3+1 formado por artículos de 20 €, 15 €, 10 € y 5 €, el artículo gratis es el de 5 €. El cliente paga 45 € en lugar de 50 €.
Esta regla no afecta al descuento por tramos, que se aplica a cada artículo de la oferta.
Agrupación de cantidades
- Por producto: todas las combinaciones de una misma referencia cuentan juntas. Seis botes del mismo gel de ducha activan una oferta 4+2 aunque sean tres aromas distintos.
- Por combinación: cada variante cuenta por sí misma. Hacen falta seis unidades del mismo aroma para activar la misma oferta.
- Mix and match: todas las unidades de los productos vinculados a la oferta alimentan el mismo recuento. Útil para montar un 4+2 sobre una gama completa.
Prioridad y acumulación entre ofertas
Las ofertas se evalúan por orden de prioridad, del valor más bajo al más alto. Cada oferta consume las unidades que utiliza y la siguiente trabaja sobre el resto. Una misma unidad nunca recibe descuento dos veces.
Ejemplo: siete artículos en el carrito y una oferta 4+2 con prioridad 10. El lote consume seis unidades, y la séptima queda disponible para una oferta de prioridad 20 sobre el mismo producto.
Da una prioridad baja a tus ofertas más generosas si quieres que se apliquen primero. A igualdad de prioridad, el orden sigue el ID de la oferta.
Productos ya rebajados y precios negociados
Por defecto, una oferta se aplica sobre el precio mostrado en el carrito, es decir, después de los precios específicos y las reglas de precios de catálogo. Tres ajustes permiten modificar este comportamiento.
Excluir los productos ya en promoción
Todo producto cuya línea de carrito lleve un descuento queda fuera del cálculo de la oferta. Tampoco cuenta para alcanzar la cantidad requerida.
Excluir a los clientes con un precio específico
Pensada para las tiendas B2B y las tarifas negociadas. El módulo comprueba, producto por producto, si existe un precio específico activo reservado al cliente conectado o a su grupo por defecto. Si es así, ese producto queda fuera de la oferta para ese cliente: sin descuento en el carrito y sin etiqueta en la miniatura ni en la ficha.
- Solo cuenta el grupo por defecto del cliente, como en el cálculo de precios de PrestaShop. Un cliente vinculado a un segundo grupo que tiene un precio específico, sin que sea su grupo por defecto, paga el precio normal y conserva la oferta.
- Los precios específicos abiertos a todos los clientes y a todos los grupos no activan la exclusión.
- El precio específico se tiene en cuenta si está activo en la fecha de hoy, en la tienda, la moneda y el país del cliente. La cantidad mínima del precio específico no se tiene en cuenta.
- Un precio específico definido en una sola combinación solo excluye esa combinación en el carrito. La etiqueta sigue mostrándose mientras el precio no cubra todo el producto.
Un visitante no conectado no tiene cuenta: la exclusión solo se le aplica si el grupo Visitante tiene un precio específico. Para hacer pruebas, conéctate con la cuenta de cliente afectada y modifica la cantidad de un artículo del carrito para forzar el recálculo.
Acumulación de los tramos
Para el descuento por tramos, el ajuste Productos ya rebajados de la pestaña Oferta ofrece dos modos.
- Acumular (por defecto): el porcentaje del tramo se aplica sobre el precio ya rebajado. Un producto de 20 € rebajado a 18 € por un precio específico, con un tramo a -10 %, queda en 16,20 €.
- No acumular: el tramo se calcula sobre el precio antes de descuentos y el cliente paga el más bajo de los dos precios. Un producto ya a -20 % se queda a -20 % con un tramo a -10 %. Un producto a -5 % pasa a -10 %.
En ambos modos, los artículos ya rebajados cuentan para alcanzar el tramo.
La etiqueta
Variables del texto
El campo Texto de la etiqueta acepta cinco variables, sustituidas al mostrarse por los valores de la oferta.
{x}: cantidad comprada{y}: cantidad gratis{n}: posición del artículo rebajado{value}: valor del descuento, sin ceros innecesarios{price}: valor del descuento formateado como precio, en la moneda del cliente
También puedes escribir el texto directamente: «4+2 gratis», «3+1 de regalo», «el 2.º al -25 %». El campo está traducido, así que cada idioma tiene su formulación.
Si el campo queda vacío, el módulo genera una etiqueta corta a partir del tipo y de los valores: 4+2 para una oferta X comprados + Y gratis, -25% x2 para un N.º a -X %, Hasta -10 % para un descuento por tramos, o -10 % desde 3 si solo hay un tramo.
Para un descuento por tramos, {x} vale la cantidad del primer tramo y {value} el porcentaje del tramo más alto.
Visualización automática
Por defecto, un script front localiza las miniaturas de producto de la página, pide sus etiquetas al módulo en una sola llamada Ajax y las coloca sobre la imagen o bajo el precio según la posición de la oferta. Este funcionamiento no depende de ningún hook de miniatura, lo que cubre los temas personalizados que ya no llaman a displayProductPriceBlock. La colocación se repite tras los refrescos Ajax de la búsqueda por facetas, la paginación y el quick view.
Hook dedicado displayDfQdBadge
Para colocar la etiqueta en un punto concreto de tu tema o de otro módulo, llama al hook dedicado en la plantilla:
{hook h='displayDfQdBadge' id_product=$product.id_product}Hay dos parámetros opcionales.
mode:auto(por defecto) sigue la posición ajustada en cada oferta,inlinefuerza la visualización en el flujo,overlayfuerza la superposición sobre la imagen. El contenedor recibe automáticamenteposition: relative.context:listoproduct, para aplicar los ajustes «listados» o «ficha de producto» de la oferta. Se detecta automáticamente si no se indica.
{hook h='displayDfQdBadge' id_product=$product.id_product mode='inline'}El hook aparece en Diseño y luego Posiciones con el nombre «DataFirefly – Badge offre quantitative».
Si tu tema llama a este hook en sus plantillas, cambia el Método de visualización de las etiquetas a Manual. Si no, las etiquetas se mostrarán dos veces: una por el hook y otra por el script.
El bloque de ofertas en la ficha de producto
Para cada oferta aplicable, el bloque muestra la etiqueta, el nombre de la oferta, una frase que indica al cliente qué hacer y la descripción si has introducido una. Ejemplos de frases: «Añade 6 artículos a tu carrito, los 2 últimos serán gratis», «Añade 3 artículos a tu carrito, el lote te costará 10,00 €». El título «Ofertas en curso» solo aparece si alguna de las ofertas tiene fecha de fin.
El ajuste Ubicación de las ofertas en la ficha de producto ofrece once posiciones:
- encima o bajo el título del producto;
- bajo la referencia, bajo la descripción corta;
- encima o bajo el precio;
- encima de las combinaciones;
- encima del botón Añadir al carrito, o bajo ese botón (ubicación nativa, por defecto);
- en una pestaña dedicada en la ficha de producto;
- mediante un selector CSS personalizado.
El bloque lo genera el hook nativo displayProductAdditionalInfo y luego se desplaza en el navegador, sin modificar tu tema. La pestaña dedicada usa displayProductExtraContent. Con el selector CSS personalizado, introduce por ejemplo .product-information h1 y elige si el bloque se coloca justo antes del elemento, justo después, al principio o al final. Si el selector no encuentra nada, el bloque se queda en la ubicación nativa.
El carrito
Cálculo del descuento
En cada modificación del carrito, el motor recalcula el total de descuentos y sincroniza una regla de carrito privada. Su código interno empieza por DFQD seguido del ID del carrito. El cliente solo ve una línea de descuento y no introduce ningún código.
La regla solo se actualiza si el importe ha cambiado, lo que evita recrearla en cada carga de página. Si el total vuelve a cero, la regla se desvincula del carrito y se elimina.
Al validar el pedido, la regla se desactiva y su fecha de fin se lleva al pasado para que no pueda reutilizarse. Permanece asociada al pedido, por lo que sigue visible en tus exportaciones contables y sirve para un abono.
El importe del descuento no puede superar el total de productos del carrito. PrestaShop lo limita automáticamente en ese caso.
Detalle por oferta
El importe aportado por cada oferta se muestra en la ubicación elegida en los ajustes. En modo acordeón, la línea Descuento(s) nativa se vuelve clicable y despliega el detalle. El estado abierto o cerrado se conserva en los refrescos Ajax del carrito.
Líneas de producto
Con la opción Etiqueta y precio tachado en las líneas del carrito, cada línea afectada muestra la etiqueta de la oferta bajo el precio unitario, el total inicial tachado y el precio rebajado debajo. En las ofertas X comprados + Y gratis, una mención indica el número de unidades gratis y el importe ahorrado. Funciona con los temas Classic y Hummingbird, y se vuelve a aplicar cuando el tema recarga las líneas del carrito.
Incentivo para completar el lote
Cuando solo faltan unos pocos artículos para activar una oferta, un recuadro «Oferta en curso» lo indica con una frase del tipo «Un artículo más y recibes 2 gratis». Para un descuento por tramos, el recuadro indica el tramo siguiente: «Un artículo más y todos los artículos de la oferta pasan a -10 %». El botón Añadir coloca directamente en el carrito las unidades que faltan.
Línea del cupón automático
La regla de carrito generada aparece normalmente en la lista de cupones de descuento, aunque su importe ya está incluido en la línea Descuento(s). La opción Ocultar el cupón de descuento automático, activada por defecto, quita esa línea del resumen. El módulo la identifica por su nombre, configurado en los ajustes generales.
Adaptar la visualización a tu tema
Se pueden sobrescribir tres plantillas. Cópialas desde /modules/dfquantitydeal/views/templates/hook/ hacia /themes/tu-tema/modules/dfquantitydeal/views/templates/hook/.
badge.tpl: la etiqueta generada por el hookdisplayDfQdBadgeoffers.tpl: el bloque de ofertas de la ficha de productocart.tpl: el detalle de las ofertas y los incentivos del carrito
El CSS queda aislado bajo el prefijo dfqd. Para un ajuste puntual, apunta a las clases desde la hoja de estilo de tu tema en lugar de modificar views/css/front.css, que se sobrescribiría en la actualización.
Multitienda y multiidioma
Cada oferta se vincula a las tiendas que marques en la pestaña Condiciones. Una oferta creada en una tienda no aparece en las demás mientras no se vincule a ellas.
Los campos Nombre, Texto de la etiqueta y Descripción se traducen a los idiomas instalados. La etiqueta y las frases mostradas siguen el idioma del cliente.
Actualización desde una versión anterior
Instala el nuevo ZIP encima del anterior desde el gestor de módulos. Los scripts de actualización añaden los ajustes y los hooks aparecidos desde tu versión, sin tocar tus ofertas.
El paso a la 1.1.8 restablece las traducciones (inglés, italiano, español, alemán, neerlandés, polaco y portugués), corrige el guardado de las ofertas en PrestaShop 9 y la visualización de las etiquetas en los listados. También completa la base de datos de las tiendas que vienen de la 1.1.6: las columnas de la exclusión de los clientes con precio específico y del descuento por tramos se añaden si faltan. La pestaña del menú recupera su nombre traducido en cada idioma.
El paso a la 1.1.7 añade tres columnas a la tabla ps_df_quantity_deal para la exclusión de los clientes con precio específico y el descuento por tramos. Las ofertas existentes conservan su comportamiento: las dos nuevas opciones están desactivadas por defecto.
El paso a la 1.1.5 renombra la pestaña del menú en cada idioma instalado y da al hook displayDfQdBadge un título en inglés. Si el nombre del descuento del carrito se había quedado en el antiguo valor por defecto «Offres quantitatives», se sustituye por su traducción en el idioma por defecto de la tienda. Un nombre que hayas personalizado se conserva.
Resolución de problemas
La etiqueta no aparece
- Abre la configuración del módulo y revisa el panel Diagnóstico: módulo activado, hooks enganchados, ofertas activas hoy.
- Comprueba que la oferta está activa y que la fecha de hoy cae dentro de su periodo de validez.
- Revisa el alcance: un producto debe estar vinculado explícitamente a la oferta, o pertenecer a una categoría o marca marcada.
- Verifica los interruptores de visualización, en los ajustes generales y en la pestaña Etiqueta y visualización de la oferta.
- Si el método de visualización está en Manual, comprueba que tu plantilla llama al hook
displayDfQdBadge. - Si el grupo de clientes está restringido, prueba con una cuenta del grupo correcto.
- Vacía la caché de Smarty y la caché de tu servidor.
Las etiquetas aparecen dos veces
Tu tema llama al hook displayDfQdBadge y el script front también inserta las etiquetas. Cambia el Método de visualización de las etiquetas a Manual.
El descuento no se aplica en el carrito
La cantidad debe alcanzar el umbral de la oferta según el modo de agrupación elegido. En modo Por combinación, seis unidades repartidas en tres variantes no activan una oferta 4+2. Comprueba además que el producto no esté excluido por la opción Excluir los productos ya en promoción, ni el cliente por la opción sobre los precios específicos. Para un descuento por tramos sobre varios productos, la agrupación debe estar en Mix and match.
Dos ofertas se pisan
Ese comportamiento es el esperado: una unidad consumida por la primera oferta sale del cálculo de la segunda. Si quieres que una oferta pase antes que la otra, baja su prioridad.
La etiqueta o el bloque de ofertas aparece en el sitio equivocado
Para la etiqueta, cambia la posición de la oferta a En línea (bajo el precio), o llama al hook displayDfQdBadge en el punto deseado de tu plantilla de miniatura. Para el bloque de ofertas, elige otra ubicación o usa el selector CSS personalizado.
El enlace de prueba de las etiquetas devuelve un error 404
Vacía la caché en Parámetros Avanzados y luego Rendimiento, y después vuelve a guardar los ajustes de Tráfico & SEO para regenerar las URL amigables.
Desinstalación
La desinstalación elimina las ocho tablas del módulo, sus claves de configuración y la pestaña del menú Catálogo. Las reglas de carrito ya asociadas a pedidos anteriores se conservan, para no alterar tu histórico contable.