Memvalidasi ZUGFeRD dengan Mustang: apa yang pass, apa yang fail, dan alasannya

Jika Anda mengirim e-invoice ke pelanggan B2B Jerman pada 2026, file tersebut harus ZUGFeRD-compliant atau akan ditolak saat diterima. Sama di Prancis dengan Factur-X. Formatnya adalah wrapper PDF/A-3 dengan EN 16931 CII XML terlampir; membuatnya dari nol tidak sederhana, dan validasi membutuhkan reference engine.

Dalam praktiknya engine itu adalah Mustang (mustangproject.org): proyek Java open-source yang mengekstrak embedded XML dari PDF/A-3 dan memvalidasinya terhadap EN 16931 Schematron. Mustang punya dukungan terdalam untuk ZUGFeRD dan Factur-X di antara tool open-source, dan banyak independent verifiers menjalankannya.

Artikel ini membahas failure modes yang ditandai Mustang dan cara lebih cepat menjalankannya.

Apa yang sebenarnya dicek Mustang

Saat Anda memberi Mustang PDF Factur-X atau ZUGFeRD, kira-kira ia melakukan:

1. Extract embedded file. PDF/A-3 menyimpan attachments di name tree /EmbeddedFiles. Mustang mencari canonical filename (factur-x.xml untuk Factur-X, zugferd-invoice.xml untuk ZUGFeRD 2.x) dan membaca bytes.
2. Check AFRelationship. Attached file harus dideklarasikan sebagai AFRelationship="Alternative" sesuai baseline Factur-X / ZUGFeRD. Nilai lain (Source, Data, Supplement) fail.
3. Check XMP namespace dan version. Factur-X 1.0 memakai urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#. ZUGFeRD 2.x memakai urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#. Namespace atau version string salah akan fail.
4. Parse XML sebagai Cross-Industry Invoice (CII). XML harus well-formed dan mulai dengan CII root element yang benar (rsm:CrossIndustryInvoice).
5. Run EN 16931 Schematron. Ini bagian utama validasi: sekitar 200 business rules tentang field semantics, mandatory codes, totals math, VAT logic, party identifiers, dan lainnya.

Pass = invoice dapat diterima oleh AP system mana pun yang EN 16931-conformant di EU. Fail = AP automation pelanggan akan menolak invoice saat receipt dan tim AR mendapat manual exception.

Lima failure mode yang paling sering

Ini sering muncul di sisi Mustang pada validator saat tim menguji e-invoice pertama mereka.

1. Wrong AFRelationship

ERROR: Embedded file factur-x.xml uses AFRelationship="Source",
expected "Alternative".

PDF spec mengizinkan beberapa relationship types untuk attached files. Factur-X / ZUGFeRD secara spesifik membutuhkan Alternative, artinya attached XML adalah alternative representation dari visible PDF content. Jika PDF generator memakai Data (default di banyak libraries), Mustang langsung fail. PDF visual tetap render, tetapi structured payload tidak valid bagi AP system.

2. Wrong / missing XMP namespace

ERROR: XMP metadata missing fx:DocumentType or fx:DocumentFileName under
namespace urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#.

XMP packet PDF harus menyatakan profile Factur-X (MINIMUM, BASIC, EN 16931, EXTENDED) dan filename yang harus dicari. Ini mudah terlewat saat menulis wrapper PDF/A-3 manual; endpoint gPdf /api/v1/e-invoice/render mengeluarkannya otomatis.

3. CII XML well-formed, tetapi EN 16931 Schematron fail

ERROR: BR-CO-25 — In an invoice (BR-01) the
  ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime is required when
  ram:DocumentTypeCode is 380.

Inilah sebagian besar failure dunia nyata. XML valid secara sintaks; business rules yang fail. EN 16931 Schematron rules punya stable IDs (BR-01, BR-CO-25, dll.) yang bisa dicari di spesifikasi. Yang umum:

• BR-01: invoice harus punya unique invoice number.
• BR-04: invoice harus punya issue date.
• BR-05: invoice harus punya invoice type code.
• BR-CO-25: payment terms required ketika document type adalah “Commercial invoice”.
• BR-Z-01: VAT category codes harus salah satu dari S, Z, E, AE, K, G, O, L, M.

Perbaiki source data, rebuild, lalu re-validate.

4. PDF/A wrapper tidak valid

INFO: CII XML extracted and validates against EN 16931.
ERROR: PDF/A-3b conformance check failed: missing Output Intent.

Di sini XML check Mustang pass, tetapi underlying PDF/A-3 wrapper fail. Penyebab umum: XML benar, tetapi yang di-emit adalah PDF biasa, bukan PDF/A-3. Embedded file ada, tetapi archival wrapper rules tidak terpenuhi. Validator di gpdf.com/validator/ menangkap ini dengan menjalankan veraPDF paralel: PDF/A-3 fail muncul di kolom veraPDF sementara Mustang melaporkan XML pass.

5. Encoding / declaration mismatch

ERROR: XML declares <?xml version="1.0" encoding="UTF-8"?> but the
embedded byte stream is UTF-8 with BOM. Mustang strict mode rejects BOM.

Ini cukup umum saat XML tool mengeluarkan UTF-8 BOM dan bytes itu di-embed raw. Solusi: strip BOM sebelum embedding. Endpoint e-invoice gPdf menormalisasi ini.

Cara menjalankan Mustang tanpa install Java

Install Java + Mustang CLI masih oke untuk one-off check. Untuk ongoing verification — setiap invoice yang dibuat, setiap CI run yang assert e-invoice compliance — itu friction yang tidak perlu.

gpdf.com/validator/ menjalankan Mustang di browser:

1. Drag PDF Factur-X / ZUGFeRD ke upload zone.
2. Validator mengekstrak embedded XML dan menjalankan Schematron engine Mustang (compiled ke JavaScript / WebAssembly, berjalan di Cloudflare Worker).
3. Report Mustang kembali side-by-side dengan report PDF/A-3 dari veraPDF, karena kedua layer harus pass.
4. Download JSON report untuk QA evidence.

Tanpa login. Tanpa quota. Jenis Mustang yang sama seperti yang Anda install via Maven, disajikan sebagai free public service.

TL;DR

Mustang menandai 5 failure modes umum; sebagian besar artinya file dibuat oleh tool yang tidak mengeluarkan Factur-X / ZUGFeRD PDF/A-3 yang fully-conformant. E-invoice API gPdf mengeluarkannya dalam satu call. validator memverifikasi hasilnya dengan Mustang + veraPDF paralel.

Sebagian besar bug yang ditangkap Mustang ada di wrapper atau AFRelationship, bukan hanya XML semantics. Generate file dengan benar sudah menyelesaikan sebagian besar pekerjaan; validator adalah receipt yang membuktikannya.