Problem
A business system had to produce ZATCA-compliant e-invoices: UBL 2.1 XML structure, ECDSA signing and, for the relevant transactions, clearance through the ZATCA API. This is a compliance pipeline, not a print setting.
Business Context
The business operates in a jurisdiction where Phase 2 e-invoicing is mandatory. Invoices were already generated by the ERP layer; they now had to leave the system as compliant signed XML.
Constraints
- Compliant UBL 2.1 XML structure with correct tax data.
- ECDSA signing with the provisioned certificate (CSID).
- Clearance flow for transactions that require it.
- The engine must live inside the business system and stay maintainable.
Analysis
The signing engine candidates divided by language and licensing. The Java options were heavier; a pure-Python engine (MIT-licensed) matched the stack, the team and the requirement to keep the pipeline inside the app.
Architecture
The engine is a set of Python modules inside the business app: invoice XML generation, tax data generation, initial and final invoice signing, clearance utilities and decoding. The system calls them at the right state in the invoice lifecycle.
Solution
Generate the UBL 2.1 XML, sign it with ECDSA using the CSID, and route it through the clearance API where required — all from the existing invoice flow.
Technology
- Pure-Python signing engine (zatca_bev, MIT)
- UBL 2.1 XML generation
- ECDSA signing + CSID
- ZATCA clearance utilities
- Inside the ERP app (erpgalaxy)
Implementation
The engine files were integrated into the app's ZATCA module and wired to the invoice lifecycle, then verified against real invoices in production.
Challenges
XML structure compliance, clearance semantics for different invoice types, and keeping signing key handling inside the system without scattering it across modules.
Outcome
Compliant, signed, cleared e-invoices now leave the system directly — the invoice the business already knows is the invoice the authority accepts.
Lessons
Select compliance engines for maintainability and fit, not just headline features. A pure-Python, well-licensed engine that lives inside the system beats a heavier integration you cannot understand.
Future Improvements
Phase 2 edge-case coverage (credit notes, and the additional fields for simplified vs. standard invoices) and monitoring on clearance failures.