1
Phase 1: Preparation & Registration (Week 1)
- Verify your company is in the current wave — check ZATCA portal for your effective date
- Prepare Commercial Registration — must be active and valid
- Register technical contact in ZATCA portal
- Review VAT registration — confirm VAT number correct
- Choose certified solution provider — Odoo Enterprise, SAP, Oracle, etc.
- Schedule test environment access — ZATCA Sandbox
2
Phase 2: Technical Setup (Week 1-2)
- Obtain CSID (Cryptographic Stamp Identifier) from ZATCA Sandbox
- Configure digital certificate in ERP
- Setup CSR (Certificate Signing Request)
- Test Sandbox endpoints: /compliance/invoices/clearance + /compliance/invoices/reporting
- Configure UBL 2.1 XML invoice templates
- Generate QR code templates in Base64 format
- Setup UUID generation per invoice (UUID v4)
- Setup hash chain for immutability
- Configure invoice numbering sequence (must be sequential, no gaps)
3
Phase 3: Data Mapping (Week 2)
- Map customer data: VAT number, address, contact
- Map product data: UNSPSC codes, VAT category, unit of measure
- Map tax rates: 15% standard, 0% (zero-rated), exempt
- Map fiscal categories: B2B clearance, B2C reporting, export
- Map currency codes ISO 4217 (SAR, USD, etc.)
- Map payment methods per ZATCA standards
- Map invoice types: standard, credit note, debit note, prepayment
4
Phase 4: Testing (Week 2-3)
- Test standard invoice (B2B clearance)
- Test simplified invoice (B2C reporting)
- Test credit note generation
- Test debit note generation
- Test prepayment invoice
- Test invoice cancellation workflow
- Verify XML schema validation against ZATCA XSD
- Verify QR code readable with any scanner
- Verify cryptographic stamp valid against public key
- Test offline scenario — if ZATCA API down, invoice must cache and retry
- Test concurrent invoices (100+ per second)
5
Phase 5: Edge Cases
- Export of services — VAT 0%, customer outside KSA
- Reverse charge mechanism — for imports
- Multiple line items with different tax rates
- Discounts — line-level + invoice-level
- Foreign currency invoices — exchange rate snapshot
- Long-form invoices (50+ line items)
- Customer with no VAT (B2C)
- Customer with foreign VAT (GCC + non-GCC)
6
Phase 6: Go-Live (Week 3-4)
- Obtain Production CSID from ZATCA portal
- Switch endpoints from Sandbox to Production
- Issue test invoice in production + verify clearance
- Setup monitoring + alerts for failed submissions
- Train accounting team on new workflow
- Confirm backup + retention policy (minimum 8 years)
7
Common Troubleshooting
1. Invoice rejected with "Invalid Signature" error
Cause: private key or certificate invalid. Fix: regenerate CSID + re-upload certificate.
2. QR Code doesn't open in any scanner
Cause: base64 encoding wrong or TLV format incorrect. Fix: use ZATCA's official TLV generator for validation.
3. Sequence numbers have gaps
Cause: invoices cancelled mid-stream. Fix: ZATCA requires reason for gaps in monthly report.
4. Timeout on clearance endpoint
Cause: ZATCA API slow during peak hours. Fix: retry logic with exponential backoff (max 3 retries).