Tuân thủ ZUGFeRD / Factur-X: hồ sơ hóa đơn EN 16931 được nhúng

Tổng quan nhanh

Tuyên bố về ranh giới. NextPDF tạo ra hồ sơ XML được nhúng; tính hợp lệ về thuế và pháp lý do cơ quan tiếp nhận quyết định, không phải thư viện.

ZUGFeRD / Factur-X là hóa đơn lai: một tệp PDF người đọc được (trên nền lưu trữ PDF/A-3) kèm một XML Cross-Industry-Invoice (CII) máy đọc được, được nhúng và tuân theo mô hình dữ liệu ngữ nghĩa EN 16931. NextPDF Core cung cấp hợp đồng embedder (NextPDF\Contracts\EInvoice); engine Factur-X 1.08 cụ thể nằm trong gói Premium nextpdf/pro. Thư viện tạo cấu trúc XML được nhúng và tệp đính kèm PDF/A-3. Một trình xác thực EN 16931 / Schematron, hoặc cơ quan thuế tiếp nhận, quyết định tính hợp lệ về thuế.

Cài đặt

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core cung cấp EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface, và ValidationResult trong NextPDF\Contracts\EInvoice. Docblock của interface nêu rõ rằng bậc Pro (engine byte-rewrite Factur-X 1.08) và bậc Enterprise (builder do PDF/A quản lý) hiện thực hợp đồng này. Riêng Core không tự nhúng hóa đơn. Nó định nghĩa hợp đồng byte-in/byte-out mà các bậc đó đáp ứng.

Tổng quan khái niệm

NextPDF\Contracts\EInvoice\ProfileType phân biệt mức tuân thủ EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Phương thức isEn16931Conformant() mã hóa trực tiếp quy tắc từ EN 16931-1. MINIMUM và BASIC_WL không tuân thủ EN 16931 (chúng không đáp ứng yêu cầu về số bội của định danh đặc tả BT-24 và yêu cầu về dòng mục). BASIC, EN16931, EXTENDED, XRECHNUNG tuân thủ EN 16931.

Embedder (EmbedderInterface) theo hợp đồng phải:

phân tích CII XML được cung cấp qua XmlGuard (an toàn với XXE);
chèn lược đồ mở rộng XMP Factur-X cho hồ sơ đã khai báo;
đính kèm XML dưới dạng một tệp được nhúng với AFRelationship đúng (Data / Alternative) để nền lưu trữ PDF/A-3 (§6.7.5 yêu cầu về tệp được nhúng — khóa F/UF) có thể mang nó.

NextPDF xuất ra cấu trúc này. Nó không khẳng định rằng hóa đơn hợp lệ về thuế. Cơ quan tiếp nhận đưa ra quyết định đó dựa trên các quy tắc nghiệp vụ EN 16931 §7 và bất kỳ CIUS quốc gia nào.

Bề mặt API

Ký hiệu	Vai trò
`Contracts\EInvoice\EmbedderInterface`	Hợp đồng byte-in/byte-out; Pro/Enterprise hiện thực nó.
`Contracts\EInvoice\ProfileType` (enum)	Bộ phân biệt hồ sơ EN 16931.
`ProfileType::isEn16931Conformant(): bool`	False với MINIMUM/BASIC_WL; true với BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Hợp đồng xác thực trả về `ValidationResult` chứa các vi phạm quy tắc.

Ví dụ mã — bắt đầu nhanh

<?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";

Ví dụ mã — môi trường thực tế

Trong môi trường thực tế, pipeline (bậc Pro) nhúng CII XML vào một tệp PDF/A-3 nền. Sau đó, nó chạy một trình xác thực EN 16931 Schematron, hoặc gửi đến cơ quan tiếp nhận, và dùng báo cáo đó làm cổng quyết định. NextPDF xuất ra XML được nhúng và tệp đính kèm PDF/A-3; trình xác thực hoặc cơ quan quyết định tính hợp lệ về thuế. Riêng Core không thể chạy pipeline này. Cần có nextpdf/pro để dùng engine embedder.

Trường hợp đặc biệt & lưu ý

Core chỉ có hợp đồng. Không có nextpdf/pro thì không có embedder cụ thể. Mã gọi phải phụ thuộc vào interface và suy giảm rõ ràng khi thiếu bản hiện thực Pro.
MINIMUM / BASIC_WL không phải là EN 16931. isEn16931Conformant() trả về false cho những hồ sơ này; đừng quảng bá là hóa đơn EN 16931 khi dùng chúng.
Nền PDF/A-3. XML được nhúng nằm trong một bộ chứa lưu trữ PDF/A-3; các khóa tệp được nhúng F/UF (PDF/A §6.7.5) phải có mặt.
XML được phân tích an toàn với XXE. Hợp đồng yêu cầu phân tích bằng XmlGuard; một embedder tùy chỉnh không được tạo điểm khai thác XXE.
Tính hợp lệ không phải là phán quyết của thư viện. Việc tạo ra một tệp Factur-X đúng cấu trúc không có nghĩa là cơ quan thuế sẽ chấp nhận nó.

Hiệu năng

Quá trình nhúng ghi lại PDF để thêm tệp đính kèm XML và lược đồ mở rộng XMP. Ngân sách thời gian thực là ≤ 1500 ms, mức đỉnh ≤ 128 MB cho một hóa đơn điển hình.

Ghi chú bảo mật

XML được nhúng được phân tích theo cách an toàn với XXE qua XmlGuard. XML hóa đơn chứa thông tin định danh cá nhân (PII) trong bối cảnh thương mại, bao gồm thông tin về các bên và số tiền. Nó được nhúng, chứ không được mã hóa. Tính bảo mật của hóa đơn là trách nhiệm của bên tích hợp.

Lưu trú dữ liệu & biện pháp giảm thiểu PII

XML hóa đơn mang theo PII liên quan đến các bên và tài chính. Việc nhúng diễn ra trong tiến trình; không có dữ liệu nào rời khỏi tiến trình trong quá trình nhúng. Việc truyền dữ liệu đến cơ quan tiếp nhận nằm ngoài phạm vi và là trách nhiệm về lưu trú dữ liệu của bên tích hợp.

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

Không bao giờ ghi nhật ký CII XML hoặc các byte PDF được nhúng — chúng chứa PII của hóa đơn. Chỉ ghi nhật ký tên hồ sơ và kết luận về cấu trúc.

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

Một tệp Factur-X không được bảo vệ bằng kiểm soát truy cập. XML được nhúng có thể được đọc bởi bất kỳ ai có tệp đó. Tệp lai bảo đảm hóa đơn có thể được máy đọc, chứ không bảo đảm tính bảo mật hay sự chấp nhận về thuế của nó.

Hành vi ở chế độ FIPS

Quá trình nhúng không thực hiện thao tác mật mã. Một hóa đơn Factur-X đã ký là vấn đề riêng của công thức chữ ký và kế thừa trạng thái FIPS của công thức đó. Trang này không đưa ra tuyên bố nào về việc ký.

Mức tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Một hóa đơn EN 16931 chứa các thuật ngữ nghiệp vụ của mô hình dữ liệu ngữ nghĩa.	EN 16931-1	§6.4
Việc tuân thủ EN 16931 phụ thuộc vào yêu cầu số bội của các quy tắc nghiệp vụ mà một hóa đơn tuân thủ phải đáp ứng.	EN 16931-1	§7
Hồ sơ Factur-X EN 16931 yêu cầu CII-XML tuân thủ quy tắc nghiệp vụ.	Factur-X 1.08	EN 16931 profile
Hồ sơ Factur-X EN 16931 yêu cầu các nội dung hóa đơn bắt buộc.	Factur-X 1.08	EN 16931 profile
Factur-X là một tệp lai: XML máy đọc được nhúng cùng với PDF người đọc được.	Factur-X 1.08	Basic
XML được nhúng nằm trong nền lưu trữ PDF/A (các khóa tệp được nhúng F/UF).	ISO 19005-4	§6.7.5

Các trích dẫn là con trỏ clause-id + reference_id đến kho ngữ liệu xác minh. Không có văn bản tiêu chuẩn nào được tái tạo; các điều khoản được tóm tắt bằng lời của NextPDF.