Hóa đơn

Tổng quan nhanh

NextPDF Enterprise tạo các hóa đơn lai có cấu trúc ZUGFeRD / Factur-X / Peppol-UBL và xác thực XML hóa đơn theo mô hình dữ liệu EN 16931 cùng các bộ quy tắc Schematron. Nó tạo ra các hóa đơn có cấu trúc tuân theo mô hình dữ liệu được định nghĩa trong EN 16931; nó không phải là một trình xác thực của cơ quan thuế và không chứng nhận tài liệu nào.

Khả dụng và cấp phép

Khả năng này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các class của khả năng này. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/enterprise:^3

Engine Schematron dùng extension ext-xsl của PHP. Hãy cài đặt và bật nó trước khi chạy xác thực Schematron.

Tổng quan khái niệm

Module Invoice có ba bề mặt độc lập: nhúng (embedding) hóa đơn có cấu trúc, xác thực XML EN 16931, và thực thi quy tắc Schematron.

Nhúng. ZugferdEmbedder đính kèm một payload XML ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII do người gọi cung cấp vào một carrier PDF/A, tạo ra một hóa đơn lai. Hai định dạng carrier được hỗ trợ: PDF/A-4f (ISO 19005-4:2020), carrier hiện đại được ưu tiên, và PDF/A-3b (ISO 19005-3:2012) để tương thích ngược. ZugferdXmpSchema tiêm khai báo extension-schema XMP của Factur-X mà carrier cần. PeppolEmbedder thực hiện cùng vai trò cho XML hóa đơn hoặc credit-note Peppol BIS Billing 3.0 UBL 2.1 do người gọi cung cấp, đính kèm nó với quan hệ associated-file và kiểu MIME đúng. NextPDF không tổng hợp XML hóa đơn; người gọi cung cấp XML hợp lệ và vẫn là bên phát hành hóa đơn.

Xác thực. InvoiceXmlValidator kiểm tra XML hóa đơn theo mô hình dữ liệu ngữ nghĩa EN 16931 và các kỳ vọng về container ZUGFeRD / Factur-X, bao gồm specification identifier BT-24 mà quy tắc nghiệp vụ BR-1 của EN 16931 bắt buộc. Nó chạy ở một trong hai chế độ: COMPAT (mặc định; các phát hiện cardinality EN 16931 ở ranh giới được báo cáo dưới dạng cảnh báo để giữ tương thích ngược cho các fixture hiện có) và STRICT (cardinality BT-24 là một lỗi cứng, phản chiếu ngữ nghĩa của các trình xác thực bên ngoài). Chế độ có thể chọn theo từng lời gọi, theo override môi trường, hoặc theo chính sách phù hợp tiêu chuẩn.

Schematron. SchematronValidator chạy các bộ quy tắc Schematron đã biên dịch sẵn (các quy tắc .sch CEN EN 16931 được biên dịch thành XSLT tại thời điểm build) trên XML hóa đơn bằng bộ xử lý XSLT trong tiến trình của PHP, và phân tích báo cáo SVRL thành các phát hiện có cấu trúc. Enum ZugferdProfile mô hình hóa các hồ sơ phù hợp tiêu chuẩn — MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, và CIUS XRechnung B2G của Đức trên nền EN 16931.

Module này tuyên bố và không tuyên bố điều gì

Module này tạo và kiểm tra dữ liệu hóa đơn có cấu trúc. Nó không khẳng định rằng một tài liệu 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 sẽ được bất kỳ cơ quan nào chấp nhận.

• Trình xác thực chỉ kiểm tra mô hình ngữ nghĩa EN 16931 và container ZUGFeRD / Factur-X / UBL. Nó không phải là một trình xác thực của cơ quan thuế. Các mở rộng quốc gia và nền tảng clearance — ví dụ SDI của Ý, Chorus Pro của Pháp, transport XRechnung của Đức — nằm ngoài phạm vi ở mức transport.
• Như chính EN 16931-1 nêu, mô hình ngữ nghĩa lõi mang theo thông tin thiết yếu mà một hóa đơn điện tử cần để hỗ trợ tuân thủ pháp lý và tài chính; bên phát hành hóa đơn chịu trách nhiệm đáp ứng các quy định của luật pháp liên quan. Đây không phải là một trình xác thực của cơ quan thuế.
• Việc hỗ trợ một tiêu chuẩn không giống với việc phù hợp với nó. Hãy tham vấn các cố vấn thuế và tuân thủ của bạn để đánh giá tính đầy đủ về quy định trong khu vực pháp lý của bạn.

Vì sao nó hoạt động theo cách này

Module cố ý không bao giờ tổng hợp XML hóa đơn. Nhúng, xác thực EN 16931, và thực thi Schematron là ba bề mặt độc lập trên XML mà người gọi cung cấp và sở hữu. Điều này giữ cho NextPDF là một bên tạo và kiểm tra, không bao giờ là bên phát hành, vì trách nhiệm pháp lý không thể ủy thác cho một thư viện. Xác thực mặc định là COMPAT, nên một phát hiện cardinality ở ranh giới là một cảnh báo chứ không phải một sự thoái lui. STRICT là tùy chọn bật khi bạn cần ngữ nghĩa của trình xác thực bên ngoài. Kết quả là một sự tách bạch rõ ràng: NextPDF báo cáo những gì nó quan sát được, và bên phát hành quyết định liệu tài liệu có đáp ứng luật hay không. Bối cảnh thiết kế: Hóa đơn và hóa đơn điện tử.

Bề mặt API

Class	Trách nhiệm
ZugferdEmbedder	Đính kèm XML ZUGFeRD / Factur-X CII vào một carrier PDF/A-4f hoặc PDF/A-3b.
ZugferdXmpSchema	Tiêm khai báo extension-schema XMP của Factur-X.
ZugferdProfile	Enum hồ sơ phù hợp tiêu chuẩn (MINIMUM … EXTENDED, XRECHNUNG).
PeppolEmbedder	Đính kèm XML hóa đơn / credit-note Peppol BIS 3.0 UBL vào một carrier PDF/A.
InvoiceXmlValidator	Kiểm tra XML theo mô hình dữ liệu EN 16931; chế độ COMPAT hoặc STRICT.
InvoiceValidatorMode	Enum chế độ xác thực: COMPAT (mặc định) hoặc STRICT.
SchematronValidator	Chạy các bộ quy tắc Schematron đã biên dịch sẵn; phân tích các phát hiện SVRL.
InvoiceValidationResult / SchematronResult	Kết quả có cấu trúc: hồ sơ, các phát hiện, mức độ nghiêm trọng.

Mẫu mã — Bắt đầu nhanh

use NextPDF\Enterprise\Invoice\ZugferdEmbedder;
use NextPDF\Enterprise\Invoice\ZugferdProfile;

$pdf = ZugferdEmbedder::basic($pdfAManager, $fileAttachment, $ciiXml)
    ->embed(ZugferdProfile::EN16931);

Mẫu mã — Production

use NextPDF\Enterprise\Invoice\InvoiceXmlValidator;
use NextPDF\Enterprise\Invoice\InvoiceValidatorMode;

$result = $validator->validate($ciiXml, InvoiceValidatorMode::STRICT);

foreach ($result->findings as $finding) {
    $logger->warning('invoice.finding', [
        'rule'     => $finding->ruleId,
        'severity' => $finding->severity->value,
    ]);
}
// A clean result is one input to your decision, not a compliance verdict.
// The invoice issuer remains responsible for relevant legislation.

Trường hợp biên và lưu ý

• Một PDF đúng định dạng nhưng không mang payload hóa đơn nhận diện được sẽ cho ra một kết quả “not an invoice” thay vì ném lỗi.
• COMPAT là chế độ xác thực mặc định: một specification identifier BT-24 còn thiếu được báo cáo dưới dạng cảnh báo, để các điểm gọi gate trên một cờ hợp lệ boolean không bị thoái lui. Dùng STRICT để biến BT-24 thành một lỗi cứng khớp với ngữ nghĩa của KoSIT / Mustang bên ngoài.
• Người gọi cung cấp XML hóa đơn. NextPDF không tạo hay sửa nó; một danh sách phát hiện rỗng không làm cho một payload không phù hợp trở nên phù hợp.
• Engine Schematron yêu cầu ext-xsl. Các bộ quy tắc được biên dịch tại thời điểm build; runtime chỉ thực thi XSLT đã biên dịch sẵn.

Hiệu năng

Chi phí xác thực tỷ lệ với kích thước XML nhúng và số lượng quy tắc Schematron. Chi phí nhúng tỷ lệ với kích thước carrier và bị chi phối bởi việc tuần tự hóa PDF/A. Ngân sách hiệu năng của trang phản ánh việc render tài liệu, không phải thông lượng hóa đơn.

Ghi chú bảo mật

Mọi việc phân tích cú pháp XML đều đi qua XML guard đã được gia cố: việc phân giải external-entity bị tắt (an toàn XXE), DOCTYPE bị từ chối, và việc giải nén bị giới hạn. Bộ xử lý XSLT chạy với việc nạp tài nguyên mạng và hệ thống tệp bị tắt và không bao giờ đăng ký các hàm PHP, nên document(), xsl:include, xsl:import và result-document không thể tiếp cận mạng hay đĩa. Hãy coi XML hóa đơn từ các nguồn không tin cậy là thù địch.

Cư trú dữ liệu và biện pháp giảm thiểu PII

XML hóa đơn có thể chứa dữ liệu cá nhân, thương mại và tài chính. Việc xử lý diễn ra trong tiến trình và cục bộ; module không thực hiện cuộc gọi mạng đi ra nào trong quá trình nhúng hay xác thực. Hãy áp dụng các kiểm soát lưu giữ và tối thiểu hóa của riêng bạn cho XML và các phát hiện được trích xuất.

Telemetry an toàn và làm sạch nhật ký

Các phát hiện và nhật ký xác thực có thể bao gồm các định danh quy tắc và giá trị tag. Chúng không bao gồm payload hóa đơn đầy đủ. Hãy làm sạch hoặc che các giá trị trường trước khi chuyển tiếp nhật ký tới các sink dùng chung nếu những giá trị đó nhạy cảm.

Phù hợp tiêu chuẩn

Hành vi	Tham chiếu	Trạng thái
Mô hình ngữ nghĩa lõi của hóa đơn	EN 16931-1:2026 §4	Được xây dựng theo; bên phát hành vẫn chịu trách nhiệm về luật pháp liên quan
Specification identifier (BT-24)	EN 16931-1:2026 BR-1	Được kiểm tra (cảnh báo trong COMPAT, lỗi trong STRICT)
Syntax binding UN/CEFACT CII	CEN/TS 16931-3-3:2020	Hỗ trợ nhúng
Syntax binding UBL 2.1	CEN/TS 16931-3-2:2020	Hỗ trợ nhúng
Tệp đính kèm 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

Bảng này ghi lại các đặc tả mà NextPDF Enterprise được xây dựng theo và những gì nó kiểm tra. Nó không phải là một tuyên bố về chứng nhận, sự phê duyệt của cơ quan thuế, hay tính đầy đủ về quy định. Bên phát hành hóa đơn chịu trách nhiệm đáp ứng các quy định của luật pháp liên quan; đây không phải là một trình xác thực của cơ quan thuế.

Hành vi ở FIPS-mode

Module này không thực hiện việc ký mật mã nào. Việc ký một hóa đơn lai và việc lưu giữ khóa ở FIPS-mode nằm ngoài phạm vi ở đây; xem module Signature.

Mô hình mối đe dọa

XML hóa đơn không tin cậy là đầu vào chính. Biện pháp giảm thiểu: phân tích cú pháp an toàn XXE, từ chối DOCTYPE, giải nén có giới hạn, một bộ xử lý XSLT với việc nạp tài nguyên mạng và tệp bị tắt, và không tổng hợp tuyên bố — người gọi cung cấp và sở hữu nội dung hóa đơn.

Hợp đồng hành vi

• ZugferdEmbedder / PeppolEmbedder đính kèm XML hóa đơn do người gọi cung cấp vào một carrier PDF/A-4f hoặc PDF/A-3b; NextPDF không bao giờ tổng hợp XML hóa đơn.
• InvoiceXmlValidator chạy ở COMPAT (mặc định; cardinality EN 16931 ở ranh giới là một cảnh báo) hoặc STRICT (cardinality BT-24 là một lỗi cứng).
• SchematronValidator thực thi các bộ quy tắc đã biên dịch sẵn thông qua bộ xử lý XSLT trong tiến trình và phân tích các phát hiện SVRL; một danh sách phát hiện rỗng không làm cho một payload không phù hợp trở nên phù hợp.
• Mọi việc phân tích cú pháp XML đều an toàn XXE: phân giải external-entity bị tắt, DOCTYPE bị từ chối, giải nén bị giới hạn.

Ranh giới công bố

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

Phương án dự phòng Core

NextPDF Core không tạo hay xác thực các hóa đơn có cấu trúc. Một triển khai chỉ có Core có thể tạo một PDF nhưng không có việc nhúng ZUGFeRD / Factur-X / Peppol, không có trình xác thực EN 16931, và không có engine Schematron.

Phương án dự phòng Pro

Trong một triển khai chỉ có Pro, bề mặt được hỗ trợ là việc phát hiện và xác thực hóa đơn điện tử bậc Pro của các payload Factur-X / ZUGFeRD. Pro không tạo các carrier lai ZUGFeRD / Factur-X hay Peppol-UBL, không thêm hồ sơ CIUS XRechnung, và không chạy engine Schematron trong tiến trình; một cấu hình yêu cầu việc tạo, hồ sơ CIUS XRechnung, hay Schematron trong một triển khai chỉ có Pro không có thành phần Enterprise nào để đáp ứng nó. Xem Pro Compliance để biết bề mặt phát hiện và xác thực của Pro.

Ghi chú ranh giới Enterprise

Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của kho mã nguồn và ngoài phạm vi của sổ tay này.

Ranh giới triển khai

Engine Schematron yêu cầu extension PHP ext-xsl; việc cấp phát 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ộ; module không thực hiện cuộc gọi mạng đi ra nào trong quá trình nhúng hay 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 ngoài module này và là trách nhiệm của người vận hành.

Ranh giới tuân thủ pháp lý

NextPDF tạo các hóa đơn có cấu trúc tuân theo mô hình dữ liệu được định nghĩa trong EN 16931 và báo cáo các phát hiện về 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 rằng bất kỳ hóa đơn nào sẽ được một cơ quan thuế, tòa án hay cơ quan đăng ký chấp nhận. Bên phát hành hóa đơn chịu trách nhiệm đáp ứng các quy định của luật pháp liên quan; đây không phải là một trình xác thực của cơ quan thuế. Các nền tảng hóa đơn điện tử quốc gia, các mô hình clearance, các yêu cầu lưu trữ bắt buộc, và các yêu cầu chữ ký số khác nhau theo khu vực pháp lý và là trách nhiệm của bên phát hành. Hãy tham vấn các cố vấn thuế và pháp lý của bạn.

Xem thêm

• Invoice reference — tham chiếu mức API cho các bộ nhúng, bộ xác thực, và engine Schematron.
• Pro Compliance — phát hiện và xác thực hóa đơn điện tử bậc Pro.
• Document E-Filing — tối ưu hóa việc gửi tới tòa án/cơ quan đăng ký.
• Tổng quan Enterprise
• Ma trận tính năng Core so với Pro so với Enterprise