ZUGFeRD / Factur-X conformance: the embedded EN 16931 invoice profile

At a glance

Boundary statement. NextPDF produces the embedded XML profile; fiscal and legal validity is decided by the receiving authority, not the library.

ZUGFeRD / Factur-X is a hybrid invoice: a human-readable PDF (a PDF/A-3 archival substrate) with an embedded machine-readable Cross-Industry-Invoice (CII) XML that follows the EN 16931 semantic data model. NextPDF Core ships the embedder contract (NextPDF\Contracts\EInvoice); the concrete Factur-X 1.08 engine ships in the Premium nextpdf/pro package. The library produces the embedded XML and PDF/A-3 attachment structure. An EN 16931 / Schematron validator, or the receiving tax authority, decides fiscal validity.

Install

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core ships EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface, and ValidationResult in NextPDF\Contracts\EInvoice. The interface docblock is explicit: the Pro tier (Factur-X 1.08 byte-rewrite engine) and the Enterprise tier (PDF/A-managed builder) implement this contract. Core alone does not embed an invoice. It defines the byte-in/byte-out contract those tiers satisfy.

Conceptual overview

NextPDF\Contracts\EInvoice\ProfileType is the EN 16931 conformance discriminator: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Its isEn16931Conformant() encodes the rule directly from EN 16931-1. MINIMUM and BASIC_WL are not EN 16931 conformant (they fail the BT-24 specification-identifier cardinality and the line-item requirement). BASIC, EN16931, EXTENDED, XRECHNUNG are EN 16931 conformant.

The embedder (EmbedderInterface) is contracted to:

parse the supplied CII XML through XmlGuard (XXE-safe);
inject the Factur-X XMP extension schema for the declared profile;
attach the XML as an embedded file with the correct AFRelationship (Data / Alternative) so the PDF/A-3 archival substrate (§6.7.5 embedded-file requirements — F/UF keys) carries it.

NextPDF emits this structure. It does not assert that the invoice is fiscally valid. The receiving authority makes that determination against EN 16931 §7 business rules and any national CIUS.

API surface

Symbol	Effect
`Contracts\EInvoice\EmbedderInterface`	Byte-in/byte-out contract; Pro/Enterprise implement it.
`Contracts\EInvoice\ProfileType` (enum)	EN 16931 profile discriminator.
`ProfileType::isEn16931Conformant(): bool`	False for MINIMUM/BASIC_WL; true for BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Validation contract returning a `ValidationResult` of rule violations.

Code sample — Quick start

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ProfileType;

// Core: choose and check the profile before delegating embedding to Pro.
$profile = ProfileType::EN16931;

if (!$profile->isEn16931Conformant()) {
    fwrite(STDERR, "Profile {$profile->value} is not EN 16931 conformant.\n");
    exit(1);
}

// The concrete embedder is provided by nextpdf/pro:
//   $embedder = /* the Factur-X embedder from nextpdf/pro; see the Premium docs */;
//   $pdfWithInvoice = $embedder->embed($basePdfBytes, $ciiXml, $options);
echo "Profile {$profile->value} selected (embedding requires nextpdf/pro).\n";

Code sample — Production

The production pipeline (Pro tier) embeds the CII XML into a PDF/A-3 base. It then runs an EN 16931 Schematron validator, or submits to the receiving authority, and treats that report as the gate. NextPDF emits the embedded XML and PDF/A-3 attachment; the validator or authority decides fiscal validity. Core alone cannot run this pipeline. nextpdf/pro is required for the embedder engine.

Edge cases & gotchas

Core has contracts only. Without nextpdf/pro there is no concrete embedder. Calling code must depend on the interface and degrade clearly when the Pro implementation is absent.
MINIMUM / BASIC_WL are not EN 16931. isEn16931Conformant() returns false for these; do not advertise an EN 16931 invoice when using them.
PDF/A-3 substrate. The embedded XML rides in a PDF/A-3 archival container; the embedded-file F/UF keys (PDF/A §6.7.5) must be present.
XML is parsed XXE-safe. The contract requires XmlGuard parsing; a custom embedder must not introduce an XXE sink.
Validity is not the library’s verdict. Producing a structurally correct Factur-X file does not mean the tax authority will accept it.

Performance

Embedding rewrites the PDF to add the XML attachment and the XMP extension schema. Budgeted at wall ≤ 1500 ms, peak ≤ 128 MB for a typical invoice.

Security notes

The embedded XML is parsed XXE-safe via XmlGuard. The invoice XML contains commercial personally identifiable information (PII), including parties and amounts. It is embedded, not encrypted. Invoice confidentiality is the integrator’s responsibility.

Data Residency & PII Mitigations

The invoice XML carries party and financial PII. Embedding is in-process; no data leaves the process during embedding. Transmission to a receiving authority is out of scope and is the integrator’s data-residency responsibility.

Safe Telemetry & Log Scrubbing

Never log the CII XML or the embedded PDF bytes — they contain invoice PII. Log only the profile name and a structural verdict.

Threat model

A Factur-X file is not access-controlled. The embedded XML is readable by anyone with the file. The hybrid guarantees machine-readability of the invoice, not its confidentiality or its fiscal acceptance.

FIPS-mode behavior

Embedding performs no cryptography. A signed Factur-X invoice is a separate signature-recipe concern and inherits that recipe’s FIPS posture. This page makes no signing claim.

Conformance

Claim	Spec	Clause
An EN 16931 invoice carries the semantic-data-model business terms.	EN 16931-1	§6.4
EN 16931 compliance is governed by business-rule cardinality a conformant invoice shall satisfy.	EN 16931-1	§7
The Factur-X EN 16931 profile requires CII-XML business-rule conformance.	Factur-X 1.08	EN 16931 profile
The Factur-X EN 16931 profile mandates the required invoice content.	Factur-X 1.08	EN 16931 profile
Factur-X is a hybrid: machine-readable XML embedded alongside the human-readable PDF.	Factur-X 1.08	Basic
The embedded XML rides in a PDF/A archival substrate (embedded-file F/UF keys).	ISO 19005-4	§6.7.5

Citations are clause-id + reference_id pointers into the verification corpus. No standards text is reproduced; clauses are summarized in NextPDF’s words.