DF Samples : commande d’échantillons (PrestaShop 8 & 9)

Présentation

DF Samples ajoute un bouton « Commander un échantillon » sur vos fiches produit. L’échantillon peut être gratuit ou facturé quelques euros, pour le produit ou pour la déclinaison choisie par le client. Le module génère un produit échantillon caché pour chaque produit inscrit, verrouille la quantité à 1, applique des limites par client sur le contenu du panier, mesure la conversion échantillon vers achat et relance vos clients par email avec un bon de réduction optionnel.

Le module est compatible PrestaShop 8.0 à 9.x, multi-boutique et multilingue, et n’utilise aucun override du cœur. Cette documentation porte sur la version 1.1.0.

Installation

1. Dans le back-office, allez dans Modules > Gestionnaire de modules.
2. Cliquez sur Installer un module et déposez le fichier dfsamples.zip.
3. Ouvrez Catalogue > Échantillons (DF) : c’est là que se trouvent la liste des produits, le tableau de bord et les réglages.

À l’installation, le module crée :

• trois tables : dfsamples_product, dfsamples_order et dfsamples_cart ;
• une catégorie Échantillons désactivée, sous la catégorie Accueil, accessible à tous les groupes de clients, qui recevra les produits échantillons ;
• ses réglages par défaut et un jeton de sécurité pour la tâche cron ;
• l’onglet d’administration Catalogue > Échantillons (DF) ;
• une copie du modèle d’email anglais pour chaque langue installée qui n’en a pas.

Il s’enregistre sur 12 hooks, dont displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder et actionOrderStatusPostUpdate.

Mettre à jour depuis la version 1.0.0

Installez le nouveau ZIP par-dessus l’ancien, depuis le gestionnaire de modules. Le script de mise à jour :

• ajoute la table dfsamples_cart et les nouvelles colonnes ;
• enregistre les nouveaux hooks ;
• crée la catégorie Échantillons et y déplace vos produits échantillons existants ;
• renomme leurs fiches au nouveau format et ajoute les images manquantes (sous PrestaShop 9, la version 1.0.0 ne copiait pas l’image) ;
• conserve vos produits inscrits, vos statistiques et votre historique de relances.

Si une étape échoue, le bouton Resynchroniser les échantillons, en haut de la page du module, rejoue la synchronisation de tous les produits échantillons.

Ajouter un produit au programme d’échantillons

1. Ouvrez Catalogue > Échantillons (DF) et cliquez sur Ajouter un produit.
2. Recherchez le produit par nom ou par référence, puis sélectionnez-le. Les produits déjà inscrits et les produits échantillons sont exclus des résultats.
3. Saisissez le prix de l’échantillon TTC. Saisissez 0,00 pour un échantillon gratuit.
4. Définissez le maximum par client pour ce produit sur la fenêtre glissante (0 = illimité).
5. Activez Échantillon par déclinaison si le produit a des déclinaisons et que le client doit choisir la sienne (voir plus bas).
6. Enregistrez.

Ce que fait le module à l’enregistrement

Le module crée un produit échantillon caché, ou met à jour celui qui existe :

• nom traduit, au format « Échantillon : Nom du produit » (Sample, Muestra, Muster, Campione dans les autres langues) ;
• référence au format SMPL suivi de l’identifiant du produit source ;
• prix HT calculé à partir du prix TTC saisi et de la règle de taxe du produit source ;
• image de couverture du produit source recopiée sur tous les formats d’image ;
• catégorie par défaut : la catégorie Échantillons ;
• visibilité « nulle part » : le produit n’apparaît ni dans les listes ni dans la recherche ;
• commande autorisée hors stock, pour ne jamais bloquer une demande ;
• poids issu du réglage global, utilisé par les transporteurs.

Si vous modifiez ensuite le prix, l’option de déclinaison, le poids global ou l’état actif, le produit échantillon est resynchronisé. S’il a été supprimé manuellement du catalogue, il est recréé au prochain enregistrement.

Échantillon par déclinaison

Avec l’option Échantillon par déclinaison, le client choisit sa déclinaison sur la fiche produit comme pour un achat normal, puis clique sur le bouton, qui devient « Commander un échantillon de cette déclinaison ».

• La déclinaison est enregistrée sur la ligne d’échantillon, par exemple « Format : A4, Papier : Couché 300 g ». Elle s’affiche dans un champ « Variante » du panier, de la commande, de la facture et de l’email de relance.
• Chaque déclinaison donne une ligne distincte. Une même déclinaison ne peut pas être ajoutée deux fois.
• Le maximum par client du produit est compté par déclinaison.
• Le prix de l’échantillon est le même pour toutes les déclinaisons du produit.

Réglages

Les réglages se trouvent sous la liste des produits, sur la page Catalogue > Échantillons (DF).

Réglages généraux

• Position du bouton : sous le bouton d’ajout au panier (displayProductActions), dans le bloc d’informations complémentaires (displayProductAdditionalInfo), ou emplacement personnalisé uniquement (displayDfSamplesButton, voir la section suivante).
• Prix d’échantillon par défaut TTC : valeur proposée à la création d’un échantillon.
• Poids d’échantillon : en kilogrammes, appliqué à tous les produits échantillons, utilisé pour les frais de port.
• Compte client obligatoire : activé par défaut. Les limites par client ne s’appliquent de manière fiable qu’à des clients identifiés.
• Remises de groupe client sur les échantillons : appliquer (comportement par défaut de PrestaShop) ou ne pas appliquer. Voir « Prix et remises de groupe ».
• Catégorie des échantillons : catégorie par défaut de tous les produits échantillons. Laissez-la désactivée. Si vous en choisissez une autre, les échantillons existants y sont déplacés.
• Rediriger les pages échantillons : activé par défaut. Un visiteur qui arrive sur la page d’un produit échantillon est redirigé en 301 vers le produit d’origine.
• Conversion comptabilisée sur : l’achat du produit échantillonné uniquement, ou n’importe quel achat ultérieur.

Limites

• Maximum d’échantillons par panier : 0 = illimité.
• Maximum d’échantillons par client et par fenêtre : tous produits échantillons confondus, 0 = illimité.
• Fenêtre glissante : en jours, 30 par défaut. Avec 0, les limites par client portent sur toutes les commandes passées, sans limite de durée.

Relance automatique

• Activer les emails de relance.
• Délai après la commande d’échantillon : en jours, 14 par défaut.
• Uniquement les clients inscrits à la newsletter : à activer si votre base légale pour les emails commerciaux est le consentement.
• Inclure un bon de réduction : un bon nominatif à usage unique est généré pour chaque relance.
• Montant du bon : en pourcentage, 10 par défaut.
• Validité du bon : en jours, 30 par défaut.

L’URL de la tâche cron est affichée dans cette section et dans le tableau de bord.

Afficher le bouton avec Creative Elements ou un thème personnalisé

Si votre fiche produit est construite avec un page builder, les hooks natifs ne sont pas toujours rendus, ou pas à l’endroit voulu. Le module fournit un hook dédié, displayDfSamplesButton.

1. Dans les réglages, choisissez Position du bouton : Emplacement personnalisé uniquement (displayDfSamplesButton). Le bouton n’est alors plus ajouté aux hooks natifs, ce qui évite un double affichage.
2. Avec Creative Elements : dans le modèle de la fiche produit, ajoutez le widget Module à l’endroit voulu, choisissez le module DF Samples et le hook displayDfSamplesButton.
3. Dans un thème personnalisé : ajoutez {hook h='displayDfSamplesButton'} dans le template de la fiche produit, par exemple dans templates/catalog/product.tpl.

Le bouton suit la déclinaison sélectionnée et se met à jour quand le client en change, quel que soit l’emplacement.

Prix et remises de groupe

Le prix de l’échantillon est indépendant du produit d’origine : les prix dégressifs, les prix spécifiques et la quantité minimale du produit d’origine ne s’appliquent pas. Seule une règle de prix catalogue qui vise tous les produits sans distinction s’appliquerait aussi aux échantillons.

La remise d’un groupe de clients (Clients > Groupes, par exemple -15 % pour les revendeurs) s’applique par défaut à tous les produits, échantillons compris. Avec le réglage Ne pas appliquer, le module exclut les produits échantillons de la remise de chaque groupe : vos revendeurs paient l’échantillon au prix fixé, et la remise continue de s’appliquer au reste du catalogue. Les groupes créés plus tard sont pris en compte automatiquement.

Le bouton affiche le prix que paiera le client connecté, remise de groupe et TVA comprises.

Limites et contrôle du panier

Les règles sont vérifiées à chaque enregistrement du panier, et pas seulement au clic sur le bouton. Un ajout par les boutons + et – de la page panier, par une URL d’ajout directe, par « Commander à nouveau » ou par la fusion de panier à la connexion passe donc par les mêmes contrôles :

1. les lignes d’échantillons désactivés sont retirées ;
2. les doublons sont retirés (même échantillon, ou même déclinaison en mode déclinaison) ;
3. la quantité de chaque ligne est ramenée à 1 ;
4. le maximum par panier est appliqué ;
5. le maximum par produit et le maximum global par client sont appliqués sur la fenêtre glissante.

Quand une ligne doit être retirée, c’est la plus récente qui part. Le client voit un message sur la page panier ou de commande. Les commandes annulées, remboursées ou en erreur de paiement ne sont pas comptées dans les limites. Les paniers créés par un employé dans le back-office ne sont pas soumis aux limites.

Configurer la tâche cron

Les relances partent par une tâche cron. Planifiez toutes les heures l’URL affichée dans les réglages. Exemple de crontab :

0 * * * * wget -q -O /dev/null "https://votre-boutique.com/module/dfsamples/cron?token=VOTRE_JETON"

Chaque exécution traite jusqu’à 50 commandes et renvoie un résumé JSON : processed, sent, skipped, waiting et retry.

Règles appliquées par la tâche cron

• Un seul email par commande, même si elle contient plusieurs échantillons. Il liste les produits testés et contient au plus un bon de réduction.
• Seuls les échantillons non convertis et non relancés sont pris en compte, une fois le délai écoulé.
• La commande d’échantillon doit avoir atteint un statut payé, expédié ou livré. Une commande encore en attente de paiement est revue plus tard, puis abandonnée si elle n’est toujours pas payée 60 jours après l’échéance de la relance.
• Les commandes annulées, remboursées ou en erreur de paiement sont ignorées.
• Un échantillon dont le produit a été acheté dans la même commande n’est pas relancé.
• Si l’option newsletter est active, les clients non inscrits ne sont pas relancés.
• En cas d’échec d’envoi, le module réessaie aux exécutions suivantes, au plus trois fois et à six heures d’intervalle minimum. Le bon généré pour un email qui n’est pas parti est supprimé.
• Deux exécutions simultanées ne peuvent pas envoyer le même email : chaque commande est réservée avant traitement.

Suivi de conversion

À la validation de chaque commande contenant un échantillon, le module enregistre le client, son email, le produit source, la déclinaison, la langue et la boutique.

Quand ce client passe une commande ultérieure, les échantillons correspondants sont marqués convertis :

• en mode produit (par défaut) : si la commande contient le produit dont il a reçu l’échantillon ;
• en mode tout achat : dès que la commande contient un produit réel.

La conversion n’est comptée que lorsque la commande d’achat atteint un statut validé (paiement accepté, par exemple). Une commande payée par virement est donc comptée à la réception du paiement. Un achat dans la même commande que l’échantillon n’est pas une conversion.

Tableau de bord

Le panneau au-dessus de la liste des produits affiche :

• Échantillons commandés : nombre de lignes d’échantillon enregistrées ;
• Conversions : nombre d’échantillons suivis d’un achat, et taux de conversion ;
• CA des conversions : total TTC des commandes de conversion, converti dans la devise par défaut ;
• Relances en attente.

La liste des produits affiche aussi, par produit, le nombre d’échantillons commandés, le nombre de conversions et l’état de l’option déclinaison.

Emails de relance

Les modèles se trouvent dans le dossier mails du module, en français, anglais, espagnol, allemand et italien, en version HTML et texte (dfsamples_followup). Pour les autres langues installées, le modèle anglais est copié à l’installation : traduisez-le dans le dossier mails/ suivi du code de la langue, par exemple mails/nl/.

Variables disponibles :

• {firstname} et {lastname} ;
• {product_name} : le ou les produits testés, séparés par des virgules ;
• {product_link} : lien vers la fiche du premier produit ;
• {voucher_block} : bon de réduction mis en forme pour la version HTML, vide si le bon est désactivé ;
• {voucher_text} : même contenu pour la version texte ;
• {shop_name}.

Bons de réduction

Quand l’option est active, chaque relance génère une règle panier PrestaShop :

• code au format SMPL suivi de huit caractères aléatoires ;
• réservée au client destinataire, utilisable une seule fois ;
• réduction en pourcentage, durée de validité configurable.

Les bons sont visibles dans Catalogue > Réductions > Règles panier.

Catalogue, sitemap et flux produits

Les produits échantillons ont la visibilité « nulle part » et sont rangés dans la catégorie Échantillons désactivée. Ils n’apparaissent pas dans les listes, la recherche ni les blocs de mise en avant, et leur page redirige vers le produit d’origine. La plupart des modules de sitemap et de flux ignorent ces produits. Si le vôtre les inclut, excluez la catégorie Échantillons ou les références commençant par SMPL dans ses réglages.

Compatibilité avec le tunnel de commande

Le module n’intervient pas dans le tunnel de commande : un échantillon est une ligne produit classique. Il fonctionne avec le checkout natif et avec les checkouts en une page qui reprennent les étapes natives de PrestaShop. Le message de retrait d’un échantillon s’affiche sur les pages panier et commande.

Désinstallation

La désinstallation supprime les tables, les réglages et l’onglet du module. Les produits échantillons sont désactivés, pas supprimés, et la catégorie Échantillons est conservée, pour que l’historique de vos commandes reste cohérent. Une réinstallation réutilise cette catégorie. Vous pouvez supprimer ces produits et la catégorie manuellement si vous n’en avez plus besoin.

Dépannage

Le bouton n’apparaît pas sur la fiche produit

Vérifiez que le produit est inscrit et actif dans Catalogue > Échantillons (DF). Changez ensuite la position du bouton : certains thèmes ne rendent pas displayProductActions. Avec un page builder, utilisez le hook displayDfSamplesButton.

Un message remplace le bouton

« Vous avez atteint la limite d’échantillons pour ce produit » : le client a atteint son maximum sur la fenêtre glissante. « Votre panier contient déjà le maximum de N échantillons par commande » : le maximum par panier est atteint. Ajustez les limites si nécessaire.

Les produits échantillons n’ont pas d’image

C’était le cas des échantillons créés par la version 1.0.0 sous PrestaShop 9. Cliquez sur Resynchroniser les échantillons : les images manquantes sont ajoutées.

Le prix affiché n’est pas celui attendu

Le prix se saisit TTC et est converti en HT selon la TVA du produit source. Pour un client d’un groupe avec remise, vérifiez le réglage « Remises de groupe client sur les échantillons ». Une règle de prix catalogue globale s’applique aussi aux échantillons.

Les relances ne partent pas

Appelez l’URL de la tâche cron dans un navigateur et lisez le résumé JSON. enabled: false signifie que les relances sont désactivées. waiting désigne des commandes d’échantillon pas encore payées. Vérifiez aussi le délai, l’option newsletter et la configuration email de la boutique (Paramètres avancés > Email).

Un échantillon disparaît du panier

C’est le contrôle du panier : doublon, maximum par panier ou limite du client atteinte. Le client voit un message sur la page panier.