Compliance — Riferimento approfondito

In breve

Il modulo Compliance raggruppa tre superfici indipendenti sotto NextPDF\Pro\Compliance:

• Reporting dei tag di lingua — una facciata di policy /Lang strict PDF/UA-2 più un reporter di eventi di conformità strutturato, in forma PSR-3.
• Gestione delle fatture elettroniche — validazione Factur-X 1.08 / ZUGFeRD 2.4 rispetto al modello semantico EN 16931 ed emissione ibrida PDF/A-3.
• Provenienza — incorporazione ed estrazione di manifest store C2PA forniti dal chiamante tramite un parser JUMBF rafforzato contro gli attacchi; la sintesi dei claim resta in preview.

Il modulo riporta ciò che verifica. Non certifica i documenti e non esegue la firma crittografica.

Disponibilità e licenze

Questa funzionalità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un license envelope di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Non esiste alcun flag di licenza per singola funzionalità. È una funzionalità dell’edizione Pro. Il generatore sperimentale di claim C2PA richiede inoltre un opt-in esplicito tramite ambiente (vedere Casi limite e modalità di errore).

Superficie API pubblica

composer require nextpdf/pro:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
LangComplianceReporter::warn() / ::error()	string $tag, string $reason, ?string $clauseReference = null	Emette un record JSON strutturato per ogni evento di tag di lingua tramite il logger PSR-3	void	JsonException se il record fallisce la codifica JSON	warn = rifiuto in modalità lax; error = rifiuto in modalità strict
LangComplianceReporter::reportException()	InvalidBcp47TagException $exception, string $severity = 'error'	Estrae tag e ragione dall’eccezione; delega a warn() o error()	void	Come sopra	Percorso di comodità
LangComplianceReporter::buildRecord()	string $severity, string $tag, string $reason, ?string $clauseReference = null	Costruisce l’array del record senza registrare	array	Non solleva eccezioni	Per sink personalizzati come riepiloghi JSON per file
ConformancePolicy::default()	?LoggerInterface $logger = null	Policy strict UA-2: i tag /Lang malformati o non registrati vengono rifiutati	self	Non solleva eccezioni	Il valore predefinito v5.0 è strict
ConformancePolicy::fromCore()	CoreConformancePolicy $core, ?LoggerInterface $logger = null	Avvolge una policy Core esistente così com’è; nessun asse invertito	self	Non solleva eccezioni	Preferire default() per la postura strict
ConformancePolicy::withStrictUa2()	bool $enabled	Restituisce una copia con l’asse strict impostato; la disattivazione emette un notice PSR-3	self	Non solleva eccezioni	Opt-out deprecato; rimozione prevista in 6.0.0
ConformancePolicy::isStrictUa2() / ::mode()	—	Legge la policy Core sottostante	bool / ConformanceMode	Non solleva eccezioni	—
EInvoiceValidator::validate()	string $pdfPath	Pipeline completa: controllo del wrapper PDF/A-3, estrazione degli allegati, rilevamento del profilo, regole EN 16931, Schematron	EInvoiceValidationResult	Sottoclasse di EInvoiceException in caso di errore di I/O, struttura PDF malformata o crash degli strumenti	Interfaccia SPI congelata; un PDF non-fattura-elettronica ben formato restituisce un risultato, non solleva mai eccezioni
EInvoiceXmlValidator::validate()	string $xmlPayload, ValidatorContext $context	Pre-flight strutturale più il corpus di regole semantiche approfondite EN 16931 su un payload CII	contratto ValidationResult	Non solleva eccezioni per input non valido; il rifiuto emerge come risultato fallito con findings	Validatore concreto cross-tier; input filtrato tramite XmlGuard
EInvoiceValidationResult::isValid()	—	Vero solo quando wrapper, specifica dell’allegato, profilo e sintassi reggono e non esiste alcuna violazione FATAL	bool	Non solleva eccezioni	Un elenco di violazioni vuoto da solo non equivale alla validità
EInvoiceValidationResult::notAnEInvoice()	—	Risultato deterministico tutto-null, tutto-false	self	Non solleva eccezioni	Factory per il caso «non è una fattura ibrida»
EInvoiceProfile	enum con backing stringa	Casi MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, con backing di URN BT-24	—	—	isEn16931Conformant() è false per MINIMUM e BASIC_WL
EInvoiceSyntax	enum con backing stringa	Casi UN_CEFACT_CII, UBL_INVOICE, UBL_CREDIT_NOTE	—	—	Solo CII è isFacturXEligible(); UBL è solo per la validazione
BusinessRuleViolation	string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null	DTO di violazione immutabile	—	—	Famiglie di rule-id BR-, BR-CO-, BR-CL-, BR-DEC-, BR-FXEXT-
BusinessRuleSeverity	enum con backing stringa	FATAL invalida la fattura; WARNING segnala un problema di qualità	—	—	Rispecchia i livelli Schematron di EN 16931
FacturXEmbedder::embed()	vedere il blocco della firma	Aggiunge stream di file incorporato, filespec e XMP a un sorgente PDF/A; riscrive la xref	void	EInvoiceException in caso di XML malformato, sorgente illeggibile, catalogo mancante, sorgente con object stream o xref stream, o errore di scrittura dell’output	Il file sorgente resta intatto
FacturXEmbedderOptions::default()	—	/AFRelationship /Alternative, nome file factur-x.xml, tipo INVOICE, versione 1.0	self	Non solleva eccezioni	I valori predefiniti soddisfano il mandato tedesco e restano accettati in Francia
FacturXEmbedderOptions::withRelationship() / ::withFilename()	string	Restituisce una copia con l’override applicato	self	InvalidArgumentException fuori dagli insiemi di accettazione	Relazioni: Source, Data, Alternative; i nomi file includono zugferd-invoice.xml e xrechnung.xml
FacturXEmbedderOptions::withDocumentType()	string $documentType	Restituisce una copia con l’override del tipo di documento XMP	self	Non solleva eccezioni	I valori non sono enumerati in modo difensivo
FacturXContractEmbedder::embed()	string $pdfBytes, string $xmlPayload, EmbedderOptions $options	Adattatore byte-in, byte-out su FacturXEmbedder tramite file temporanei di breve durata	string	EInvoiceException; il profilo XRECHNUNG viene rifiutato in quanto solo Enterprise	Implementazione cross-tier di EmbedderInterface
C2paManifestEmbedder::embed()	string $pdfBytes, ManifestStore $store	Incorpora la serializzazione in byte dello store nella posizione del profilo	string	C2paException in caso di qualsiasi errore di incorporazione	Interfaccia SPI congelata; solo byte, nessun I/O
C2paManifestEmbedder::extract()	string $pdfBytes	Analizza uno store incorporato tramite il parser JUMBF rafforzato	ManifestStore|null	Sottoclasse di C2paException quando uno store è presente ma viola un limite di rafforzamento	Null indica l’assenza; l’assenza non solleva mai eccezioni
ManifestStore::fromBoxes() / ::empty()	list<JumbfBox> / —	Costruisce il value object immutabile dello store	self	Non solleva eccezioni	L’ordine dei box è determinante per l’uguaglianza in round-trip
ManifestStore::toBytes() / ::isEmpty() / ::size()	—	Serializza i box radice; uno store vuoto si serializza in una stringa vuota	string / bool / int	Non solleva eccezioni	—
JumbfBoxParser::parse()	string $bytes	Analizza i box JUMBF di livello radice sotto limiti rigidi	list<JumbfBox>	MalformedJumbfException, JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException	Limiti: profondità 8, 64 MiB per box, 128 MiB totali, MAX_CHILDREN_PER_SUPERBOX 4096
JumbfBox::superbox() / ::leaf()	string $tbox, …	Costruisce un box validato; toBytes() fa round-trip attraverso il parser	self	MalformedJumbfException quando il TBox non è esattamente di 4 byte	—
C2paCapabilityStatus::current() / ::summary()	—	Riporta la maturità della funzionalità C2PA, attualmente preview-draft	self / string	Non solleva eccezioni	Marcatore di preview verificabile dalla macchina
Feature::PREVIEW_C2PA_DRAFT->isEnabled()	—	Legge l’ambiente del processo a ogni chiamata; solo il letterale '1' abilita	bool	Non solleva eccezioni	Variabile d’ambiente NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT
ExperimentalC2paEmbedder::buildManifestStore()	string $sourceBytes, string $producer	Costruisce un manifest store ancorato alla draft con una singola asserzione di claim con hash-binding SHA-256	ManifestStore	Il costruttore solleva LogicException quando il flag di preview è disattivato	Preview; formato wire ancorato a uno snapshot draft; nessuna firma del claim emessa

Firme dei punti d’ingresso, verbatim:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

Contratto di comportamento

Reporting dei tag di lingua. LangComplianceReporter emette un record JSON strutturato per ogni evento di tag di lingua PDF/UA-2. Ogni record porta con sé il discriminatore di evento fisso, una severità (warn per un rifiuto in modalità lax, error per un rifiuto in modalità strict), il tag incriminato verbatim, una ragione leggibile dalla macchina, i componenti del tag analizzato (oppure null quando il tag non soddisfa la grammatica di forma RFC 5646), un riferimento alla clausola §8.4.4 della ISO 14289-2 e un timestamp UTC con microsecondi. Il JSON viaggia come corpo del messaggio PSR-3; i sink a valle analizzano direttamente il campo del messaggio. ConformancePolicy è la facciata Premium sopra la policy di conformità Core. Il suo valore predefinito applica la gestione strict della lingua UA-2 e rifiuta un tag malformato o non registrato che raggiunge /Lang. L’helper di opt-out withStrictUa2(false) ripristina il comportamento lax legacy e registra un notice PSR-3 quando il valore effettivo cambia davvero. NextPDF contrassegna quell’helper come deprecato dalla v5.0 con rimozione prevista in 6.0.0. Per migrare: verificare il corpus alla ricerca di valori /Lang malformati con composer pdfua2:audit-lang-tags <pdf-or-dir>, correggerli, quindi rimuovere la chiamata di opt-out.

Gestione delle fatture elettroniche. EInvoiceValidator è il contratto SPI congelato per la validazione dei PDF ibridi: controllo del wrapper PDF/A-3, estrazione degli allegati /AF, rilevamento del profilo dall’identificatore di specifica BT-24, il motore di regole di business EN 16931 e una passata Schematron. Un PDF non-Factur-X ben formato restituisce EInvoiceValidationResult::notAnEInvoice() anziché sollevare un’eccezione; solo gli errori di I/O, una struttura PDF malformata o i crash degli strumenti sollevano una sottoclasse di EInvoiceException. EInvoiceXmlValidator è il validatore XML concreto cross-tier: filtra l’input tramite il XmlGuard di Core, esegue il pre-flight strutturale e il corpus di regole semantiche approfondite EN 16931, e fallisce in modo chiuso — gli errori del motore emergono come findings di errore, mai come passaggi silenziosi. FacturXEmbedder modifica un sorgente PDF/A in un PDF/A-3 ibrido: aggiunge uno stream di file incorporato, una filespec con un /AFRelationship configurabile e un packet di estensione XMP Factur-X, quindi riscrive la tabella di riferimenti incrociati classica. Sia l’array /AF del catalogo sia il name tree /Names /EmbeddedFiles referenziano l’allegato, così i lettori ZUGFeRD legacy lo risolvono.

Provenienza. C2paManifestEmbedder incorpora un manifest store C2PA fornito dal chiamante in una stringa di byte PDF, oppure ne estrae uno. ManifestStore è il value object immutabile che attraversa il confine. La giuntura è solo byte e vendor-neutral: non sintetizza claim, non ingerisce riferimenti URI né risolve binding di hash, e non esegue alcun I/O di rete o di filesystem. extract() restituisce null in caso di assenza ed è economico sui PDF privi di store. Ogni estrazione non-null ha già superato i limiti di rafforzamento di JumbfBoxParser.

Questo modulo riporta ciò che verifica. Non certifica un documento, non lo rende giuridicamente vincolante e non garantisce che alcun output soddisfi una normativa. Il validatore di fatture elettroniche non è un validatore dell’autorità fiscale ed esclude le estensioni nazionali (per esempio l’SDI italiano, il Chorus Pro francese, lo XRechnung tedesco). Come afferma EN 16931-1, l’emittente della fattura resta responsabile del rispetto delle regole della legislazione pertinente. Il supporto di uno standard non equivale alla conformità ad esso. Rivolgersi al proprio team di conformità per la sufficienza normativa.

Casi limite e modalità di errore

• Un PDF non-Factur-X ben formato restituisce un risultato «non è una fattura elettronica»; non solleva un’eccezione.
• Un elenco vuoto di violazioni di regole di business non significa di per sé che il documento sia valido; si applicano anche i controlli sul wrapper e sugli allegati.
• FacturXEmbedder fallisce in modo chiuso su sorgenti che usano object stream compressi (/Type /ObjStm) o stream di riferimenti incrociati (/Type /XRef, /XRefStm ibrido). Risalvare prima tali sorgenti con una tabella di riferimenti incrociati classica.
• I payload XML sono filtrati tramite il XmlGuard di Core: dichiarazioni DOCTYPE o di entità, input sovradimensionato e UTF-8 non valido vengono rifiutati con un EInvoiceException sul percorso di incorporazione, o con un risultato fallito sul percorso di validazione.
• FacturXContractEmbedder rifiuta il profilo XRECHNUNG in modo esplicito anziché declassarlo silenziosamente; l’emissione XRechnung è una funzionalità Enterprise.
• C2paManifestEmbedder::extract() distingue l’assenza (null) dalla malformazione (una sottoclasse di C2paException che nomina l’invariante violato: struttura malformata, bomb di dimensione o conteggio, ciclo di offset, profondità di annidamento).
• La costruzione di ExperimentalC2paEmbedder solleva un LogicException a meno che il flag di ambiente di preview non sia uguale a '1'. Il suo formato wire è ancorato a uno snapshot draft C2PA e può cambiare senza preavviso; non emette alcuna firma del claim. Questa funzionalità resta in preview finché il profilo PDF C2PA non si congela.
• L’opt-out lax strict UA-2 è deprecato; migrare al valore predefinito strict (vedere Contratto di comportamento).
• Questo modulo non esegue la firma crittografica. La firma dei claim C2PA e la custodia delle chiavi sono fuori ambito; vedere il modulo Security per il comportamento di firma in modalità FIPS.

Conformità

Comportamento	Riferimento	Stato
Dichiarazione della lingua naturale (/Lang)	ISO 14289-2:2024 §8.4.4	Verificato / riportato
Modello semantico della fattura core	EN 16931-1:2026	Verificato (l’emittente resta responsabile)
File associati / stream di file incorporati	ISO 32000-2:2020 §14.13.2	Emesso (/AF, /EF, /Params)
Relazione dell’allegato e regole del container	Factur-X 1.08 §3.1, §6.2	Emesso / verificato (default /AFRelationship /Alternative)
Manifest store C2PA / JUMBF	C2PA 2.1 §11.1	Incorporazione / estrazione supportate; sintesi dei claim in preview

Questo registra le specifiche rispetto a cui il modulo è realizzato e ciò che verifica o emette. Non costituisce una dichiarazione di certificazione o di sufficienza normativa. NextPDF non detiene alcuna certificazione per questi standard.

Note di sviluppo

• La forma del record del reporter è un contratto stabile; le regole di alerting a valle possono ancorarsi al discriminatore di evento fisso.
• La disattivazione di strict UA-2 emette un notice di deprecazione visibile in telemetria solo quando il valore effettivo cambia; riasserire il valore corrente è silenzioso.
• L’embedder Factur-X preserva i byte sorgente verbatim e aggiunge nuovi oggetti; mira a preservare la conformità PDF/A-3 ma non riesegue la validazione. Far passare l’output attraverso un validatore PDF/A esterno per un’attestazione solida.
• La giuntura C2PA congela cinque invarianti: nessun import di terze parti, contratto solo byte, nessun I/O, estrazione null-on-miss e nessuna sintesi di claim nel layer stabile.
• I limiti di JumbfBoxParser sono costanti pubbliche; dimensionare gli input che si accettano rispetto ad essi anziché riderivare i limiti.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi file dei runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Guida alla funzionalità Compliance
• Anteprima C2PA
• Security — Riferimento approfondito
• Specifiche