Memvalidasi E-Invoice: veraPDF dan Mustang di Delphi

Sebuah faktur Factur-X atau ZUGFeRD sejatinya adalah dua dokumen yang memakai satu nama file. Dokumen luarnya adalah kontainer PDF/A-3 yang harus bisa diterima oleh aplikasi pembaca arsip untuk sepuluh tahun ke depan. Dokumen di bagian dalamnya adalah faktur XML yang harus bisa diurai oleh sistem akuntansi pihak pembeli sesuai dengan standar EN 16931. Kesalahan yang sering membuat faktur rusak terkirim ke tahap produksi adalah pemikiran bahwa bila bagian pertama benar maka bagian kedua otomatis benar. Nyatanya tidak. Sebuah file bisa saja berupa PDF/A-3 yang sempurna namun membawa XML yang ditolak otoritas pajak, dan ia juga bisa membawa XML EN 16931 yang sempurna di dalam kontainer yang gagal saat divalidasi arsipnya. Kedua lapis tersebut divalidasi oleh dua alat berbeda yang tidak tahu menahu satu sama lain, dan alur kerja (pipeline) yang nyata harus memenuhi keduanya

Dua validator, dua pertanyaan berbeda

veraPDF merupakan implementasi acuan untuk format PDF/A. Jika diarahkan ke sebuah faktur, alat ini akan menjawab satu pertanyaan: apakah ini file PDF/A-3 yang patuh standar. Alat ini mengecek hal-hal yang dipedulikan oleh ISO 19005-3. Apakah semua fonta disematkan. Apakah OutputIntent ada. Apakah metadata XMP mendeskripsikan bagian dan level kepatuhan yang benar. Untuk e-invoice, alat ini juga memeriksa sistem berkas terkait (associated-file) yang disyaratkan oleh PDF/A-3, sebab XML-nya ikut tersemat dengan sebuah /AFRelationship serta entri array /AF di katalog dokumen. veraPDF tidak peduli apakah hitungan total fakturnya akurat, karena hal tersebut berada di luar batas tugasnya

Mustang adalah alat validator open-source dari Mustangproject. Alat ini menanyakan pertanyaan yang menyilang: apakah XML yang disematkan adalah faktur yang valid. Alat ini mencocokkan XML dengan skema dari profil yang dideklarasikan, lalu menerapkan aturan bisnis EN 16931 dan aturan spesifik negara di atasnya, termasuk CIUS dari XRechnung. Alat ini memeriksa apakah nomor identitas PPN penjual disertakan bila angka totalnya mensyaratkan hal tersebut, apakah nominal kelonggaran (allowance) dan biaya (charge) sinkron dengan nilai total dokumen, dan apakah URN profil dalam XML selaras dengan profil yang diutarakan file tersebut. Mustang tidak memedulikan apakah PDF di luarnya menyematkan fonta, karena hal itu merupakan tugas veraPDF

Masing-masing alat tidak menggantikan yang lain. veraPDF bisa meloloskan kontainer yang sempurna sekalipun membawa XML omong kosong. Mustang meloloskan XML sempurna meskipun dibungkus dalam kontainer yang kehilangan OutputIntent. Masing-masing alat menangkap cacat yang diabaikan oleh alat lainnya, inilah mengapa rangkaian validasi yang serius harus menjalankan keduanya dan menganggap sebuah file siap rilis hanya ketika kedua alat setuju

Matriks validasi

Untuk membuktikan pustaka ini memproduksi file yang bertahan dari kedua gerbang pengujian tersebut, rangkaian harness pengujinya membangun sebuah matriks. Enam profil faktur mencakup cakupan yang sering dijumpai alur kerja Eropa pada praktiknya: Factur-X EN 16931, Factur-X BASIC, varian B2B Prancis Factur-X EXTENDED, XRechnung 3.0, ZUGFeRD 1.0 COMFORT, dan ZUGFeRD 2.0 BASIC. Setiap profil dibuat berdasarkan dua level sub-kepatuhan PDF/A, yakni 3b dan 3u, sebab level B dan level U memiliki syarat pemetaan Unicode yang beda dan file yang lulus satu level bisa gagal di level lainnya. Enam profil dikali dua level sama dengan dua belas file, dan semuanya dirender di latar (headless) memakai baris kode yang juga sama persis dengan yang disertakan contoh GUI, jadi berkas-berkas sampel ini tidak diperbaiki secara manual demi lulus pengujian ini

Modul generator akan menulis semua dua belas file dan sebuah skrip mengumpankan tiap file tersebut ke kedua alat validasi. Di uji coba penuh awal, veraPDF berhasil meloloskan keseluruhan dua belas file. Perihal tatanan sistem pendukung kontainer terbukti presisi di seluruh elemen: file pendamping sukses terdaftar, level kepatuhan XMP dideklarasikan sesuai, serta intent output juga terpasang. Di sisi lain Mustang meloloskan delapan dokumen. Empat e-invoice yang ditolak ini merupakan dokumen format PDF/A-3 berstruktur sah patuh kaidah namun menyimpan muatan data XML cacat dan tertolak verifikasi bisnis, dan kondisi seperti inilah alasannya Anda memerlukan arsitektur sepasang perangkat penguji guna mengendus kecacatan ini. Andaikan skrip otomatis ini sekadar bergantung kepada veraPDF murni sendirian saja, keempat faktur bermasalah ini pasti divonis berhasil siap terkirim

Dua perbaikan yang menutup kesenjangan itu

Keempat faktur yang gagal pada Mustang itu berasal dari sepasang biang perkara berbeda, lalu cara perbaikan dari setiap penyebab ini menyajikan sebuah wawasan esensial yang sungguh berharga sebelum Anda sendiri memulai mengolah pembuatan profilnya nanti

Penyebab cacat perdana menyangkut jenis struktur Factur-X profil EXTENDED khusus relasi bisnis ke bisnis B2B negara Prancis. Skrip pembuat awal membubuhkan penamaan string internal untuk tingkat level kepatuhan serta teks referensi internal sebagai identitas panduannya, dan Mustang mengembalikan penolakan berbekal rincian notifikasi kesalahan jenis invalid-conformance-value lantas disusul pesan gagal dengan label unsupported-profile-type. Latar insidennya tak lain lantaran lokasi wadah bidang data XMP tag fx:ConformanceLevel dilarang dipakai sebagai sarana isian penamaan sebebasnya kreasi profil kepunyaan kita sendiri. Dokumen standar Factur-X menetapkan secara tegas eksklusif lima takaran standar murni baginya: MINIMUM, BASIC WL, BASIC, EN 16931, hingga EXTENDED. Suatu rupa e-invoice khusus jenis B2B Prancis di atas kertas di tataran tingkat metadata XMP senantiasa diproses dinilai selaku dokumen jenis profil EXTENDED. Nuansa karakter penempatan peruntukan negara Prancis dalam file fakturnya tak diekspresikan via perakitan rekayasa takaran tipe nilai kepatuhan profil mandiri bernomor enam. Informasi spesifik negara ini disampaikan lewat sandi inisial singkatan nama negara, yakni FR, ditambah oleh penempatan nomor identitas pengenal panduan di rincian tatanan XML di bagian dalamnya, di mana kode tersebut mutlak mengharuskan sisipan prefiks karakter urn:cen.eu:en16931:2017#conformant# sebagai cap bukti CIUS itu sesuai format kepatuhan dari basis parameter EN 16931. Penerapan nilai tipe EXTENDED bawaan ini seraya menyisipkan sandi inisial kode wilayah negara berupa parameter FR dipadukan bersama format panduan teks URN akurat yang sesuai standar akan memperbaiki struktur file faktur itu menjadi patuh

Di ruang lingkungan peruntukan antarmuka pemrograman aplikasi milik library itu, perbaikannya terwujud dalam pemanggilan fungsional terhadap komando AddFacturXAssociatedFileFromString seraya mensinkronkan nilai level jenis kepatuhan, kode letak regional benua negaranya, hingga nilai jenis sandi parameter penanda panduannya. Parameter nilai level tingkatan parameter patuhnya (conformance level) diisikan kode jenis wujud jenis bawaan token standar, sementara parameter elemen parameter argumen parameter wilayah lokasinya wajib mendapati huruf sandi inisial karakter FR, lantas isian kode identitas URN kepemilikan wujud nama sandi panduannya diam mendiami wujud format tipe rincian nilai besaran rangkaian byte XML isian yang kelak disodorkan didistribusikan disuntikkan disusupkan tersebut

var
  FileID: Integer;
begin
  PDF.SetPDFAMode(5);            // PDF/A-3b
  PDF.NewDocument;
  // ... draw the human-readable invoice page ...
  // ExtendedXML carries an EN 16931 guideline URN of the form
  //   urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended
  FileID := PDF.AddFacturXAssociatedFileFromString(
    ExtendedXML,
    'EXTENDED',          // standard fx:ConformanceLevel, not an internal label
    'factur-x.xml',
    'Factur-X EXTENDED invoice',
    'Alternative',       // /AFRelationship
    '1.0',
    'FR');               // France B2B marked by country code, not by conformance
  if FileID = 0 then
    raise Exception.Create('Factur-X attachment rejected');
  PDF.SaveToFile('02_Factur-X-EXTENDED-FR_PDFA-3b.pdf');
end;

Penyebab kedua berhubungan dengan profil ZUGFeRD 1.0 COMFORT, dan ini sama sekali tidak terkait dengan metadata. ZUGFeRD 1.0 divalidasi terhadap XSD :1p0, yang memiliki aturan lebih ketat terkait kardinalitas (cardinality) dibandingkan dengan apa yang tertulis di ringkasan dokumentasinya. XSD mensyaratkan bahwa elemen rekapitulasi tajuk (header settlement summation), ram:SpecifiedTradeSettlementMonetarySummation, wajib memuat masing-masing tepat satu ram:ChargeTotalAmount dan ram:AllowanceTotalAmount. XML yang dihasilkan sebelumnya menghilangkan keduanya, sehingga Mustang melaporkan bahwa elemen-elemen ini wajib hadir tepat satu kali. Ini bukanlah elemen opsional karena skema tersebut menetapkan nilai minOccurs sebagai satu. Menyertakan keduanya sesuai urutan pada XSD, yakni persis sesudah ram:LineTotalAmount, dengan nilai 0.00 bilamana tidak ada biaya atau kelonggaran, terbukti memenuhi syarat skema tersebut. Nilai nol berarti elemen itu ada; absennya sebuah elemen berarti pelanggaran skema. Dengan diimplementasikannya dua perbaikan ini, matriks pengujian pun mencetak hasil dua belas dari dua belas di Mustang sekaligus menjaga hasil dua belas dari dua belas di veraPDF

Kolom XRechnung yang membalik status dari tidak valid ke valid

XRechnung patut mendapat catatan khusus karena pedoman CIUS Jermannya menambahkan sekumpulan aturan bisnis yang tidak ada di standar bawaan EN 16931, dan aturan-aturan ini bisa menggagalkan file dengan cara yang sekilas terlihat normal-normal saja. Dua aturan di antaranya terkait dengan alamat elektronik. BT-34 adalah elemen alamat elektronik pihak penjual dan BT-49 adalah elemen alamat elektronik pihak pembeli, yakni titik akhir rute (routing endpoints) yang dipakai oleh portal sektor publik Jerman guna mengirim dan mengkonfirmasi faktur. Di model awal EN 16931, elemen-elemen ini sifatnya opsional. Akan tetapi, XRechnung mewajibkannya. Jika salah satu sengaja tak dimasukkan, faktur tersebut akan bernilai valid secara bentuk dan skema, namun tetap akan ditolak

Hal yang ketiga menyangkut aturan BR-DE-6, yang mewajibkan hadirnya elemen nomor telepon kontak dari pihak penjual. Elemen informasi kontak seperti ini sering kali diabaikan oleh para pengembang lantaran ini dianggap layaknya presentasi rupa alih-alih elemen data pokok, dan ketidakhadirannya lantas memicu respon kegagalan validasi yang menunjuk pada grup kontak penjual, bukan menunjuk langsung secara eksplisit pada elemen spesifik apa yang tertinggal. Menyematkan nilai BT-34, BT-49, beserta elemen rincian nomor kontak sang penjual itulah yang sukses menggeser status sebuah file XRechnung yang semula tidak valid menjadi valid di ranah uji Mustang, dan tidak satupun perubahan ini berimbas sedikitpun terhadap hal-hal yang ditangkap oleh veraPDF, mengingat letak ketiga elemen ini murni tersembunyi di dalam XML itu sendiri

Mengalirkan output pustaka ke validator

Prinsip arsitektur di balik program pengujian ini dapat ditarik fungsinya ke berbagai sistem bisnis. Pustaka PDF menuliskan dokumen kontainer yang selaras lalu menyisipkan elemen XML-nya. Pustaka ini tidak, dan tidak seharusnya, bertindak sok memposisikan dirinya selaku pemutus otoritas aturan bisnis EN 16931. Metode ValidateFacturXInvoice yang tersemat di ranah pustaka semata-mata memeriksa urusan konsistensi integritas sang kontainer, lantas mengevaluasi agar kumpulan /AF array di katalog, himpunan struktur nama file tersemat, elemen metadata XMP DocumentFileName, atribut nilai profil, kode pengidentifikasi panduan, maupun wujud /AFRelationship keseluruhan unsur tersebut saling tervalidasi selaras setuju satu sama lain, namun pustaka ini sama sekali menolak berupaya untuk menakar menjustifikasi akurasi isi sandi perhitungan pajaknya ataupun menjumlahkan merekonsiliasi seluruh nominal pembayarannya. Porsi taktik arsitektural metode bagi beban rincian urusan ini buat suatu platform sistem berlatar bisnis sepatutnyalah untuk sistem Anda lalu merobek membongkar mengambil isi XML ini dari PDF seraya menyerahkannya mendelegasikannya melimpahkannya lurus kepada peranti evaluator validator spesifik murni perihal dokumen elektronik e-invoice, mutlak murni persis laksana model struktur skema harness uji kita yang mengumpankan berkas xml tersebut telak menarget aplikasi Mustang

Tahapan upaya membaca mengekstrak memindai ulang berkas tersebut menjelaskan pada Anda detail perihal apa-apa saja isian parameter wujud isian komando isian parameter komponen isian yang sebenarnya ditancapkan di berkas itu. Metode DetectFacturXInvoice berfungsi menyajikan isian lapor informasi bilamana suatu dokumen memuat rupa invoice berhasil ditangkap wujud dikenali, kemudian fungsi GetFacturXInvoiceInfo difungsikan buat menyerap melacak atribut informasi kolom atribut info metadata menurut rujukan identitas tandanya (tag): letak tag bernomor 1 yaitu wujud atribut isian elemen komponen nama file tumpangan aslinya, parameter tanda markah 2 lantas menarget wujud XMP DocumentFileName, tatanan marka tanda nomor urut 5 berisi info taraf level wujud nilai level porsi tingkat level level derajat tingkatan kepatuhan purna level kepatuhan level kepatuhannya (conformance level), marka 6 menyangkut pengidentifikasi kode panduan, dan kode tanda 7 adalah elemen /AFRelationship. Usaha memastikan wujud bahwa tingkat level taraf kepatuhan kepatuhannya level kepatuhan rincian derajat level kepatuhan yang Anda baca kembali itu berupa porsi wujud atribut rupa token elemen parameter berwujud rincian parameter token standar dan rupa parameter bukanlah label nilai identitas label sepotong penamaan seutas atribut wujud nilai string internal (an internal label) ialah mewujud strategi cara lintasan jalur skenario cara merupakan solusi cara trik langkah pendekatan strategi purna metode parameter siasat jalan siasat paling irit murah efisien termudah wujud langkah paling ekonomis sangat ringan paling murah gampang paling tatanan perihal isian ringkas termurah termurah buat menjerat melacak mengetahui mengendus mengungkap menemukan mengetahui meraba menangkap mengendus menyabot mendeteksi mengungkap membedah mengais mengungkap menyoroti melacak isian wujud menangkap blunder keliru cacat salah lapor noda kekeliruan kesalahan porsi kesalahan parameter insiden wujud wujud kekeliruan parameter elemen dari insiden blunder isian EXTENDED tersebut dari di rute tatkala waktu porsi sewaktu parameter sebelum waktu tatanan saat sebelum di sebelum isian dimensi sebelum letak (before) sebiji dokumen isian satu rupa dokumen rute suatu berkas file fungsional isian parameter dokumen dokumen isian wujud berkas file file (a file) melenggang isian minggat pergi parameter cabut wujud berangkat terkirim lepas meninggalkan porsi dari meninggalkan mengudara berangkat meninggalkan berangkat berangkat (leaves) mesin perakitan arsitektur dapur wujud sarana wujud mesin perakitan kompilasi produksi lini perakitan komponen produksi fungsional dari porsi siklus proses isian tahapan rute mesin arsitektur program tatanan ruang isian dari tatanan sistem mesin mesin alat program kompilasi proses lini porsi elemen arsitektur peranti alat kompilasi (your build)

function ExtractAndInspect(const PdfPath: string): AnsiString;
var
  Profile, Guideline: WideString;
begin
  Result := '';
  PDF.LoadFromFile(PdfPath);
  if PDF.DetectFacturXInvoice = 1 then
  begin
    Profile   := PDF.GetFacturXInvoiceInfo(5);  // fx:ConformanceLevel
    Guideline := PDF.GetFacturXInvoiceInfo(6);  // XML guideline ID
    Writeln('Profile:   ', Profile);
    Writeln('Guideline: ', Guideline);
    // Hand the raw XML to a dedicated EN 16931 / Mustang validator.
    Result := PDF.ExtractFacturXXMLToString;
  end;
end;

Jika alur produksi Anda juga harus memverifikasi kelayakan pra-cetak (preflight) dari kontainernya sebelum tahapan pembubuhan tanda tangan (signing), perihal tugas tahap uji ini dirangkum di ulasan uji kelayakan PDF/A dan PDF/UA dalam Delphi, lalu bentangan alur yang lebih masif terkait kepatuhan-dan-tanda-tangan lurus diuraikan melalui artikel pusat kendali kepatuhan dan tanda tangan dokumen (compliance and signing workbench). Keduanya dibangun di atas jalur eksekusi pemrograman serupa yang hadir sebagai wujud integrasi dari Delphi PDF Library bagi Delphi dan C++Builder, berdampingan bersama susunan API pendukung rute PDF/A, pengait berkas terkait (associated-file), serta atribut spesifikasi metadata yang digunakan di sini