Pre-Built REST API & Webhook MiddlewarePre-Built REST API & Webhook Middleware

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.

Technical Data Pipeline

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.

01. ERP Source

Invoice Origination

Custom ERP / Retail POS / Hospital HIMS / Travel & Logistics Billing

02. Connector Layer

Payload Extraction

Pre-Built REST JSON API (POST /api/v1/erp/invoices, /api/v2/invoices/submit) or Scheduled Pull Sync

03. Saky ZATCA Middleware

XML & Cryptographic Stamp

Pre-Built JSON-to-UBL 2.1 XML Mapping, Schematron Check, ECDSA Signing & FATOORA Submission

04. ERP Write-Back

Cleared XML & QR Return

Pre-Built JSON API Response + HMAC Webhook Callback with Cleared XML, UUID & Base64 TLV QR

Engineering Challenges Solved

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.

Connector Capabilities

Custom ERP & POS ZATCA Capabilities

Pre-Built in Saky Middleware

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.

Implementation Evidence: Implemented in routes/api_v1.ts, routes/api_v2.ts, middleware/hmacMiddleware.ts, and services/xmlService.ts; verified in verify_v1_api.ts.
Pre-Built in Saky Middleware

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`).

Implementation Evidence: Implemented in IntegrationService.processInvoiceRecord (integrationService.ts lines 283–452) and deployed across 4 KSA branches.
API-Based Integration

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`).

Implementation Evidence: Implemented in IntegrationService.fetchAndProcessInvoices (lines 102–233), IntegrationService.reflectStatusToERP (lines 638–765), and SyncService.
Customer-Specific ERP Development

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.

Implementation Evidence: Documented in INTEGRATION.md and ApiDocs.tsx with complete JSON request/response examples and webhook verification guides.
Supported Invoice & Note Types

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
Transparent Engineering Scope

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.

1. Pre-Built in Saky Middleware

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)
2. API-Based Integration

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)
3. Customer-Specific ERP Scope

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
Onboarding Roadmap

4-Step Custom ERP & POS Integration Process

01

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.

02

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.

03

Branch EGS & CSID Onboarding

Register each branch or POS group, complete the 6 mandatory ZATCA compliance check invoice types, and issue Production CSIDs.

04

Production Cutover & Audit Monitoring

Switch API keys to production, embed returned QR codes on your customer PDFs/receipts, and monitor real-time clearance logs.

Integration FAQ

Custom ERP & POS ZATCA Phase 2 Questions

Any system capable of making HTTPS REST requests (.NET, Java, PHP, Python, Node.js, Go, Ruby) or exposing a REST/webhook feed can integrate. We also support SAP and Oracle landscapes via API middleware and custom adapter implementation (not marketed as native pre-built SAP/Oracle connectors).
KSA Enterprise Integration Assessment

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.