Enterprise édition

Facture — référence détaillée

En bref

Le module Invoice comporte trois surfaces indépendantes : l’intégration, la validation et l’exécution des règles Schematron. ZugferdEmbedder et PeppolEmbedder attachent le XML de facture fourni par l’appelant à un support PDF/A-4f ou PDF/A-3b et renvoient un résultat structuré. InvoiceXmlValidator effectue un contrôle préalable structurel EN 16931 avec une sévérité au choix, COMPAT ou STRICT. SchematronValidator exécute des jeux de règles Schematron précompilés au sein du processus et analyse les constats SVRL. NextPDF ne génère pas le XML de facture ; l’appelant fournit et détient la charge utile.

Disponibilité et licence

Cette capacité est fournie avec NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Nuance par niveau : la détection et la validation des factures électroniques relèvent du niveau Pro (module Pro Compliance). L’intégration des factures hybrides, le profil CIUS XRechnung et le moteur Schematron intégré au processus sont réservés à Enterprise. Il n’existe aucun code de capacité distinct par fonctionnalité au-delà de la limite du paquet nextpdf/enterprise.

Surface de l’API publique

composer require nextpdf/enterprise:^3

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Intègre du XML CII de profil BASIC : passe XmlGuard, validation structurelle, injection du schéma XMP, attachement	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Chemin rapide ; point de départ recommandé
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Même pipeline au profil MINIMUM	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Chemin rapide
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Entrée du constructeur ; rejette un XML vide	`self`	`InvalidArgumentException`	Se configure via `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Remplace la relation `/Alternative` par défaut ; encadré par le référentiel de règles des fichiers associés	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` rejetés pour les factures
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Appel terminal du constructeur : XmlGuard, validation facultative, contrôle du support, XMP, attachement	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Un échec de validation nomme la première erreur
`ZugferdProfile` (enum)	—	Cas MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG attache `xrechnung.xml` ; les profils CII attachent `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Enregistre la description RDF Factur-X et l’entrée de schéma d’extension PDF/A	`XmpMetadata`	Aucune	Appelée par `embed()` ; utilisable aussi directement
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Intègre le XML UBL Peppol BIS 3.0 d’une facture ou d’un avoir	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Noms de fichiers par défaut `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Entrée du constructeur ; rejette un XML ou un nom de fichier vide	`self`	`InvalidArgumentException`	Se configure via `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Passe XmlGuard, contrôle du support, filtrage par le référentiel de règles, attachement	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Nouvelle vérification du référentiel tenant compte du support au moment de l’intégration
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	Contrôle préalable structurel EN 16931 ; sévérité COMPAT par défaut	`InvoiceValidationResult`	Ne lève pas ; les échecs apparaissent comme des constats d’erreur	Le mode se résout par l’argument, puis l’environnement, puis COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Contrôle de l’élément racine et de l’espace de noms pour les charges CII	`bool`	Ne lève pas ; renvoie `false`	Sonde de détection peu coûteuse
`InvoiceValidatorMode` (enum)	—	`COMPAT` (par défaut) maintient les constats BT-24 en avertissement ; `STRICT` les élève au rang d’erreur	—	—	`fromEnvironment()` retombe sur COMPAT en cas de valeur absente ou non reconnue
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Agrégats immuables : `isValid`, `getErrors()`, `getWarnings()` ; niveau, code, message par constat	—	—	`InvoiceValidationResult::fail()` encapsule une erreur unique
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Exécute un XSLT Schematron précompilé ; analyse le SVRL en constats	`SchematronResult`	`InvalidArgumentException` pour un XSLT manquant ou illisible ; les défaillances du moteur renvoient un résultat d’erreur	Durée mesurée dans `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Adaptateur inter-niveaux ; mappe les constats d’erreur vers des objets `RuleViolation` du contrat	`list<RuleViolation>`	Identique à `validate()`	Les constats de niveau info sont ignorés
`SchematronResult` / `SchematronFinding`	—	Verdict, constats, durée ; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` marque les défaillances du moteur comme invalides
`SchematronCacheInterface`	—	Contrat de cache à détection d’altération : `getVerified()`, `set()`, `computeKey()`	—	—	Échoue en mode fermé en cas d’empreinte non concordante
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	Cache de fichiers vérifié en SHA-256 avec écritures par renommage atomique	—	`InvalidArgumentException`, `SchematronCacheException`	Le répertoire doit exister ou pouvoir être créé, et être accessible en écriture
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	Épingles de jeux de règles verrouillées en SHA-256 : `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` en cas de JSON de verrou mal formé	Des empreintes vides ou mal formées échouent en mode fermé
`InvoiceContractValidator`	`?SemanticValidator`	Adaptateur `ValidatorInterface` inter-niveaux ; contrôle préalable structurel plus règles sémantiques approfondies EN 16931	`ContractResult`	Échoue en mode fermé ; les erreurs du moteur apparaissent comme des constats d’erreur	Lié sur les chemins du framework lorsque `nextpdf/premium` est installé
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Adaptateur `EmbedderInterface` inter-niveaux ; intégration octets en entrée / octets en sortie	`string` (octets PDF)	Propage les défaillances du délégué	Délègue au moteur de réécriture d’octets de niveau Pro
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Taxonomie des défaillances du module	—	—	Toutes étendent `RuntimeException`

public static function basic(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $xmlData,
): ZugferdEmbedResult

public function embed(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
): ZugferdEmbedResult

public static function invoice(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $ublXml,
): PeppolEmbedResult

public static function validate(
    string $xmlData,
    ZugferdProfile $profile,
    ?InvoiceValidatorMode $mode = null,
): InvoiceValidationResult

public function validate(string $xsltPath, string $xmlData): SchematronResult

Contrat de comportement

Intégration. ZugferdEmbedder attache une charge utile XML CII UN/CEFACT ZUGFeRD 2.4 / Factur-X 1.08 fournie par l’appelant à un support PDF/A. Il prend en charge deux supports : PDF/A-4f (ISO 19005-4:2020), le support moderne à privilégier, et PDF/A-3b (ISO 19005-3:2012) pour la rétrocompatibilité. embed() exécute toujours d’abord une passe de sécurité XmlGuard, puis la validation structurelle sauf si withoutValidation() a été défini, puis vérifie que le support prend en charge les fichiers intégrés, injecte la déclaration de schéma d’extension XMP via ZugferdXmpSchema et attache le XML en tant que fichier associé. La relation d’attachement vaut par défaut la recommandation du référentiel /Alternative ; les remplacements passent par le même référentiel, qui impose l’ensemble de relations ISO 32000-2:2020 §14.13 et le sous-ensemble de facture EN 16931. PeppolEmbedder réalise l’équivalent pour le XML UBL 2.1 Peppol BIS Billing 3.0 de facture ou d’avoir fourni par l’appelant. Aucun des deux intégrateurs ne génère de XML de facture.

Validation. InvoiceXmlValidator contrôle le XML CII au regard des attentes structurelles EN 16931 : élément racine, sections obligatoires, cardinalité de l’en-tête, lignes lorsque le profil les exige et l’identifiant de spécification BT-24 imposé par la règle métier BR-1. InvoiceValidatorMode sélectionne la sévérité. COMPAT (par défaut) signale un BT-24 manquant ou non concordant comme un avertissement, afin qu’un contrôle de validité booléen ne régresse pas. STRICT en fait dans les deux cas une erreur bloquante et vérifie en outre la cohérence du profil au regard du ZugferdProfile déclaré, reproduisant la sémantique des validateurs externes KoSIT / Mustang. Le mode se résout dans cet ordre : argument explicite, puis la substitution d’environnement INVOICE_VALIDATOR_MODE, puis COMPAT. Les résultats sont des objets structurés InvoiceValidationResult / InvoiceValidationFinding ; le validateur renvoie des constats plutôt que de lever une exception.

Schematron. SchematronValidator exécute des jeux de règles Schematron précompilés — les règles CEN EN 16931 .sch compilées en XSLT à la construction — à l’aide du processeur XSLT PHP intégré au processus. Il analyse le rapport SVRL en objets SchematronFinding / SchematronResult : les assertions en échec deviennent des constats d’erreur, les rapports réussis deviennent des constats d’information. Un cache facultatif (SchematronCacheInterface, avec l’implémentation fichier par renommage atomique) sert des octets de feuille de style vérifiés, indexés par l’empreinte du contenu et la version du compilateur. VersionPinRegistry épingle chaque jeu de règles externe à une version verrouillée en SHA-256 et échoue en mode fermé en cas de dérive ou d’empreintes mal formées.

Ce module produit et contrôle des données de facture structurées. Il n’affirme pas qu’un document est une facture légalement conforme, qu’il est approuvé par l’administration fiscale ou que son acceptation est garantie par une quelconque autorité. Le validateur contrôle uniquement le modèle sémantique EN 16931 et le conteneur ZUGFeRD / Factur-X / UBL ; il exclut les extensions nationales (par exemple le SDI italien, Chorus Pro français, le transport XRechnung allemand). Comme l’énonce EN 16931-1, l’émetteur de la facture est responsable du respect des règles de la législation applicable ; ce n’est pas un validateur de l’administration fiscale. La prise en charge d’une norme n’équivaut pas à sa conformité.

Cas limites et modes de défaillance

Un XML vide échoue immédiatement : les constructeurs lèvent InvalidArgumentException ; InvoiceXmlValidator::validate() renvoie un résultat en échec.
XmlGuard rejette les déclarations DOCTYPE, l’expansion d’entités, les charges surdimensionnées et les caractères de contrôle. Les intégrateurs le remontent sous forme de ZugferdEmbeddingException ou PeppolEmbeddingException, la cause étant préservée.
withoutValidation() et withoutSanitization() ne contournent jamais la passe de sécurité XmlGuard. Seuls les contrôles structurels des termes métier peuvent être omis.
Un support sans prise en charge des fichiers intégrés (tout autre que PDF/A-4f ou PDF/A-3b) lève InvalidArgumentException en nommant les versions acceptées.
Une valeur AFRelationship non autorisée est rejetée à la limite du constructeur ; une nouvelle vérification du référentiel tenant compte du support s’exécute de nouveau dans embed().
COMPAT maintient un BT-24 manquant à la sévérité avertissement ; STRICT transforme les BT-24 manquants ou non concordants avec le profil en erreurs bloquantes.
SchematronValidator ne lève une exception que pour un chemin XSLT manquant ou illisible. Les échecs de transformation ou d’analyse SVRL renvoient SchematronResult::error() avec isValid à faux.
Une entrée de cache dont les octets stockés échouent à la vérification d’empreinte est évincée et la feuille de style est relue depuis le disque ; des octets corrompus ne sont jamais renvoyés.
Le processeur XSLT s’exécute avec le chargement de ressources fichier et réseau bloqué et n’enregistre jamais de fonctions PHP ; document(), xsl:include, xsl:import et result-document ne peuvent charger aucune ressource.
VersionPinRegistry rejette les empreintes SHA-256 vides ou mal formées à l’ingestion et à la régénération ; verifyArtefact() renvoie faux plutôt que de laisser passer une épingle non vérifiable.
Ce module n’effectue aucune signature cryptographique ; le comportement en mode FIPS est hors périmètre ici (voir le module Signature).

Conformité

Comportement	Référence	Statut
Modèle sémantique de base de la facture	EN 16931-1:2026 §4	Développé selon ; l’émetteur demeure responsable
Identifiant de spécification (BT-24)	EN 16931-1:2026 BR-1	Avertissement en COMPAT, erreur en STRICT
Liaison de syntaxe UN/CEFACT CII	CEN/TS 16931-3-3:2020	Intégration prise en charge
Liaison de syntaxe UBL 2.1	CEN/TS 16931-3-2:2020	Intégration prise en charge
Fichier associé PDF/A-3	ISO 19005-3:2012 §6.7.8	Support pris en charge
Fichier intégré PDF/A-4f	ISO 19005-4:2020 Annex A	Support pris en charge
Valeurs de relation des fichiers associés	ISO 32000-2:2020 §14.13	Encadré par le référentiel
Analyse du rapport Schematron / SVRL	ISO/IEC 19757-3	Développé selon (fondé sur le produit ; norme absente du corpus de citations)

Développé selon, sans certification ni approbation par l’administration fiscale. NextPDF ne détient aucune certification pour l’une de ces normes. NextPDF produit des factures structurées conformes au modèle de données EN 16931 et rapporte des constats de règles ; il ne produit pas de factures légalement conformes, ne fournit pas de sortie approuvée par l’administration fiscale et ne garantit pas leur acceptation. Consulte tes conseillers fiscaux et juridiques.

Notes de développement

Le moteur Schematron requiert l’extension PHP ext-xsl ; son approvisionnement et son activation relèvent de la responsabilité de l’exploitant.
Le traitement est intégré au processus et local. Aucun appel réseau sortant n’a lieu pendant l’intégration ou la validation. Le transport national de facturation électronique, les plateformes de clearance et les systèmes d’archivage sont externes à ce module.
Les jeux de règles sont compilés de .sch vers XSLT à la construction ; l’exécution ne fait tourner que des feuilles de style précompilées.
Les clés de cache incorporent le sel de version du compilateur (actuellement nextpdf-schxslt-1.0) ; son incrémentation invalide les caches déployés sans étape de purge.
Les épingles de jeux de règles résident dans le fichier de verrou enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH) ; la CI vérifie les artefacts déployés au regard des empreintes épinglées.
Les appelants inter-niveaux utilisent InvoiceContractValidator et ZugferdContractEmbedder ; les appelants Enterprise natifs du niveau utilisent directement ZugferdEmbedder et InvoiceXmlValidator.

Limite de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

Capacité Invoice — le pendant de cette référence, côté capacité.
Pro Compliance — détection/validation de niveau Pro.
Dépôt électronique de documents
Vue d’ensemble Enterprise