Invoice — 深度参考

概览

Invoice 模块有三个相互独立的接口面：内嵌、校验，以及 Schematron 规则执行。ZugferdEmbedder 与 PeppolEmbedder 会将调用方提供的发票 XML 附加到 PDF/A-4f 或 PDF/A-3b 载体上，并返回一个结构化结果。InvoiceXmlValidator 会运行一次 EN 16931 结构预检，其严重程度可选择 COMPAT 或 STRICT。SchematronValidator 会在进程内执行预编译的 Schematron 规则包，并解析 SVRL 发现。NextPDF 不生成发票 XML；载荷由调用方提供并拥有。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发布，并通过一个 Enterprise 层级的授权信封激活。缺少该授权项的部署不会加载此能力的类。比较版本并获取授权。

逐层级细节：电子发票检测与校验是 Pro 层级的接口面（Pro Compliance 模块）。混合发票内嵌、XRechnung CIUS 配置文件，以及进程内的 Schematron 引擎仅限 Enterprise。除 nextpdf/enterprise 包边界之外，没有单独的逐功能能力代码。

公共 API 接口面

composer require nextpdf/enterprise:^3

符号	参数	默认行为	返回	抛出或失败于	备注
ZugferdEmbedder::basic()	PdfAManager, FileAttachment, string $xmlData	内嵌 BASIC 配置文件的 CII XML：XmlGuard 检查、结构校验、XMP schema 注入、附加	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	快捷路径；推荐的起点
ZugferdEmbedder::minimum()	PdfAManager, FileAttachment, string $xmlData	在 MINIMUM 配置文件下使用相同流水线	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	快捷路径
ZugferdEmbedder::create()	ZugferdProfile, string $xmlData	Builder 入口；拒绝空 XML	self	InvalidArgumentException	通过 withoutValidation()、withDescription() 配置
ZugferdEmbedder::withAfRelationship() / PeppolEmbedder::withAfRelationship()	AFRelationship|string	覆盖默认的 /Alternative 关系；受关联文件规则手册限制	self	InvalidArgumentException	发票拒绝 Schema、EncryptedPayload、FormData
ZugferdEmbedder::embed()	PdfAManager, FileAttachment	终结性 builder 调用：XmlGuard、可选校验、载体检查、XMP、附加	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	校验失败会指明第一个错误
ZugferdProfile（枚举）	—	取值 MINIMUM、BASIC_WL、BASIC、EN16931、EXTENDED、XRECHNUNG	—	—	XRECHNUNG 附加 xrechnung.xml；CII 配置文件附加 factur-x.xml
ZugferdXmpSchema::apply()	XmpMetadata, ZugferdProfile	注册 Factur-X RDF 描述与 PDF/A 扩展 schema 条目	XmpMetadata	无	由 embed() 调用；也可直接使用
PeppolEmbedder::invoice() / ::creditNote()	PdfAManager, FileAttachment, string $ublXml	内嵌 Peppol BIS 3.0 UBL 发票或贷项通知 XML	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	默认文件名 invoice.xml / creditnote.xml
PeppolEmbedder::create()	string $ublXml, string $filename = 'invoice.xml'	Builder 入口；拒绝空 XML 或文件名	self	InvalidArgumentException	通过 withFilename()、withDescription()、withoutSanitization() 配置
PeppolEmbedder::embed()	PdfAManager, FileAttachment	XmlGuard 检查、载体检查、规则手册限制、附加	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	在内嵌时对载体感知的规则手册再检查一次
InvoiceXmlValidator::validate()	string $xmlData, ZugferdProfile, ?InvoiceValidatorMode	EN 16931 结构预检；默认 COMPAT 严重程度	InvoiceValidationResult	不抛出；失败以错误发现形式呈现	模式先解析参数，再解析环境，最后回退 COMPAT
InvoiceXmlValidator::isCrossIndustryInvoice()	string $xmlData	对 CII 载荷进行根元素与命名空间检查	bool	不抛出；返回 false	低成本检测探针
InvoiceValidatorMode（枚举）	—	COMPAT（默认）将 BT-24 发现保持为警告；STRICT 将其提升为错误	—	—	fromEnvironment() 在未设置或无法识别的取值上回退 COMPAT
InvoiceValidationResult / InvoiceValidationFinding	—	不可变聚合：isValid、getErrors()、getWarnings()；每条发现含级别、代码、消息	—	—	InvoiceValidationResult::fail() 封装单个错误
SchematronValidator::validate()	string $xsltPath, string $xmlData	执行预编译的 Schematron XSLT；将 SVRL 解析为发现	SchematronResult	XSLT 缺失或不可读抛出 InvalidArgumentException；引擎失败返回一个错误结果	计时记录于 durationMs
SchematronValidator::runRules()	string $xslPath, string $xmlPayload	跨层级适配器；将错误发现映射为契约 RuleViolation 对象	list<RuleViolation>	同 validate()	跳过 info 级别的发现
SchematronResult / SchematronFinding	—	结论、发现、时长；getFailedAssertions()、getSuccessfulReports()	—	—	SchematronResult::error() 将引擎失败标记为无效
SchematronCacheInterface	—	篡改检测缓存契约：getVerified()、set()、computeKey()	—	—	在摘要不匹配时失败关闭
AtomicRenameSchematronCache	string $cacheDir, bool $atomicRename = true, LoggerInterface	采用原子重命名写入、经 SHA-256 校验的文件缓存	—	InvalidArgumentException, SchematronCacheException	目录必须存在或可创建，且可写
VersionPinRegistry	array $pins, ?string $sourcePath	经 SHA-256 锁定的规则包固定：loadFromLockFile()、get()、verifyArtefact()、regenerateLockFile()	—	锁文件 JSON 格式错误时抛出 VersionPinException、InvalidArgumentException、JsonException	空白或格式错误的摘要失败关闭
InvoiceContractValidator	?SemanticValidator	跨层级 ValidatorInterface 适配器；结构预检加 EN 16931 深度语义规则	ContractResult	失败关闭；引擎错误以错误发现形式呈现	在安装 nextpdf/premium 时绑定到框架路径
ZugferdContractEmbedder	FacturXContractEmbedder	跨层级 EmbedderInterface 适配器；字节进/字节出内嵌	string（PDF 字节）	传播委托失败	委托给 Pro 层级的字节重写引擎
ZugferdEmbeddingException, PeppolEmbeddingException, SchematronCacheException, VersionPinException	—	模块失败分类	—	—	均继承自 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

行为契约

内嵌。 ZugferdEmbedder 会将调用方提供的 ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML 载荷附加到一个 PDF/A 载体上。它支持两种载体：PDF/A-4f（ISO 19005-4:2020），即首选的现代载体，以及为向后兼容而保留的 PDF/A-3b（ISO 19005-3:2012）。embed() 总是先运行一次 XmlGuard 安全检查，然后在未设置 withoutValidation() 时进行结构校验，接着验证载体支持内嵌文件，经由 ZugferdXmpSchema 注入 XMP 扩展 schema 声明，并将该 XML 作为关联文件附加。附件关系默认为规则手册推荐的 /Alternative；覆盖值会经过同一规则手册，该手册强制执行 ISO 32000-2:2020 §14.13 的关系集合与 EN 16931 发票子集。PeppolEmbedder 针对调用方提供的 Peppol BIS Billing 3.0 UBL 2.1 发票或贷项通知 XML 执行等效操作。两个内嵌器都不生成发票 XML。

校验。 InvoiceXmlValidator 会依照 EN 16931 结构预期检查 CII XML：根元素、必需的分节、表头基数、在配置文件要求处的行项目，以及由业务规则 BR-1 强制要求的 BT-24 规范标识符。InvoiceValidatorMode 用于选择严重程度。COMPAT（默认）会将缺失或不匹配的 BT-24 报告为警告，以免一个布尔有效性门槛发生回退。STRICT 会将其变为硬错误，并额外针对声明的 ZugferdProfile 断言配置文件一致性，对齐外部 KoSIT / Mustang 校验器的语义。该模式按以下顺序解析：显式参数，然后是 INVOICE_VALIDATOR_MODE 环境覆盖，最后是 COMPAT。结果是结构化的 InvoiceValidationResult / InvoiceValidationFinding 对象；该校验器返回发现而非抛出异常。

Schematron。 SchematronValidator 会执行预编译的 Schematron 规则集——即在构建时编译为 XSLT 的 CEN EN 16931 .sch 规则——使用进程内的 PHP XSLT 处理器。它会将 SVRL 报告解析为 SchematronFinding / SchematronResult 对象：失败的断言成为错误发现，成功的报告成为 info 发现。一个可选缓存（SchematronCacheInterface，带有原子重命名的文件实现）会依内容摘要加编译器版本为键，提供经校验的样式表字节。VersionPinRegistry 会将每个外部规则包固定到一个经 SHA-256 锁定的版本，并在发生漂移或摘要格式错误时失败关闭。

该模块生产并检查结构化发票数据。它不断言任何文档是一份法律合规的发票、是经税务机关批准的，或保证会被任何机关受理。该校验器仅检查 EN 16931 语义模型以及 ZUGFeRD / Factur-X / UBL 容器；它排除各国扩展（例如意大利 SDI、法国 Chorus Pro、德国 XRechnung 传输）。正如 EN 16931-1 所述，发票开具方有责任满足相关立法的规则；这不是一个税务机关校验器。对某项标准的支持并不等于符合该标准。

边界情形与失败模式

• 空 XML 会快速失败：builder 抛出 InvalidArgumentException；InvoiceXmlValidator::validate() 返回一个失败结果。
• XmlGuard 会拒绝 DOCTYPE 声明、实体展开、超大载荷以及控制字符。内嵌器会将其以 ZugferdEmbeddingException 或 PeppolEmbeddingException 呈现，并保留原始原因。
• withoutValidation() 与 withoutSanitization() 绝不会绕过 XmlGuard 安全检查。仅结构性的业务术语检查可被跳过。
• 不支持内嵌文件的载体（除 PDF/A-4f 或 PDF/A-3b 之外的任何载体）会引发 InvalidArgumentException，并指明可接受的版本。
• 不被允许的 AFRelationship 取值会在 builder 边界处被拒绝；在 embed() 内部会再运行一次载体感知的规则手册再检查。
• COMPAT 会将缺失的 BT-24 保持在警告严重程度；STRICT 会将缺失以及配置文件不匹配的 BT-24 取值变为硬错误。
• SchematronValidator 仅在 XSLT 路径缺失或不可读时抛出。转换或 SVRL 解析失败会返回 isValid 为 false 的 SchematronResult::error()。
• 存储字节未通过摘要校验的缓存条目会被逐出，并从磁盘重新读取样式表；被污染的字节绝不会被返回。
• XSLT 处理器在文件与网络资源加载被阻断的情况下运行，且从不注册 PHP 函数；document()、xsl:include、xsl:import 与 result-document 均无法加载资源。
• VersionPinRegistry 会在摄入时与再生成时拒绝空白或格式错误的 SHA-256 摘要；verifyArtefact() 会返回 false，而非放行一个无法核实的固定。
• 本模块不执行任何密码学签名；FIPS 模式行为不在此处范围内（参见 Signature 模块）。

符合性

行为	参考	状态
核心发票语义模型	EN 16931-1:2026 §4	依其构建；开具方仍负有责任
规范标识符（BT-24）	EN 16931-1:2026 BR-1	COMPAT 中为警告，STRICT 中为错误
UN/CEFACT CII 语法绑定	CEN/TS 16931-3-3:2020	支持内嵌
UBL 2.1 语法绑定	CEN/TS 16931-3-2:2020	支持内嵌
PDF/A-3 关联文件	ISO 19005-3:2012 §6.7.8	支持该载体
PDF/A-4f 内嵌文件	ISO 19005-4:2020 Annex A	支持该载体
关联文件关系取值	ISO 32000-2:2020 §14.13	受规则手册限制
Schematron / SVRL 报告解析	ISO/IEC 19757-3	依其构建（以产品为依据；该标准不在引用语料库中）

依其构建，而非认证或税务机关批准。NextPDF 未持有上述任何标准的认证。NextPDF 生产符合 EN 16931 数据模型的结构化发票并报告规则发现；它不生产法律合规的发票、不提供经税务机关批准的输出，也不保证受理。请咨询你的税务与法律顾问。

开发说明

• Schematron 引擎需要 ext-xsl PHP 扩展；预置并启用它是运营方的责任。
• 处理在进程内本地完成。在内嵌或校验期间不发生任何对外网络调用。各国电子发票传输、清算平台与归档系统位于本模块之外。
• 规则包在构建时从 .sch 编译为 XSLT；运行时仅执行预编译的样式表。
• 缓存键会折入编译器版本盐值（当前为 nextpdf-schxslt-1.0）；提升它会使已部署的缓存失效，而无需清除步骤。
• 规则包固定存放在位于 enterprise/config/invoice-versions.lock 的锁文件中（VersionPinRegistry::DEFAULT_LOCK_PATH）；CI 会针对固定的摘要校验已部署的工件。
• 跨层级调用方使用 InvoiceContractValidator 与 ZugferdContractEmbedder；层级原生的 Enterprise 调用方直接使用 ZugferdEmbedder 与 InvoiceXmlValidator。

发布边界

本页仅记录外部可观察的行为以及受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀不在范围内。

另请参阅

• Invoice 能力 —— 本参考的能力对应页。
• Pro Compliance —— Pro 层级的检测/校验。
• Document E-Filing
• Enterprise 概述