ZATCA-EINVOICING

1. ZATCA Phase 2 E-Invoicing Engine & Microservice

Automates Saudi Arabia's Phase 2 tax e-invoicing logic by extracting CSID credentials, constructing UBL 2.1 XML invoices, generating Base64 TLV QR codes, and routing payloads to a local Flask microservice for cryptographic canonical hashing.

⚙️ Workflow Architecture & Node Breakdown

Manual Execution Trigger: Initiates the end-to-end testing pipeline for XML construction and microservice signing.

JavaScript Code Nodes: Initializes invoice line items, customer details, and constructs the official UBL 2.1 XML data structures.

Extract CSID Credentials: Extracts Cryptographic Stamp Identifier (CSID) certificates and keys required for ZATCA Phase 2 signing.

Build UBL XML & TLV QR: Dynamically calculates the mandatory 5-tag TLV (Tag-Length-Value) Base64 QR code payload.

Sign via Flask Microservice (HTTP Request): Sends raw XML payloads to a local Python/Flask backend (app.py running on host.docker.internal:5000) to execute XML C14N canonicalization and compute SHA-256 hashes.

Consolidate ZATCA Payload: Merges signed cryptographic hashes, Base64 QR strings, and XML structures into a consolidated JSON payload.

Mock Compliance Response: Simulates ZATCA clearance and reporting API response states for local testing.

🚀 Planned Upgrades / Production Roadmap

Live CSID Onboarding: Automate the dynamic request of Compliance and Production CSIDs via ZATCA's official Sandbox and Production REST APIs.

Database Persistence: Connect PostgreSQL/MySQL node drivers to store generated UUIDs, invoice counter values (ICV), and previous invoice hashes (PIH) for audit trailing.

Production Deployment: Containerize the Flask microservice and n8n engine using Docker Compose for cloud VPS deployment.