Enterprise phiên bản

Invoice — Tài liệu tham chiếu chuyên sâu

Nhìn tổng quan

Module Invoice có ba bề mặt độc lập: nhúng, xác thực, và thực thi quy tắc Schematron. ZugferdEmbedder và PeppolEmbedder đính kèm XML hóa đơn do bên gọi cung cấp vào một carrier PDF/A-4f hoặc PDF/A-3b và trả về một kết quả có cấu trúc. InvoiceXmlValidator chạy một pre-flight cấu trúc EN 16931 với mức độ nghiêm trọng COMPAT hoặc STRICT có thể chọn. SchematronValidator thực thi các bộ quy tắc Schematron đã biên dịch trước trong tiến trình và phân tích các phát hiện SVRL. NextPDF không tạo ra XML hóa đơn; bên gọi cung cấp và sở hữu payload.

Tình trạng khả dụng và cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt với một license envelope bậc Enterprise. Một triển khai không có entitlement đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Sắc thái theo từng bậc: phát hiện và xác thực hóa đơn điện tử là bề mặt bậc Pro (module Pro Compliance). Nhúng hóa đơn lai, profile XRechnung CIUS, và engine Schematron trong tiến trình chỉ có ở Enterprise. Không có mã năng lực riêng theo từng tính năng ngoài ranh giới gói nextpdf/enterprise.

Bề mặt Public API

composer require nextpdf/enterprise:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Nhúng CII XML profile BASIC: bước XmlGuard, xác thực cấu trúc, tiêm XMP schema, đính kèm	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Đường nhanh; điểm khởi đầu được khuyến nghị
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Cùng pipeline ở profile MINIMUM	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Đường nhanh
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Điểm vào builder; từ chối XML rỗng	`self`	`InvalidArgumentException`	Cấu hình qua `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Ghi đè quan hệ `/Alternative` mặc định; được kiểm soát bởi rulebook tệp liên kết	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` bị từ chối cho hóa đơn
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Lệnh gọi builder kết thúc: XmlGuard, xác thực tùy chọn, kiểm tra carrier, XMP, đính kèm	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Thất bại xác thực nêu tên lỗi đầu tiên
`ZugferdProfile` (enum)	—	Các case MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG đính kèm `xrechnung.xml`; các profile CII đính kèm `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Đăng ký mô tả RDF Factur-X và mục extension-schema PDF/A	`XmpMetadata`	Không	Được `embed()` gọi; cũng có thể dùng trực tiếp
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Nhúng XML hóa đơn hoặc credit-note Peppol BIS 3.0 UBL	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Tên tệp mặc định `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Điểm vào builder; từ chối XML hoặc tên tệp rỗng	`self`	`InvalidArgumentException`	Cấu hình qua `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Bước XmlGuard, kiểm tra carrier, cổng rulebook, đính kèm	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Kiểm tra lại rulebook có nhận biết carrier tại thời điểm nhúng
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	Pre-flight cấu trúc EN 16931; mức độ COMPAT mặc định	`InvoiceValidationResult`	Không ném; thất bại xuất hiện dưới dạng các phát hiện lỗi	Chế độ giải quyết theo tham số, rồi môi trường, rồi COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Kiểm tra root-element và namespace cho payload CII	`bool`	Không ném; trả về `false`	Thăm dò phát hiện chi phí thấp
`InvoiceValidatorMode` (enum)	—	`COMPAT` (mặc định) giữ các phát hiện BT-24 ở mức cảnh báo; `STRICT` nâng chúng thành lỗi	—	—	`fromEnvironment()` trở về COMPAT khi giá trị không đặt hoặc không nhận biết
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Các tổng hợp bất biến: `isValid`, `getErrors()`, `getWarnings()`; level, code, message theo từng phát hiện	—	—	`InvoiceValidationResult::fail()` bọc một lỗi đơn
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Thực thi một XSLT Schematron đã biên dịch trước; phân tích SVRL thành các phát hiện	`SchematronResult`	`InvalidArgumentException` cho XSLT thiếu hoặc không đọc được; thất bại engine trả về một kết quả lỗi	Thời gian được ghi trong `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Adapter liên bậc; ánh xạ các phát hiện lỗi sang các đối tượng `RuleViolation` của contract	`list<RuleViolation>`	Giống `validate()`	Các phát hiện mức info bị bỏ qua
`SchematronResult` / `SchematronFinding`	—	Kết luận, các phát hiện, thời lượng; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` đánh dấu các thất bại engine là không hợp lệ
`SchematronCacheInterface`	—	Contract cache phát hiện giả mạo: `getVerified()`, `set()`, `computeKey()`	—	—	Fail-closed khi digest không khớp
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	Cache tệp được kiểm chứng SHA-256 với ghi đổi-tên-nguyên-tử	—	`InvalidArgumentException`, `SchematronCacheException`	Thư mục phải tồn tại hoặc có thể tạo, và ghi được
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	Các pin bộ quy tắc khóa bằng SHA-256: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` khi lock JSON không đúng định dạng	Digest trống hoặc không đúng định dạng sẽ fail-closed
`InvoiceContractValidator`	`?SemanticValidator`	Adapter `ValidatorInterface` liên bậc; pre-flight cấu trúc cộng các quy tắc ngữ nghĩa sâu EN 16931	`ContractResult`	Fail-closed; lỗi engine xuất hiện dưới dạng các phát hiện lỗi	Được gắn trên các đường dẫn framework khi `nextpdf/premium` được cài
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Adapter `EmbedderInterface` liên bậc; nhúng byte-vào / byte-ra	`string` (byte PDF)	Truyền tiếp các thất bại của delegate	Ủy thác cho engine ghi-lại-byte bậc Pro
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Phân loại thất bại của module	—	—	Tất cả kế thừa `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

Hợp đồng hành vi

Nhúng. ZugferdEmbedder đính kèm một payload XML ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII do bên gọi cung cấp vào một carrier PDF/A. Nó hỗ trợ hai carrier: PDF/A-4f (ISO 19005-4:2020), carrier hiện đại được ưa dùng, và PDF/A-3b (ISO 19005-3:2012) để tương thích ngược. embed() luôn chạy một bước bảo mật XmlGuard trước, rồi xác thực cấu trúc trừ khi withoutValidation() được đặt, rồi kiểm chứng rằng carrier hỗ trợ tệp nhúng, tiêm khai báo XMP extension-schema qua ZugferdXmpSchema, và đính kèm XML như một tệp liên kết. Quan hệ đính kèm mặc định theo khuyến nghị /Alternative của rulebook; các ghi đè đi qua cùng rulebook đó, vốn thực thi tập quan hệ ISO 32000-2:2020 §14.13 và tập con hóa đơn EN 16931. PeppolEmbedder thực hiện việc tương đương cho XML hóa đơn hoặc credit-note Peppol BIS Billing 3.0 UBL 2.1 do bên gọi cung cấp. Không embedder nào tạo ra XML hóa đơn.

Xác thực. InvoiceXmlValidator kiểm tra CII XML so với các kỳ vọng cấu trúc EN 16931: root element, các phần bắt buộc, số lượng (cardinality) header, các dòng mục nơi profile yêu cầu chúng, và specification identifier BT-24 được business rule BR-1 bắt buộc. InvoiceValidatorMode chọn mức độ nghiêm trọng. COMPAT (mặc định) báo cáo một BT-24 bị thiếu hoặc không khớp như một cảnh báo để một cổng hợp lệ kiểu boolean không bị hồi quy. STRICT biến cả hai thành một lỗi cứng và còn khẳng định tính nhất quán profile so với ZugferdProfile được khai báo, phản ánh ngữ nghĩa của validator KoSIT / Mustang bên ngoài. Chế độ giải quyết theo thứ tự: tham số tường minh, rồi ghi đè môi trường INVOICE_VALIDATOR_MODE, rồi COMPAT. Kết quả là các đối tượng InvoiceValidationResult / InvoiceValidationFinding có cấu trúc; validator trả về các phát hiện thay vì ném exception.

Schematron. SchematronValidator thực thi các bộ quy tắc Schematron đã biên dịch trước — các quy tắc CEN EN 16931 .sch được biên dịch sang XSLT tại thời điểm build — bằng bộ xử lý XSLT PHP trong tiến trình. Nó phân tích báo cáo SVRL thành các đối tượng SchematronFinding / SchematronResult: các assertion thất bại trở thành các phát hiện lỗi, các report thành công trở thành các phát hiện info. Một cache tùy chọn (SchematronCacheInterface, với hiện thực file đổi-tên-nguyên-tử) cung cấp các byte stylesheet đã kiểm chứng, khóa theo digest nội dung cộng phiên bản compiler. VersionPinRegistry ghim mọi bộ quy tắc bên ngoài vào một phiên bản khóa bằng SHA-256 và fail-closed khi có trôi lệch hoặc digest không đúng định dạng.

Module này tạo ra và kiểm tra dữ liệu hóa đơn có cấu trúc. Nó không khẳng định rằng bất kỳ tài liệu nào là một hóa đơn tuân thủ pháp luật, rằng nó được cơ quan thuế phê duyệt, hay rằng nó được bảo đảm được bất kỳ cơ quan nào chấp nhận. Validator chỉ kiểm tra mô hình ngữ nghĩa EN 16931 và container ZUGFeRD / Factur-X / UBL; nó loại trừ các phần mở rộng quốc gia (ví dụ SDI của Ý, Chorus Pro của Pháp, transport XRechnung của Đức). Như EN 16931-1 nêu rõ, người phát hành hóa đơn chịu trách nhiệm đáp ứng các quy tắc của pháp luật liên quan; đây không phải là một validator của cơ quan thuế. Việc hỗ trợ một tiêu chuẩn không phải là sự phù hợp với tiêu chuẩn đó.

Trường hợp biên và các chế độ thất bại

XML rỗng thất bại nhanh: các builder ném InvalidArgumentException; InvoiceXmlValidator::validate() trả về một kết quả thất bại.
XmlGuard từ chối các khai báo DOCTYPE, giải nén thực thể, payload quá cỡ, và các ký tự điều khiển. Các embedder biểu lộ điều này thành ZugferdEmbeddingException hoặc PeppolEmbeddingException với nguyên nhân được giữ nguyên.
withoutValidation() và withoutSanitization() không bao giờ bỏ qua bước bảo mật XmlGuard. Chỉ các kiểm tra business-term cấu trúc là có thể bỏ qua.
Một carrier không hỗ trợ tệp nhúng (bất kỳ thứ gì khác PDF/A-4f hoặc PDF/A-3b) phát sinh InvalidArgumentException nêu tên các phiên bản được chấp nhận.
Một giá trị AFRelationship không được phép bị từ chối ở ranh giới builder; một lần kiểm tra lại rulebook có nhận biết carrier chạy lại bên trong embed().
COMPAT giữ một BT-24 bị thiếu ở mức độ nghiêm trọng cảnh báo; STRICT biến các giá trị BT-24 bị thiếu và không khớp profile thành lỗi cứng.
SchematronValidator chỉ ném khi đường dẫn XSLT thiếu hoặc không đọc được. Các thất bại transform hoặc phân tích SVRL trả về SchematronResult::error() với isValid bằng false.
Một mục cache có các byte lưu trữ không qua được kiểm chứng digest sẽ bị loại bỏ và stylesheet được đọc lại từ đĩa; các byte bị đầu độc không bao giờ được trả về.
Bộ xử lý XSLT chạy với việc nạp tài nguyên tệp và mạng bị chặn và không bao giờ đăng ký các hàm PHP; document(), xsl:include, xsl:import, và result-document không thể nạp tài nguyên.
VersionPinRegistry từ chối các digest SHA-256 trống hoặc không đúng định dạng khi nạp vào và khi tái tạo; verifyArtefact() trả về false thay vì cho qua một pin không thể kiểm chứng.
Module này không thực hiện ký bằng mật mã nào; hành vi ở chế độ FIPS nằm ngoài phạm vi ở đây (xem module Signature).

Phù hợp tiêu chuẩn

Hành vi	Tham chiếu	Trạng thái
Mô hình ngữ nghĩa hóa đơn cốt lõi	EN 16931-1:2026 §4	Xây dựng dựa trên; người phát hành vẫn chịu trách nhiệm
Specification identifier (BT-24)	EN 16931-1:2026 BR-1	Cảnh báo ở COMPAT, lỗi ở STRICT
UN/CEFACT CII syntax binding	CEN/TS 16931-3-3:2020	Hỗ trợ nhúng
UBL 2.1 syntax binding	CEN/TS 16931-3-2:2020	Hỗ trợ nhúng
Tệp liên kết PDF/A-3	ISO 19005-3:2012 §6.7.8	Hỗ trợ carrier
Tệp nhúng PDF/A-4f	ISO 19005-4:2020 Annex A	Hỗ trợ carrier
Các giá trị quan hệ tệp liên kết	ISO 32000-2:2020 §14.13	Được kiểm soát bởi rulebook
Phân tích báo cáo Schematron / SVRL	ISO/IEC 19757-3	Xây dựng dựa trên (dựa trên sản phẩm; tiêu chuẩn không có trong kho citation)

Xây dựng dựa trên, không phải chứng nhận hay phê duyệt của cơ quan thuế. NextPDF không nắm giữ chứng nhận nào cho bất kỳ tiêu chuẩn nào trong số này. NextPDF tạo ra các hóa đơn có cấu trúc phù hợp với mô hình dữ liệu EN 16931 và báo cáo các phát hiện quy tắc; nó không tạo ra các hóa đơn tuân thủ pháp luật, không cung cấp đầu ra được cơ quan thuế phê duyệt, và không bảo đảm được chấp nhận. Hãy tham vấn các cố vấn thuế và pháp lý của bạn.

Ghi chú phát triển

Engine Schematron yêu cầu extension PHP ext-xsl; việc cung cấp và bật nó là trách nhiệm của người vận hành.
Việc xử lý diễn ra trong tiến trình và cục bộ. Không có lệnh gọi mạng ra ngoài trong khi nhúng hoặc xác thực. Transport hóa đơn điện tử quốc gia, các nền tảng clearance, và các hệ thống lưu trữ nằm bên ngoài module này.
Các bộ quy tắc được biên dịch từ .sch sang XSLT tại thời điểm build; runtime chỉ thực thi các stylesheet đã biên dịch trước.
Các khóa cache gộp thêm salt phiên bản compiler (hiện tại nextpdf-schxslt-1.0); tăng nó lên làm vô hiệu các cache đã triển khai mà không cần một bước xóa.
Các pin bộ quy tắc nằm trong tệp lock tại enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI kiểm chứng các artifact đã triển khai so với các digest đã ghim.
Các bên gọi liên bậc dùng InvoiceContractValidator và ZugferdContractEmbedder; các bên gọi Enterprise bản-địa-bậc dùng ZugferdEmbedder và InvoiceXmlValidator trực tiếp.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp helper, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Năng lực Invoice — bản đối ứng năng lực của tài liệu tham chiếu này.
Pro Compliance — phát hiện/xác thực ở bậc Pro.
Document E-Filing
Tổng quan Enterprise