Invoice

At a glance

NextPDF Enterprise produces ZUGFeRD / Factur-X / Peppol-UBL structured hybrid invoices and validates invoice XML against the EN 16931 data model and Schematron rule sets. It produces structured invoices conforming to the data model defined in EN 16931; it is not a tax-authority validator and does not certify any document.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Install

composer require nextpdf/enterprise:^3

The Schematron engine uses the PHP ext-xsl extension. Install and enable it before running Schematron validation.

Conceptual overview

The Invoice module has three independent surfaces: structured-invoice embedding, EN 16931 XML validation, and Schematron rule execution.

Embedding. ZugferdEmbedder attaches a caller-supplied ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML payload to a PDF/A carrier, producing a hybrid invoice. Two carrier formats are supported: PDF/A-4f (ISO 19005-4:2020), the preferred modern carrier, and PDF/A-3b (ISO 19005-3:2012) for backward compatibility. ZugferdXmpSchema injects the Factur-X XMP extension-schema declaration the carrier needs. PeppolEmbedder performs the same role for caller-supplied Peppol BIS Billing 3.0 UBL 2.1 invoice or credit-note XML, attaching it with the correct associated-file relationship and MIME type. NextPDF does not synthesize invoice XML; the caller provides valid XML and remains the invoice issuer.

Validation. InvoiceXmlValidator checks invoice XML against the EN 16931 semantic data model and the ZUGFeRD / Factur-X container expectations, including the BT-24 specification identifier that EN 16931 business rule BR-1 mandates. It runs in one of two modes: COMPAT (the default; borderline EN 16931 cardinality findings are reported as warnings to preserve backward compatibility for existing fixtures) and STRICT (BT-24 cardinality is a hard error, mirroring external-validator semantics). The mode is selectable per call, by environment override, or by conformance policy.

Schematron. SchematronValidator runs pre-compiled Schematron rule sets (the CEN EN 16931 .sch rules compiled to XSLT at build time) against invoice XML using the in-process PHP XSLT processor, and parses the SVRL report into structured findings. The ZugferdProfile enum models the conformance profiles — MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, and the German XRechnung B2G CIUS over EN 16931.

Scope

This module produces and checks structured invoice data.

• The validator checks the EN 16931 semantic model and the ZUGFeRD / Factur-X / UBL container only. National extensions and clearance platforms — for example Italian SDI, French Chorus Pro, German XRechnung transport — are out of scope at the transport level.
• As EN 16931-1 itself states, the core semantic model carries the essential information an electronic invoice needs to support legal and fiscal compliance; the invoice issuer is responsible for meeting the rules of relevant legislation.

Why it works this way

The module deliberately never synthesizes invoice XML. Embedding, EN 16931 validation, and Schematron execution are three independent surfaces over XML the caller supplies and owns. This keeps NextPDF a producer and checker, never the issuer, because legal responsibility cannot be delegated to a library. Validation defaults to COMPAT, so a borderline cardinality finding is a warning rather than a regression. STRICT is opt-in when you need external-validator semantics. The result is a clean separation: NextPDF reports what it observes, and the issuer decides whether the document meets the law. Design background: Invoices and e-invoicing.

API surface

Class	Responsibility
ZugferdEmbedder	Attach ZUGFeRD / Factur-X CII XML to a PDF/A-4f or PDF/A-3b carrier.
ZugferdXmpSchema	Inject the Factur-X XMP extension-schema declaration.
ZugferdProfile	Conformance-profile enum (MINIMUM … EXTENDED, XRECHNUNG).
PeppolEmbedder	Attach Peppol BIS 3.0 UBL invoice / credit-note XML to a PDF/A carrier.
InvoiceXmlValidator	Check XML against the EN 16931 data model; COMPAT or STRICT mode.
InvoiceValidatorMode	Validation-mode enum: COMPAT (default) or STRICT.
SchematronValidator	Run pre-compiled Schematron rule sets; parse SVRL findings.
InvoiceValidationResult / SchematronResult	Structured results: profile, findings, severities.

Code sample — Quick start

use NextPDF\Enterprise\Invoice\ZugferdEmbedder;
use NextPDF\Enterprise\Invoice\ZugferdProfile;

$pdf = ZugferdEmbedder::basic($pdfAManager, $fileAttachment, $ciiXml)
    ->embed(ZugferdProfile::EN16931);

Code sample — Production

use NextPDF\Enterprise\Invoice\InvoiceXmlValidator;
use NextPDF\Enterprise\Invoice\InvoiceValidatorMode;

$result = $validator->validate($ciiXml, InvoiceValidatorMode::STRICT);

foreach ($result->findings as $finding) {
    $logger->warning('invoice.finding', [
        'rule'     => $finding->ruleId,
        'severity' => $finding->severity->value,
    ]);
}
// A clean result is one input to your decision, not a compliance verdict.
// The invoice issuer remains responsible for relevant legislation.

Edge cases & gotchas

• A well-formed PDF that carries no recognizable invoice payload yields a “not an invoice” result rather than throwing.
• COMPAT is the default validation mode: a missing BT-24 specification identifier is reported as a warning, so call sites that gate on a boolean validity flag do not regress. Use STRICT to make BT-24 a hard error that matches external KoSIT / Mustang semantics.
• The caller supplies the invoice XML. NextPDF does not generate or correct it; an empty findings list does not make a non-conformant payload conformant.
• The Schematron engine requires ext-xsl. Rule sets are compiled at build time; runtime executes the pre-compiled XSLT only.

Performance

Validation cost scales with embedded XML size and the number of Schematron rules. Embedding cost scales with carrier size and is dominated by PDF/A serialization. The page performance budget reflects documentation rendering, not invoice throughput.

Security notes

All XML parsing routes through the hardened XML guard: external-entity resolution is disabled (XXE-safe), DOCTYPE is rejected, and decompression is bounded. The XSLT processor runs with network and file-system resource loading disabled and never registers PHP functions, so document(), xsl:include, xsl:import, and result-document cannot reach the network or disk. Treat invoice XML from untrusted sources as hostile.

Data residency & PII mitigations

Invoice XML may contain personal, commercial, and financial data. Processing is in-process and local; the module performs no outbound network calls during embedding or validation. Apply your own retention and minimization controls to extracted XML and findings.

Safe telemetry & log scrubbing

Findings and validation logs may include rule identifiers and tag values. They do not include full invoice payloads. Scrub or redact field values before forwarding logs to shared sinks if those values are sensitive.

Conformance

Behavior	Reference	Status
Core invoice semantic model	EN 16931-1:2026 §4	Built against; issuer remains responsible for relevant legislation
Specification identifier (BT-24)	EN 16931-1:2026 BR-1	Checked (warning in COMPAT, error in STRICT)
UN/CEFACT CII syntax binding	CEN/TS 16931-3-3:2020	Embed supported
UBL 2.1 syntax binding	CEN/TS 16931-3-2:2020	Embed supported
PDF/A-3 associated file	ISO 19005-3:2012 §6.7.8	Carrier supported
PDF/A-4f embedded file	ISO 19005-4:2020 Annex A	Carrier supported

This table records the specifications NextPDF Enterprise is built against and what it checks. It is not a statement of certification, tax-authority approval, or regulatory sufficiency. The invoice issuer is responsible for meeting the rules of relevant legislation; this is not a tax-authority validator.

FIPS-mode behavior

This module performs no cryptographic signing. Signing a hybrid invoice and FIPS-mode key custody are out of scope here; see the Signature module.

Threat model

Untrusted invoice XML is the primary input. Mitigations: XXE-safe parsing, DOCTYPE rejection, bounded decompression, an XSLT processor with network and file resource loading disabled, and no claim synthesis — the caller supplies and owns the invoice content.

Behavior contract

• ZugferdEmbedder / PeppolEmbedder attach caller-supplied invoice XML to a PDF/A-4f or PDF/A-3b carrier; NextPDF never synthesizes invoice XML.
• InvoiceXmlValidator runs in COMPAT (default; borderline EN 16931 cardinality is a warning) or STRICT (BT-24 cardinality is a hard error).
• SchematronValidator executes pre-compiled rule sets through the in-process XSLT processor and parses SVRL findings; an empty findings list does not make a non-conformant payload conformant.
• All XML parsing is XXE-safe: external-entity resolution disabled, DOCTYPE rejected, decompression bounded.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Core fallback

NextPDF Core does not generate or validate structured invoices. A Core-only deployment can produce a PDF but has no ZUGFeRD / Factur-X / Peppol embedding, no EN 16931 validator, and no Schematron engine.

Pro fallback

In a Pro-only deployment, the supported surface is Pro-tier e-invoice detection and validation of Factur-X / ZUGFeRD payloads. Pro does not generate ZUGFeRD / Factur-X or Peppol-UBL hybrid carriers, does not add the XRechnung CIUS profile, and does not run the in-process Schematron engine; a configuration that requests generation, the XRechnung CIUS profile, or Schematron in a Pro-only deployment has no Enterprise component to satisfy it. See Pro Compliance for the Pro detection and validation surface.

Enterprise boundary note

Internal mechanism detail stays in the source repository’s internal documentation and is out of scope for this manual.

Deployment boundary

The Schematron engine requires the ext-xsl PHP extension; provisioning and enabling it is the operator’s responsibility. Processing is in-process and local; the module makes no outbound network calls during embedding or validation. National e-invoicing transport, clearance platforms, and archival systems are external to this module and are the operator’s responsibility.

Legal-compliance boundary

NextPDF produces structured invoices conforming to the data model defined in EN 16931 and reports rule findings. The invoice issuer is responsible for meeting the rules of relevant legislation. National e-invoicing platforms, clearance models, archival mandates, and digital-signature requirements vary by jurisdiction and are the issuer’s responsibility. Consult your tax and legal advisers.

See also

• Invoice reference — API-level reference for the embedders, validators, and Schematron engine.
• Pro Compliance — Pro-tier e-invoice detection and validation.
• Document E-Filing — court/registry delivery optimization.
• Enterprise overview
• Core vs Pro vs Enterprise feature matrix