Enterprise รุ่น

Invoice — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยย่อ

โมดูล Invoice มีสามพื้นผิวที่เป็นอิสระต่อกัน ได้แก่ การฝัง การตรวจสอบ และการรันกฎ Schematron ZugferdEmbedder และ PeppolEmbedder แนบ XML ใบแจ้งหนี้ที่ผู้เรียกจัดหาเข้ากับ carrier PDF/A-4f หรือ PDF/A-3b และคืนผลลัพธ์ที่มีโครงสร้าง InvoiceXmlValidator รันการตรวจก่อนเชิงโครงสร้างตาม EN 16931 พร้อมระดับความรุนแรง COMPAT หรือ STRICT ที่เลือกได้ SchematronValidator รันชุดกฎ Schematron ที่คอมไพล์ไว้ล่วงหน้าในกระบวนการและแจงข้อค้นพบ SVRL NextPDF ไม่สร้าง XML ใบแจ้งหนี้ ผู้เรียกเป็นผู้จัดหาและเป็นเจ้าของ payload

การมีให้ใช้และการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับ Enterprise การนำไปติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับ license

รายละเอียดต่อขั้น: การตรวจหาและการตรวจสอบ e-invoice เป็นพื้นผิวขั้น Pro (โมดูล Pro Compliance) ส่วนการฝังใบแจ้งหนี้แบบ hybrid, โปรไฟล์ XRechnung CIUS และเอนจิน Schematron ในกระบวนการเป็นของ Enterprise เท่านั้น ไม่มีรหัสความสามารถต่อฟีเจอร์แยกต่างหากนอกเหนือจากขอบเขตแพ็กเกจ nextpdf/enterprise

พื้นผิว Public API

composer require nextpdf/enterprise:^3

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	ค่าที่คืน	ข้อยกเว้นหรือความล้มเหลว	หมายเหตุ
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	ฝัง CII XML โปรไฟล์ BASIC: ผ่าน XmlGuard, ตรวจสอบเชิงโครงสร้าง, ฉีด XMP schema, แนบไฟล์	`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` เริ่มต้น ควบคุมโดย rulebook ของ associated-file	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` ถูกปฏิเสธสำหรับใบแจ้งหนี้
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	การเรียก builder ปลายทาง: XmlGuard, การตรวจสอบเสริม, ตรวจ carrier, 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 extension-schema	`XmpMetadata`	ไม่มี	ถูกเรียกโดย `embed()` และใช้ได้โดยตรงเช่นกัน
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	ฝัง XML ใบแจ้งหนี้หรือใบลดหนี้ Peppol BIS 3.0 UBL	`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, ตรวจ carrier, เกต rulebook, แนบไฟล์	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	ตรวจ rulebook ซ้ำแบบรู้ carrier ในเวลาฝัง
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	การตรวจก่อนเชิงโครงสร้าง EN 16931 ระดับความรุนแรง COMPAT โดยค่าเริ่มต้น	`InvoiceValidationResult`	ไม่ยกข้อยกเว้น ความล้มเหลวปรากฏเป็นข้อค้นพบข้อผิดพลาด	โหมดเลือกจาก argument ก่อน แล้ว environment แล้ว COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	ตรวจ root-element และ namespace สำหรับ payload CII	`bool`	ไม่ยกข้อยกเว้น คืนค่า `false`	โพรบตรวจหาแบบต้นทุนต่ำ
`InvoiceValidatorMode` (enum)	—	`COMPAT` (ค่าเริ่มต้น) คงข้อค้นพบ BT-24 ไว้ที่คำเตือน ส่วน `STRICT` ยกระดับเป็นข้อผิดพลาด	—	—	`fromEnvironment()` ถอยกลับไป COMPAT เมื่อค่าไม่ถูกตั้งหรือไม่รู้จำ
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	แอกกริเกตแบบไม่เปลี่ยนแปลง: `isValid`, `getErrors()`, `getWarnings()` พร้อม level, code, message ต่อข้อค้นพบ	—	—	`InvoiceValidationResult::fail()` ห่อข้อผิดพลาดเดี่ยว
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	รัน Schematron XSLT ที่คอมไพล์ไว้ล่วงหน้า แจง SVRL เป็นข้อค้นพบ	`SchematronResult`	`InvalidArgumentException` เมื่อ XSLT ขาดหายหรืออ่านไม่ได้ ความล้มเหลวของเอนจินคืนผลลัพธ์ข้อผิดพลาด	เวลาที่ใช้ถูกบันทึกใน `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	อะแดปเตอร์ข้ามขั้น จับคู่ข้อค้นพบข้อผิดพลาดกับออบเจกต์ `RuleViolation` ของ contract	`list<RuleViolation>`	เช่นเดียวกับ `validate()`	ข้อค้นพบระดับ info ถูกข้าม
`SchematronResult` / `SchematronFinding`	—	คำตัดสิน, ข้อค้นพบ, ระยะเวลา พร้อม `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` ทำเครื่องหมายความล้มเหลวของเอนจินว่าไม่ผ่าน
`SchematronCacheInterface`	—	สัญญาแคชแบบตรวจจับการดัดแปลง: `getVerified()`, `set()`, `computeKey()`	—	—	ล้มแบบปิดเมื่อ digest ไม่ตรง
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	file cache ที่ตรวจสอบด้วย SHA-256 พร้อมการเขียนแบบ atomic-rename	—	`InvalidArgumentException`, `SchematronCacheException`	ไดเรกทอรีต้องมีอยู่หรือสร้างได้ และเขียนได้
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	การปักหมุด rule-pack ที่ล็อกด้วย SHA-256: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` เมื่อ lock JSON ผิดรูปแบบ	digest ว่างหรือผิดรูปแบบล้มแบบปิด
`InvoiceContractValidator`	`?SemanticValidator`	อะแดปเตอร์ `ValidatorInterface` ข้ามขั้น การตรวจก่อนเชิงโครงสร้างพร้อมกฎเชิงความหมายเชิงลึก EN 16931	`ContractResult`	ล้มแบบปิด ข้อผิดพลาดของเอนจินปรากฏเป็นข้อค้นพบข้อผิดพลาด	ผูกบนเส้นทาง framework เมื่อติดตั้ง `nextpdf/premium`
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	อะแดปเตอร์ `EmbedderInterface` ข้ามขั้น ฝังแบบ byte-in / byte-out	`string` (ไบต์ PDF)	ส่งต่อความล้มเหลวของ delegate	มอบหมายให้เอนจิน byte-rewrite ขั้น 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 แนบ payload XML แบบ ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII ที่ผู้เรียกจัดหาเข้ากับ carrier PDF/A มันรองรับสอง carrier ได้แก่ PDF/A-4f (ISO 19005-4:2020) ซึ่งเป็น carrier สมัยใหม่ที่นิยม และ PDF/A-3b (ISO 19005-3:2012) เพื่อความเข้ากันได้แบบย้อนหลัง embed() รันการตรวจความปลอดภัย XmlGuard ก่อนเสมอ จากนั้นตรวจสอบเชิงโครงสร้างเว้นแต่ตั้ง withoutValidation() ไว้ แล้วยืนยันว่า carrier รองรับไฟล์ที่ฝัง ฉีดการประกาศ XMP extension-schema ผ่าน ZugferdXmpSchema และแนบ XML เป็น associated file ความสัมพันธ์ของการแนบมีค่าเริ่มต้นตามคำแนะนำของ rulebook คือ /Alternative การแทนที่จะผ่าน rulebook เดียวกันซึ่งบังคับใช้ชุดความสัมพันธ์ตาม ISO 32000-2:2020 §14.13 และเซ็ตย่อยใบแจ้งหนี้ EN 16931 PeppolEmbedder ทำสิ่งที่เทียบเท่าสำหรับ XML ใบแจ้งหนี้หรือใบลดหนี้ Peppol BIS Billing 3.0 UBL 2.1 ที่ผู้เรียกจัดหา ตัว embedder ทั้งสองไม่สร้าง XML ใบแจ้งหนี้

การตรวจสอบ InvoiceXmlValidator ตรวจสอบ CII XML เทียบกับความคาดหมายเชิงโครงสร้าง EN 16931 ได้แก่ root element, ส่วนที่จำเป็น, cardinality ของ header, รายการบรรทัดที่โปรไฟล์กำหนด และ specification identifier BT-24 ที่กำหนดโดย business rule BR-1 InvoiceValidatorMode เลือกระดับความรุนแรง COMPAT (ค่าเริ่มต้น) รายงาน BT-24 ที่ขาดหายหรือไม่ตรงกันเป็นคำเตือน เพื่อไม่ให้เกตความถูกต้องแบบ boolean ถดถอย ส่วน STRICT ทำให้เป็นข้อผิดพลาดร้ายแรงและยังยืนยันความสอดคล้องของโปรไฟล์เทียบกับ ZugferdProfile ที่ประกาศไว้ สะท้อนความหมายของ validator KoSIT / Mustang ภายนอก โหมดเลือกตามลำดับ: argument ที่ระบุชัด แล้วการแทนที่ผ่าน environment INVOICE_VALIDATOR_MODE แล้ว COMPAT ผลลัพธ์เป็นออบเจกต์ InvoiceValidationResult / InvoiceValidationFinding ที่มีโครงสร้าง ตัวตรวจสอบคืนข้อค้นพบแทนการยกข้อยกเว้น

Schematron SchematronValidator รันชุดกฎ Schematron ที่คอมไพล์ไว้ล่วงหน้า — กฎ .sch ของ CEN EN 16931 ที่คอมไพล์เป็น XSLT ในเวลา build — โดยใช้ตัวประมวลผล XSLT ของ PHP ในกระบวนการ มันแจงรายงาน SVRL เป็นออบเจกต์ SchematronFinding / SchematronResult โดย failed assertion กลายเป็นข้อค้นพบข้อผิดพลาด และ successful report กลายเป็นข้อค้นพบระดับ info แคชเสริม (SchematronCacheInterface พร้อมการนำไปใช้แบบ file แบบ atomic-rename) ให้บริการไบต์ stylesheet ที่ตรวจสอบแล้วโดยใช้คีย์เป็น content digest บวกกับเวอร์ชันคอมไพเลอร์ VersionPinRegistry ปักหมุดทุก rule pack ภายนอกไว้กับเวอร์ชันที่ล็อกด้วย SHA-256 และล้มแบบปิดเมื่อมีการเบี่ยงเบนหรือ digest ผิดรูปแบบ

โมดูลนี้สร้างและตรวจสอบข้อมูลใบแจ้งหนี้ที่มีโครงสร้าง มัน ไม่ ยืนยันว่าเอกสารใดเป็นใบแจ้งหนี้ที่ถูกต้องตามกฎหมาย ว่าได้รับการอนุมัติจากหน่วยงานภาษี หรือว่ารับประกันการยอมรับโดยหน่วยงานใด ตัวตรวจสอบตรวจเฉพาะแบบจำลองเชิงความหมาย EN 16931 และ container ZUGFeRD / Factur-X / UBL เท่านั้น ไม่รวมส่วนขยายระดับชาติ (ตัวอย่างเช่น Italian SDI, French Chorus Pro, German XRechnung transport) ดังที่ EN 16931-1 ระบุไว้ ผู้ออกใบแจ้งหนี้เป็นผู้รับผิดชอบในการปฏิบัติตามกฎของกฎหมายที่เกี่ยวข้อง นี่ไม่ใช่ตัวตรวจสอบของหน่วยงานภาษี การรองรับมาตรฐานไม่ใช่ความสอดคล้องกับมาตรฐานนั้น

กรณีขอบและโหมดความล้มเหลว

XML ว่างล้มเหลวทันที: builder ยก InvalidArgumentException ส่วน InvoiceXmlValidator::validate() คืนผลลัพธ์ที่ล้มเหลว
XmlGuard ปฏิเสธการประกาศ DOCTYPE, การขยาย entity, payload ที่ใหญ่เกิน และอักขระควบคุม ตัว embedder แสดงสิ่งนี้เป็น ZugferdEmbeddingException หรือ PeppolEmbeddingException โดยคงสาเหตุไว้
withoutValidation() และ withoutSanitization() ไม่เคยข้ามการตรวจความปลอดภัย XmlGuard ข้ามได้เฉพาะการตรวจ business-term เชิงโครงสร้างเท่านั้น
carrier ที่ไม่รองรับไฟล์ที่ฝัง (อื่นใดนอกจาก PDF/A-4f หรือ PDF/A-3b) ยก InvalidArgumentException ที่ระบุเวอร์ชันที่ยอมรับ
ค่า AFRelationship ที่ไม่อนุญาตถูกปฏิเสธที่ขอบเขต builder และการตรวจ rulebook ซ้ำแบบรู้ carrier รันอีกครั้งภายใน embed()
COMPAT คง BT-24 ที่ขาดหายไว้ที่ระดับความรุนแรงคำเตือน ส่วน STRICT ทำให้ค่า BT-24 ที่ขาดหายและไม่ตรงโปรไฟล์เป็นข้อผิดพลาดร้ายแรง
SchematronValidator ยกข้อยกเว้นเฉพาะเมื่อเส้นทาง XSLT ขาดหายหรืออ่านไม่ได้ ความล้มเหลวของการแปลงหรือการแจง SVRL คืน SchematronResult::error() โดย isValid เป็น false
รายการแคชที่ไบต์ที่จัดเก็บไม่ผ่านการตรวจสอบ digest จะถูกขับออกและอ่าน stylesheet ใหม่จากดิสก์ ไบต์ที่ถูกวางยาไม่เคยถูกคืน
ตัวประมวลผล XSLT รันโดยปิดการโหลดทรัพยากรไฟล์และเครือข่าย และไม่เคยลงทะเบียนฟังก์ชัน PHP document(), xsl:include, xsl:import และ result-document ไม่สามารถโหลดทรัพยากรได้
VersionPinRegistry ปฏิเสธ digest SHA-256 ที่ว่างหรือผิดรูปแบบตอน ingest และตอน regenerate verifyArtefact() คืนค่า false แทนที่จะปล่อยผ่านหมุดที่ตรวจสอบไม่ได้
โมดูลนี้ไม่ทำการลงลายเซ็นเชิงการเข้ารหัสลับใด ๆ พฤติกรรมในโหมด FIPS อยู่นอกขอบเขตที่นี่ (ดูโมดูล Signature)

ความสอดคล้อง

พฤติกรรม	เอกสารอ้างอิง	สถานะ
แบบจำลองเชิงความหมายหลักของใบแจ้งหนี้	EN 16931-1:2026 §4	สร้างเทียบกับ ผู้ออกยังคงรับผิดชอบ
ตัวระบุข้อกำหนด (BT-24)	EN 16931-1:2026 BR-1	คำเตือนใน COMPAT ข้อผิดพลาดใน STRICT
การผูก syntax UN/CEFACT CII	CEN/TS 16931-3-3:2020	รองรับการฝัง
การผูก syntax UBL 2.1	CEN/TS 16931-3-2:2020	รองรับการฝัง
associated file PDF/A-3	ISO 19005-3:2012 §6.7.8	รองรับ carrier
embedded file PDF/A-4f	ISO 19005-4:2020 Annex A	รองรับ carrier
ค่าความสัมพันธ์ของ associated-file	ISO 32000-2:2020 §14.13	ควบคุมโดย rulebook
การแจงรายงาน Schematron / SVRL	ISO/IEC 19757-3	สร้างเทียบกับ (อิงผลิตภัณฑ์ มาตรฐานไม่อยู่ใน citation corpus)

สร้างเทียบกับมาตรฐาน ไม่ใช่การรับรองหรือการอนุมัติจากหน่วยงานภาษี NextPDF ไม่ถือการรับรองใดสำหรับมาตรฐานเหล่านี้ NextPDF สร้างใบแจ้งหนี้ที่มีโครงสร้างซึ่งสอดคล้องกับแบบจำลองข้อมูล EN 16931 และรายงานข้อค้นพบของกฎ มันไม่สร้างใบแจ้งหนี้ที่ถูกต้องตามกฎหมาย ไม่ให้ผลลัพธ์ที่หน่วยงานภาษีอนุมัติ และไม่รับประกันการยอมรับ ปรึกษาที่ปรึกษาด้านภาษีและกฎหมายของคุณ

หมายเหตุการพัฒนา

เอนจิน Schematron ต้องใช้ส่วนขยาย PHP ext-xsl การจัดเตรียมและการเปิดใช้งานเป็นความรับผิดชอบของผู้ปฏิบัติการ
การประมวลผลทำในกระบวนการและในเครื่อง ไม่มีการเรียกเครือข่ายขาออกระหว่างการฝังหรือการตรวจสอบ การส่ง e-invoicing ระดับชาติ แพลตฟอร์ม clearance และระบบการเก็บถาวรอยู่ภายนอกโมดูลนี้
rule pack ถูกคอมไพล์จาก .sch เป็น XSLT ในเวลา build ส่วน runtime รันเฉพาะ stylesheet ที่คอมไพล์ไว้ล่วงหน้าเท่านั้น
คีย์แคชรวม salt เวอร์ชันคอมไพเลอร์ (ปัจจุบัน nextpdf-schxslt-1.0) การเพิ่มค่านี้ทำให้แคชที่ติดตั้งใช้ไม่ได้โดยไม่ต้องมีขั้นตอน purge
หมุด rule-pack อยู่ในไฟล์ lock ที่ enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH) CI ตรวจสอบอาร์ทิแฟกต์ที่ติดตั้งเทียบกับ digest ที่ปักหมุด
ผู้เรียกข้ามขั้นใช้ InvoiceContractValidator และ ZugferdContractEmbedder ส่วนผู้เรียก Enterprise ที่เป็น tier-native ใช้ ZugferdEmbedder และ InvoiceXmlValidator โดยตรง

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น internal namespace paths, helper classes, ตารางกลไก, ชื่อไฟล์ runbook และ ticket prefixes อยู่นอกขอบเขต

ดูเพิ่มเติม

ความสามารถ Invoice — คู่ความสามารถของเอกสารอ้างอิงนี้
Pro Compliance — การตรวจหา/ตรวจสอบในขั้น Pro
Document E-Filing
ภาพรวม Enterprise