Enterprise edisi

Invoice — Referensi Mendalam

Sekilas

Modul Invoice memiliki tiga permukaan independen: penyematan, validasi, dan eksekusi aturan Schematron. ZugferdEmbedder dan PeppolEmbedder melampirkan XML invoice yang disediakan pemanggil ke pembawa PDF/A-4f atau PDF/A-3b dan mengembalikan hasil terstruktur. InvoiceXmlValidator menjalankan pre-flight struktural EN 16931 dengan tingkat keparahan COMPAT atau STRICT yang dapat dipilih. SchematronValidator mengeksekusi paket aturan Schematron yang telah dikompilasi sebelumnya secara in-process dan mengurai temuan SVRL. NextPDF tidak menghasilkan XML invoice; pemanggil menyediakan dan memiliki payload.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan amplop lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Nuansa per-tier: deteksi dan validasi e-invoice adalah permukaan tier Pro (modul Pro Compliance). Penyematan invoice hibrida, profil CIUS XRechnung, dan mesin Schematron in-process bersifat khusus Enterprise. Tidak ada kode kapabilitas per-fitur terpisah di luar batas paket nextpdf/enterprise.

Permukaan API publik

composer require nextpdf/enterprise:^3

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Menyematkan XML CII profil BASIC: lintasan XmlGuard, validasi struktural, injeksi skema XMP, pelampiran	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Jalur cepat; titik awal yang direkomendasikan
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Pipeline yang sama pada profil MINIMUM	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Jalur cepat
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Titik masuk builder; menolak XML kosong	`self`	`InvalidArgumentException`	Konfigurasikan via `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Menimpa hubungan `/Alternative` bawaan; dibatasi oleh rulebook berkas terkait	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` ditolak untuk invoice
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Panggilan builder terminal: XmlGuard, validasi opsional, pemeriksaan pembawa, XMP, pelampiran	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Kegagalan validasi menyebut kesalahan pertama
`ZugferdProfile` (enum)	—	Kasus MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG melampirkan `xrechnung.xml`; profil CII melampirkan `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Mendaftarkan deskripsi RDF Factur-X dan entri skema-ekstensi PDF/A	`XmpMetadata`	None	Dipanggil oleh `embed()`; juga dapat digunakan langsung
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Menyematkan XML invoice atau credit-note UBL Peppol BIS 3.0	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Nama berkas bawaan `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Titik masuk builder; menolak XML atau nama berkas kosong	`self`	`InvalidArgumentException`	Konfigurasikan via `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Lintasan XmlGuard, pemeriksaan pembawa, gerbang rulebook, pelampiran	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Pemeriksaan-ulang rulebook yang sadar pembawa saat embed
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	Pre-flight struktural EN 16931; tingkat keparahan COMPAT secara bawaan	`InvoiceValidationResult`	Tidak melempar; kegagalan muncul sebagai temuan error	Mode diselesaikan dari argumen, lalu environment, lalu COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Pemeriksaan elemen-akar dan namespace untuk payload CII	`bool`	Tidak melempar; mengembalikan `false`	Probe deteksi murah
`InvoiceValidatorMode` (enum)	—	`COMPAT` (bawaan) menjaga temuan BT-24 pada peringatan; `STRICT` mempromosikannya menjadi error	—	—	`fromEnvironment()` mundur ke COMPAT pada nilai yang tidak diset atau tidak dikenali
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Agregat immutable: `isValid`, `getErrors()`, `getWarnings()`; level, kode, pesan per temuan	—	—	`InvoiceValidationResult::fail()` membungkus satu error
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Mengeksekusi XSLT Schematron yang telah dikompilasi; mengurai SVRL menjadi temuan	`SchematronResult`	`InvalidArgumentException` untuk XSLT yang hilang atau tidak terbaca; kegagalan mesin mengembalikan hasil error	Waktu dicatat di `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Adaptor lintas-tier; memetakan temuan error ke objek `RuleViolation` kontrak	`list<RuleViolation>`	Sama seperti `validate()`	Temuan level-info dilewati
`SchematronResult` / `SchematronFinding`	—	Verdict, temuan, durasi; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` menandai kegagalan mesin sebagai invalid
`SchematronCacheInterface`	—	Kontrak cache deteksi-perusakan: `getVerified()`, `set()`, `computeKey()`	—	—	Gagal-tertutup pada ketidakcocokan digest
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	Cache berkas terverifikasi-SHA-256 dengan penulisan atomic-rename	—	`InvalidArgumentException`, `SchematronCacheException`	Direktori harus ada atau dapat dibuat, dan dapat ditulis
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	Pin paket-aturan terkunci-SHA-256: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` pada JSON kunci yang salah bentuk	Digest kosong atau salah bentuk gagal-tertutup
`InvoiceContractValidator`	`?SemanticValidator`	Adaptor `ValidatorInterface` lintas-tier; pre-flight struktural plus aturan semantik-mendalam EN 16931	`ContractResult`	Gagal-tertutup; kesalahan mesin muncul sebagai temuan error	Terikat pada jalur framework ketika `nextpdf/premium` terpasang
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Adaptor `EmbedderInterface` lintas-tier; embed byte-masuk / byte-keluar	`string` (byte PDF)	Meneruskan kegagalan delegasi	Mendelegasikan ke mesin byte-rewrite tier Pro
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Taksonomi kegagalan modul	—	—	Semua mewarisi `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

Kontrak perilaku

Penyematan. ZugferdEmbedder melampirkan payload XML UN/CEFACT CII ZUGFeRD 2.4 / Factur-X 1.08 yang disediakan pemanggil ke pembawa PDF/A. Ia mendukung dua pembawa: PDF/A-4f (ISO 19005-4:2020), pembawa modern yang lebih disukai, dan PDF/A-3b (ISO 19005-3:2012) untuk kompatibilitas mundur. embed() selalu menjalankan lintasan keamanan XmlGuard terlebih dahulu, lalu validasi struktural kecuali withoutValidation() telah diset, lalu memverifikasi pembawa mendukung berkas tersemat, menginjeksikan deklarasi skema-ekstensi XMP via ZugferdXmpSchema, dan melampirkan XML sebagai berkas terkait. Hubungan lampiran bawaannya adalah rekomendasi rulebook /Alternative; penimpaan melewati rulebook yang sama, yang memberlakukan set hubungan ISO 32000-2:2020 §14.13 dan subset invoice EN 16931. PeppolEmbedder melakukan hal setara untuk XML invoice atau credit-note UBL 2.1 Peppol BIS Billing 3.0 yang disediakan pemanggil. Tidak ada embedder yang menghasilkan XML invoice.

Validasi. InvoiceXmlValidator memeriksa XML CII terhadap ekspektasi struktural EN 16931: elemen akar, seksi yang diperlukan, kardinalitas header, item baris ketika profil mensyaratkannya, dan pengidentifikasi spesifikasi BT-24 yang diwajibkan oleh aturan bisnis BR-1. InvoiceValidatorMode memilih tingkat keparahan. COMPAT (bawaan) melaporkan BT-24 yang hilang atau tidak cocok sebagai peringatan agar gerbang validitas boolean tidak mengalami regresi. STRICT menjadikan keduanya error keras dan juga menegaskan konsistensi profil terhadap ZugferdProfile yang dideklarasikan, mencerminkan semantik validator KoSIT / Mustang eksternal. Mode diselesaikan dengan urutan: argumen eksplisit, lalu penimpaan environment INVOICE_VALIDATOR_MODE, lalu COMPAT. Hasil berupa objek terstruktur InvoiceValidationResult / InvoiceValidationFinding; validator mengembalikan temuan alih-alih melempar.

Schematron. SchematronValidator mengeksekusi set aturan Schematron yang telah dikompilasi sebelumnya — aturan .sch CEN EN 16931 yang dikompilasi ke XSLT saat build — menggunakan prosesor XSLT PHP in-process. Ia mengurai laporan SVRL menjadi objek SchematronFinding / SchematronResult: assertion yang gagal menjadi temuan error, laporan yang berhasil menjadi temuan info. Cache opsional (SchematronCacheInterface, dengan implementasi berkas atomic-rename) menyajikan byte stylesheet terverifikasi yang di-key oleh digest konten plus versi kompiler. VersionPinRegistry menyematkan setiap paket aturan eksternal ke versi terkunci-SHA-256 dan gagal-tertutup pada drift atau digest yang salah bentuk.

Modul ini menghasilkan dan memeriksa data invoice terstruktur. Ia tidak menegaskan bahwa suatu dokumen adalah invoice yang patuh secara hukum, bahwa ia disetujui otoritas pajak, atau bahwa ia dijamin diterima oleh otoritas mana pun. Validator memeriksa model semantik EN 16931 dan kontainer ZUGFeRD / Factur-X / UBL saja; ia mengecualikan ekstensi nasional (misalnya SDI Italia, Chorus Pro Prancis, transport XRechnung Jerman). Sebagaimana dinyatakan EN 16931-1, penerbit invoice bertanggung jawab memenuhi aturan legislasi yang relevan; ini bukan validator otoritas pajak. Dukungan terhadap suatu standar bukanlah konformitas terhadapnya.

Kasus tepi & mode kegagalan

XML kosong gagal cepat: builder melempar InvalidArgumentException; InvoiceXmlValidator::validate() mengembalikan hasil gagal.
XmlGuard menolak deklarasi DOCTYPE, ekspansi entitas, payload berlebihan ukuran, dan karakter kontrol. Embedder memunculkannya sebagai ZugferdEmbeddingException atau PeppolEmbeddingException dengan penyebab dipertahankan.
withoutValidation() dan withoutSanitization() tidak pernah melewati lintasan keamanan XmlGuard. Hanya pemeriksaan istilah-bisnis struktural yang dapat dilewati.
Pembawa tanpa dukungan berkas tersemat (selain PDF/A-4f atau PDF/A-3b) memunculkan InvalidArgumentException yang menyebut versi yang diterima.
Nilai AFRelationship yang tidak diizinkan ditolak di batas builder; pemeriksaan-ulang rulebook yang sadar pembawa berjalan kembali di dalam embed().
COMPAT menjaga BT-24 yang hilang pada tingkat keparahan peringatan; STRICT menjadikan nilai BT-24 yang hilang dan tidak-cocok-profil sebagai error keras.
SchematronValidator melempar hanya untuk jalur XSLT yang hilang atau tidak terbaca. Kegagalan transform atau parse-SVRL mengembalikan SchematronResult::error() dengan isValid false.
Entri cache yang byte tersimpannya gagal verifikasi digest dikeluarkan dan stylesheet dibaca-ulang dari disk; byte yang teracuni tidak pernah dikembalikan.
Prosesor XSLT berjalan dengan pemuatan sumber daya berkas dan jaringan diblokir dan tidak pernah mendaftarkan fungsi PHP; document(), xsl:include, xsl:import, dan result-document tidak dapat memuat sumber daya.
VersionPinRegistry menolak digest SHA-256 yang kosong atau salah bentuk saat ingest dan saat regenerasi; verifyArtefact() mengembalikan false alih-alih meloloskan pin yang tidak dapat diverifikasi.
Modul ini tidak melakukan penandatanganan kriptografis; perilaku mode-FIPS di luar cakupan di sini (lihat modul Signature).

Konformitas

Behavior	Reference	Status
Model semantik inti invoice	EN 16931-1:2026 §4	Dibangun terhadap; penerbit tetap bertanggung jawab
Pengidentifikasi spesifikasi (BT-24)	EN 16931-1:2026 BR-1	Peringatan di COMPAT, error di STRICT
Pengikatan sintaks UN/CEFACT CII	CEN/TS 16931-3-3:2020	Embed didukung
Pengikatan sintaks UBL 2.1	CEN/TS 16931-3-2:2020	Embed didukung
Berkas terkait PDF/A-3	ISO 19005-3:2012 §6.7.8	Pembawa didukung
Berkas tersemat PDF/A-4f	ISO 19005-4:2020 Annex A	Pembawa didukung
Nilai hubungan berkas terkait	ISO 32000-2:2020 §14.13	Dibatasi rulebook
Parsing laporan Schematron / SVRL	ISO/IEC 19757-3	Dibangun terhadap (berbasis produk; standar tidak ada dalam korpus sitasi)

Dibangun-terhadap, bukan sertifikasi atau persetujuan otoritas pajak. NextPDF tidak memegang sertifikasi untuk satupun standar ini. NextPDF menghasilkan invoice terstruktur yang konform terhadap model data EN 16931 dan melaporkan temuan aturan; ia tidak menghasilkan invoice yang patuh secara hukum, tidak menyediakan output yang disetujui otoritas pajak, dan tidak menjamin penerimaan. Konsultasikan dengan penasihat pajak dan hukum Anda.

Catatan pengembangan

Mesin Schematron memerlukan ekstensi PHP ext-xsl; penyediaan dan pengaktifannya adalah tanggung jawab operator.
Pemrosesan bersifat in-process dan lokal. Tidak ada panggilan jaringan keluar selama penyematan atau validasi. Transport e-invoicing nasional, platform clearance, dan sistem arsip berada di luar modul ini.
Paket aturan dikompilasi dari .sch ke XSLT saat build; runtime hanya mengeksekusi stylesheet yang telah dikompilasi sebelumnya.
Kunci cache melipat salt versi-kompiler (saat ini nextpdf-schxslt-1.0); menaikkannya membatalkan cache yang telah di-deploy tanpa langkah purge.
Pin paket-aturan berada di berkas kunci pada enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI memverifikasi artefak yang di-deploy terhadap digest yang disematkan.
Pemanggil lintas-tier menggunakan InvoiceContractValidator dan ZugferdContractEmbedder; pemanggil Enterprise tier-native menggunakan ZugferdEmbedder dan InvoiceXmlValidator secara langsung.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan awalan tiket berada di luar cakupan.

Lihat juga

Kapabilitas Invoice — pasangan kapabilitas dari referensi ini.
Pro Compliance — deteksi/validasi tier Pro.
Document E-Filing
Gambaran umum Enterprise