Kesesuaian ZUGFeRD / Factur-X: profil faktur EN 16931 tertanam

Sekilas pandang

Pernyataan batasan. NextPDF menghasilkan profil XML yang tertanam; validitas fiskal dan legal ditentukan oleh otoritas penerima, bukan oleh pustaka.

ZUGFeRD / Factur-X adalah faktur hibrida: PDF yang dapat dibaca manusia (substrat arsip PDF/A-3) dengan XML Cross-Industry-Invoice (CII) tertanam yang dapat dibaca mesin dan mengikuti model data semantik EN 16931. NextPDF Core menyertakan kontrak embedder (NextPDF\Contracts\EInvoice); mesin Factur-X 1.08 yang konkret disertakan dalam paket Premium nextpdf/pro. Pustaka ini menghasilkan XML yang tertanam dan struktur lampiran PDF/A-3. Validitas fiskal ditentukan oleh Validator EN 16931 / Schematron, atau oleh otoritas pajak penerima, bukan oleh pustaka.

Instalasi

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

Core menyertakan EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface, dan ValidationResult di NextPDF\Contracts\EInvoice. Docblock antarmuka ini menyatakannya secara eksplisit: tingkat Pro (mesin byte-rewrite Factur-X 1.08) dan tingkat Enterprise (builder PDF/A-managed) mengimplementasikan kontrak ini. Core saja tidak menanamkan faktur. Core mendefinisikan kontrak byte-in/byte-out yang dipenuhi oleh tingkat tersebut.

Ikhtisar konseptual

NextPDF\Contracts\EInvoice\ProfileType adalah pembeda profil untuk kesesuaian EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Metode isEn16931Conformant() mengodekan aturan tersebut langsung dari EN 16931-1. MINIMUM dan BASIC_WL tidak sesuai EN 16931 (keduanya tidak memenuhi kardinalitas pengenal spesifikasi BT-24 dan persyaratan item baris). BASIC, EN16931, EXTENDED, XRECHNUNG sesuai EN 16931.

Embedder (EmbedderInterface) terikat kontrak untuk:

• mengurai XML CII yang diberikan melalui XmlGuard (aman terhadap XXE);
• menyuntikkan skema ekstensi XMP Factur-X untuk profil yang dideklarasikan;
• melampirkan XML sebagai berkas tertanam dengan AFRelationship yang benar (Data / Alternative) sehingga substrat arsip PDF/A-3 (persyaratan berkas tertanam §6.7.5 — kunci F/UF) memuatnya.

NextPDF menghasilkan struktur ini. Struktur ini tidak menyatakan bahwa faktur tersebut valid secara fiskal. Otoritas penerimalah yang membuat keputusan tersebut berdasarkan aturan bisnis EN 16931 §7 dan CIUS nasional mana pun.

Permukaan API

Simbol	Efek
Contracts\EInvoice\EmbedderInterface	Kontrak byte-in/byte-out; diimplementasikan oleh Pro/Enterprise.
Contracts\EInvoice\ProfileType (enum)	Pembeda profil untuk EN 16931.
ProfileType::isEn16931Conformant(): bool	False untuk MINIMUM/BASIC_WL; true untuk BASIC/EN16931/EXTENDED/XRECHNUNG.
Contracts\EInvoice\ValidatorInterface	Kontrak validasi yang mengembalikan ValidationResult berisi pelanggaran aturan.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Alur produksi (tingkat Pro) menanamkan XML CII ke dalam basis PDF/A-3. Setelah itu, alur ini menjalankan validator Schematron EN 16931, atau mengirimkannya ke otoritas penerima, lalu menjadikan laporannya sebagai gerbang keputusan. NextPDF menghasilkan XML yang tertanam dan lampiran PDF/A-3; validator atau otoritaslah yang menentukan validitas fiskal. Core saja tidak dapat menjalankan alur ini. nextpdf/pro diperlukan untuk mesin embedder.

Kasus tepi & jebakan

• Core hanya memiliki kontrak. Tanpa nextpdf/pro tidak ada embedder konkret. Kode pemanggil harus bergantung pada antarmuka dan menurunkan kemampuan secara eksplisit saat implementasi Pro tidak tersedia.
• MINIMUM / BASIC_WL bukan EN 16931. isEn16931Conformant() mengembalikan false untuk profil ini; jangan mengiklankan faktur EN 16931 saat menggunakannya.
• Substrat PDF/A-3. XML yang tertanam berada dalam kontainer arsip PDF/A-3; kunci berkas tertanam F/UF (PDF/A §6.7.5) harus ada.
• XML diurai dengan cara yang aman terhadap XXE. Kontrak ini mewajibkan penguraian XmlGuard; embedder khusus tidak boleh memperkenalkan sink XXE.
• Validitas bukan keputusan pustaka. Menghasilkan berkas Factur-X yang benar secara struktural tidak berarti otoritas pajak akan menerimanya.

Performa

Penanaman menulis ulang PDF untuk menambahkan lampiran XML dan skema ekstensi XMP. Anggarannya adalah wall ≤ 1500 ms dan puncak ≤ 128 MB untuk faktur biasa.

Catatan keamanan

XML yang tertanam diurai dengan cara yang aman terhadap XXE melalui XmlGuard. XML faktur berisi informasi komersial yang dapat mengidentifikasi individu (PII), termasuk pihak-pihak dan jumlah. XML ini tertanam, bukan dienkripsi. Kerahasiaan faktur adalah tanggung jawab integrator.

Residensi data & mitigasi PII

XML faktur membawa PII pihak terkait dan data finansial. Penanaman berlangsung di dalam proses; tidak ada data yang keluar dari proses selama penanaman. Pengiriman ke otoritas penerima berada di luar cakupan dan menjadi tanggung jawab integrator terkait residensi data.

Telemetri aman & pembersihan log

Jangan pernah mencatat XML CII atau byte PDF yang tertanam dalam log — keduanya berisi PII faktur. Hanya catat nama profil dan putusan struktural dalam log.

Model ancaman

Berkas Factur-X tidak memiliki kontrol akses bawaan. XML yang tertanam dapat dibaca oleh siapa pun yang memiliki berkasnya. Hibrida ini menjamin keterbacaan mesin atas faktur, bukan kerahasiaannya maupun penerimaan fiskalnya.

Perilaku mode FIPS

Penanaman tidak melakukan kriptografi. Faktur Factur-X yang ditandatangani ditangani oleh resep tanda tangan tersendiri dan mewarisi postur FIPS dari resep tersebut. Halaman ini tidak membuat klaim penandatanganan.

Kesesuaian

Klaim	Spesifikasi	Klausul	reference_id
Faktur EN 16931 membawa istilah bisnis model data semantik.	EN 16931-1	§6.4
Kesesuaian EN 16931 diatur oleh kardinalitas aturan bisnis yang harus dipenuhi oleh faktur yang sesuai.	EN 16931-1	§7
Profil EN 16931 Factur-X mewajibkan kesesuaian aturan bisnis CII-XML.	Factur-X 1.08	Profil EN 16931
Profil EN 16931 Factur-X mewajibkan konten faktur yang diperlukan.	Factur-X 1.08	Profil EN 16931
Factur-X adalah hibrida: XML yang dapat dibaca mesin tertanam bersama PDF yang dapat dibaca manusia.	Factur-X 1.08	Basic
XML yang tertanam berada dalam substrat arsip PDF/A (kunci berkas tertanam F/UF).	ISO 19005-4	§6.7.5

Kutipan berupa penunjuk clause-id + reference_id ke dalam korpus verifikasi. Tidak ada teks standar yang direproduksi; klausul diringkas dengan kata-kata NextPDF sendiri.

Lihat juga

• Halaman utama kesesuaian
• Kesesuaian PDF/A-4
• Dasar PDF 2.0
• Modul kesesuaian