Intégrer Factur-X dans son logiciel de facturation : guide technique

L'intégration de Factur-X dans un logiciel de facturation existant repose sur l'ajout d'un module de génération qui transforme vos données de facturation en un fichier conforme. Voici l'architecture type :

Le flux de génération Factur-X

1. Extraction des données : votre logiciel extrait les données de la facture depuis la base de données (émetteur, destinataire, lignes, montants, TVA)
2. Génération du XML CII : un module construit le fichier factur-x.xml au format UN/CEFACT CII D16B, conforme au profil choisi
3. Génération du PDF : votre moteur de rendu habituel crée le document PDF visuel de la facture
4. Conversion en PDF/A-3 : le PDF est converti au format d'archivage PDF/A-3 (ISO 19005-3)
5. Fusion : le fichier XML est embarqué en pièce jointe dans le PDF/A-3, avec les métadonnées XMP requises
6. Validation : le fichier final est vérifié avec un validateur de conformité

La bonne nouvelle, c'est que les bibliothèques open source comme factur-x (Python) ou Mustang (Java) encapsulent les étapes 4 et 5 en une seule opération : vous fournissez un PDF standard et un XML, et la bibliothèque produit le fichier Factur-X conforme.

Le fichier XML embarqué dans un Factur-X suit le schéma UN/CEFACT CII D16B. Sa structure est hiérarchique et comprend plusieurs sections principales :

Structure du fichier factur-x.xml

• ExchangedDocumentContext : identifie le profil Factur-X utilisé (Minimum, Basic, EN 16931, etc.) via un identifiant de guideline
• ExchangedDocument : contient le numéro de facture, la date d'émission, le type de document (380 pour facture) et les notes éventuelles
• SupplyChainTradeTransaction : le cœur de la facture, subdivisé en trois parties :
  • ApplicableHeaderTradeAgreement : informations sur le vendeur et l'acheteur (noms, adresses, identifiants fiscaux)
  • ApplicableHeaderTradeDelivery : informations de livraison (adresse, date)
  • ApplicableHeaderTradeSettlement : données financières (devise, ventilation TVA, montants totaux, conditions de paiement)
• IncludedSupplyChainTradeLineItem : lignes de détail de la facture (à partir du profil Basic)

Bonnes pratiques de génération XML

• Utilisez toujours l'encodage UTF-8 pour supporter les caractères accentués français
• Respectez strictement l'ordre des balises défini par le schéma XSD officiel
• Utilisez les codes normalisés : codes pays ISO 3166, codes devises ISO 4217, codes TVA UN/CEFACT
• Formatez les dates en YYYYMMDD (format 102 du schéma CII) : 20260401 pour le 1er avril 2026
• Les montants doivent utiliser le point comme séparateur décimal (pas la virgule)

Voici les principales bibliothèques open source disponibles pour intégrer Factur-X dans votre logiciel, classées par langage de programmation :

Python : factur-x (par Akretion)

La bibliothèque de référence pour Python. Elle permet de créer, lire et valider des factures Factur-X :

• Installation : pip install factur-x
• Fonctions principales : generate_from_binary() pour créer un Factur-X à partir d'un PDF et d'un XML, get_xml_from_pdf() pour extraire le XML d'un Factur-X existant
• Support de tous les profils (Minimum à Extended)
• Licence : BSD, utilisable librement y compris dans des logiciels commerciaux

Java : Mustang / ZUGFeRD

La bibliothèque Mustang est la référence pour l'écosystème Java :

• Disponible sur Maven Central : org.mustangproject
• Support complet de Factur-X et ZUGFeRD 2.x
• Inclut un validateur intégré pour vérifier la conformité
• Licence : Apache 2.0

.NET / C# : ZUGFeRD-csharp

Pour les développements .NET et C# :

• Package NuGet disponible : ZUGFeRD-csharp
• API simple pour la génération et la lecture de factures
• Compatible .NET Framework et .NET Core

PHP : Factur-X PHP

Pour les applications web en PHP, plusieurs bibliothèques communautaires permettent la génération de Factur-X à partir de frameworks comme Laravel ou Symfony.

La conversion d'un PDF standard en PDF/A-3 est l'étape technique la plus délicate de l'intégration Factur-X. Le format PDF/A-3 (ISO 19005-3) impose des contraintes strictes que les bibliothèques de génération PDF classiques ne respectent pas toujours.

Contraintes du PDF/A-3

• Polices embarquées : toutes les polices utilisées dans le document doivent être intégralement embarquées dans le fichier. Pas de référence à des polices système.
• Espaces colorimétriques : tous les éléments graphiques doivent utiliser des profils ICC déclarés. Pas de couleurs dépendantes du périphérique.
• Métadonnées XMP : le fichier doit contenir un flux XMP (Extensible Metadata Platform) décrivant le document et le fichier XML embarqué.
• Transparence : le PDF/A-3 permet la transparence (contrairement au PDF/A-1), mais elle doit être correctement déclarée.
• Pas de JavaScript : aucun script ne doit être présent dans le fichier.
• Pas de contenu chiffré : le document ne doit pas être protégé par mot de passe.

Métadonnées XMP spécifiques à Factur-X

Le fichier PDF/A-3 doit contenir des métadonnées XMP spécifiques identifiant le fichier comme un Factur-X :

• Namespace Factur-X : urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#
• DocumentFileName : factur-x.xml
• DocumentType : INVOICE
• Version : la version de la spécification (ex : 1.0)
• ConformanceLevel : le profil utilisé (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED)

La validation est une étape critique de l'intégration Factur-X. Un fichier qui semble correct visuellement peut contenir des erreurs structurelles qui entraîneront son rejet par les plateformes de réception.

Les trois niveaux de validation

1. Validation PDF/A-3 : vérifie que le conteneur PDF est conforme à la norme ISO 19005-3. Utilisez veraPDF (outil open source de référence) pour cette vérification.
2. Validation XML CII : vérifie que le fichier factur-x.xml est conforme au schéma XSD du profil déclaré. Les erreurs courantes sont les balises manquantes, les types de données incorrects et les codes non reconnus.
3. Validation métier : vérifie la cohérence des données (somme des lignes = total HT, calcul de TVA correct, SIRET valide). Cette validation va au-delà de la conformité technique.

Outils de validation recommandés

• Validateur FNFE-MPE : l'outil officiel du Forum National de la Facture Électronique pour valider les fichiers Factur-X
• veraPDF : validateur open source de référence pour la conformité PDF/A
• Mustang Validator : inclus dans la bibliothèque Java Mustang, permet la validation programmatique
• Environnement de test PPF : simulez l'envoi de vos factures sur la plateforme de test du PPF pour vérifier leur acceptation

Prévoyez également des tests de bout en bout : envoyez des factures de test à travers votre PDP ou le PPF et vérifiez qu'elles sont correctement reçues et interprétées par le destinataire. Cette étape permet de détecter les problèmes d'interopérabilité qui ne sont pas visibles par la seule validation locale.

Une fois vos factures Factur-X générées et validées, la dernière étape consiste à les transmettre via une PDP ou le PPF. Voici comment connecter votre logiciel aux plateformes de transmission.

Connexion via API REST

Les PDP et le PPF proposent des API REST pour l'envoi automatisé des factures :

• Authentification : généralement via OAuth 2.0 ou certificat client. Votre PDP vous fournit les identifiants et la documentation technique.
• Envoi de facture : un appel POST avec le fichier Factur-X en pièce jointe et les métadonnées de routage (SIRET destinataire, plateforme du destinataire).
• Suivi des statuts : un appel GET pour récupérer le statut de chaque facture (déposée, transmise, reçue, acceptée, refusée).
• Réception : un endpoint de callback (webhook) ou un appel GET périodique pour récupérer les factures reçues de vos fournisseurs.

Modes de connexion alternatifs

Si l'intégration API n'est pas possible, d'autres modes de connexion existent :

• SFTP : dépôt et récupération de fichiers via un répertoire sécurisé. Adapté aux systèmes legacy.
• EDI (AS2/AS4) : pour les entreprises disposant déjà d'une infrastructure EDI.
• Portail web : dépôt manuel de fichiers sur l'interface web de votre PDP ou du PPF.

Gestion des statuts de facture

La réforme introduit un cycle de vie de la facture avec des statuts obligatoires que votre logiciel doit gérer :

• Déposée : la facture est envoyée à la plateforme de l'émetteur
• Transmise : la facture est transmise à la plateforme du destinataire
• Reçue : le destinataire a accusé réception
• Acceptée / Refusée : le destinataire a validé ou contesté la facture