gPdf render/edge
ব্লগ

Mustang দিয়ে ZUGFeRD validate করা: কী pass করে, কী fail করে, কেন

Mustang হলো Factur-X / ZUGFeRD-এর de-facto reference checker। PDF/A-3-এ CII XML embed করলে সাধারণ failure modes এবং ship করার আগে verification।

by gPdf ইঞ্জিনিয়ারিং দল
#e-invoice#zugferd#factur-x#validation

২০২৬ সালে আপনি যদি জার্মান B2B customer-কে e-invoice পাঠান, ফাইলটি হয় ZUGFeRD-compliant হবে, নয়তো receipt পর্যায়েই bounce করবে। France-এ Factur-X-এর ক্ষেত্রেও একই কথা। Format হলো PDF/A-3 wrapper, যার সঙ্গে EN 16931 CII XML attached থাকে। Scratch থেকে generate করা কঠিন, আর validate করতে reference engine লাগে।

প্র্যাকটিক্যালি সেই engine হলো Mustang (mustangproject.org)। এটি open-source Java project, PDF/A-3 থেকে embedded XML extract করে EN 16931 Schematron-এর বিরুদ্ধে validate করে। ZUGFeRD ও Factur-X support-এর ক্ষেত্রে open-source tools-এর মধ্যে Mustang সবচেয়ে গভীর, এবং অনেক independent verifier এটিই চালায়।

এই পোস্টে Mustang যে failure modes ধরে এবং দ্রুত চালানোর পদ্ধতি দেখানো হলো।

Mustang আসলে কী check করে

Factur-X বা ZUGFeRD PDF দিলে Mustang মোটামুটি এসব করে:

  1. Embedded file extract করে। PDF/A-3 attachments রাখে /EmbeddedFiles name tree-তে। Mustang canonical filename খোঁজে (factur-x.xml for Factur-X, zugferd-invoice.xml for ZUGFeRD 2.x) এবং bytes পড়ে।
  2. AFRelationship check করে। Attached file-কে Factur-X / ZUGFeRD baseline অনুযায়ী AFRelationship="Alternative" হতে হবে। অন্য কিছু (Source, Data, Supplement) fail।
  3. XMP namespace এবং version check করে। Factur-X 1.0 ব্যবহার করে urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#। ZUGFeRD 2.x ব্যবহার করে urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#। ভুল namespace বা version string fail।
  4. XML-কে Cross-Industry Invoice (CII) হিসেবে parse করে। XML well-formed হতে হবে এবং সঠিক CII root element (rsm:CrossIndustryInvoice) দিয়ে শুরু হতে হবে।
  5. EN 16931 Schematron চালায়। Validation-এর বড় অংশ: প্রায় ২০০ business rules, field semantics, mandatory codes, totals math, VAT logic, party identifiers ইত্যাদি।

Pass মানে invoice EU-র যেকোনো EN 16931-conformant AP system-এ acceptable। Fail মানে customer-এর AP automation receipt-এ invoice reject করবে এবং AR team manual exception পাবে।

পাঁচটি failure mode যা সবচেয়ে বেশি দেখি

Teams যখন প্রথম e-invoices test করে, validator এর Mustang side-এ এগুলো বারবার আসে।

1. Wrong AFRelationship

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

PDF spec attached files-এর জন্য একাধিক relationship type allow করে। Factur-X / ZUGFeRD নির্দিষ্টভাবে Alternative চায়, অর্থাৎ attached XML visible PDF content-এর alternative representation। আপনার PDF generator যদি Data ব্যবহার করে (অনেক library-র default), Mustang সঙ্গে সঙ্গে fail করবে। Visible PDF render ঠিক থাকবে, কিন্তু structured payload 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#.

PDF-এর XMP packet-এ ঘোষণা করতে হবে এটি কোন Factur-X profile (MINIMUM, BASIC, EN 16931, EXTENDED) এবং কোন filename খুঁজতে হবে। হাতে PDF/A-3 wrapper লিখলে এটি সহজে বাদ পড়ে; gPdf-এর /api/v1/e-invoice/render endpoint এগুলো auto-emit করে।

3. CII XML well-formed, কিন্তু 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.

Real-world failures-এর বড় অংশ এটি। XML syntactically valid; business rules fail। EN 16931 Schematron rules-এর stable IDs আছে (BR-01, BR-CO-25 ইত্যাদি), specification-এ lookup করা যায়। Common ones:

  • BR-01: invoice-এ unique invoice number থাকতে হবে।
  • BR-04: issue date থাকতে হবে।
  • BR-05: invoice type code থাকতে হবে।
  • BR-CO-25: document type “Commercial invoice” হলে payment terms required।
  • BR-Z-01: VAT category codes S, Z, E, AE, K, G, O, L, M-এর একটি হতে হবে।

Source data ঠিক করুন, rebuild করুন, re-validate করুন।

4. PDF/A wrapper আসলে validate করে না

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

এখানে Mustang-এর XML check pass, কিন্তু underlying PDF/A-3 wrapper fail। Common cause: XML ঠিক আছে, কিন্তু output ordinary PDF, PDF/A-3 নয়। Embedded file আছে, কিন্তু archival wrapper rules পূরণ হয়নি। gpdf.com/validator/ parallel-এ veraPDF চালিয়ে এটি ধরে: PDF/A-3 fail veraPDF column-এ দেখা যায়, Mustang 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.

XML tool যদি UTF-8 BOM emit করে এবং raw bytes embed হয়, এটি surprising হলেও common issue। Fix: embed করার আগে BOM strip করুন। gPdf-এর e-invoice endpoint এটি normalise করে।

Java install না করেও Mustang চালানো

One-off check-এর জন্য Java + Mustang CLI install করা ঠিক আছে। কিন্তু ongoing verification — প্রতিটি generated invoice, প্রতিটি CI run যা e-invoice compliance assert করে — এর জন্য এটি unnecessary friction।

gpdf.com/validator/ Mustang browser-এ চালায়:

  1. Factur-X / ZUGFeRD PDF upload zone-এ drag করুন।
  2. Validator embedded XML extract করে এবং Mustang-এর Schematron engine চালায় (JavaScript / WebAssembly-এ compiled, Cloudflare Worker-এ run)।
  3. Mustang report, veraPDF-এর PDF/A-3 report-এর সঙ্গে side-by-side ফিরে আসে, কারণ দুই layer-ই pass হতে হবে।
  4. QA evidence-এর জন্য JSON report download করুন।

No login. No quota. Maven দিয়ে install করা Mustang-এর মতোই check, শুধু free public service হিসেবে।

TL;DR

Mustang 5 common failure modes ধরে; বেশিরভাগের সারকথা হলো file এমন tool দিয়ে generated যা fully-conformant Factur-X / ZUGFeRD PDF/A-3 emit করে না। gPdf-এর E-invoice API এক call-এ compliant file emit করে। validator Mustang + veraPDF দিয়ে result parallel verify করে।

Mustang যে bugs ধরে তার বেশিরভাগ wrapper বা AFRelationship সমস্যা, শুধু XML semantics নয়। File সঠিকভাবে generate করাই লড়াইয়ের বড় অংশ; validator হলো proof receipt।