Custom Checkout Fields : documentation

Présentation

DataFirefly Custom Checkout Fields ajoute des champs personnalisés au tunnel de commande et au formulaire d’inscription de PrestaShop 8 et 9 : numéro de bon de commande, date de livraison souhaitée, SIRET, secteur d’activité, pièce jointe ou tout autre champ que vous créez. Les valeurs sont contrôlées avant la validation de la commande, puis reprises sur la fiche commande, la facture PDF, le bon de livraison, les e-mails, les listes du back-office, les exports CSV et le webservice.

Installation

1. Dans le back-office, ouvrez Modules > Gestionnaire de modules et cliquez sur Installer un module.
2. Sélectionnez le fichier dfcheckoutfields.zip.
3. L’installation crée trois tables, le dossier protégé upload/dfcheckoutfields, les menus Commandes > Champs personnalisés et Commandes > Export des champs, et cinq champs prêts à l’emploi.
4. Cliquez sur Configurer pour régler les options générales.

Pour une mise à jour, installez le nouveau ZIP par-dessus l’ancien : les scripts de mise à jour ajoutent les nouvelles colonnes sans toucher à vos champs ni aux valeurs enregistrées.

Les champs créés à l’installation

• Numéro de bon de commande (po_number) : texte de 50 caractères au plus, enregistré sur la commande, affiché sur la facture, le bon de livraison et en colonne de la liste des commandes.
• Date de livraison souhaitée (desired_date) : date à J+2 au plus tôt, jours ouvrés uniquement.
• SIRET (siret) : contrôlé par clé de Luhn, enregistré sur le compte client, demandé à l’inscription et au checkout, limité aux clients dont le pays est la France.
• Secteur d’activité (sector) : liste de huit secteurs, enregistrée sur le compte client, demandée à l’inscription.
• Pièce jointe (attachment) : PDF, images et documents Office, 8 Mo au plus.

Aucun de ces champs n’est obligatoire par défaut. Modifiez-les, désactivez-les ou supprimez-les selon vos besoins.

Réglages généraux

Modules > Gestionnaire de modules > Champs personnalisés commande et inscription > Configurer.

• Position du bloc dans le tunnel de commande : étape paiement, au-dessus des moyens de paiement (par défaut), ou étape livraison, sous les transporteurs. Un panier composé uniquement de produits virtuels utilise toujours l’étape paiement.
• Titre du bloc : affiché au checkout, sur les pages de commande, les PDF et dans les e-mails, par langue.
• Position sur la facture PDF : en-tête sous le numéro de facture, ou bas de la facture. Voir la section Facture et bon de livraison.
• Note privée si un champ obligatoire manque : ajoute la liste des champs manquants à la note privée de la commande quand un module de paiement contourne le contrôle du checkout.
• Copier les champs SIRET dans le SIRET natif du client : garde à jour le champ SIRET de la fiche client utilisé par le mode B2B de PrestaShop.

Créer ou modifier un champ

Commandes > Champs personnalisés, puis Ajouter un champ ou le crayon d’une ligne. Le formulaire n’affiche que les options utiles au type et à l’enregistrement choisis.

Champ

• Libellé, texte indicatif et texte d’aide : par langue. Une langue laissée vide reprend le libellé de la langue par défaut.
• Code : identifiant technique en minuscules, chiffres et tirets bas. Il sert aussi de variable d’e-mail {dfcf_CODE} et de nom de colonne dans le webservice.
• Type : texte, texte multiligne, nombre, e-mail, date, liste déroulante, case à cocher, SIRET ou fichier.
• Enregistré sur : Commande (une valeur par commande) ou Compte client (valeur conservée sur la fiche client, préremplie au checkout et copiée sur chaque commande).
• Options de la liste : une option par ligne au format clé|Libellé, par exemple industry|Industrie. Gardez les mêmes clés dans toutes les langues.

Où et quand

• Afficher à l’inscription et obligatoire à l’inscription : champs enregistrés sur le compte client uniquement, hors type fichier. Ils apparaissent aussi dans le formulaire Mes informations de l’espace client.
• Afficher au checkout et obligatoire au checkout.
• Afficher seulement si : voir la section Affichage conditionnel.
• Pays : pays de l’adresse de facturation au checkout, pays du visiteur à l’inscription. Vide pour tous les pays.
• Groupes de clients : tout décoché pour tous les groupes.

Validation

• Longueur maximale : 0 pour la valeur par défaut (255 caractères, 2000 en multiligne).
• Motif de validation : expression régulière sans délimiteurs, par exemple ^[A-Z]{2}[0-9]{6}$.
• Délai minimum et horizon maximum en jours pour une date enregistrée sur la commande.
• Jours ouvrés uniquement : refuse le samedi et le dimanche.
• Jours de fermeture : un par ligne, 2026-12-24 pour un jour, 2026-08-01:2026-08-21 pour une période, 12-25 pour chaque année.
• Extensions autorisées et taille maximale pour un fichier. Les scripts et exécutables sont toujours refusés.

Documents et exports

Afficher au client (confirmation, espace client, e-mails client), sur la facture PDF, sur le bon de livraison, en colonne filtrable des listes du back-office, dans les exports CSV.

Liste des champs

Les icônes de la liste activent ou désactivent un réglage d’un clic. Glissez les lignes pour changer l’ordre d’affichage. L’action Dupliquer crée une copie désactivée avec le code code_copy. Un champ qui a des valeurs sur des commandes ne peut pas être supprimé : désactivez-le pour conserver l’historique.

Affichage conditionnel

Exemple : n’afficher le SIRET qu’aux entreprises.

1. Créez un champ Case à cocher enregistré sur le compte client, code is_company, libellé Je suis une entreprise.
2. Éditez le champ SIRET, section Où et quand, et choisissez Afficher seulement si : Je suis une entreprise. Laissez « a l’une de ces valeurs » vide : pour une case à cocher, cela signifie cochée.

Pour une liste déroulante, indiquez les clés attendues séparées par des virgules, par exemple health,public. Les conditions s’enchaînent : un champ dont le champ parent est masqué est masqué lui aussi. Un champ masqué n’est jamais obligatoire et sa valeur n’est pas conservée. Le champ parent doit être affiché au même endroit (inscription ou checkout), ou déjà renseigné sur le compte client.

Côté client

Au checkout

Le bloc s’affiche à l’étape choisie. Chaque valeur est enregistrée pendant la saisie. Tant qu’un champ obligatoire est vide ou invalide, le clic sur Commander (ou Continuer à l’étape livraison) est bloqué, le message s’affiche sous le champ et la page défile jusqu’à lui. La pièce jointe s’envoie par glisser-déposer ou par clic, avec une barre de progression. Le client peut la retirer et en envoyer une autre.

À l’inscription et dans Mes informations

Les champs du compte client marqués Afficher à l’inscription s’ajoutent au formulaire natif de création de compte, au formulaire invité du checkout et au formulaire Mes informations. Les erreurs s’affichent comme celles des champs PrestaShop.

Après la commande

Les valeurs marquées Afficher au client apparaissent sur la page de confirmation et dans le détail de la commande de l’espace client. La pièce jointe y est téléchargeable par le client propriétaire de la commande.

Facture et bon de livraison

Bas de la facture : le module utilise le hook displayPDFInvoice et affiche un tableau après les totaux. Aucun fichier n’est modifié.

En-tête, sous le numéro de facture : PrestaShop n’a pas de hook à cet endroit. En enregistrant ce réglage, le module ajoute un bloc délimité par {* dfcf:start *} et {* dfcf:end *} à la fin de themes/VOTRE_THEME/pdf/invoice.summary-tab.tpl. Si le fichier n’existe pas, il est créé à partir de celui de PrestaShop. S’il existe déjà, le module le complète et garde une copie .dfcf-backup. Repasser en Bas de la facture ou désinstaller retire le bloc. Si le fichier n’est pas modifiable, un message indique son chemin.

Avec DataFirefly Invoice Editor, qui remplace le rendu de la facture, utilisez le réglage Bas de la facture : l’éditeur reprend le contenu des modules à l’emplacement que vous choisissez.

Le bon de livraison utilise le hook displayPDFDeliverySlip, champ par champ.

E-mails

Deux types de variables sont disponibles dans les e-mails qui contiennent l’identifiant de la commande, notamment order_conf et new_order :

• {dfcf_fields} : toutes les valeurs dans un tableau. Dans order_conf, seuls les champs marqués Afficher au client sont inclus. Dans new_order, destiné au marchand, tous les champs le sont.
• {dfcf_CODE} : une valeur, par exemple {dfcf_po_number} ou {dfcf_desired_date}.

Ajoutez-les dans Design > Thème des e-mails, ou dans les fichiers de mails de votre thème.

Back-office

• Page commande : carte Champs personnalisés avec toutes les valeurs. Le bouton Modifier permet de corriger une valeur ou de remplacer la pièce jointe.
• Fiche client : carte avec les champs enregistrés sur le compte client, modifiable de la même façon.
• Listes : chaque champ marqué Colonne filtrable apparaît dans la liste des commandes avec un filtre texte. Les champs du compte client apparaissent aussi dans la liste des clients.

Export CSV

Commandes > Export des champs. Choisissez Commandes ou Clients, la période, les états de commande (tout décoché pour tous), le séparateur, et si seules les lignes avec au moins une valeur sont exportées. Le fichier est en UTF-8 avec BOM, lisible directement par Excel. Les commandes sont exportées avec leur référence, date, état, client, totaux HT et TTC et devise, suivis des champs marqués Inclure dans les exports CSV.

Webservice

1. Paramètres avancés > Webservice : activez le webservice et créez ou éditez une clé.
2. Cochez GET sur la ressource dfcf_values.
3. Appelez /api/dfcf_values?filter[id_order]=[123]&display=full.

Chaque valeur est renvoyée avec id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label et has_file. Les valeurs de profil client ont id_order et id_cart à 0.

Pièces jointes et sécurité

Chaque fichier est contrôlé sur son extension (liste du champ) et sur son contenu réel : un script renommé en .pdf est refusé. Il est stocké dans upload/dfcheckoutfields avec un nom aléatoire et sans extension, dossier dont l’accès direct est interdit par un fichier .htaccess. Sur Nginx, ajoutez une règle location ^~ /upload/dfcheckoutfields/ { deny all; }. Le téléchargement passe toujours par le module, qui vérifie que le visiteur est le client de la commande ou un employé.

RGPD

Les valeurs enregistrées sur un compte client sont supprimées avec le client. Le module répond aux demandes d’export et de suppression du module RGPD officiel de PrestaShop. Les valeurs copiées sur les commandes sont conservées avec la commande.

Dépannage

Le bloc n’apparaît pas au checkout

Vérifiez que le champ est actif, marqué Afficher au checkout, et que le groupe et le pays du client correspondent à ses restrictions. Si vous avez choisi l’étape livraison, vérifiez que votre thème appelle le hook displayAfterCarrier.

Le bouton Commander n’est pas bloqué

Le module reconnaît le bouton des thèmes Classic et Hummingbird. Un thème qui remplace ce bouton par un autre élément, ou un paiement express lancé depuis la fiche produit, n’est pas couvert : activez la note privée pour être averti des commandes incomplètes.

Les champs n’apparaissent pas dans l’en-tête de la facture

Vérifiez que le fichier pdf/invoice.summary-tab.tpl du thème est modifiable, enregistrez à nouveau les réglages, puis videz le cache dans Paramètres avancés > Performances.

Une variable d’e-mail s’affiche telle quelle

Elle n’est remplie que dans les e-mails qui contiennent l’identifiant de la commande. Vérifiez aussi que le code correspond exactement à celui du champ.