Invoice — 深入參考

概覽

Invoice 模組有三個獨立的介面：嵌入、驗證，以及 Schematron 規則執行。ZugferdEmbedder 與 PeppolEmbedder 會把呼叫端提供的發票 XML 附加到 PDF/A-4f 或 PDF/A-3b 載體上，並回傳一個結構化結果。InvoiceXmlValidator 會執行一道 EN 16931 結構預檢，其嚴重性可選 COMPAT 或 STRICT。SchematronValidator 會在行程內執行預先編譯的 Schematron 規則包，並剖析 SVRL findings。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 結構描述注入、附加	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 (enum)	—	列舉值 MINIMUM、BASIC_WL、BASIC、EN16931、EXTENDED、XRECHNUNG	—	—	XRECHNUNG 附加 xrechnung.xml；CII 設定檔附加 factur-x.xml
ZugferdXmpSchema::apply()	XmpMetadata, ZugferdProfile	註冊 Factur-X RDF 描述與 PDF/A 擴充結構描述項目	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	不拋出；失敗以錯誤 findings 呈現	模式的解析順序為引數、然後環境、然後 COMPAT
InvoiceXmlValidator::isCrossIndustryInvoice()	string $xmlData	對 CII 酬載進行根元素與命名空間檢查	bool	不拋出；回傳 false	低成本的偵測探針
InvoiceValidatorMode (enum)	—	COMPAT（預設）會把 BT-24 findings 維持在警告；STRICT 會把它們提升為錯誤	—	—	fromEnvironment() 在未設定或無法辨識的值時退回 COMPAT
InvoiceValidationResult / InvoiceValidationFinding	—	不可變的聚合：isValid、getErrors()、getWarnings()；每個 finding 有 level、code、message	—	—	InvoiceValidationResult::fail() 包裝單一錯誤
SchematronValidator::validate()	string $xsltPath, string $xmlData	執行預先編譯的 Schematron XSLT；把 SVRL 剖析為 findings	SchematronResult	XSLT 缺失或無法讀取時拋出 InvalidArgumentException；引擎失敗回傳錯誤結果	計時記錄於 durationMs
SchematronValidator::runRules()	string $xslPath, string $xmlPayload	跨層級轉接器；把錯誤 findings 對應到合約 RuleViolation 物件	list<RuleViolation>	與 validate() 相同	會略過 info 層級的 findings
SchematronResult / SchematronFinding	—	判定、findings、持續時間；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()	—	VersionPinException、InvalidArgumentException、鎖定 JSON 格式不正確時的 JsonException	空白或格式不正確的摘要會失敗關閉
InvoiceContractValidator	?SemanticValidator	跨層級 ValidatorInterface 轉接器；結構預檢加上 EN 16931 深度語意規則	ContractResult	失敗關閉；引擎錯誤以錯誤 findings 呈現	安裝 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 擴充結構描述宣告，並把該 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 物件；驗證器回傳 findings 而非拋出例外。

Schematron。SchematronValidator 會以行程內的 PHP XSLT 處理器，執行預先編譯的 Schematron 規則集——即在建置時編譯為 XSLT 的 CEN EN 16931 .sch 規則。它會把 SVRL 報告剖析為 SchematronFinding/SchematronResult 物件：失敗的斷言成為錯誤 findings，成功的報告成為 info findings。一個可選的快取（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 資料模型的結構化發票並回報規則 findings；它不產生合法合規的發票、不提供稅務機關核可的輸出，也不保證被接受。請諮詢你的稅務與法律顧問。

開發注意事項

• Schematron 引擎需要 ext-xsl PHP 擴充；佈建並啟用它是操作者的責任。
• 處理在行程內於本機進行。在嵌入或驗證期間不會發生任何對外網路呼叫。各國電子發票傳輸、結算平台與封存系統，屬於本模組之外。
• 規則包在建置時從 .sch 編譯為 XSLT；執行期只執行預先編譯的樣式表。
• 快取鍵會納入編譯器版本 salt（目前為 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 總覽