ZUGFeRD / Factur-X 一致性：内嵌的 EN 16931 发票配置文件

快速概览

边界声明。 NextPDF 产生内嵌的 XML 配置文件；税务与法律有效性由收件机关决定，而非库。

ZUGFeRD / Factur-X 是一种混合发票：一份人类可读的 PDF（以 PDF/A-3 作为归档基底），其中内嵌一份机器可读、遵循 EN 16931 语义数据模型的跨行业发票（Cross-Industry-Invoice，CII）XML。NextPDF Core 提供 嵌入器契约（NextPDF\Contracts\EInvoice）；具体的 Factur-X 1.08 引擎随 Premium 的 nextpdf/pro 包提供。库负责产生内嵌的 XML 与 PDF/A-3 附件结构；税务有效性则由 EN 16931 / Schematron 验证器，或由收件税务机关决定。

安装

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

Core 提供 EmbedderInterface、ProfileInterface、ProfileType、ValidatorInterface 以及 ValidationResult，均位于 NextPDF\Contracts\EInvoice 之下。接口的 docblock 已明确指出：Pro 层（Factur-X 1.08 字节重写引擎）与 Enterprise 层（PDF/A 托管构建器）负责实现此契约。Core 本身不会内嵌发票；它定义的是各层需要满足的 byte-in/byte-out 契约。

概念总览

NextPDF\Contracts\EInvoice\ProfileType 是判断 EN 16931 一致性的依据：MINIMUM、BASIC_WL、BASIC、EN16931、EXTENDED、XRECHNUNG。它的 isEn16931Conformant() 直接按 EN 16931-1 编码这项规则。MINIMUM 与 BASIC_WL 并非 EN 16931 一致（它们不符合 BT-24 规格标识符基数规则与逐项明细要求）。BASIC、EN16931、EXTENDED、XRECHNUNG 为 EN 16931 一致。

嵌入器（EmbedderInterface）按照契约必须：

通过 XmlGuard 解析提供的 CII XML（防 XXE）；
为所声明的配置文件注入 Factur-X 的 XMP 扩展 schema；
以正确的 AFRelationship（Data / Alternative）将 XML 作为内嵌文件附加，使 PDF/A-3 归档基底（§6.7.5 内嵌文件要求——F/UF 键）能够承载它。

NextPDF 产出这个结构。它并不主张该发票在税务上有效；该判定属于收件机关，依据 EN 16931 §7 业务规则以及任何国家级的 CIUS 作出。

API 接口

符号	作用
`Contracts\EInvoice\EmbedderInterface`	byte-in/byte-out 契约；由 Pro/Enterprise 实现。
`Contracts\EInvoice\ProfileType`（枚举）	EN 16931 配置文件的判别依据。
`ProfileType::isEn16931Conformant(): bool`	对 MINIMUM/BASIC_WL 返回 false；对 BASIC/EN16931/EXTENDED/XRECHNUNG 返回 true。
`Contracts\EInvoice\ValidatorInterface`	验证契约，返回一份记录规则违反项的 `ValidationResult`。

代码示例——快速上手

<?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";

代码示例——生产环境

生产环境管线（Pro 层）会把 CII XML 嵌入 PDF/A-3 基底。接着它会执行 EN 16931 Schematron 验证器（或提交给收件机关）。它把那份报告视为 gate（把关）。NextPDF 产出内嵌的 XML 与 PDF/A-3 附件；税务有效性由 validator/authority 决定。Core 本身无法执行这条管线；嵌入器引擎需要 nextpdf/pro。

边界情况与陷阱

Core 只有契约。 没有 nextpdf/pro 就没有具体的嵌入器。调用端代码必须依赖接口，并在 Pro 实现缺席时明确降级处理。
MINIMUM / BASIC_WL 并非 EN 16931。 isEn16931Conformant() 对这些配置文件返回 false；使用它们时不要对外宣称是 EN 16931 发票。
PDF/A-3 基底。 内嵌的 XML 承载于 PDF/A-3 归档容器中；内嵌文件的 F/UF 键（PDF/A §6.7.5）必须存在。
XML 以防 XXE 方式解析。 此契约要求使用 XmlGuard 解析；自定义的嵌入器不得引入 XXE 漏洞。
有效性并非库的裁决。 产出一份结构正确的 Factur-X 文件，并不等于声明税务机关会接受它。

性能

内嵌会重写 PDF，以加入 XML 附件与 XMP 扩展 schema。预算上限为一般发票挂钟时间 ≤ 1500 ms、峰值内存 ≤ 128 MB。

安全注意事项

内嵌的 XML 会通过 XmlGuard 以防 XXE 方式解析。发票 XML 本质上含有商业 PII（交易方、金额）；它是内嵌的，并未加密。发票的机密性由集成者负责。

数据驻留与 PII 缓解

发票 XML 承载交易方与财务 PII。内嵌是在进程内完成；内嵌过程中没有任何数据离开该进程。传输到收件机关不在本页范围内，而属于集成者的数据驻留责任。

安全遥测与日志清洗

切勿记录 CII XML 或内嵌后的 PDF 字节——它们含有发票 PII。只记录配置文件名称与结构性判定结果。

威胁模型

Factur-X 文件不受访问控制保护。任何持有该文件的人都能读取内嵌的 XML。这种混合文件保证的是发票的机器可读性，而非机密性或税务上的接受度。

FIPS 模式行为

内嵌不执行任何密码学运算。已签名的 Factur-X 发票属于另一项签名配方的议题，并沿用该配方的 FIPS 态势；本页不对签名作任何主张。

一致性

主张	规格	条款
EN 16931 发票承载语义数据模型的业务术语。	EN 16931-1	§6.4
EN 16931 合规受业务规则基数约束；一份一致的发票必须满足这些基数。	EN 16931-1	§7
Factur-X 的 EN 16931 配置文件要求 CII-XML 符合业务规则一致性要求。	Factur-X 1.08 规范	EN 16931 配置文件
Factur-X 的 EN 16931 配置文件规定了必填的发票内容。	Factur-X 1.08 规范	EN 16931 配置文件
Factur-X 是一种混合文件：机器可读的 XML 与人类可读的 PDF 一同内嵌。	Factur-X 1.08 规范	基础
内嵌的 XML 承载于 PDF/A 归档基底中（内嵌文件的 F/UF 键）。	ISO 19005-4	§6.7.5

引用采用条款 ID 加 reference_id 指针，指向验证语料库。不复制任何标准原文；条款均以 NextPDF 自己的话概括。