Documentation et premiers pas

Démarrage rapide

Du PDF au verdict de conformité en trois étapes. L’exemple ci-dessous reprend le déroulement réel utilisé par la démo en ligne.

1. Ajouter le package Facturexa.ZugferdValidator via NuGet. Les référentiels officiels (schéma XML et Schematron) sont fournis et trouvés automatiquement.
2. Enregistrer la clé de licence une fois au démarrage de l’application. Vous la recevez par e-mail et la retrouvez à tout moment dans votre compte client.
3. Pour chaque facture, valider le PDF (ou le XML) en un seul appel.

using Facturexa.ZugferdValidator;

// Une fois au démarrage : enregistrer la clé de licence.
ZugferdValidatorLicense.RegisterLicense("…");

// Valider la facture PDF : enveloppe PDF, schéma XML et Schematron officiel en un seul appel.
var result = ZugferdValidator.Validate("facture.pdf", "FA-2026-0001");

Console.WriteLine(result.IsValid ? "Valide" : "Non conforme");

Le déroulement complet avec gestion des erreurs figure dans la section Validator.

Installation et prérequis

Chaque bibliothèque est un package NuGet autonome et peut être intégrée séparément.

Déploiement des référentiels (Validator)

• Fonctionnement hors ligne : tous les référentiels (schéma XML, Schematron, listes de codes) sont inclus dans le package. Aucune connexion Internet n’est nécessaire à l’exécution et le Validator n’appelle aucun service externe – la vérification de licence est également locale. Aucune règle de pare-feu n’est requise.
• Le package copie automatiquement Official Schematron\ (les règles Schematron et, sous XSD\, le schéma XML) à côté de votre application lors de la compilation et de la publication – y compris pour ASP.NET classique (sous bin\), le fichier unique (single-file), ClickOnce et lorsque vous intégrez le Validator via votre propre bibliothèque ou votre propre package NuGet.
• Après une rétrogradation du package, nettoyer ou régénérer une fois la solution afin que les fichiers de référentiel plus anciens remplacent les plus récents dans le dossier de sortie.
• Fournir le dossier vous-même : définir <FacturexaContentAutoCopy>false</FacturexaContentAutoCopy> dans le projet, avec PackageReference ajouter ExcludeAssets="contentFiles" à la référence du package, et définir SchematronChecker.SchematronDirectory sur ce dossier.

Profils et versions

Factur-X/ZUGFeRD définit plusieurs profils avec des niveaux de détail différents. Le tableau ci-dessous indique ceux que le Validator contrôle et que le Creator génère.

Version

Le Creator écrit toujours selon la spécification en vigueur : Factur-X 1.09.2 / ZUGFeRD 2.5.2 (applicable à partir du 1^er septembre 2026), y compris les sous-lignes EXTENDED pour les kits et les lots. Vous ne choisissez pas de version dans Save(…) – les nouvelles spécifications arrivent avec une nouvelle version du package.

La spécification implémentée par la DLL intégrée peut être interrogée à l’exécution : ZugferdCreatorInfo.SupportedSpecification.

Validator : valider un PDF

Enregistrez la clé de licence une fois au démarrage de l’application. Le Validator trouve automatiquement les référentiels officiels à côté de la DLL (sous bin\ pour ASP.NET classique) ; ensuite, un appel par validation suffit. Passez le PDF complet : le Validator extrait lui-même le XML embarqué, contrôle l’enveloppe PDF (PDF/A-3, métadonnées Factur-X), puis valide le XML selon le schéma XML et le Schematron officiel. Un fichier XML seul fonctionne de la même façon – la détection se fait sur le contenu, pas sur l’extension. IsValid est vrai si aucune étape ne signale d’erreur ; IsPdfValid et IsSchemaValid donnent les verdicts partiels.

using Facturexa.ZugferdValidator;

// Une fois au démarrage de l’application.
ZugferdValidatorLicense.RegisterLicense("…");

// PDF ou XML : enveloppe PDF, schéma XML et Schematron officiel en un seul appel.
var result = ZugferdValidator.Validate("facture.pdf", "FA-2026-0001");

Console.WriteLine(result.IsValid ? "Valide" : "Non conforme");
Console.WriteLine($"Enveloppe PDF : {result.IsPdfValid}"); // null pour un XML seul
Console.WriteLine($"Référentiel : {result.SchematronRuleSet}");

foreach (var error in result.Errors)
    Console.WriteLine($"{error.Stage}: {error}"); // p. ex. "Schematron: BR-CO-15 (BT-112): ..."

Pour aller plus loin : page produit Validator · essayer la démo

Creator : créer une facture

Enregistrer la clé de licence une fois au démarrage, puis renseigner l’en-tête, les parties, les lignes et les totaux, choisir un profil et enregistrer. La sortie est actuellement en CII (UBL est prévu).

using Facturexa.ZugferdCreator;

// Une fois au démarrage de l’application.
ZugferdCreatorLicense.RegisterLicense("…");

var invoice = new EInvoice
{
    InvoiceNumber = "FA-2026-0001",
    InvoiceDate = DateTime.Today
};

invoice.SetSellerTradeParty("Exemple SAS", "75001", "Paris", "1 rue de l’Exemple", CountryID.FR);
invoice.AddSellerSpecifiedTaxRegistration("FR12345678901", TaxRegistrationSchemeID.VA);
invoice.SetBuyerTradeParty("Client SARL", "69002", "Lyon", "2 place du Client", CountryID.FR);

invoice.AddIncludedSupplyChainTradeLineItem(
    name: "Prestation de conseil", netUnitPrice: 100.00m, unitCode: UnitCode.C62,
    billedQuantity: 3m, lineTotalAmount: 300.00m, taxPercent: 20m);

invoice.AddApplicableTradeTax(300.00m, 20m, 60.00m, TaxTypeCode.VAT, TaxCategoryCode.S);

invoice.LineTotalAmount = 300.00m;
invoice.TaxBasisAmount = 300.00m;
invoice.TaxTotalAmount = 60.00m;
invoice.GrandTotalAmount = 360.00m;
invoice.DuePayableAmount = 360.00m;

using var xmlStream = new MemoryStream();
invoice.Save(xmlStream, InvoiceProfile.Comfort);

Pour aller plus loin : page produit Creator · essayer la démo

Reader : lire une facture

Le Reader lit une facture – XML seul (CII ou UBL) ou PDF avec XML embarqué ; le format est détecté automatiquement – et renvoie les champs sous forme d’objet. Il peut aussi en générer une vue PDF lisible.

using Facturexa.ZugferdReader;

// Lire un PDF ou un XML – le nom de fichier aide à détecter le format.
using var stream = File.OpenRead("facture.pdf");
var invoice = ZugferdReader.Read(stream, "facture.pdf");

Console.WriteLine(invoice.InvoiceNumber);
Console.WriteLine(invoice.InvoiceDate?.ToString("dd/MM/yyyy"));
Console.WriteLine(invoice.Seller?.Name);
Console.WriteLine($"{invoice.LineItems.Count} ligne(s), {invoice.GrandTotalAmount:N2} {invoice.CurrencyCode}");

// Facultatif : générer une vue PDF lisible de la facture.
byte[] viewPdf = ZugferdReader.CreatePdf(invoice);
File.WriteAllBytes("facture-vue.pdf", viewPdf);

Pour aller plus loin : page produit Reader · essayer la démo

Valeurs de retour

Les principaux champs des objets résultat en un coup d’œil.

ZugferdValidationResult – Validator.Validate(…)

ZugferdPdfCheckResult – ZugferdValidationResult.PdfCheck

API précédente : ZugferdPdfReader.ReadZugferdXml(…) et ZugferdPdfValidator.Validate(…) continuent de fonctionner jusqu’à la version 8.0, mais sont marquées obsolètes depuis la 7.4.0. Passez plutôt le PDF directement à ZugferdValidator.Validate(…).

InvoiceViewModel – ZugferdReader.Read(…)

Gestion des erreurs et dépannage

Les pièges les plus fréquents lors de l’intégration et leur cause. Les messages des bibliothèques sont en anglais et cités tels quels.

Étapes suivantes