Enterprise Edition

Invoice — Ausführliche Referenz

Auf einen Blick

Das Invoice-Modul besitzt drei unabhängige Oberflächen: Einbettung, Validierung und Schematron-Regelausführung. ZugferdEmbedder und PeppolEmbedder hängen vom Aufrufer bereitgestelltes Rechnungs-XML an einen PDF/A-4f- oder PDF/A-3b-Träger an und liefern ein strukturiertes Ergebnis zurück. InvoiceXmlValidator führt einen strukturellen EN-16931-Vorabtest mit wählbarer COMPAT- oder STRICT-Schweregradstufe aus. SchematronValidator führt vorkompilierte Schematron-Regelpakete prozessintern aus und parst SVRL-Befunde. NextPDF erzeugt kein Rechnungs-XML; der Aufrufer stellt die Nutzlast bereit und verantwortet sie.

Verfügbarkeit und Lizenzierung

Diese Fähigkeit ist in NextPDF Enterprise (nextpdf/enterprise) enthalten und wird mit einem Lizenzumschlag der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

Unterschiede je Stufe: Die Erkennung und Validierung von E-Rechnungen ist die Oberfläche der Pro-Stufe (Pro-Compliance-Modul). Die Einbettung hybrider Rechnungen, das XRechnung-CIUS-Profil und die prozessinterne Schematron-Engine sind ausschließlich der Enterprise-Stufe vorbehalten. Es gibt keinen gesonderten Fähigkeitscode je Funktion jenseits der Paketgrenze von nextpdf/enterprise.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Bettet CII-XML im BASIC-Profil ein: XmlGuard-Durchlauf, strukturelle Validierung, XMP-Schema-Injektion, Anhang	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Schnellpfad; empfohlener Ausgangspunkt
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Dieselbe Pipeline im MINIMUM-Profil	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Schnellpfad
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Builder-Einstieg; weist leeres XML zurück	`self`	`InvalidArgumentException`	Konfiguration über `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Überschreibt die standardmäßige `/Alternative`-Beziehung; durch das Regelwerk für zugeordnete Dateien reglementiert	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` für Rechnungen zurückgewiesen
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Abschließender Builder-Aufruf: XmlGuard, optionale Validierung, Trägerprüfung, XMP, Anhang	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Ein Validierungsfehler benennt den ersten Fehler
`ZugferdProfile` (Enum)	—	Fälle MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG hängt `xrechnung.xml` an; CII-Profile hängen `factur-x.xml` an
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Registriert die Factur-X-RDF-Beschreibung und den PDF/A-Erweiterungsschema-Eintrag	`XmpMetadata`	Keine	Wird von `embed()` aufgerufen; auch direkt nutzbar
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Bettet Peppol-BIS-3.0-UBL-Rechnungs- oder -Gutschrift-XML ein	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Standarddateinamen `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Builder-Einstieg; weist leeres XML oder leeren Dateinamen zurück	`self`	`InvalidArgumentException`	Konfiguration über `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	XmlGuard-Durchlauf, Trägerprüfung, Regelwerk-Kontrolle, Anhang	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Trägerbewusste erneute Regelwerkprüfung zum Einbettungszeitpunkt
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	Struktureller EN-16931-Vorabtest; standardmäßig COMPAT-Schweregrad	`InvoiceValidationResult`	Wirft nicht; Fehler erscheinen als Fehlerbefunde	Der Modus wird über Argument, dann Umgebung, dann COMPAT aufgelöst
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Wurzelelement- und Namensraumprüfung für CII-Nutzlasten	`bool`	Wirft nicht; gibt `false` zurück	Günstige Erkennungssonde
`InvoiceValidatorMode` (Enum)	—	`COMPAT` (Standard) hält BT-24-Befunde auf Warnstufe; `STRICT` stuft sie zu Fehlern hoch	—	—	`fromEnvironment()` fällt bei nicht gesetzten oder unbekannten Werten auf COMPAT zurück
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Unveränderliche Aggregate: `isValid`, `getErrors()`, `getWarnings()`; Stufe, Code, Nachricht je Befund	—	—	`InvoiceValidationResult::fail()` kapselt einen einzelnen Fehler
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Führt ein vorkompiliertes Schematron-XSLT aus; parst SVRL in Befunde	`SchematronResult`	`InvalidArgumentException` bei fehlendem oder nicht lesbarem XSLT; Engine-Fehler liefern ein Fehlerergebnis	Zeitmessung in `durationMs` erfasst
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Stufenübergreifender Adapter; bildet Fehlerbefunde auf Vertrags-`RuleViolation`-Objekte ab	`list<RuleViolation>`	Wie `validate()`	Info-Befunde werden übersprungen
`SchematronResult` / `SchematronFinding`	—	Verdikt, Befunde, Dauer; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` markiert Engine-Fehler als ungültig
`SchematronCacheInterface`	—	Manipulationserkennender Cache-Vertrag: `getVerified()`, `set()`, `computeKey()`	—	—	Schließt bei Digest-Abweichung fehlersicher
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	SHA-256-verifizierter Dateicache mit Atomic-Rename-Schreibvorgängen	—	`InvalidArgumentException`, `SchematronCacheException`	Verzeichnis muss vorhanden oder anlegbar und beschreibbar sein
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	SHA-256-gesperrte Regelpaket-Pins: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` bei fehlerhaftem Lock-JSON	Leere oder fehlerhafte Digests schließen fehlersicher
`InvoiceContractValidator`	`?SemanticValidator`	Stufenübergreifender `ValidatorInterface`-Adapter; struktureller Vorabtest plus tiefe EN-16931-Semantikregeln	`ContractResult`	Schließt fehlersicher; Engine-Fehler erscheinen als Fehlerbefunde	Auf Framework-Pfaden gebunden, wenn `nextpdf/premium` installiert ist
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Stufenübergreifender `EmbedderInterface`-Adapter; Byte-ein/Byte-aus-Einbettung	`string` (PDF-Bytes)	Reicht Delegate-Fehler weiter	Delegiert an die Byte-Rewrite-Engine der Pro-Stufe
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Fehlertaxonomie des Moduls	—	—	Alle erweitern `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

Verhaltensvertrag

Einbettung. ZugferdEmbedder hängt eine vom Aufrufer bereitgestellte ZUGFeRD-2.4-/Factur-X-1.08-UN/CEFACT-CII-XML-Nutzlast an einen PDF/A-Träger an. Er unterstützt zwei Träger: PDF/A-4f (ISO 19005-4:2020), den bevorzugten modernen Träger, und PDF/A-3b (ISO 19005-3:2012) zur Abwärtskompatibilität. embed() führt stets zuerst einen XmlGuard-Sicherheitsdurchlauf aus, dann eine strukturelle Validierung, sofern nicht withoutValidation() gesetzt wurde, prüft anschließend, dass der Träger eingebettete Dateien unterstützt, injiziert die XMP-Erweiterungsschema-Deklaration über ZugferdXmpSchema und hängt das XML als zugeordnete Datei an. Die Anhangsbeziehung entspricht standardmäßig der Regelwerksempfehlung /Alternative; Überschreibungen laufen durch dasselbe Regelwerk, das den Beziehungssatz aus ISO 32000-2:2020 §14.13 und die EN-16931-Rechnungsuntermenge durchsetzt. PeppolEmbedder leistet das Äquivalent für vom Aufrufer bereitgestelltes Peppol-BIS-Billing-3.0-UBL-2.1-Rechnungs- oder -Gutschrift-XML. Keiner der Embedder erzeugt Rechnungs-XML.

Validierung. InvoiceXmlValidator prüft CII-XML gegen die strukturellen EN-16931-Erwartungen: Wurzelelement, erforderliche Abschnitte, Header-Kardinalität, Positionen dort, wo das Profil sie verlangt, und den BT-24-Spezifikationsbezeichner, der durch die Geschäftsregel BR-1 vorgeschrieben ist. InvoiceValidatorMode wählt den Schweregrad. COMPAT (Standard) meldet einen fehlenden oder nicht übereinstimmenden BT-24 als Warnung, damit ein boolescher Gültigkeitsgate nicht zurückfällt. STRICT macht aus beidem einen harten Fehler und prüft zudem die Profilkonsistenz gegen das deklarierte ZugferdProfile, wobei es die Semantik externer KoSIT-/Mustang-Validatoren nachbildet. Der Modus wird in dieser Reihenfolge aufgelöst: explizites Argument, dann die Umgebungsüberschreibung INVOICE_VALIDATOR_MODE, dann COMPAT. Ergebnisse sind strukturierte InvoiceValidationResult-/InvoiceValidationFinding-Objekte; der Validator gibt Befunde zurück, statt zu werfen.

Schematron. SchematronValidator führt vorkompilierte Schematron-Regelsätze aus — die zum Build-Zeitpunkt zu XSLT kompilierten CEN-EN-16931-.sch-Regeln — mithilfe des prozessinternen PHP-XSLT-Prozessors. Er parst den SVRL-Bericht in SchematronFinding-/SchematronResult-Objekte: fehlgeschlagene Assertions werden zu Fehlerbefunden, erfolgreiche Reports zu Info-Befunden. Ein optionaler Cache (SchematronCacheInterface, mit der Atomic-Rename-Dateiimplementierung) liefert verifizierte Stylesheet-Bytes, geschlüsselt über Inhalts-Digest plus Compiler-Version. VersionPinRegistry pinnt jedes externe Regelpaket auf eine SHA-256-gesperrte Version und schließt bei Drift oder fehlerhaften Digests fehlersicher.

Dieses Modul erzeugt und prüft strukturierte Rechnungsdaten. Es behauptet nicht, dass ein Dokument eine rechtlich konforme Rechnung ist, dass es von einer Steuerbehörde genehmigt ist oder dass seine Annahme durch eine Behörde garantiert ist. Der Validator prüft ausschließlich das semantische EN-16931-Modell und den ZUGFeRD-/Factur-X-/UBL-Container; er schließt nationale Erweiterungen aus (zum Beispiel italienisches SDI, französisches Chorus Pro, deutschen XRechnung-Transport). Wie EN 16931-1 feststellt, ist der Rechnungsaussteller dafür verantwortlich, die Regeln der einschlägigen Gesetzgebung zu erfüllen; dies ist kein Validator einer Steuerbehörde. Die Unterstützung eines Standards ist keine Konformität mit ihm.

Grenzfälle und Fehlerverhalten

Leeres XML schlägt sofort fehl: Builder werfen InvalidArgumentException; InvoiceXmlValidator::validate() gibt ein fehlgeschlagenes Ergebnis zurück.
XmlGuard weist DOCTYPE-Deklarationen, Entity-Expansion, übergroße Nutzlasten und Steuerzeichen zurück. Embedder legen dies als ZugferdEmbeddingException oder PeppolEmbeddingException mit erhaltener Ursache offen.
withoutValidation() und withoutSanitization() umgehen niemals den XmlGuard-Sicherheitsdurchlauf. Nur die strukturellen Geschäftsbegriffsprüfungen sind überspringbar.
Ein Träger ohne Unterstützung eingebetteter Dateien (alles außer PDF/A-4f oder PDF/A-3b) löst eine InvalidArgumentException aus, die die akzeptierten Versionen benennt.
Ein unzulässiger AFRelationship-Wert wird an der Builder-Grenze zurückgewiesen; eine trägerbewusste erneute Regelwerkprüfung läuft nochmals innerhalb von embed().
COMPAT hält einen fehlenden BT-24 auf Warnschweregrad; STRICT macht fehlende und profilunverträgliche BT-24-Werte zu harten Fehlern.
SchematronValidator wirft nur bei einem fehlenden oder nicht lesbaren XSLT-Pfad. Transform- oder SVRL-Parse-Fehler geben SchematronResult::error() mit isValid false zurück.
Ein Cache-Eintrag, dessen gespeicherte Bytes die Digest-Verifikation nicht bestehen, wird verworfen und das Stylesheet wird erneut von der Festplatte gelesen; vergiftete Bytes werden niemals zurückgegeben.
Der XSLT-Prozessor läuft mit blockiertem Datei- und Netzwerkressourcenladen und registriert niemals PHP-Funktionen; document(), xsl:include, xsl:import und result-document können keine Ressourcen laden.
VersionPinRegistry weist leere oder fehlerhafte SHA-256-Digests bei der Aufnahme und bei der Neuerzeugung zurück; verifyArtefact() gibt false zurück, statt einen nicht verifizierbaren Pin durchzulassen.
Dieses Modul führt keine kryptografische Signierung durch; das FIPS-Modus-Verhalten liegt hier außerhalb des Geltungsbereichs (siehe das Signature-Modul).

Konformität

Verhalten	Referenz	Status
Semantisches Kernmodell der Rechnung	EN 16931-1:2026 §4	Umgesetzt gegen; Aussteller bleibt verantwortlich
Spezifikationsbezeichner (BT-24)	EN 16931-1:2026 BR-1	Warnung in COMPAT, Fehler in STRICT
UN/CEFACT-CII-Syntaxbindung	CEN/TS 16931-3-3:2020	Einbettung unterstützt
UBL-2.1-Syntaxbindung	CEN/TS 16931-3-2:2020	Einbettung unterstützt
PDF/A-3-zugeordnete Datei	ISO 19005-3:2012 §6.7.8	Träger unterstützt
PDF/A-4f-eingebettete Datei	ISO 19005-4:2020 Annex A	Träger unterstützt
Beziehungswerte zugeordneter Dateien	ISO 32000-2:2020 §14.13	Regelwerk-reglementiert
Schematron-/SVRL-Bericht-Parsing	ISO/IEC 19757-3	Umgesetzt gegen (produktbasiert; Standard nicht im Zitatkorpus)

Umgesetzt gegen, keine Zertifizierung und keine Genehmigung durch eine Steuerbehörde. NextPDF hält keine Zertifizierung für einen dieser Standards. NextPDF erzeugt strukturierte Rechnungen, die dem EN-16931-Datenmodell entsprechen, und meldet Regelbefunde; es erzeugt keine rechtlich konformen Rechnungen, liefert keine von einer Steuerbehörde genehmigte Ausgabe und garantiert keine Annahme. Konsultieren Sie Ihre Steuer- und Rechtsberater.

Entwicklungshinweise

Die Schematron-Engine erfordert die PHP-Erweiterung ext-xsl; ihre Bereitstellung und Aktivierung liegt in der Verantwortung des Betreibers.
Die Verarbeitung erfolgt prozessintern und lokal. Während der Einbettung oder Validierung erfolgen keine ausgehenden Netzwerkaufrufe. Nationaler E-Rechnungs-Transport, Clearance-Plattformen und Archivsysteme sind für dieses Modul extern.
Regelpakete werden zum Build-Zeitpunkt von .sch zu XSLT kompiliert; die Laufzeit führt ausschließlich vorkompilierte Stylesheets aus.
Cache-Schlüssel binden das Compiler-Versions-Salt ein (derzeit nextpdf-schxslt-1.0); dessen Erhöhung invalidiert bereitgestellte Caches ohne einen Purge-Schritt.
Regelpaket-Pins liegen in der Lock-Datei unter enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); die CI verifiziert bereitgestellte Artefakte gegen die gepinnten Digests.
Stufenübergreifende Aufrufer nutzen InvoiceContractValidator und ZugferdContractEmbedder; stufennative Enterprise-Aufrufer nutzen ZugferdEmbedder und InvoiceXmlValidator direkt.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namensraumpfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

Invoice-Fähigkeit — Fähigkeits-Gegenstück zu dieser Referenz.
Pro Compliance — Erkennung/Validierung der Pro-Stufe.
Document E-Filing
Enterprise-Übersicht