Faktur dan e-invoicing

Spec Spec: EN 16931-1:2026, BT-24 EN 16931-1:2026 BT-24 Spec Spec: Factur-X 1.08 Factur-X 1.08 Spec Spec: ISO 32000-2:2020, §14.13 ISO 32000-2:2020 §14.13 Evidence ⊕ Mixed evidence Evidence: Mixed evidence

Sekilas pandang

Faktur modern adalah dua dokumen dalam satu berkas: halaman yang dibaca manusia dan payload XML yang terbaca mesin serta diuraikan oleh sistem perpajakan. Halaman ini menelusuri skenario faktur hibrida dari kewajiban hingga keluaran: apa yang dipersyaratkan ZUGFeRD dan Factur-X, bagaimana NextPDF melampirkan dan memeriksa payload terstruktur, serta di titik mana konformitas berhenti sebagai tugas mesin dan menjadi tanggung jawab Anda.

Mengapa ini penting

Beberapa yurisdiksi kini mewajibkan faktur terstruktur untuk penagihan business-to-business atau business-to-government. Tantangannya, faktur hibrida bisa terlihat sempurna di layar tetapi tetap ditolak. Penolakan terjadi pada XML yang disematkan, bukan pada pikselnya. Jika payload terstruktur kehilangan pengidentifikasi spesifikasi, mendeklarasikan profil yang salah, atau dilampirkan dengan relasi yang keliru, platform penerima akan menolaknya. Dari sisi Anda, kegagalan ini sering kali senyap, lalu baru muncul beberapa hari kemudian saat pembayaran sudah tertahan.

Membenahinya sekali saja, pada lapisan yang menghasilkan berkas, jauh lebih murah daripada menemukannya satu per satu pada faktur yang sudah lolos.

Versi singkatnya

• Faktur hibrida yang patuh adalah pembawa PDF/A dengan payload XML konforman yang disematkan sebagai associated file. Metadata pembawa harus mendeklarasikan profilnya.
• Satu field yang paling sering menentukan apakah faktur diterima atau ditolak adalah BT-24, pengidentifikasi spesifikasi. Aturan bisnis BR-1 pada EN 16931 mewajibkan setiap faktur memuatnya. Nilainya berupa URN yang menamai profil secara tepat — misalnya urn:cen.eu:en16931:2017 untuk profil EN 16931 (COMFORT).
• Peran NextPDF adalah penyematan dan validasi struktural atas XML yang disediakan pemanggil. Ia tidak menyusun isi faktur dan bukan validator otoritas pajak.
• Penerbit tetap bertanggung jawab atas ketepatan hukum dan fiskal. Hasil validasi yang bersih adalah salah satu masukan untuk keputusan tersebut, bukan sebuah sertifikat.

Bagaimana NextPDF menanganinya

NextPDF memperlakukan faktur terstruktur sebagai kontrak lintas-tier, bukan satu fitur tunggal. Mesin inti mendefinisikan antarmukanya — sebuah embedder, sebuah profile descriptor, sebuah validator — dan tier Premium menyediakan implementasinya. Pemisahan ini disengaja. Permukaan publik dibekukan di inti, sehingga call site dan pengujian menangani profil serta hasilnya dengan cara yang sama, apa pun tier yang menopangnya.

Alurnya memiliki empat tahap, dan urutannya penting karena setiap tahap bergantung pada tahap sebelumnya.

1. Author the invoice XML You (or your ERP) produce a UN/CEFACT CII or Peppol UBL payload. NextPDF never synthesizes invoice content.
2. Produce the PDF/A carrier A PDF/A-3 or PDF/A-4f document is the human-readable face and the conformant container the standard requires.
3. Embed the payload The embedder attaches the XML as an associated file with the correct AFRelationship, and injects the Factur-X XMP profile declaration.
4. Validate, then ship A structural pass checks the root, the required sections, and BT-24 against the declared profile before the file leaves your system.

Skenario e-invoice hibrida secara menyeluruh: Anda menyusun XML dan memegang ketepatan hukumnya; NextPDF membawanya dan memeriksanya secara struktural; platform penerima membuat keputusan penerimaan akhir.

Kontrak embedder bersifat byte-masuk, byte-keluar: pembawa PDF/A dan payload XML masuk, lalu byte PDF hibrida keluar. Sebelum apa pun dilampirkan, XML diuraikan melalui guard yang diperketat, yang menolak DOCTYPE, membatasi ukuran masukan, dan menolak karakter kontrol terlarang XML 1.0. Ini menutup serangan XML External Entity dan Billion-Laughs sejak desainnya, karena XML faktur lazim datang dari luar batas kepercayaan Anda.

Profile descriptor menjawab empat pertanyaan yang dibutuhkan sistem hilir: URN profil kanonik, nilai BT-24 yang harus dinyatakan, nama stabil untuk log, dan diskriminan tier-netral agar pengujian paritas dapat mengelompokkan hasilnya. Descriptor menunjukkan celah yang ada secara eksplisit. Profil ZUGFeRD MINIMUM tidak memuat pengidentifikasi spesifikasi BT-24, dan descriptor mengembalikan null untuknya alih-alih merekayasa satu. Itulah juga sebabnya MINIMUM dan BASIC WL tidak konforman terhadap EN 16931. Mesin mengodekan realitas kardinalitas, bukan menyembunyikannya.

Human-factors note: Human-factors note

Validator memiliki dua mode, dan mode standarnya konservatif. Dalam mode standar, BT-24 yang hilang dilaporkan sebagai peringatan agar pipeline yang sudah ada, yang menjadikan sebuah boolean sebagai gate keputusan, tidak mengalami regresi diam-diam. Mode strict menaikkan temuan yang sama menjadi hard error, selaras dengan semantik validator eksternal. Mode dipilih secara sengaja per pemanggilan. Mesin tidak memilihkan postur risiko untuk Anda, dan ia memberi tahu postur mana yang aktif alih-alih membiarkan Anda menyimpulkannya sendiri.

Apa kata buktinya

Perilaku di atas bertumpu pada tiga sumber, dan masing-masing membawa jenis bukti yang berbeda.

Standar menetapkan kewajibannya. Spec Spec: EN 16931-1:2026, BR-1 EN 16931-1:2026 BR-1 menjadikan pengidentifikasi spesifikasi wajib ada pada setiap faktur. Apendiks teknis Factur-X menetapkan nilai URN per profil, termasuk EN 16931 yaitu urn:cen.eu:en16931:2017. Pembawa itu sendiri merupakan urusan PDF: Spec Spec: ISO 32000-2:2020, §9 ISO 32000-2:2020 §9 mencatat bahwa rendering yang paling dapat diprediksi dan diandalkan terjadi ketika semua fon disematkan — relevan secara langsung, karena faktur yang harus tetap terbaca sepuluh tahun ke depan tidak boleh bergantung pada lingkungan fon pembaca.

Kode menjaga kontraknya. Evidence { } Code-backed Evidence: Code-backed EmbedderInterface, ProfileInterface, dan ValidatorInterface di inti adalah antarmuka nyata dan tier-netral. ProfileType::isEn16931Conformant() mengodekan pengecualian MINIMUM / BASIC WL ke dalam sistem tipe. ValidationResult adalah DTO immutable yang isValid-nya merupakan konjungsi dari “tidak ada temuan error” dan “tidak ada pelanggaran aturan fatal”.

Perilakunya didokumentasikan di tingkat kapabilitas untuk tier Premium: Evidence § Standard-backed Evidence: Standard-backed embedder melampirkan XML CII atau Peppol UBL ZUGFeRD 2.4 / Factur-X 1.08 yang disediakan pemanggil ke pembawa PDF/A-4f atau PDF/A-3b dengan relasi associated-file yang benar. Validator memeriksa model semantik EN 16931 dan pengidentifikasi BT-24. Tahap Schematron menjalankan jaringan aturan CEN yang dikompilasi ke XSLT. Tidak satu pun proses ini menghasilkan atau mengoreksi isi faktur.

Contoh praktis

Bentuk di bawah ini mengilustrasikan titik integrasinya, bukan integrasi yang siap disalin-tempel. Pembuatan pembawa dan embedder berasal dari tier Premium, sedangkan XML-nya milik Anda.

<?php

declare(strict_types=1);

use NextPDF\Contracts\EInvoice\ProfileType;
use NextPDF\Contracts\EInvoice\ValidatorContext;
use NextPDF\Contracts\EInvoice\ValidatorInterface;
use NextPDF\Contracts\EInvoice\EmbedderInterface;
use NextPDF\Contracts\EInvoice\EmbedderOptions;
use Psr\Log\LoggerInterface;

/**
 * Validate first, embed second, never ship an invalid payload.
 *
 * @param non-empty-string $carrierPdf  PDF/A-3 or PDF/A-4f carrier bytes
 * @param non-empty-string $ciiXml      Caller-authored UN/CEFACT CII XML
 *
 * @return non-empty-string Hybrid invoice bytes, ready to deliver
 */
function buildHybridInvoice(
    ValidatorInterface $validator,
    EmbedderInterface $embedder,
    LoggerInterface $logger,
    string $carrierPdf,
    string $ciiXml,
): string {
    // STRICT mode: a missing BT-24 is a hard error, not a warning.
    $context = new ValidatorContext(
        profile: ProfileType::EN16931,
        strictMode: true,
    );

    $result = $validator->validate($ciiXml, $context);

    if (!$result->isValid) {
        foreach ($result->getErrors() as $finding) {
            $logger->error('invoice.structural_finding', [
                'message' => $finding->message,
            ]);
        }

        // A failed structural check is your signal to stop, not to ship.
        throw new \RuntimeException('Invoice XML failed structural validation.');
    }

    $options = new EmbedderOptions(profile: ProfileType::EN16931);

    return $embedder->embed($carrierPdf, $ciiXml, $options);
}

Urutan tersebut adalah intinya. Validasi jauh lebih murah daripada faktur yang ditolak dan pembayaran yang tertunda, sehingga validasi dijalankan sebelum payload sempat dilampirkan.

Kesalahpahaman umum

Kesalahpahaman yang paling mahal adalah “NextPDF membuat faktur saya patuh.” Ia tidak melakukannya. Halaman ini menyatakannya dengan tegas. Mesin menyematkan dan memeriksa secara struktural XML yang Anda susun. Hasil struktural yang lolos berarti payload memiliki struktur yang diharapkan EN 16931 dan mendeklarasikan profil yang Anda minta. Itu tidak berarti faktur tersebut memadai secara hukum, disetujui otoritas pajak, atau dijamin diterima oleh platform clearance mana pun. Ekstensi nasional dan transport clearance berada di luar cakupan pada tingkat mesin. Sebagaimana dirumuskan oleh EN 16931-1 sendiri, model inti membawa informasi yang dibutuhkan untuk mendukung kepatuhan. Penerbit bertanggung jawab untuk memenuhi peraturan perundang-undangan yang berlaku.

Jebakan kedua yang lebih tersamar: dukungan terhadap suatu standar bukanlah konformitas terhadap standar tersebut. Konformitas adalah properti dari berkas akhir beserta validator, bukan properti dari pustaka yang menghasilkannya.

Cakupan dan batasan

• NextPDF tidak menyusun atau mengoreksi isi faktur. Pemanggil menyediakan XML yang valid dan tetap menjadi penerbit faktur. Daftar temuan kosong tidak membuat payload non-konforman menjadi konforman.
• Penyematan terstruktur dan validasi Schematron adalah kapabilitas tier Premium. Core mendefinisikan kontraknya; implementasinya memerlukan paket komersial. Lihat batasan di bawah ini.
• Validator hanya memeriksa model semantik EN 16931 serta kontainer ZUGFeRD / Factur-X / UBL. Ia bukan validator otoritas pajak. Transport SDI, Chorus Pro, dan XRechnung berada di luar cakupan di tingkat transport.
• Profil MINIMUM dan BASIC WL tidak konforman terhadap EN 16931 dan tidak memuat pengidentifikasi spesifikasi BT-24 — secara sengaja, mencerminkan kardinalitas standar, bukan keterbatasan mesin.
• Mesin Schematron membutuhkan ext-xsl. Rangkaian aturan dikompilasi pada waktu build. Runtime hanya mengeksekusi XSLT yang telah dikompilasi sebelumnya, dengan pemuatan sumber daya jaringan dan filesystem dinonaktifkan.
• Halaman ini menjelaskan perilaku pada tingkat kapabilitas. Ia tidak menjamin penerimaan oleh otoritas atau platform tertentu mana pun.

Structured e-invoice embedding and validation — edition availability

Edition	Availability
Core	○ Core mendefinisikan kontrak lintas-tier (EmbedderInterface, ProfileInterface, ValidatorInterface) tetapi tidak menyertakan implementasi faktur-terstruktur apa pun. Pembawa PDF biasa tanpa payload terstruktur adalah keluaran khusus Core.
Pro	○ Penyematan CII Factur-X 1.08 ke dalam pembawa PDF/A dan profile descriptor EN 16931 tersedia.
Enterprise	○ Menambahkan penyematan UBL Peppol BIS 3.0, XRechnung B2G CIUS, validasi XML COMPAT/STRICT, dan mesin aturan Schematron in-process.

Dokumen terkait

• Pengarsipan dan PDF/A — mengapa pembawa faktur adalah berkas PDF/A dan apa yang dijaminnya untuk keterbacaan jangka panjang.
• Panduan keputusan integrasi — paket ekosistem mana yang cocok untuk pipeline penagihan (generasi berbasis antrean, framework bridge, atau Connect).
• Mengoperasikan NextPDF di produksi — cara mengamati temuan dan kegagalan validasi saat faktur mengalir dalam volume besar.

Glosarium

• Faktur hibrida — satu berkas PDF yang sekaligus memuat halaman yang terbaca manusia dan payload faktur XML tersemat yang terbaca mesin.
• ZUGFeRD / Factur-X — nama Jerman dan Prancis untuk pendekatan faktur hibrida yang sama: payload XML Cross Industry Invoice (CII) UN/CEFACT yang disematkan dalam pembawa PDF/A.
• EN 16931 — standar Eropa yang mendefinisikan model data semantik dari elemen inti suatu faktur elektronik.
• BT-24 (Pengidentifikasi spesifikasi) — istilah bisnis EN 16931 yang nilainya berupa URN yang menamai secara tepat profil yang dipatuhi faktur. Diwajibkan oleh aturan bisnis BR-1.
• Profil — disebut juga tingkat konformitas (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG). Menentukan istilah bisnis mana yang harus dimuat oleh sebuah faktur.
• Associated file — berkas yang dilampirkan di dalam PDF dengan relasi terdeklarasi (AFRelationship) yang menjelaskan bagaimana ia berkaitan dengan dokumen yang tampak; mekanisme yang membawa XML faktur.
• Schematron — bahasa aturan yang digunakan untuk menyatakan aturan bisnis EN 16931. NextPDF menjalankan jaringan aturan CEN yang dikompilasi ke XSLT.