Conformità ZUGFeRD / Factur-X: profilo di fattura EN 16931 incorporato

In breve

Dichiarazione di delimitazione. NextPDF produce il profilo XML incorporato; la validità fiscale e legale è determinata dall’autorità ricevente, non dalla libreria.

ZUGFeRD / Factur-X è una fattura ibrida: un PDF leggibile da una persona (un substrato di archiviazione PDF/A-3) con un XML Cross-Industry-Invoice (CII) incorporato e leggibile dalla macchina, conforme al modello di dati semantico EN 16931. NextPDF Core fornisce il contratto dell’embedder (NextPDF\Contracts\EInvoice); il motore concreto Factur-X 1.08 è fornito nel pacchetto Premium nextpdf/pro. La libreria produce l’XML incorporato e la struttura dell’allegato PDF/A-3; un validatore EN 16931 / Schematron — o l’autorità fiscale ricevente — decide la validità fiscale.

Installazione

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core fornisce EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface e ValidationResult in NextPDF\Contracts\EInvoice. Il docblock dell’interfaccia lo indica esplicitamente: l’edizione Pro (motore di riscrittura dei byte Factur-X 1.08) e l’edizione Enterprise (builder PDF/A gestito) implementano questo contratto. Core da solo non incorpora una fattura — definisce il contratto byte-in/byte-out implementato dalle edizioni.

Panoramica concettuale

NextPDF\Contracts\EInvoice\ProfileType funge da discriminatore di conformità EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Il suo isEn16931Conformant() codifica direttamente la regola di EN 16931-1. MINIMUM e BASIC_WL non sono conformi a EN 16931 (non soddisfano la cardinalità dell’identificatore di specifica BT-24 e il requisito delle righe di dettaglio). BASIC, EN16931, EXTENDED, XRECHNUNG sono conformi a EN 16931.

Il contratto impone all’embedder (EmbedderInterface) di:

analizzare in modo sicuro contro XXE l’XML CII fornito tramite XmlGuard;
inserire lo schema di estensione XMP Factur-X per il profilo dichiarato;
allegare l’XML come file incorporato con la corretta AFRelationship (Data / Alternative), affinché il substrato di archiviazione PDF/A-3 (requisiti per i file incorporati §6.7.5 — chiavi F/UF) possa trasportarlo.

NextPDF genera questa struttura. Non afferma che la fattura sia fiscalmente valida; tale determinazione spetta all’autorità ricevente, in base alle regole di business EN 16931 §7 e a eventuali CIUS nazionali.

Superficie API

Simbolo	Effetto
`Contracts\EInvoice\EmbedderInterface`	Contratto byte-in/byte-out; lo implementano Pro/Enterprise.
`Contracts\EInvoice\ProfileType` (enum)	Discriminatore di profilo EN 16931.
`ProfileType::isEn16931Conformant(): bool`	False per MINIMUM/BASIC_WL; true per BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Contratto di convalida che restituisce un `ValidationResult` con le violazioni delle regole.

Esempio di codice — Avvio rapido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ProfileType;

// Core: choose and check the profile before delegating embedding to Pro.
$profile = ProfileType::EN16931;

if (!$profile->isEn16931Conformant()) {
    fwrite(STDERR, "Profile {$profile->value} is not EN 16931 conformant.\n");
    exit(1);
}

// The concrete embedder is provided by nextpdf/pro:
//   $embedder = /* the Factur-X embedder from nextpdf/pro; see the Premium docs */;
//   $pdfWithInvoice = $embedder->embed($basePdfBytes, $ciiXml, $options);
echo "Profile {$profile->value} selected (embedding requires nextpdf/pro).\n";

Esempio di codice — Produzione

La pipeline di produzione (edizione Pro) incorpora l’XML CII in una base PDF/A-3. Esegue quindi un validatore Schematron EN 16931 (o invia all’autorità ricevente). Considerare quel report come criterio decisivo. NextPDF genera l’XML incorporato e l’allegato PDF/A-3; il validatore/l’autorità decide la validità fiscale. Core da solo non può eseguire questa pipeline — nextpdf/pro è necessario per il motore embedder.

Casi limite e insidie

Core include solo i contratti. Senza nextpdf/pro non esiste alcun embedder concreto. Il codice chiamante deve dipendere dall’interfaccia e gestire in modo chiaro l’assenza dell’implementazione Pro.
MINIMUM / BASIC_WL non sono EN 16931. isEn16931Conformant() restituisce false per questi; non dichiarare una fattura EN 16931 quando li si utilizza.
Substrato PDF/A-3. L’XML incorporato viaggia in un contenitore di archiviazione PDF/A-3; devono essere presenti le chiavi del file incorporato F/UF (PDF/A §6.7.5).
L’XML viene analizzato in modo sicuro contro XXE. Il contratto richiede l’analisi tramite XmlGuard; un embedder personalizzato non deve introdurre una superficie esposta a XXE.
La validità non è il verdetto della libreria. Produrre un file Factur-X strutturalmente corretto non garantisce che l’autorità fiscale lo accetti.

Prestazioni

L’incorporamento riscrive il PDF per aggiungere l’allegato XML e lo schema di estensione XMP. Budget atteso: wall ≤ 1500 ms, picco ≤ 128 MB per una fattura tipica.

Note sulla sicurezza

L’XML incorporato viene analizzato in modo sicuro contro XXE tramite XmlGuard. L’XML della fattura contiene per sua natura informazioni di identificazione personale (PII) legate alla transazione commerciale (parti, importi) — è incorporato, non cifrato. La riservatezza della fattura è responsabilità dell’integratore.

Residenza dei dati e mitigazioni delle PII

L’XML della fattura contiene PII delle parti e dati finanziari. L’incorporamento avviene in-process; nessun dato lascia il processo durante l’incorporamento. La trasmissione a un’autorità ricevente esula dall’ambito ed è responsabilità dell’integratore in materia di residenza dei dati.

Telemetria sicura e pulizia dei log

Non registrare mai nei log l’XML CII o i byte del PDF incorporato — contengono le PII della fattura. Registrare nei log solo il nome del profilo e il verdetto strutturale.

Modello di minaccia

Un file Factur-X non è soggetto a controllo degli accessi. L’XML incorporato è leggibile da chiunque disponga del file. L’ibrido garantisce che la fattura sia leggibile dalla macchina, non la sua riservatezza né la sua accettazione fiscale.

Comportamento in modalità FIPS

L’incorporamento non esegue alcuna operazione crittografica. Una fattura Factur-X firmata è una questione distinta, relativa alla procedura di firma, e ne eredita la postura FIPS; questa pagina non formula alcuna affermazione sulla firma.

Conformità

Affermazione	Specifica	Clausola
Una fattura EN 16931 contiene i termini di business del modello di dati semantico.	EN 16931-1	§6.4
La conformità EN 16931 è regolata dalla cardinalità delle regole di business che una fattura conforme deve soddisfare.	EN 16931-1	§7
Il profilo Factur-X EN 16931 richiede la conformità alle regole di business del CII-XML.	Factur-X 1.08	profilo EN 16931
Il profilo Factur-X EN 16931 impone il contenuto obbligatorio della fattura.	Factur-X 1.08	profilo EN 16931
Factur-X è un ibrido: XML leggibile dalla macchina incorporato insieme al PDF leggibile da una persona.	Factur-X 1.08	Basic
L’XML incorporato viaggia in un substrato di archiviazione PDF/A (chiavi F/UF del file incorporato).	ISO 19005-4	§6.7.5

Le citazioni sono puntatori clause-id + reference_id nel corpus di verifica. Non viene riprodotto alcun testo delle norme; le clausole sono riassunte nelle parole di NextPDF.