Offres quantitatives & badges promo : documentation

Installation

Le module s’installe comme n’importe quel module PrestaShop, par le back-office ou par FTP.

1. Depuis Modules puis Gestionnaire de modules, cliquez sur Installer un module et déposez le fichier dfquantitydeal.zip.
2. Par FTP, décompressez l’archive dans le dossier /modules/ de votre boutique, puis installez DataFirefly – Offres quantitatives et badges promo depuis le gestionnaire de modules.
3. Videz le cache dans Paramètres avancés puis Performances.

L’installation crée huit tables préfixées ps_df_quantity_deal, greffe le module sur neuf hooks, crée le hook displayDfQdBadge et ajoute l’onglet Offres quantitatives dans le menu Catalogue.

Langues du module

Le français est la langue source du module. Les traductions sont livrées dans le dossier translations/ pour l’anglais, l’italien, l’espagnol, l’allemand, le néerlandais, le polonais et le portugais.

• Le back-office s’affiche dans la langue de l’employé connecté.
• Les textes vus par le client (phrases du bloc des offres, incitations du panier, boutons) suivent la langue de la boutique.
• L’onglet du menu prend le nom traduit dans chaque langue installée.
• Tant que le libellé de la remise panier garde sa valeur par défaut, il s’affiche traduit dans la langue du client. Si vous le personnalisez dans les réglages généraux, votre texte est utilisé dans toutes les langues.

Pour ajuster une formulation, passez par International puis Traductions, type Traductions des modules installés, module dfquantitydeal.

Réglages généraux

Le bouton Configurer de la fiche module ouvre les réglages qui s’appliquent à toutes les offres.

• Activer le module : coupe l’affichage des badges et le calcul des remises sans désinstaller.
• Badges sur les listings : affiche le badge sur les vignettes des pages catégorie, des résultats de recherche et des blocs de produits.
• Badge sur la fiche produit : interrupteur séparé, pour afficher le badge uniquement en listing si vous le souhaitez.
• Tableau des offres sur la fiche produit : affiche le bloc qui liste les offres applicables au produit.
• Détail des offres dans le panier : affiche le montant apporté par chaque offre.
• Emplacement du détail des offres : accordéon sous la ligne Réduction(s) (par défaut), au-dessus de la ligne Livraison, sous le total TTC du panier, ou sous la liste des produits.
• Badge et prix barré sur les lignes du panier : sur chaque ligne concernée, affiche le badge de l’offre, barre le prix initial et affiche le prix remisé en dessous.
• Masquer le bon de réduction automatique : retire du récapitulatif la ligne du bon généré par le module, déjà comptée dans la ligne Réduction(s). Le client ne peut donc pas supprimer une remise recalculée à chaque modification du panier.
• Inciter à compléter le lot dans le panier : affiche un encart quand il ne manque que quelques articles pour déclencher une offre.
• Calculer les remises TTC : activé, la règle de panier porte un montant toutes taxes comprises. Désactivé, le montant est hors taxes et PrestaShop applique la TVA selon vos règles.
• Libellé de la remise panier : texte affiché sur la ligne de remise du panier et de la commande.
• Taille de police du badge (px) : 13 par défaut.
• Méthode d’affichage des badges : automatique (injection par le script front), manuelle (uniquement via le hook displayDfQdBadge) ou les deux.
• Emplacement des offres sur la fiche produit : voir la section dédiée plus bas.
• Sélecteur CSS personnalisé et Position par rapport au sélecteur : utilisés uniquement avec l’emplacement « Sélecteur CSS personnalisé ».

Diagnostic

La page de configuration affiche un panneau Diagnostic au-dessus des réglages. Il indique si le module est activé, si chaque hook utile existe en base et si le module y est greffé, le nombre d’offres actives aujourd’hui et le nombre d’offres rattachées à la boutique courante.

Le lien Tester le point d’entrée des badges ouvre le contrôleur front qui fournit les badges. Une réponse JSON confirme qu’il répond. Une erreur 404 signifie qu’il faut vider le cache et régénérer les URL simplifiées.

Créer une offre

Ouvrez Catalogue puis Offres quantitatives, et cliquez sur Nouvelle offre. Le formulaire est réparti en trois onglets.

Onglet Offre

• Nom de l’offre : champ traduit, utilisé dans la liste du back-office et dans le bloc des offres de la fiche produit.
• Type d’offre : les six mécaniques décrites plus bas. Le formulaire masque les champs inutiles selon le type choisi.
• Quantité achetée (X) et Quantité offerte (Y) : pour le type X achetés + Y offerts, et X seul pour le prix de lot.
• Rang de l’article remisé (N) : 2 pour « le 2e à -25 % », 3 pour « le 3e à -50 % ».
• Valeur de la remise : pourcentage, montant de remise ou prix imposé selon le type. Le libellé du champ change automatiquement.
• Paliers de remise : pour la remise par paliers uniquement. Un tableau où chaque ligne associe une quantité minimale à un pourcentage. Le bouton Ajouter un palier crée une ligne, la corbeille la supprime. Chaque palier doit offrir une remise plus élevée que le précédent.
• Produits déjà remisés : pour la remise par paliers uniquement. Cumuler applique le palier sur le prix déjà remisé, Ne pas cumuler garde la meilleure des deux remises. Voir la section dédiée plus bas.
• Offre répétable : activée, l’offre s’applique autant de fois que la quantité le permet (12 articles déclenchent deux fois une offre 4+2). Désactivée, elle ne s’applique qu’une fois par panier. Champ masqué pour la remise par paliers, qui porte toujours sur toute la quantité.
• Regroupement des quantités : par produit, par déclinaison, ou mix and match.
• Priorité : les valeurs les plus basses passent en premier.
• Activer l’offre : équivalent du bouton d’activation dans la liste.

Onglet Conditions

• Périmètre : tout le catalogue, produits sélectionnés, catégories sélectionnées ou marques sélectionnées. Le champ de sélection correspondant apparaît selon le choix.
• Produits concernés : tapez au moins deux caractères pour lancer la recherche. Elle porte sur le nom, la référence et l’ID. Cliquez sur un résultat pour l’ajouter à la liste.
• Catégories concernées : arbre de catégories avec cases à cocher. Un produit rattaché à l’une des catégories cochées déclenche l’offre.
• Marques concernées : liste des fabricants de la boutique.
• Groupes de clients : laissez tout décoché pour appliquer l’offre à tous les groupes, visiteurs compris.
• Exclure les produits déjà en promotion : les produits qui bénéficient d’un prix spécifique sortent du calcul.
• Exclure les clients ayant un prix spécifique : un client dont le compte ou le groupe par défaut a un prix spécifique sur le produit ne reçoit ni la remise ni le badge. Voir la section dédiée plus bas.
• Date de début et Date de fin : laissez vide pour une offre permanente. Une date seule est complétée à 00:00:00 pour le début et 23:59:59 pour la fin.
• Boutiques : visible uniquement si le mode multi-boutique est actif.

Onglet Badge et affichage

• Texte du badge : champ traduit. Laissez vide pour une génération automatique à partir des valeurs de l’offre.
• Couleur de fond et Couleur du texte : sélecteurs de couleur, valeurs par défaut rouge et blanc.
• Forme : carré, coins arrondis, pilule, ruban diagonal, pastille ronde.
• Position sur la vignette : haut gauche, haut droite, bas gauche, bas droite, ou en ligne sous le prix.
• Afficher sur les listings, sur la fiche produit, dans le tableau des offres : trois interrupteurs par offre, en complément des réglages globaux.
• Description de l’offre : texte riche traduit, affiché dans le bloc des offres de la fiche produit.

Les six types d’offres

X achetés + Y offerts

Le format classique du 2+1, 3+1 ou 4+2. Le moteur découpe les unités éligibles du panier en lots de X plus Y. Pour chaque lot complet, les Y unités les moins chères sont offertes.

Exemple : offre 4+2, six articles à 4,49 € dans le panier. Un lot complet, deux unités offertes, remise de 8,98 €. Avec cinq articles seulement, aucun lot n’est complet et la remise est nulle.

Le Nième à -X %

Le moteur découpe les unités en lots de N. Dans chaque lot, l’unité de rang N reçoit le pourcentage de remise. Comme les unités sont triées par prix décroissant, l’article remisé est le moins cher du lot.

Exemple : offre « le 2e à -25 % », quatre articles à 20 €. Deux lots de deux, deux articles remisés de 5 €, remise totale de 10 €.

Le Nième à -X €

Même découpage, mais la remise est un montant fixe. Elle est plafonnée au prix de l’article : une remise de 30 € sur un article à 8 € donne 8 € de remise, pas 30 €.

Le Nième à prix imposé

L’article de rang N est ramené au prix que vous fixez. La remise correspond à la différence. Pour « le 2e à 1 € » sur deux articles à 12 €, la remise est de 11 €.

Prix de lot

Pour chaque lot de X unités, le total est ramené au prix que vous annoncez. Sur une offre 3 pour 10 € avec six articles à 5 €, le moteur forme deux lots et applique 10 € de remise au total.

Remise par paliers

Vous définissez des seuils de quantité, chacun avec son pourcentage. Le palier le plus élevé atteint s’applique à chaque article de l’offre, pas seulement au dernier.

Exemple : paliers -5 % dès 2 articles et -10 % dès 3. Un article : pas de remise. Deux articles à 10 € et 20 € : 1,50 € de remise (5 % de 30 €). Quatre articles pour 50 € : 5 € de remise, soit -10 % sur les quatre.

Pour atteindre un palier avec des produits différents, une catégorie entière par exemple, choisissez le regroupement Mix and match. En regroupement Par produit, chaque référence doit atteindre le palier pour elle-même. La remise par paliers n’est pas répétable : elle porte toujours sur toute la quantité.

Quel article est offert

Le moteur trie les unités éligibles par prix décroissant, puis applique l’avantage aux moins chères de chaque lot. C’est la règle utilisée par la grande distribution et celle qu’attend le client.

Sur un lot 3+1 composé d’articles à 20 €, 15 €, 10 € et 5 €, l’article offert est celui à 5 €. Le client paye 45 € au lieu de 50 €.

Cette règle ne concerne pas la remise par paliers, qui s’applique à chaque article de l’offre.

Regroupement des quantités

• Par produit : toutes les déclinaisons d’une même référence comptent ensemble. Six flacons du même gel douche déclenchent une offre 4+2 même s’il s’agit de trois parfums différents.
• Par déclinaison : chaque variante compte pour elle-même. Il faut six unités du même parfum pour déclencher la même offre.
• Mix and match : toutes les unités des produits rattachés à l’offre alimentent le même compte. Utile pour faire du 4+2 sur une gamme complète.

Priorité et cumul entre offres

Les offres sont évaluées dans l’ordre de leur priorité, de la plus basse à la plus haute. Chaque offre consomme les unités qu’elle utilise, et l’offre suivante travaille sur le reste. Une même unité n’est jamais remisée deux fois.

Exemple : sept articles dans le panier, une offre 4+2 en priorité 10. Six unités sont consommées par le lot, la septième reste disponible pour une offre de priorité 20 qui viserait le même produit.

Produits déjà remisés et prix négociés

Par défaut, une offre s’applique sur le prix affiché dans le panier, donc après les prix spécifiques et les règles de prix catalogue. Trois réglages permettent d’ajuster ce comportement.

Exclure les produits déjà en promotion

Tout produit dont la ligne de panier porte une réduction sort du calcul de l’offre. Il ne compte pas non plus pour atteindre la quantité requise.

Exclure les clients ayant un prix spécifique

Pensée pour les boutiques B2B et les tarifs négociés. Le module vérifie, produit par produit, s’il existe un prix spécifique actif réservé au client connecté ou à son groupe par défaut. Si c’est le cas, ce produit sort de l’offre pour ce client : pas de remise au panier, pas de badge sur la vignette ni sur la fiche.

• Seul le groupe par défaut du client compte, comme dans le calcul de prix de PrestaShop. Un client rattaché à un second groupe qui a un prix spécifique, sans que ce soit son groupe par défaut, paie le prix normal et garde l’offre.
• Les prix spécifiques ouverts à tous les clients et à tous les groupes ne déclenchent pas l’exclusion.
• Le prix spécifique est retenu s’il est actif à la date du jour, sur la boutique, la devise et le pays du client. La quantité minimale du prix spécifique n’est pas prise en compte.
• Un prix spécifique posé sur une seule déclinaison n’exclut que cette déclinaison dans le panier. Le badge reste affiché tant que le prix ne couvre pas tout le produit.

Cumul des paliers

Pour la remise par paliers, le réglage Produits déjà remisés de l’onglet Offre propose deux modes.

• Cumuler (par défaut) : le pourcentage du palier s’applique sur le prix déjà remisé. Un produit à 20 € passé à 18 € par un prix spécifique, avec un palier à -10 %, revient à 16,20 €.
• Ne pas cumuler : le palier est calculé sur le prix avant réduction et le client paie le plus bas des deux prix. Un produit déjà à -20 % reste à -20 % avec un palier à -10 %. Un produit à -5 % passe à -10 %.

Dans les deux modes, les articles déjà remisés comptent pour atteindre le palier.

Le badge

Variables du texte

Le champ Texte du badge accepte cinq variables, remplacées à l’affichage par les valeurs de l’offre.

• {x} : quantité achetée
• {y} : quantité offerte
• {n} : rang de l’article remisé
• {value} : valeur de la remise, sans zéros inutiles
• {price} : valeur de la remise formatée en prix, dans la devise du client

Vous pouvez aussi écrire le texte en dur : « 4+2 gratuits », « 3+1 offert », « le 2e à -25 % ». Le champ est traduit, donc chaque langue a sa formulation.

Si le champ reste vide, le module génère un libellé court à partir du type et des valeurs : 4+2 pour une offre X achetés Y offerts, -25% x2 pour un Nième à pourcentage, Jusqu'à -10 % pour une remise par paliers, ou -10 % dès 3 s’il n’y a qu’un palier.

Pour une remise par paliers, {x} vaut la quantité du premier palier et {value} le pourcentage du palier le plus élevé.

Affichage automatique

Par défaut, un script front repère les vignettes produits de la page, demande leurs badges au module en un seul appel Ajax, puis les pose sur l’image ou sous le prix selon la position de l’offre. Ce fonctionnement ne dépend d’aucun hook de vignette, ce qui couvre les thèmes personnalisés qui n’appellent plus displayProductPriceBlock. Le placement est rejoué après les rafraîchissements Ajax de la recherche à facettes, de la pagination et du quick view.

Hook dédié displayDfQdBadge

Pour placer le badge à un endroit précis de votre thème ou d’un autre module, appelez le hook dédié dans le template :

{hook h='displayDfQdBadge' id_product=$product.id_product}

Deux paramètres optionnels sont disponibles.

• mode : auto (par défaut) suit la position réglée sur chaque offre, inline force l’affichage dans le flux, overlay force la surimpression sur l’image. Le conteneur reçoit automatiquement position: relative.
• context : list ou product, pour appliquer les réglages « listing » ou « fiche produit » de l’offre. Détecté automatiquement si absent.

{hook h='displayDfQdBadge' id_product=$product.id_product mode='inline'}

Le hook apparaît dans Apparence puis Positions sous le nom « DataFirefly – Badge offre quantitative ».

Le bloc des offres sur la fiche produit

Pour chaque offre applicable, le bloc affiche le badge, le nom de l’offre, une phrase qui indique au client quoi faire, et la description si vous en avez saisi une. Exemples de phrases : « Ajoutez 6 articles à votre panier, les 2 derniers seront offerts », « Ajoutez 3 articles à votre panier, le lot vous coûtera 10,00 € ». Le titre « Offres en cours » n’apparaît que si l’une des offres a une date de fin.

Le réglage Emplacement des offres sur la fiche produit propose onze positions :

• au-dessus ou sous le titre du produit ;
• sous la référence, sous la description courte ;
• au-dessus ou sous le prix ;
• au-dessus des déclinaisons ;
• au-dessus du bouton d’ajout au panier, ou sous ce bouton (emplacement natif, par défaut) ;
• dans un onglet dédié sous la fiche ;
• à l’aide d’un sélecteur CSS personnalisé.

Le bloc est rendu par le hook natif displayProductAdditionalInfo, puis déplacé côté navigateur, sans modifier votre thème. L’onglet dédié passe par displayProductExtraContent. Avec le sélecteur CSS personnalisé, saisissez par exemple .product-information h1 et choisissez si le bloc se place juste avant, juste après, au début ou à la fin de l’élément. Si le sélecteur ne trouve rien, le bloc reste à l’emplacement natif.

Le panier

Calcul de la remise

À chaque modification du panier, le moteur recalcule le total des remises et synchronise une règle de panier privée. Son code interne commence par DFQD suivi de l’identifiant du panier. Le client ne voit qu’une ligne de remise et n’a aucun code à saisir.

La règle est mise à jour uniquement si le montant a changé, ce qui évite de la recréer à chaque chargement de page. Si le total retombe à zéro, la règle est détachée du panier puis supprimée.

À la validation de la commande, la règle est désactivée et sa date de fin est ramenée dans le passé pour qu’elle ne puisse pas être réutilisée. Elle reste rattachée à la commande, donc visible dans vos exports comptables et utilisable pour un avoir.

Détail par offre

Le montant apporté par chaque offre s’affiche à l’emplacement choisi dans les réglages. En mode accordéon, la ligne Réduction(s) native devient cliquable et déplie le détail. L’état ouvert ou fermé est conservé lors des rafraîchissements Ajax du panier.

Lignes produits

Avec l’option Badge et prix barré sur les lignes du panier, chaque ligne concernée affiche le badge de l’offre sous le prix unitaire, le total initial barré et le prix remisé en dessous. Pour les offres X achetés Y offerts, une mention précise le nombre d’unités offertes et le montant économisé. L’affichage fonctionne avec les thèmes Classic et Hummingbird, et se réapplique quand le thème recharge les lignes du panier.

Incitation à compléter le lot

Quand il ne manque que quelques articles pour déclencher une offre, un encart « Offre en cours » l’annonce avec une phrase du type « Encore 1 article et vous en recevez 2 offerts ». Pour une remise par paliers, l’encart indique le palier suivant : « Encore 1 article et tous les articles de l’offre passent à -10 % ». Le bouton Ajouter place directement les unités manquantes dans le panier.

Ligne du bon automatique

La règle de panier générée apparaît normalement dans la liste des bons de réduction, alors que son montant est déjà compté dans la ligne Réduction(s). L’option Masquer le bon de réduction automatique, activée par défaut, retire cette ligne du récapitulatif. Le module la repère par son libellé, configuré dans les réglages généraux.

Adapter l’affichage à votre thème

Trois templates sont surchargeables. Copiez-les depuis /modules/dfquantitydeal/views/templates/hook/ vers /themes/votre-theme/modules/dfquantitydeal/views/templates/hook/.

• badge.tpl : le badge rendu par le hook displayDfQdBadge
• offers.tpl : le bloc des offres de la fiche produit
• cart.tpl : le détail des offres et les incitations du panier

Le CSS est isolé sous le préfixe dfqd. Pour un ajustement ponctuel, ciblez les classes depuis votre feuille de style de thème plutôt que de modifier views/css/front.css, qui serait écrasé à la mise à jour.

Multi-boutique et multilingue

Chaque offre est rattachée aux boutiques que vous cochez dans l’onglet Conditions. Une offre créée sur une boutique n’apparaît pas sur les autres tant qu’elle n’y est pas rattachée.

Les champs Nom, Texte du badge et Description sont traduits dans les langues installées. Le badge et les phrases affichés reprennent la langue du client.

Mise à jour depuis une version antérieure

Installez le nouveau ZIP par-dessus l’ancien depuis le gestionnaire de modules. Les scripts de mise à jour ajoutent les réglages et les hooks apparus depuis votre version, sans toucher à vos offres.

Le passage en 1.1.8 rétablit les traductions (anglais, italien, espagnol, allemand, néerlandais, polonais et portugais), corrige l’enregistrement des offres sur PrestaShop 9 et l’affichage des badges sur les listings. Il complète aussi la base des boutiques qui viennent de la 1.1.6 : les colonnes de l’exclusion des clients à prix spécifique et de la remise par paliers sont ajoutées si elles manquent. L’onglet du menu reprend son nom traduit dans chaque langue.

Le passage en 1.1.7 ajoute trois colonnes à la table ps_df_quantity_deal pour l’exclusion des clients à prix spécifique et la remise par paliers. Les offres existantes gardent leur comportement : les deux nouvelles options sont désactivées par défaut.

Le passage en 1.1.5 renomme l’onglet du menu dans chaque langue installée et donne au hook displayDfQdBadge un titre en anglais. Si le libellé de la remise panier est resté sur l’ancienne valeur par défaut « Offres quantitatives », il est remplacé par sa traduction dans la langue par défaut de la boutique. Un libellé que vous avez personnalisé est conservé.

Dépannage

Le badge ne s’affiche pas

1. Ouvrez la configuration du module et lisez le panneau Diagnostic : module activé, hooks greffés, offres actives aujourd’hui.
2. Vérifiez que l’offre est active et que la date du jour est dans sa période de validité.
3. Vérifiez le périmètre : un produit doit être explicitement rattaché à l’offre, ou appartenir à une catégorie ou une marque cochée.
4. Contrôlez les interrupteurs d’affichage, dans les réglages généraux et dans l’onglet Badge et affichage de l’offre.
5. Si la méthode d’affichage est sur Manuelle, vérifiez que votre template appelle bien le hook displayDfQdBadge.
6. Si le groupe de clients est restreint, testez avec un compte du bon groupe.
7. Videz le cache Smarty et le cache de votre serveur.

Les badges apparaissent deux fois

Votre thème appelle le hook displayDfQdBadge et le script front injecte aussi les badges. Passez la Méthode d’affichage des badges sur Manuelle.

La remise ne s’applique pas au panier

La quantité doit atteindre le seuil de l’offre selon le mode de regroupement choisi. En mode Par déclinaison, six unités réparties sur trois variantes ne déclenchent pas une offre 4+2. Vérifiez aussi que le produit n’est pas exclu par l’option sur les produits déjà en promotion, ni le client par l’option sur les prix spécifiques. Pour une remise par paliers sur plusieurs produits, le regroupement doit être sur Mix and match.

Deux offres se marchent dessus

Ce comportement est attendu : une unité consommée par la première offre sort du calcul de la seconde. Si vous voulez qu’une offre passe avant l’autre, baissez sa priorité.

Le badge ou le bloc des offres apparaît au mauvais endroit

Pour le badge, passez la position de l’offre sur En ligne (sous le prix), ou appelez le hook displayDfQdBadge à l’endroit voulu de votre template de vignette. Pour le bloc des offres, choisissez un autre emplacement ou utilisez le sélecteur CSS personnalisé.

Le lien de test des badges renvoie une erreur 404

Videz le cache dans Paramètres avancés puis Performances, puis enregistrez de nouveau les réglages de Trafic et SEO pour régénérer les URL simplifiées.

Désinstallation

La désinstallation supprime les huit tables du module, ses clés de configuration et l’onglet du menu Catalogue. Les règles de panier déjà rattachées à des commandes passées sont conservées, pour ne pas altérer votre historique comptable.