Factur-X — Guide complet (PrestaShop 8 & 9)

Ce guide couvre l’installation, la configuration et l’utilisation du module DataFirefly Factur-X (dffacturx) pour PrestaShop 8 et 9. Le module transforme vos commandes en factures électroniques hybrides au format Factur-X : un PDF/A-3b lisible et imprimable qui contient, embarquées à l’intérieur, les données structurées de la facture au format XML CII (norme EN 16931).

Présentation

Une facture Factur-X est un fichier unique qui réunit deux usages. Votre client ouvre un PDF classique, qu’il peut lire, imprimer et archiver. Son logiciel comptable, ou la plateforme qui traite la facture, lit directement le XML embarqué sans avoir à interpréter l’image. Il n’y a plus deux fichiers à synchroniser, donc plus de risque d’écart entre ce qui est affiché et ce qui est traité.

Le module couvre la génération de ces fichiers : il produit le XML, rend le PDF et embarque l’un dans l’autre avec les métadonnées attendues. La transmission via une Plateforme Agréée est une couche distincte, détaillée dans la section sur la portée réglementaire.

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 7.4 minimum, 8.1 ou supérieur recommandé
• TCPDF, fourni d’origine avec PrestaShop — aucune installation supplémentaire
• Extensions PHP : dom (construction du XML), zlib (lecture des métadonnées XMP compressées), zip (génération en masse)

Installation

1. Dans le back-office, allez dans Modules → Gestionnaire de modules → Installer un module.
2. Déposez le fichier dffacturx.zip. Vous pouvez aussi copier le dossier dffacturx directement dans le répertoire modules/ de votre boutique.
3. Lancez l’installation. Le module enregistre ses hooks et crée un onglet Factur-X sous le menu Commandes.
4. Ouvrez la configuration et renseignez l’identité du vendeur avant de générer votre première facture.

Configuration

Identité du vendeur

C’est l’étape obligatoire. Ces informations alimentent à la fois le PDF visible et le XML structuré. Sans elles, le XML sera rejeté par un validateur.

• Raison sociale — pré-remplie avec le nom de votre boutique, à corriger si votre dénomination légale diffère.
• SIREN — 9 chiffres, sans espaces. Indispensable : il est transmis dans le XML avec l’identifiant de schéma adéquat.
• SIRET — 14 chiffres, optionnel mais recommandé.
• N° de TVA intracommunautaire — indispensable si vous êtes assujetti (ex. FR12345678901).
• Forme juridique et capital social — affichés dans les mentions légales en pied de facture.
• Adresse, code postal, ville, pays — le pays est attendu au format ISO à deux lettres (ex. FR).
• Contact, téléphone, email — repris dans le XML sur les profils EN 16931 et supérieurs.

Profil Factur-X

Le profil détermine le niveau de détail du XML et l’identifiant de spécification qui y est inscrit. Le module l’ajuste automatiquement selon votre choix.

• EN 16931 — recommandé. Correspond au socle complet de la norme européenne, accepté partout.
• BASIC — XML plus léger, conserve le détail des lignes.
• EXTENDED — profil étendu, pour les cas nécessitant des données supplémentaires.
• MINIMUM et BASIC WL — profils sans détail de lignes, réservés à des usages spécifiques.

Options

• Téléchargement client — active un lien dans l’espace compte. Le module vérifie que la commande appartient bien au client connecté avant de servir le fichier.
• Génération automatique — si vous renseignez un identifiant d’état de commande, une facture est générée et enregistrée dans le dossier generated du module dès qu’une commande atteint cet état. Les erreurs éventuelles sont écrites dans les logs PrestaShop sans bloquer le changement de statut.

Générer une facture

Depuis la fiche commande

Ouvrez une commande dans le back-office : un panneau Factur-X apparaît en bas de la page principale. Il rappelle le profil actif et propose deux boutons — Télécharger PDF Factur-X pour le fichier hybride complet, et Télécharger XML pour le XML seul, utile lors des phases de test et de validation.

Génération en masse

Le menu Commandes → Factur-X affiche la liste de vos commandes avec, sur chaque ligne, un accès direct au PDF et au XML. Pour traiter un lot, cochez les commandes concernées et choisissez l’action groupée Télécharger les Factur-X (ZIP) : le module assemble toutes les factures dans une archive. Si une commande échoue, elle est ignorée et l’erreur est journalisée — l’archive reste exploitable.

Côté client

Si l’option est activée, un lien Mes factures Factur-X apparaît dans l’espace compte. Le contrôleur front vérifie que le client est connecté et que la commande lui appartient, sinon il redirige vers l’historique des commandes.

Ce que contient le fichier généré

Le PDF produit est un PDF/A-3b rendu par le TCPDF de PrestaShop. Le module y ajoute ensuite, par mise à jour incrémentale, les éléments qui en font une facture Factur-X :

• un objet fichier embarqué contenant le XML, nommé factur-x.xml ;
• une entrée dans le tableau des fichiers associés du catalogue, avec la relation Data ;
• une entrée dans le dictionnaire des fichiers embarqués nommés ;
• des métadonnées XMP décrivant le type de document, le nom du fichier, la version et le niveau de conformité, accompagnées du schéma d’extension PDF/A correspondant.

La mise à jour incrémentale ajoute ces objets à la fin du fichier sans modifier un seul octet du document rendu. Les polices, les flux de contenu et le profil colorimétrique produits par TCPDF restent intacts — et le module ne dépend d’aucun détail interne de TCPDF, donc d’aucune version particulière.

Le XML est un CrossIndustryInvoice UN/CEFACT. Il contient le contexte du document avec l’identifiant de spécification du profil, l’en-tête de facture, les lignes le cas échéant, l’accord commercial (vendeur et acheteur), la livraison, et le règlement avec la ventilation TVA, les remises, les charges et le récapitulatif monétaire.

Modélisation comptable

Les validateurs Factur-X ne comparent pas vos totaux à ceux de PrestaShop : ils vérifient que le document est cohérent avec lui-même. Le module recalcule donc l’ensemble des montants à partir des lignes et de la ventilation TVA, afin de satisfaire les règles d’équilibre de la norme.

• Lignes — le prix unitaire net est déduit du total ligne divisé par la quantité. L’unité utilisée est le code unité générique.
• Frais de port — modélisés en charge au niveau du document, avec leur propre taux de TVA.
• Remises — modélisées en allowance au niveau du document, réparties proportionnellement sur les différentes bases de TVA.
• Ventilation TVA — une occurrence par taux rencontré, avec base, montant et catégorie.
• Catégorie TVA — catégorie standard si le taux est supérieur à zéro, catégorie zéro sinon.
• Acompte — le montant prépayé est à zéro et le net à payer égale le total TTC : la facture est émise, la totalité reste due au sens du document.

Les cas de TVA particuliers — exonération, autoliquidation, livraison intracommunautaire — ne sont pas dérivés automatiquement. Si votre activité les implique, faites valider quelques factures représentatives et adaptez la catégorie utilisée.

Valider avant la mise en production

Cette étape n’est pas optionnelle. Générez quelques factures représentatives de votre activité — une commande simple, une commande avec remise, une commande à plusieurs taux de TVA — puis contrôlez-les avec :

• le validateur de la FNFE-MPE, référence française pour Factur-X ;
• Mustangproject, validateur open source pour la conformité EN 16931 ;
• veraPDF, pour la conformité du conteneur PDF/A-3.

Le bouton de téléchargement du XML seul est fait pour cette phase : il vous évite d’extraire manuellement la pièce jointe du PDF à chaque essai.

Portée réglementaire

La réforme française de la facturation électronique suit un calendrier en deux temps. Au 1er septembre 2026, toutes les entreprises assujetties à la TVA doivent pouvoir recevoir des factures électroniques, et les grandes entreprises et ETI doivent en émettre. Au 1er septembre 2027, l’obligation d’émission s’étend aux PME, TPE et micro-entreprises. La plupart des marchands PrestaShop doivent donc recevoir dès 2026 et émettre à partir de 2027.

Trois rôles doivent être distingués :

• Générer des fichiers Factur-X conformes — ce que fait ce module. Aucune certification ni immatriculation n’est requise.
• Transmettre les factures via une Plateforme Agréée (anciennement PDP). Le marchand choisit sa plateforme et lui remet les fichiers.
• Être une Plateforme Agréée — activité soumise à immatriculation par l’État, hors périmètre du module.

Dépannage

Le validateur rejette le XML

Vérifiez d’abord l’identité du vendeur, en particulier le SIREN et le numéro de TVA : ce sont les causes de rejet les plus fréquentes. Contrôlez ensuite l’adresse de facturation du client — un pays ou un code postal manquant peut également faire échouer la validation.

Message indiquant que TCPDF est indisponible

Le module utilise la classe TCPDF fournie par PrestaShop et, à défaut, tente de la charger depuis le répertoire des outils. Si l’erreur persiste, c’est que la bibliothèque a été retirée de votre installation : restaurez-la depuis une archive PrestaShop de la même version.

L’action groupée ZIP est indisponible

L’extension PHP zip n’est pas activée sur le serveur. Le téléchargement unitaire depuis chaque fiche commande reste disponible sans elle.

La génération automatique ne produit rien

Vérifiez que l’identifiant d’état de commande est bien renseigné dans la configuration, puis que le dossier generated du module est accessible en écriture. Les erreurs de génération sont consignées dans les logs PrestaShop avec le préfixe Factur-X.

Le PDF s’ouvre mais la pièce jointe n’apparaît pas

Tous les lecteurs n’affichent pas le panneau des pièces jointes par défaut. Ouvrez le volet dédié de votre lecteur PDF, ou utilisez le téléchargement du XML seul pour contrôler son contenu.

Architecture

Le module suit une organisation classique, avec un autoloader PSR-4 manuel dont la racine de namespace DataFirefly/FacturX pointe vers le dossier src.

• src/Builder — définition des profils et construction du XML CII.
• src/Pdf — rendu du PDF/A-3b et embarquement du XML.
• src/Service — extraction des données de commande et orchestration.
• src/Install — installation, onglet d’administration et hooks.
• controllers/admin et controllers/front — contrôleurs de téléchargement back-office et front-office.

L’architecture repose sur ModuleAdminController et Smarty, identiques entre PrestaShop 8 et 9, sans branche de code séparée ni dépendance Symfony spécifique.

Changelog

1.0.0 — 4 juin 2026

• Génération de factures hybrides Factur-X : PDF/A-3b avec XML CII embarqué.
• Profils BASIC, EN 16931 et EXTENDED sélectionnables.
• Construction du XML CII conforme UN/CEFACT avec ventilation TVA par taux.
• Embarquement autonome du XML par mise à jour incrémentale du PDF.
• Métadonnées XMP Factur-X et schéma d’extension PDF/A injectés.
• Identité vendeur entièrement paramétrable.
• Téléchargement PDF et XML sur la fiche commande, génération en masse en ZIP.
• Lien de téléchargement dans l’espace client, activable.
• Génération automatique optionnelle au passage d’un statut de commande.
• Compatible PrestaShop 8.0 à 9.0 sans branche de code séparée.