Installation
Prérequis
Magento 2.4.x — testé sur 2.4.9, compatible avec les versions 2.4.* précédentes. PHP 8.1–8.5. Compatible avec le thème Luma par défaut comme avec le thème Hyvä. Nécessite la présence des modules natifs Magento_ReCaptcha* pour la protection reCAPTCHA optionnelle (déjà inclus dans le core de Magento).
Étapes d'installation
- Ajoutez les identifiants reçus par email à
auth.jsonà la racine de votre projet Magento :{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } } composer config repositories.codingrow composer https://repo.codingrow.comcomposer require codingrow/module-withdrawal-buttonbin/magento module:enable Codingrow_WithdrawalButtonbin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush- Collez votre clé de licence dans Admin → Stores → Configuration → Codingrow Extensions → Withdrawal Button → License → License Key, enregistrez, puis
bin/magento cache:flush. - Placez le lien de demande là où les clients pourront le trouver — voir Placer le widget ci-dessous.
L'ensemble du formulaire frontend, des emails et de l'interface admin est disponible en 7 langues, sélectionnées automatiquement selon la langue du store/de l'admin :
Configuration admin
La configuration complète se trouve dans Stores → Configuration → Codingrow Extensions → Withdrawal Button : Licence, Général (activation, e-mail de notification, statuts de commande éligibles, délai de rétractation, texte/couleurs du bouton, champs personnalisés), Modèles d’e-mail et l’étiquette de retour optionnelle.
Désinstallation
composer remove codingrow/module-withdrawal-button puis
bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.
Les demandes déjà enregistrées dans codingrow_withdrawalbutton_request ne sont
jamais supprimées automatiquement — exportez d'abord la grille si vous devez en conserver une trace.
Guide d'utilisation
La page de demande de rétractation
Une page, deux étapes, exactement comme l'exige la directive de référence : le client remplit d'abord les champs fixes (nom, email, numéro de commande, date de réception) ainsi que les éventuels champs personnalisés activés, voit un résumé en lecture seule de tout ce qui a été saisi, et confirme seulement ensuite sur un bouton final distinct. Les champs cachés qui transmettent les données entre les deux étapes sont revalidés côté serveur lors de la confirmation — un client ne peut jamais contourner les vérifications en forçant directement l'étape "confirmée".
Vérification de la commande
Avant d'accepter une demande, le module vérifie que le numéro de commande existe réellement et que l'adresse email correspond à celle de cette commande (sans distinction majuscules/minuscules, fonctionne aussi bien pour les commandes invité que client inscrit). Si l'une des deux vérifications échoue, le même message générique "introuvable" s'affiche dans les deux cas — c'est volontaire : révéler "email incorrect" plutôt que "la commande n'existe pas" permettrait de tester des numéros de commande valides par essais successifs.
Statut de commande et délai de rétractation
Deux réglages dans Stores → Configuration → Codingrow Extensions → Withdrawal Button → General contrôlent quelles demandes sont acceptées, en plus de la vérification obligatoire commande/email décrite ci-dessus.
- Order statuses eligible for withdrawal — une liste à sélection multiple native de Magento (Pending / Processing / Complete / Closed / Canceled / On Hold). Une demande n'est acceptée que si le statut actuel de la commande fait partie de ceux sélectionnés ; présélectionnés à l'installation sur Pending, Processing, Complete, Closed et On Hold. Laisser la liste vide bloque toute demande quel que soit le statut de la commande — un choix délibéré du marchand, pas un bug.
- Withdrawal period (days) — le nombre de jours autorisés entre la date de réception déclarée et le moment de l'envoi de la demande (14 par défaut, le minimum prévu par la réglementation européenne sur la rétractation). Une fois ce délai écoulé, la demande est rejetée avec un message invitant le client à contacter directement le magasin ; la colonne des jours écoulés de la grille admin signale les demandes dépassant cette même limite.
Prévention des demandes en double
Une commande ne peut avoir qu'une seule demande de rétractation active, quel que soit son statut — même une demande "Rejetée". Un client qui n'est pas d'accord avec un rejet ne peut pas simplement soumettre à nouveau la même demande pour le contourner ; si une véritable exception est nécessaire, l'admin supprime d'abord la demande précédente de la grille.
Date de réception et jours écoulés
Le délai de rétractation (configurable, 14 jours par défaut) démarre à partir du moment où les biens ont été reçus, et non de la date d'achat ou de facturation — une information que Magento ne peut pas connaître par lui-même, car elle dépend du transporteur. Le formulaire la demande via un sélecteur de date HTML5 natif (sans dépendance à jQuery UI qui pourrait entrer en conflit avec un thème), plafonné pour qu'une date future ne puisse pas être saisie. La date de commande elle-même est lue automatiquement depuis la commande liée — le client n'a jamais à la saisir. Les deux dates, ainsi que les jours écoulés depuis la réception, sont affichés dans la grille admin (signalés au-delà de ce délai) et disponibles comme variables d'email.
Constructeur de champs personnalisés
Au-delà des quatre champs exigés par la loi (nom, email, numéro de commande, date de réception — toujours obligatoires, jamais supprimables), vous pouvez ajouter un nombre illimité de champs personnels depuis Stores → Configuration → Codingrow Extensions → Withdrawal Button → Custom Fields : libellé, type, s'il est obligatoire, et s'il est actuellement affiché sur le formulaire — l'ordre des lignes dans cette liste est l'ordre d'affichage sur le formulaire.
| Type | Affiché comme |
|---|---|
| Texte | Champ sur une ligne |
| Zone de texte | Zone multi-lignes |
| Liste déroulante | Un <select> avec les options saisies, une par ligne |
| Case à cocher | Une simple case (ex. "J'ai encore l'emballage d'origine") |
Les valeurs soumises pour un champ désactivé par la suite restent dans l'historique de la demande et continuent d'être affichées là où elles ont été enregistrées — seul le libellé du champ est recalculé par ID, donc renommer un champ met à jour le libellé partout où ses anciennes réponses sont aussi affichées.
Couleurs et texte du bouton
Deux champs de couleur hexadécimale (texte et fond) permettent d'adapter le bouton à votre marque — seules les couleurs changent ; la forme, le padding et la police restent toujours ceux de votre thème (Luma ou Hyvä), le bouton ne peut donc jamais se retrouver visuellement cassé. Une valeur hexadécimale invalide est simplement ignorée, avec retour à la couleur par défaut du thème. Le texte du bouton est également configurable, affiché exactement comme saisi (casse préservée, aucune mise en majuscule automatique) — laissez-le vide pour conserver le libellé traduit par défaut.
Protection reCAPTCHA
Withdrawal Button s'enregistre comme formulaire protégeable dans le système reCAPTCHA natif de Magento — Stores → Configuration → Customers → Google reCAPTCHA → Storefront → "Enable for Withdrawal Button". La version déjà configurée pour le reste du store (v2 case à cocher, v2 invisible, ou v3) s'applique automatiquement ; il n'y a aucune configuration captcha distincte à maintenir.
Grille admin et actions groupées
Chaque demande arrive dans Codingrow Extensions → Withdrawal Button, paginée et filtrable, avec des colonnes pour le numéro de commande, le client, la date de réception, les jours écoulés (signalés au-delà de 14), les valeurs des champs personnalisés et le statut. Les actions groupées permettent de mettre à jour le statut de plusieurs demandes sélectionnées à la fois, ou de supprimer des lignes pour nettoyer des données de test.
| Statut | Signification |
|---|---|
| En attente | Tout juste soumise, pas encore examinée. |
| En cours | En cours de traitement par le store. |
| Terminée | Retour/remboursement finalisé. |
| Rejetée | Le store a refusé la demande. |
| Annulée | Le client a retiré sa propre demande. |
Modèles d'email et variables
Deux modèles d'email natifs Magento — un accusé de réception client (la confirmation sur
support durable exigée par la loi) et une notification interne à l'admin — envoyés
automatiquement via TransportBuilder, exactement comme les propres emails de
commande de Magento. Clonez l'un des deux depuis Marketing → Email Templates,
modifiez le texte avec l'éditeur WYSIWYG natif, puis sélectionnez votre copie dans
Configuration → Email Templates — aucun code de templating personnalisé
impliqué.
| Variable | Contenu |
|---|---|
order_increment_id | Le numéro de commande |
order_date | La date de la commande elle-même, lue automatiquement |
receipt_date | La date à laquelle le client a déclaré avoir reçu les biens |
days_since_receipt | Jours écoulés depuis cette date |
request_id | Numéro de référence interne de cette demande |
submitted_at | Date et heure exactes de confirmation de la demande |
custom_fields_text | Tous les champs personnalisés remplis, formatés en lignes "Libellé : valeur" |
Étiquette de retour PDF
Un simple bordereau optionnel (logo, nom de l'expéditeur, adresse de retour, instructions
d'emballage) généré en interne avec Zend_Pdf — la même bibliothèque PDF que celle
utilisée par le core Magento pour les factures et expéditions, sans aucune dépendance tierce
ajoutée — et joint automatiquement à l'email de réception du client une fois activé dans
Configuration → Return Label. Téléchargez un logo, renseignez l'adresse de
retour et d'éventuelles instructions d'emballage, et chaque futur email de confirmation de
demande portera une étiquette prête à imprimer avec le numéro de référence, le numéro de
commande, le nom du client et la date de réception de cette demande, ainsi que les éventuels champs personnalisés remplis par le client.
Placer le widget
Le lien de demande n'est jamais codé en dur dans le thème — il est placé exclusivement via le système de Widgets natif de Magento, ce qui donne au marchand un contrôle total sur s'il apparaît, et où. Deux façons de le faire, selon l'étendue d'affichage souhaitée :
| Méthode | Idéal pour |
|---|---|
| Content → Elements → Widgets | Afficher le lien sur de nombreuses/toutes les pages à la fois, ou à une position fixe de la mise en page (footer, barre latérale) sur tout le site. |
| Insert Widget dans le contenu d'une page CMS | Le placer sur une seule page spécifique — par ex. la page d'accueil — exactement où vous le souhaitez dans le contenu de cette page, sans affecter les autres. |
Sur tout le site, via Content → Elements → Widgets :
- Content → Elements → Widgets → Add Widget, choisissez le widget de lien Withdrawal Button.
- Attribuez-le à "All Pages" ou "Specified Page(s)" et définissez le conteneur d'affichage (ex.
contentousidebar.additional) — sur les thèmes Hyvä, le conteneur "Footer" peut ne pas être disponible dans le sélecteur de widgets ; utilisez alors la zone de contenu principale, juste avant le footer. - Enregistrez et rechargez les pages cibles — aucun vidage de cache n'est nécessaire pour une instance de widget tout juste enregistrée.
Sur une seule page spécifique, par ex. la page d'accueil :
- Content → Pages, ouvrez la page (ex. "Home page").
- Dans l'éditeur WYSIWYG de l'onglet Content, placez le curseur où vous voulez le bouton et cliquez sur Insert Widget.
- Choisissez le widget de lien Withdrawal Button, définissez son texte d'étiquette et sa classe CSS, puis Insert — cela insère une directive
{{widget type="Codingrow\WithdrawalButton\Block\Widget\Link" ...}}directement dans le contenu de cette page, sans affecter les autres. - Enregistrez la page.
Licence
Sans clé de licence valide, la page de rétractation reste visible (un marchand ne doit jamais se retrouver sans le bouton légalement requis simplement parce qu'une licence a expiré) mais les nouvelles soumissions sont bloquées jusqu'à la saisie d'une clé dans Configuration → License → License Key.