API Development in Riyadh, Saudi Arabia

Retail / Multi-Brand

A Riyadh-based retail group (operating 85 stores across Saudi Arabia — fashion, electronics, home furnishing, and F&B — 14 brands, annual revenue SAR 2.8B) faced the mandatory ZATCA Phase 2 e-invoicing deadline. Phase 2 requiring: every B2B invoice cleared through ZATCA's API before delivery to the customer, every B2C invoice reported within 24 hours, and all invoices containing ZATCA-mandated fields including cryptographic stamps and QR codes. The specific challenges: multiple POS and billing systems (14 brands operating different systems — 4 different POS vendors across retail brands, 2 different billing systems for B2B wholesale, and a separate F&B POS. Each system generating invoices in different formats — none meeting ZATCA Phase 2 specifications. The ZATCA XML schema requiring specific fields (seller TIN, buyer TIN for B2B, invoice hash chain, QR code with specific encoded data) that the existing systems didn't capture), volume and real-time requirements (the retail group generating 45,000+ invoices daily across all stores and brands — ZATCA Phase 2 requiring real-time API calls for B2B invoices (clearance before delivery) and near-real-time reporting for B2C invoices. The API infrastructure needing to handle peak volumes during Ramadan (daily volume doubling), Saudi National Day promotions, and year-end sales), Arabic content compliance (ZATCA requiring invoice content in Arabic — item descriptions, addresses, and legal text. Many of the existing POS systems storing product data in English only — requiring Arabic product catalogue synchronisation. ZATCA also requiring Arabic error handling — when an invoice is rejected, the rejection reason must be presented to the store staff in Arabic for correction), and multi-entity complexity (the retail group operating through 6 legal entities (different CR numbers for different brand groups) — each entity having its own ZATCA registration, its own invoice numbering sequence, and its own cryptographic certificates. The API integration needing to handle multi-entity routing — determining which entity's certificate to use for each invoice based on the brand and store).

We built a centralised ZATCA e-invoicing API platform over 10 weeks: Invoice normalisation layer (weeks 1-4): connecting all POS and billing systems to a unified invoice processing platform. Each POS/billing system connected via the appropriate method — API for modern systems (2 POS vendors offering REST APIs), database CDC for systems with database access (capturing new invoices in real-time via change data capture), and file-based for legacy systems (periodic file export processed within minutes). Invoice transformation: every invoice from every source system transformed into the ZATCA-compliant XML format — with field mapping, Arabic product description lookup (product catalogue maintained centrally with Arabic and English descriptions), tax calculation validation (15% VAT correctly applied per item, with proper handling of exempt and zero-rated items), and ZATCA-mandated field addition (QR code generation, invoice hash chain computation, and cryptographic stamping using the entity's ZATCA certificate). Multi-entity handling: each invoice routed to the correct entity's processing pipeline based on the store/brand — applying the correct CR number, TIN, certificate, and invoice sequence. ZATCA API integration (weeks 3-7): real-time invoice clearance and reporting. B2B clearance: real-time API call to ZATCA for every B2B invoice. The flow: invoice generated by POS/billing → normalised and transformed → ZATCA XML created with cryptographic stamp → submitted to ZATCA API → clearance response received (approved/rejected) → if approved: invoice delivered to customer with ZATCA clearance number; if rejected: rejection reason (in Arabic) displayed to the operator for correction. Average clearance time: 1.2 seconds per invoice. Rejection handling: specific Arabic error messages for common rejection reasons — "رقم السجل التجاري غير صحيح" (incorrect CR number), "المبلغ الإجمالي لا يتطابق مع مجموع البنود" (total doesn't match line items sum) — enabling store staff to understand and correct issues immediately. B2C reporting: batch reporting of B2C invoices to ZATCA within the required 24-hour window — invoices collected throughout the day and submitted in batches every 6 hours (providing significant buffer against the 24-hour deadline). Monitoring and operations (weeks 5-10): ensuring continuous compliance. Real-time dashboard: showing ZATCA submission status across all 85 stores and 6 entities — invoices submitted, cleared, rejected, pending. Rejection rate: tracked per store and per entity with drill-down to specific rejection reasons — enabling targeted training for stores with higher rejection rates. Alert system: immediate WhatsApp alerts to operations managers for: ZATCA API unavailability (switching to queued mode — invoices queued and submitted when API recovers), high rejection rates at specific stores (indicating training need), and approaching 24-hour deadline for B2C reporting (escalation if batch submission is delayed). Arabic reporting: daily, weekly, and monthly compliance reports in Arabic — suitable for ZATCA audit requests and internal management review.

The platform launched 3 weeks before the ZATCA Phase 2 deadline — providing testing buffer. Compliance: 100% ZATCA Phase 2 compliance achieved across all 85 stores, 14 brands, and 6 legal entities by the mandatory deadline. Zero ZATCA penalties (non-compliance penalties: SAR 5,000-50,000 per violation). Processing performance: 45,000+ invoices daily processed through the platform — peak Ramadan volume of 92,000 invoices/day handled without degradation. B2B clearance: average 1.2 seconds (ZATCA API response). B2C reporting: all invoices reported within 12 hours (well within 24-hour requirement). Rejection rate: initial rejection rate of 3.8% in week 1 reduced to 0.4% by month 3 — common issues identified and addressed through store staff training and product catalogue corrections. The most common initial errors: Arabic product descriptions missing (filled in the product catalogue) and VAT calculation rounding differences (rounding rules aligned with ZATCA specifications). Operational efficiency: invoice processing time: zero additional staff time per invoice (previously: manual ZATCA-compliant invoice generation would have required estimated 15 additional staff across the 85 stores). The platform handling everything automatically — store staff continuing their normal POS workflow without ZATCA-related additional steps. Audit readiness: complete ZATCA submission history maintained — every invoice with its ZATCA clearance number, submission timestamp, and XML archive. Audit requests answered in minutes rather than weeks. Financial impact: ZATCA penalty avoidance: estimated SAR 500,000+ annually (based on observed penalties for similar-sized retailers who missed the deadline). Staff cost avoidance: SAR 720,000 annually (15 additional staff that would have been needed for manual compliance). Operational efficiency: SAR 180,000 annually (reduced invoice processing errors and disputes). Total annual benefit: SAR 1.4M. Platform development cost: SAR 680,000. Annual operating cost: SAR 120,000. First-year ROI: 88%. Ongoing: the platform handling future ZATCA requirements as regulations evolve — Phase 3 requirements accommodated through configuration changes rather than rebuilding.