Enterprise editie

Invoice — Diepe referentie

In één oogopslag

De Invoice-module heeft drie onafhankelijke oppervlakken: embedding, validatie en uitvoering van Schematron-regels. ZugferdEmbedder en PeppolEmbedder koppelen door de aanroeper aangeleverde factuur-XML aan een PDF/A-4f- of PDF/A-3b-carrier en retourneren een gestructureerd resultaat. InvoiceXmlValidator voert een structurele EN 16931-pre-flight uit met selecteerbare COMPAT- of STRICT-ernst. SchematronValidator voert vooraf gecompileerde Schematron-regelsets in-process uit en parseert SVRL-bevindingen. NextPDF genereert geen factuur-XML; de aanroeper levert en bezit de payload.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelope van het Enterprise-niveau. Een deployment zonder die entitlement laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Nuance per tier: e-factuurdetectie en -validatie vormen het Pro-oppervlak (Pro Compliance-module). Hybride-factuur-embedding, het XRechnung CIUS-profiel en de in-process Schematron-engine zijn Enterprise-only. Er is geen afzonderlijke capaciteitscode per functie buiten de pakketgrens van nextpdf/enterprise.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Bedt BASIC-profiel CII XML in: XmlGuard-pass, structurele validatie, XMP-schema-injectie, koppeling	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Snelle pad; aanbevolen startpunt
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Dezelfde pipeline op MINIMUM-profiel	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Snelle pad
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Builder-ingang; wijst lege XML af	`self`	`InvalidArgumentException`	Configureer via `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Overschrijft de standaard `/Alternative`-relatie; afgeschermd door het associated-file-regelboek	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` afgewezen voor facturen
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Afsluitende builder-aanroep: XmlGuard, optionele validatie, carriercontrole, XMP, koppelen	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Validatiefout noemt de eerste fout
`ZugferdProfile` (enum)	—	Enum-cases MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG koppelt `xrechnung.xml`; CII-profielen koppelen `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Registreert de Factur-X RDF-beschrijving en de PDF/A-extension-schema-entry	`XmpMetadata`	Geen	Aangeroepen door `embed()`; ook rechtstreeks bruikbaar
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Bedt Peppol BIS 3.0 UBL factuur- of creditnota-XML in	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Standaardbestandsnamen `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Builder-ingang; wijst lege XML of bestandsnaam af	`self`	`InvalidArgumentException`	Configureer via `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	XmlGuard-pass, carriercontrole, regelboek-gate, koppelen	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Carrier-bewuste regelboek-hercontrole tijdens embedden
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	EN 16931 structurele pre-flight; COMPAT-ernst standaard	`InvoiceValidationResult`	Werpt niet; fouten verschijnen als error-bevindingen	Modus resolvet argument, dan omgeving, dan COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Root-element- en namespace-controle voor CII-payloads	`bool`	Werpt niet; retourneert `false`	Goedkope detectieprobe
`InvoiceValidatorMode` (enum)	—	`COMPAT` (standaard) houdt BT-24-bevindingen op waarschuwing; `STRICT` promoveert ze tot fout	—	—	`fromEnvironment()` valt terug op COMPAT bij niet-gezette of niet-herkende waarden
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Immutable aggregaten: `isValid`, `getErrors()`, `getWarnings()`; niveau, code, bericht per bevinding	—	—	`InvoiceValidationResult::fail()` verpakt één enkele fout
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Voert een vooraf gecompileerde Schematron-XSLT uit; parseert SVRL in bevindingen	`SchematronResult`	`InvalidArgumentException` bij een ontbrekende of onleesbare XSLT; engine-fouten retourneren een error-resultaat	Timing vastgelegd in `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Cross-tier-adapter; mapt error-bevindingen naar contract-`RuleViolation`-objecten	`list<RuleViolation>`	Zoals `validate()`	Info-niveau-bevindingen worden overgeslagen
`SchematronResult` / `SchematronFinding`	—	Verdict, bevindingen, duur; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` markeert engine-fouten als ongeldig
`SchematronCacheInterface`	—	Tamper-detect cache-contract: `getVerified()`, `set()`, `computeKey()`	—	—	Faalt gesloten bij digest-mismatch
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	SHA-256-geverifieerde file-cache met atomic-rename-writes	—	`InvalidArgumentException`, `SchematronCacheException`	Directory moet bestaan of aanmaakbaar zijn, en beschrijfbaar zijn
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	SHA-256-vergrendelde regelset-pins: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` bij misvormde lock-JSON	Lege of misvormde digests falen gesloten
`InvoiceContractValidator`	`?SemanticValidator`	Cross-tier-`ValidatorInterface`-adapter; structurele pre-flight plus EN 16931 diep-semantische regels	`ContractResult`	Faalt gesloten; engine-fouten verschijnen als error-bevindingen	Gebonden op framework-paden wanneer `nextpdf/premium` is geïnstalleerd
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Cross-tier-`EmbedderInterface`-adapter; byte-in / byte-out embed	`string` (PDF-bytes)	Propageert delegate-fouten	Delegeert naar de byte-rewrite-engine op Pro-niveau
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Taxonomie van modulefouten	—	—	Breiden allemaal `RuntimeException` uit

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

Gedragscontract

Embedding. ZugferdEmbedder koppelt een door de aanroeper aangeleverde ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML-payload aan een PDF/A-carrier. Het ondersteunt twee carriers: PDF/A-4f (ISO 19005-4:2020), de moderne voorkeurscarrier, en PDF/A-3b (ISO 19005-3:2012) voor achterwaartse compatibiliteit. embed() voert altijd eerst een XmlGuard-beveiligingspass uit, daarna structurele validatie tenzij withoutValidation() is ingesteld, verifieert vervolgens dat de carrier embedded files ondersteunt, injecteert de XMP-extension-schema-declaratie via ZugferdXmpSchema en koppelt de XML als associated file. De koppelingsrelatie is standaard de regelboek-aanbeveling /Alternative; overrides gaan door hetzelfde regelboek, dat de relatieset uit ISO 32000-2:2020 §14.13 en de EN 16931-factuursubset afdwingt. PeppolEmbedder doet het equivalent voor door de aanroeper aangeleverde Peppol BIS Billing 3.0 UBL 2.1 factuur- of creditnota-XML. Geen van beide embedders genereert factuur-XML.

Validatie. InvoiceXmlValidator controleert CII XML tegen de structurele verwachtingen van EN 16931: root-element, vereiste secties, header-cardinaliteit, regelitems waar het profiel ze vereist, en de BT-24 specificatie-identifier die door business rule BR-1 wordt voorgeschreven. InvoiceValidatorMode selecteert de ernst. COMPAT (standaard) rapporteert een ontbrekende of niet-overeenkomende BT-24 als een waarschuwing, zodat een booleaanse geldigheidsgate niet regresseert. STRICT maakt er zowel een harde fout van als dat het de profielconsistentie toetst aan het opgegeven ZugferdProfile, wat de semantiek van externe KoSIT-/Mustang-validators weerspiegelt. De modus resolvet in deze volgorde: expliciet argument, dan de INVOICE_VALIDATOR_MODE-omgevingsoverride, dan COMPAT. Resultaten zijn gestructureerde InvoiceValidationResult- / InvoiceValidationFinding-objecten; de validator retourneert bevindingen in plaats van te werpen.

Schematron. SchematronValidator voert vooraf gecompileerde Schematron-regelsets uit — de CEN EN 16931 .sch-regels die tijdens de build naar XSLT zijn gecompileerd — met behulp van de in-process PHP-XSLT-processor. Het parseert het SVRL-rapport in SchematronFinding- / SchematronResult-objecten: mislukte asserties worden error-bevindingen, geslaagde rapporten worden info-bevindingen. Een optionele cache (SchematronCacheInterface, met de atomic-rename file-implementatie) levert geverifieerde stylesheet-bytes met als sleutel de content-digest plus de compilerversie. VersionPinRegistry pint elke externe regelset op een SHA-256-vergrendelde versie en faalt gesloten bij drift of misvormde digests.

Deze module produceert en controleert gestructureerde factuurgegevens. Het beweert niet dat een document een juridisch conforme factuur is, dat het door de belastingdienst is goedgekeurd of dat acceptatie door enige instantie is gegarandeerd. De validator controleert alleen het EN 16931 semantische model en de ZUGFeRD- / Factur-X- / UBL-container; het sluit nationale uitbreidingen uit (bijvoorbeeld het Italiaanse SDI, het Franse Chorus Pro, het Duitse XRechnung-transport). Zoals EN 16931-1 stelt, is de factuuruitgever verantwoordelijk voor het voldoen aan de regels van de relevante wetgeving; dit is geen belastingdienstvalidator. Ondersteuning van een standaard betekent geen conformiteit ermee.

Randgevallen en foutmodi

Lege XML faalt snel: builders werpen InvalidArgumentException; InvoiceXmlValidator::validate() retourneert een mislukt resultaat.
XmlGuard wijst DOCTYPE-declaraties, entity-expansie, te grote payloads en stuurtekens af. Embedders tonen dit als ZugferdEmbeddingException of PeppolEmbeddingException met behoud van de oorzaak.
withoutValidation() en withoutSanitization() omzeilen nooit de XmlGuard-beveiligingspass. Alleen de structurele business-term-controles zijn overslaanbaar.
Een carrier zonder ondersteuning voor embedded files (iets anders dan PDF/A-4f of PDF/A-3b) werpt InvalidArgumentException met vermelding van de geaccepteerde versies.
Een niet-toegestane AFRelationship-waarde wordt afgewezen aan de builder-grens; een carrier-bewuste regelboek-hercontrole draait opnieuw binnen embed().
COMPAT houdt een ontbrekende BT-24 op waarschuwingsernst; STRICT maakt ontbrekende en profiel-niet-overeenkomende BT-24-waarden tot harde fouten.
SchematronValidator werpt alleen bij een ontbrekend of onleesbaar XSLT-pad. Transformatie- of SVRL-parse-fouten retourneren SchematronResult::error() met isValid false.
Een cache-entry waarvan de opgeslagen bytes de digest-verificatie niet doorstaan, wordt verwijderd en de stylesheet wordt opnieuw van schijf gelezen; vergiftigde bytes worden nooit geretourneerd.
De XSLT-processor draait met het laden van bestands- en netwerkresources geblokkeerd en registreert nooit PHP-functies; document(), xsl:include, xsl:import en result-document kunnen geen resources laden.
VersionPinRegistry wijst lege of misvormde SHA-256-digests af bij inname en bij regeneratie; verifyArtefact() retourneert false in plaats van een niet-verifieerbare pin te laten passeren.
Deze module voert geen cryptografische ondertekening uit; FIPS-modusgedrag valt hier buiten de scope (zie de Signature-module).

Conformiteit

Gedrag	Referentie	Status
Kern factuur-semantisch model	EN 16931-1:2026 §4	Gebouwd ten opzichte van; uitgever blijft verantwoordelijk
Specificatie-identifier (BT-24)	EN 16931-1:2026 BR-1	Waarschuwing in COMPAT, fout in STRICT
UN/CEFACT CII-syntaxbinding	CEN/TS 16931-3-3:2020	Embed ondersteund
UBL 2.1-syntaxbinding	CEN/TS 16931-3-2:2020	Embed ondersteund
PDF/A-3 associated file	ISO 19005-3:2012 §6.7.8	Carrier ondersteund
PDF/A-4f embedded file	ISO 19005-4:2020 Annex A	Carrier ondersteund
Associated-file-relatiewaarden	ISO 32000-2:2020 §14.13	Regelboek-afgeschermd
Schematron- / SVRL-rapportparsing	ISO/IEC 19757-3	Gebouwd ten opzichte van (productgefundeerd; standaard niet in het citaatcorpus)

Gebouwd ten opzichte van, geen certificering of goedkeuring door de belastingdienst. NextPDF beschikt over geen enkele certificering voor deze standaarden. NextPDF produceert gestructureerde facturen die conform zijn aan het EN 16931-datamodel en rapporteert regelbevindingen; het produceert geen juridisch conforme facturen, levert geen door de belastingdienst goedgekeurde uitvoer en garandeert geen acceptatie. Raadpleeg je belasting- en juridische adviseurs.

Ontwikkelingsnotities

De Schematron-engine vereist de ext-xsl PHP-extensie; het provisioneren en inschakelen ervan is de verantwoordelijkheid van de operator.
De verwerking is in-process en lokaal. Er vinden geen uitgaande netwerkaanroepen plaats tijdens het embedden of valideren. Nationaal e-factuurtransport, clearance-platforms en archiveringssystemen vallen buiten deze module.
Regelsets worden tijdens de build van .sch naar XSLT gecompileerd; de runtime voert alleen vooraf gecompileerde stylesheets uit.
Cache-sleutels verwerken de compilerversie-salt (momenteel nextpdf-schxslt-1.0); het ophogen ervan invalideert gedeploye caches zonder een purge-stap.
Regelset-pins staan in het lock-bestand op enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI verifieert gedeploye artefacten tegen de vastgepinde digests.
Cross-tier-aanroepers gebruiken InvoiceContractValidator en ZugferdContractEmbedder; tier-native Enterprise-aanroepers gebruiken ZugferdEmbedder en InvoiceXmlValidator rechtstreeks.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

Invoice-functionaliteit — functionaliteitstegenhanger van deze referentie.
Pro Compliance — detectie/validatie op Pro-niveau.
Document E-Filing
Enterprise-overzicht