Invoice — Riferimento approfondito

In breve

Il modulo Invoice presenta tre superfici indipendenti: incorporamento, convalida ed esecuzione delle regole Schematron. ZugferdEmbedder e PeppolEmbedder allegano l’XML di fattura fornito dal chiamante a un contenitore PDF/A-4f o PDF/A-3b e restituiscono un risultato strutturato. InvoiceXmlValidator esegue un pre-flight strutturale EN 16931 con severità selezionabile COMPAT o STRICT. SchematronValidator esegue in-process pacchetti di regole Schematron pre-compilati e analizza i findings SVRL. NextPDF non genera l’XML della fattura; il chiamante fornisce il payload e ne è proprietario.

Disponibilità e licenze

Questa capability è distribuita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza.

Dettaglio per tier: il rilevamento e la convalida delle fatture elettroniche sono la superficie di tier Pro (modulo Pro Compliance). L’incorporamento di fatture ibride, il profilo XRechnung CIUS e il motore Schematron in-process sono esclusivi di Enterprise. Non esiste alcun codice di capability separato per funzionalità oltre il confine del pacchetto nextpdf/enterprise.

Superficie API pubblica

composer require nextpdf/enterprise:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
ZugferdEmbedder::basic()	PdfAManager, FileAttachment, string $xmlData	Incorpora XML CII di profilo BASIC: pass XmlGuard, convalida strutturale, iniezione dello schema XMP, allegato	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Percorso rapido; punto di partenza consigliato
ZugferdEmbedder::minimum()	PdfAManager, FileAttachment, string $xmlData	Stessa pipeline al profilo MINIMUM	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Percorso rapido
ZugferdEmbedder::create()	ZugferdProfile, string $xmlData	Ingresso builder; rifiuta XML vuoto	self	InvalidArgumentException	Configurabile tramite withoutValidation(), withDescription()
ZugferdEmbedder::withAfRelationship() / PeppolEmbedder::withAfRelationship()	AFRelationship|string	Sovrascrive la relazione predefinita /Alternative; soggetta a gate dal rulebook dei file associati	self	InvalidArgumentException	Schema, EncryptedPayload, FormData rifiutati per le fatture
ZugferdEmbedder::embed()	PdfAManager, FileAttachment	Chiamata builder terminale: XmlGuard, convalida opzionale, verifica del contenitore, XMP, allegato	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Il fallimento della convalida nomina il primo errore
ZugferdProfile (enum)	—	Casi MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG allega xrechnung.xml; i profili CII allegano factur-x.xml
ZugferdXmpSchema::apply()	XmpMetadata, ZugferdProfile	Registra la descrizione RDF di Factur-X e la voce di extension-schema PDF/A	XmpMetadata	Nessuna	Chiamato da embed(); utilizzabile anche direttamente
PeppolEmbedder::invoice() / ::creditNote()	PdfAManager, FileAttachment, string $ublXml	Incorpora l’XML di fattura o nota di credito Peppol BIS 3.0 UBL	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Nomi di file predefiniti invoice.xml / creditnote.xml
PeppolEmbedder::create()	string $ublXml, string $filename = 'invoice.xml'	Ingresso builder; rifiuta XML o nome di file vuoto	self	InvalidArgumentException	Configurabile tramite withFilename(), withDescription(), withoutSanitization()
PeppolEmbedder::embed()	PdfAManager, FileAttachment	Pass XmlGuard, verifica del contenitore, gate del rulebook, allegato	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Ri-verifica del rulebook consapevole del contenitore al momento dell’incorporamento
InvoiceXmlValidator::validate()	string $xmlData, ZugferdProfile, ?InvoiceValidatorMode	Pre-flight strutturale EN 16931; severità COMPAT per impostazione predefinita	InvoiceValidationResult	Non solleva; i fallimenti emergono come findings di errore	La modalità risolve l’argomento, poi l’ambiente, poi COMPAT
InvoiceXmlValidator::isCrossIndustryInvoice()	string $xmlData	Verifica dell’elemento radice e del namespace per i payload CII	bool	Non solleva; restituisce false	Sonda di rilevamento economica
InvoiceValidatorMode (enum)	—	COMPAT (predefinito) mantiene i findings BT-24 a livello di avviso; STRICT li promuove a errore	—	—	fromEnvironment() ripiega su COMPAT in caso di valori non impostati o non riconosciuti
InvoiceValidationResult / InvoiceValidationFinding	—	Aggregati immutabili: isValid, getErrors(), getWarnings(); livello, codice, messaggio per ciascun finding	—	—	InvoiceValidationResult::fail() incapsula un singolo errore
SchematronValidator::validate()	string $xsltPath, string $xmlData	Esegue un XSLT Schematron pre-compilato; analizza l’SVRL in findings	SchematronResult	InvalidArgumentException per un XSLT mancante o illeggibile; i fallimenti del motore restituiscono un risultato di errore	Tempistica catturata in durationMs
SchematronValidator::runRules()	string $xslPath, string $xmlPayload	Adattatore cross-tier; mappa i findings di errore su oggetti contract RuleViolation	list<RuleViolation>	Come validate()	I findings di livello info vengono ignorati
SchematronResult / SchematronFinding	—	Verdetto, findings, durata; getFailedAssertions(), getSuccessfulReports()	—	—	SchematronResult::error() marca come non validi i fallimenti del motore
SchematronCacheInterface	—	Contratto di cache con rilevamento di manomissione: getVerified(), set(), computeKey()	—	—	Fallisce in modo chiuso in caso di mancata corrispondenza del digest
AtomicRenameSchematronCache	string $cacheDir, bool $atomicRename = true, LoggerInterface	File-cache verificata con SHA-256 e scritture con rinomina atomica	—	InvalidArgumentException, SchematronCacheException	La directory deve esistere o essere creabile, e scrivibile
VersionPinRegistry	array $pins, ?string $sourcePath	Pin di pacchetti di regole bloccati con SHA-256: loadFromLockFile(), get(), verifyArtefact(), regenerateLockFile()	—	VersionPinException, InvalidArgumentException, JsonException in caso di JSON di lock malformato	I digest vuoti o malformati falliscono in modo chiuso
InvoiceContractValidator	?SemanticValidator	Adattatore cross-tier ValidatorInterface; pre-flight strutturale più regole semantiche approfondite EN 16931	ContractResult	Fallisce in modo chiuso; gli errori del motore emergono come findings di errore	Collegato sui percorsi del framework quando nextpdf/premium è installato
ZugferdContractEmbedder	FacturXContractEmbedder	Adattatore cross-tier EmbedderInterface; incorporamento byte-in / byte-out	string (byte PDF)	Propaga i fallimenti del delegato	Delega al motore di riscrittura byte di tier Pro
ZugferdEmbeddingException, PeppolEmbeddingException, SchematronCacheException, VersionPinException	—	Tassonomia dei fallimenti del modulo	—	—	Tutte estendono 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

Contratto di comportamento

Incorporamento. ZugferdEmbedder allega un payload XML UN/CEFACT CII ZUGFeRD 2.4 / Factur-X 1.08 fornito dal chiamante a un contenitore PDF/A. Supporta due contenitori: PDF/A-4f (ISO 19005-4:2020), il contenitore moderno preferito, e PDF/A-3b (ISO 19005-3:2012) per la retrocompatibilità. embed() esegue sempre prima un pass di sicurezza XmlGuard, poi la convalida strutturale a meno che non sia impostato withoutValidation(), quindi verifica che il contenitore supporti i file incorporati, inietta la dichiarazione dell’extension-schema XMP tramite ZugferdXmpSchema e allega l’XML come file associato. La relazione dell’allegato ha come valore predefinito la raccomandazione del rulebook /Alternative; le sovrascritture passano attraverso lo stesso rulebook, che impone l’insieme di relazioni ISO 32000-2:2020 §14.13 e il sottoinsieme di fattura EN 16931. PeppolEmbedder esegue l’equivalente per l’XML di fattura o nota di credito Peppol BIS Billing 3.0 UBL 2.1 fornito dal chiamante. Nessuno dei due embedder genera l’XML della fattura.

Convalida. InvoiceXmlValidator verifica l’XML CII rispetto alle aspettative strutturali EN 16931: elemento radice, sezioni richieste, cardinalità dell’intestazione, righe di dettaglio dove il profilo le richiede e l’identificatore di specifica BT-24 imposto dalla regola di business BR-1. InvoiceValidatorMode seleziona la severità. COMPAT (predefinito) riporta un BT-24 mancante o non corrispondente come avviso, in modo che un gate booleano di validità non regredisca. STRICT lo rende un errore bloccante e asserisce inoltre la coerenza del profilo rispetto al ZugferdProfile dichiarato, rispecchiando la semantica dei validatori esterni KoSIT / Mustang. La modalità si risolve nell’ordine: argomento esplicito, poi l’override d’ambiente INVOICE_VALIDATOR_MODE, poi COMPAT. I risultati sono oggetti strutturati InvoiceValidationResult / InvoiceValidationFinding; il validatore restituisce findings anziché sollevare eccezioni.

Schematron. SchematronValidator esegue insiemi di regole Schematron pre-compilati — le regole CEN EN 16931 .sch compilate in XSLT in fase di build — usando il processore XSLT PHP in-process. Analizza il report SVRL in oggetti SchematronFinding / SchematronResult: le asserzioni fallite diventano findings di errore, i report riusciti diventano findings di livello info. Una cache opzionale (SchematronCacheInterface, con l’implementazione di file con rinomina atomica) fornisce byte di stylesheet verificati indicizzati per digest del contenuto più versione del compilatore. VersionPinRegistry fissa ogni pacchetto di regole esterno a una versione bloccata con SHA-256 e fallisce in modo chiuso in caso di drift o digest malformati.

Questo modulo produce e verifica dati di fattura strutturati. Non asserisce che un documento sia una fattura legalmente conforme, che sia approvato dall’autorità fiscale o che ne sia garantita l’accettazione da parte di alcuna autorità. Il validatore verifica solo il modello semantico EN 16931 e il contenitore ZUGFeRD / Factur-X / UBL; esclude le estensioni nazionali (per esempio l’SDI italiano, il Chorus Pro francese, il trasporto XRechnung tedesco). Come afferma la EN 16931-1, l’emittente della fattura è responsabile del rispetto delle regole della legislazione pertinente; questo non è un validatore dell’autorità fiscale. Il supporto di uno standard non equivale alla conformità ad esso.

Casi limite e modalità di fallimento

• L’XML vuoto fallisce rapidamente: i builder sollevano InvalidArgumentException; InvoiceXmlValidator::validate() restituisce un risultato fallito.
• XmlGuard rifiuta le dichiarazioni DOCTYPE, l’espansione di entità, i payload sovradimensionati e i caratteri di controllo. Gli embedder lo espongono come ZugferdEmbeddingException o PeppolEmbeddingException con la causa preservata.
• withoutValidation() e withoutSanitization() non aggirano mai il pass di sicurezza XmlGuard. Solo i controlli strutturali dei business-term sono ignorabili.
• Un contenitore privo di supporto per i file incorporati (qualsiasi cosa diversa da PDF/A-4f o PDF/A-3b) solleva InvalidArgumentException nominando le versioni accettate.
• Un valore AFRelationship non consentito viene rifiutato al confine del builder; una ri-verifica del rulebook consapevole del contenitore viene eseguita di nuovo all’interno di embed().
• COMPAT mantiene un BT-24 mancante a severità di avviso; STRICT rende i valori BT-24 mancanti e non corrispondenti al profilo errori bloccanti.
• SchematronValidator solleva un’eccezione solo per un percorso XSLT mancante o illeggibile. I fallimenti di trasformazione o di parsing SVRL restituiscono SchematronResult::error() con isValid false.
• Una voce di cache i cui byte memorizzati falliscono la verifica del digest viene rimossa e lo stylesheet viene riletto dal disco; i byte avvelenati non vengono mai restituiti.
• Il processore XSLT viene eseguito con il caricamento di risorse di file e di rete bloccato e non registra mai funzioni PHP; document(), xsl:include, xsl:import e result-document non possono caricare risorse.
• VersionPinRegistry rifiuta i digest SHA-256 vuoti o malformati all’ingestione e alla rigenerazione; verifyArtefact() restituisce false anziché far passare un pin non verificabile.
• Questo modulo non esegue alcuna firma crittografica; il comportamento in modalità FIPS è fuori ambito qui (vedere il modulo Signature).

Conformità

Comportamento	Riferimento	Stato
Modello semantico essenziale della fattura	EN 16931-1:2026 §4	Sviluppato rispetto a; l’emittente resta responsabile
Identificatore di specifica (BT-24)	EN 16931-1:2026 BR-1	Avviso in COMPAT, errore in STRICT
Binding di sintassi UN/CEFACT CII	CEN/TS 16931-3-3:2020	Incorporamento supportato
Binding di sintassi UBL 2.1	CEN/TS 16931-3-2:2020	Incorporamento supportato
File associato PDF/A-3	ISO 19005-3:2012 §6.7.8	Contenitore supportato
File incorporato PDF/A-4f	ISO 19005-4:2020 Annex A	Contenitore supportato
Valori di relazione dei file associati	ISO 32000-2:2020 §14.13	Soggetto a gate dal rulebook
Parsing del report Schematron / SVRL	ISO/IEC 19757-3	Sviluppato rispetto a (basato sul prodotto; standard non presente nel corpus delle citazioni)

Sviluppato rispetto a (built-against), non una certificazione o approvazione dell’autorità fiscale. NextPDF non detiene alcuna certificazione per nessuno di questi standard. NextPDF produce fatture strutturate conformi al modello dati EN 16931 e riporta i findings delle regole; non produce fatture legalmente conformi, non fornisce output approvato dall’autorità fiscale e non garantisce l’accettazione. Consultare i propri consulenti fiscali e legali.

Note di sviluppo

• Il motore Schematron richiede l’estensione PHP ext-xsl; il provisioning e l’abilitazione sono responsabilità dell’operatore.
• L’elaborazione è in-process e locale. Non si verificano chiamate di rete in uscita durante l’incorporamento o la convalida. Il trasporto nazionale di fatturazione elettronica, le piattaforme di clearance e i sistemi di archiviazione sono esterni a questo modulo.
• I pacchetti di regole vengono compilati da .sch a XSLT in fase di build; il runtime esegue solo stylesheet pre-compilati.
• Le chiavi di cache incorporano il salt di versione del compilatore (attualmente nextpdf-schxslt-1.0); il suo incremento invalida le cache distribuite senza un passaggio di purge.
• I pin dei pacchetti di regole risiedono nel file di lock in enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); la CI verifica gli artefatti distribuiti rispetto ai digest fissati.
• I chiamanti cross-tier usano InvoiceContractValidator e ZugferdContractEmbedder; i chiamanti Enterprise nativi del tier usano direttamente ZugferdEmbedder e InvoiceXmlValidator.

Confine di pubblicazione

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

Vedere anche

• Capability Invoice — controparte capability di questo riferimento.
• Pro Compliance — rilevamento/convalida di tier Pro.
• Document E-Filing
• Panoramica di Enterprise