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 自己的話摘要。