Custom ERP, POS & Billing Software ZATCA Phase 2 API Integration
Your engineering team sends clean JSON. Saky ZATCA Connect handles UBL 2.1 XML, CSID cryptography, QR codes, and ZATCA FATOORA APIs.
Avoid building complex cryptographic signing, UBL 2.1 XML canonicalization, and SHA-256 hash chaining from scratch. Send standard JSON invoice payloads from your custom ERP or POS to Saky ZATCA Connect’s pre-built REST API, and let our middleware handle ZATCA FATOORA Phase 2.
How Custom ERP, POS & In-House Billing Systems Connects to ZATCA FATOORA
End-to-end transaction lifecycle from ERP invoice posting to ZATCA Phase 2 clearance and QR write-back.
Invoice Origination
Custom ERP / Retail POS / Hospital HIMS / Travel & Logistics Billing
Payload Extraction
Pre-Built REST JSON API (POST /api/v1/erp/invoices, /api/v2/invoices/submit) or Scheduled Pull Sync
XML & Cryptographic Stamp
Pre-Built JSON-to-UBL 2.1 XML Mapping, Schematron Check, ECDSA Signing & FATOORA Submission
Cleared XML & QR Return
Pre-Built JSON API Response + HMAC Webhook Callback with Cleared XML, UUID & Base64 TLV QR
Why Custom ERP & POS Teams Choose Middleware Over Custom In-ERP Coding
Complex XML C14N Canonicalization & ECDSA Cryptography
Implementing ZATCA’s exact XML canonicalization (C14N11), XAdES digital signature tags, secp256k1 ECDSA keys, and 9-tag TLV QR encoding directly inside legacy PHP, .NET, Java, or Node.js billing apps is error-prone and time-consuming.
Strict Sequential Hash Chaining (PIH & ICV)
Every invoice submitted by an EGS unit must embed the SHA-256 hash of the previous invoice (PIH) and an incrementing Invoice Counter Value (ICV). Concurrent POS terminals or web workers can easily break hash sequences without a serialized signing queue.
Certificate Renewal & Retry Queue Maintenance
When CSID certificates expire or ZATCA endpoints experience latency, in-house scripts without dead-letter retry queues risk dropping production invoices.
Custom ERP & POS ZATCA Capabilities
Pre-Built JSON-to-UBL 2.1 REST API (`v1` & `v2`)
Submit standard JSON invoice objects over HTTPS (`POST /api/v1/erp/invoices` or `POST /api/v2/invoices/submit`) authenticated via `X-API-Key` and `HMAC-SHA256`. ZATCA Connect constructs the complete UBL 2.1 XML document.
Serialized Hash Chain (PIH), ICV Counter & Saudi Address Parser
Automatically manages the Invoice Counter Value (ICV) and Previous Invoice Hash (PIH) per branch, parses Saudi building numbers/addresses, and normalizes VAT category codes (`S`, `Z`, `E`, `O`).
Built-In CSID Portal, Scheduled Pull Sync & Webhook Callbacks
Includes an administrative portal for CSR generation and OTP onboarding, a 2-minute scheduled pull engine (supporting Bearer, Basic, API Key, and `/gettoken` exchange), and HMAC-signed webhook callbacks (`reflectStatusToERP`).
Customer ERP Payload Mapping & Invoice PDF QR Rendering
Your development team maps your application’s outbound invoice JSON to our documented schema (or exposes an invoice feed endpoint) and embeds the returned Base64 TLV QR image onto your customer PDF or thermal receipt.
Supported Document Workflows
- Standard Tax Invoices (0100000 — B2B / B2G Clearance)
- Simplified Tax Invoices (0200000 — B2C POS Reporting)
- Standard & Simplified Credit Notes (381)
- Standard & Simplified Debit Notes (383)
- Prepayment / Advance Receipt Tax Invoices (386)
- Multi-Branch & Multi-Terminal Retail / Travel / Healthcare Billing
Custom ERP & POS Capability Classification: Pre-Built vs. API-Based vs. Custom Scope
We clearly distinguish what is pre-built inside Saky ZATCA Connect, what operates via standard APIs, and what requires customer-specific configuration in your ERP. SAP and Oracle are supported via API middleware only and are not marketed as native pre-built connectors.
Production-Ready Out of the Box
- REST JSON ingestion endpoints (POST /api/v1/erp/invoices, POST /api/v2/invoices/submit, GET /api/v1/erp/invoices/:id)
- API Key + HMAC-SHA256 signature verification (X-Signature, X-Timestamp, X-Nonce) and idempotency handling
- Automated 2-minute pull sync scheduler (SyncService) with Bearer, Basic, API Key, and token-exchange (/gettoken) support
- Saudi address & 4-digit building number parser, VAT category normalizer (S/Z/E/O), UBL 2.1 XML generator, and secp256k1 ECDSA signer
- Multi-branch CSID onboarding portal, PII-redacted audit logs (sanitizePayload), and HMAC webhook status callbacks (reflectStatusToERP)
Standardized REST / OData Contract
- HTTPS REST JSON push from any custom ERP, POS, HIMS, or travel/logistics billing platform (.NET, Java, PHP, Python, Node.js, Go)
- API middleware integration pathway for SAP (S/4HANA / ECC) and Oracle (EBS / NetSuite) via outbound REST/OData/IDoc staging feeds (no native SAP/Oracle plug-in claimed)
Tailored During Client Onboarding
- Mapping your custom ERP or POS invoice database fields to the Saky ZATCA Connect JSON payload contract
- Persisting the returned zatcaUuid, xmlHash, and Base64 TLV qrCode in your application database
- Rendering the returned Phase 2 QR code image on your customer-facing PDF invoice or thermal POS receipt template
4-Step Custom ERP & POS Integration Process
JSON Payload Contract & Tax Rule Mapping
Map your existing database invoice fields (seller, buyer, line items, VAT categories S/Z/E/O) to our documented JSON request schema.
Sandbox API Integration & XML Validation
Point your staging application to the ZATCA Connect API and validate generated UBL 2.1 XML payloads against ZATCA Schematron rules.
Branch EGS & CSID Onboarding
Register each branch or POS group, complete the 6 mandatory ZATCA compliance check invoice types, and issue Production CSIDs.
Production Cutover & Audit Monitoring
Switch API keys to production, embed returned QR codes on your customer PDFs/receipts, and monitor real-time clearance logs.
Custom ERP & POS ZATCA Phase 2 Questions
Related ZATCA Phase 2 Documentation
ZATCA CSID & Production Onboarding Guide
How CSR generation, compliance checks, and production CSIDs work.
ZATCA Clearance vs Reporting Explained
Technical comparison of B2B Clearance API and B2C Reporting API.
Complete ZATCA Phase 2 Integration Guide
Architecture blueprint for connecting ERPs to ZATCA FATOORA.
Additional ERP Integration Pathways
Request a Custom ERP & POS ZATCA Phase 2 Demo
Share your existing ERP environment and monthly invoice volume. Our integration engineers will walk you through the middleware architecture, UBL 2.1 XML transformation, and CSID onboarding flow.