Direct Answer / Quick Summary:

Before an enterprise connects its ERP or Point-of-Sale (POS) system to Saudi Arabia's live Phase 2 Production Environment, the Zakat, Tax and Customs Authority mandates thorough validation on the ZATCA Simulation Sandbox Environment (gw-fatoora.zatca.gov.sa/e-invoicing/simulation).

Zero Tax Liability: Transactions cleared or reported in the Simulation Sandbox mirror live production logic byte-for-byte, but do not incur tax obligations, create accounting debts, or affect quarterly VAT returns*.

Simulation Prerequisites: Developers require: (1) An active corporate Tax Registration Number (TRN); (2) A 6-digit Simulation OTP generated from the Fatoora Portal; (3) An ECDSA secp256k1 keypair and CSR; and (4) The official ZATCA Java SDK* for local pre-flight XML validation.

End-to-End Test Pipeline:* (1) Call /simulation/compliance with OTP to obtain a Simulation Compliance CSID; (2) Pass the 6 mandatory compliance test invoices; (3) Call /simulation/production/csids to receive a Simulation Production CSID; (4) Test live B2B clearance and B2C reporting endpoints with zero financial risk.

Architectural Taxonomy: Developer Portal vs Simulation vs Production

ZATCA provides three distinct environments across the software development lifecycle. Understanding their boundaries prevents accidental production pollution:

DimensionDeveloper Developer Portal (Sandbox)Simulation Sandbox (Staging)Production Core (Live)
Gateway Hostnamegw-fatoora.zatca.gov.sa/e-invoicing/developer-portalgw-fatoora.zatca.gov.sa/e-invoicing/simulationgw-fatoora.zatca.gov.sa/e-invoicing/core
Target AudienceSoftware vendors building generic integrations.Enterprise IT & taxpayers testing their specific ERP.Operational daily business commerce.
Taxpayer CredentialsGeneric test TRN (e.g., 399999999900003).Real Taxpayer VAT TRN with portal OTP.Real Taxpayer VAT TRN with live PCSID.
Legal Validity of InvoicesNone (Zero).None (Zero). Staging mirror.100% Legal Tax Record.
Schematron Rules EngineLatest experimental/draft Schematron rules.Exact mirror of production rules.Enforces live statutory penalties.
Rate LimitsModerate (throttled on high concurrency).High (designed for volume testing).Mission-critical enterprise throughput.
Step 1Local Terminal

Local Java SDK Audit

Validate raw UBL 2.1 XML offline using ZATCA SDK CLI; eliminate XSD and Schematron syntax errors

Step 2Fatoora Web Portal

Simulation OTP Handshake

Log into Fatoora Portal, select 'Simulation Environment', generate 6-digit test OTP

Step 3Sandbox API Gateway

Simulation CSID Issuance

Submit CSR to /simulation/compliance; obtain test Compliance CSID and secret

Step 4Simulation Engine

Execute Test Suite

Clear B2B Standard Invoices, Credit Notes, Debit Notes, and report B2C receipts in sandbox

Step 5Production Gateway

Production Go-Live

Promote verified software to live /core endpoints with 100% confidence

Local Pre-Flight Testing: The ZATCA Java SDK CLI

Before sending HTTP requests over the network, developers should use the official ZATCA Java E-Invoicing SDK to catch arithmetic, UUID, and schema bugs locally:

1. Validating XML Against Schematron Rules

Run the SDK command-line interface against your generated invoice XML:

bash|Technical Specification / Reference
Verified Schema
# Offline XML validation command
fatoora -validate -invoice sample_b2b_invoice.xml

Expected SDK Output (Success):

text|Technical Specification / Reference
Verified Schema
*** INVOICE VALIDATION RESULTS ***
[INFO] XSD Validation: PASSED
[INFO] Schematron Validation: PASSED
[INFO] Cryptographic Hash Verification: PASSED
[SUCCESS] Invoice is 100% compliant with ZATCA Phase 2 specifications.

If errors exist, the SDK outputs the exact line number and rule ID (e.g., BR-CO-10: Tax amount rounding failure on line 4), allowing developers to patch software logic prior to cloud transmission.

Step-by-Step Guide: Onboarding on the Simulation Sandbox

Connecting an ERP to the Simulation Sandbox mirrors the production onboarding process:

Step 1: Generate a Simulation OTP on Fatoora Portal

1Log into the ZATCA ERAD Portal (https://zatca.gov.sa) via Nafath.
2Open the Fatoora Service (منصة فاتورة).
3In the device onboarding wizard, select Simulation Environment (بيئة المحاكاة) rather than Production.
4Click Generate OTP. The portal renders a 6-digit Simulation OTP (valid for 60 minutes).

Step 2: Request Simulation Compliance CSID (API Call)

Submit an HTTP POST request to the simulation gateway:

http|Technical Specification / Reference
Verified Schema
POST /e-invoicing/simulation/compliance HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Accept-Language: en
Accept-Version: V2
OTP: 839201
Content-Type: application/json

Request JSON Body:

json|Technical Specification / Reference
Verified Schema
{
  "csr": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0K...[BASE64_CSR]..."
}

Response (HTTP 200 OK):

json|Technical Specification / Reference
Verified Schema
{
  "requestID": 501928,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "MIIEkjCCA3qgAwIBAgIQ...[SIMULATION_X509_CERT]...",
  "secret": "e1f2a3b4-c5d6-47e8-9f0a-1b2c3d4e5f6a",
  "errors": null
}

Step 3: Pass the Mandatory Simulation Test Cases

Using the binarySecurityToken and secret for HTTP Basic Auth, submit the 6 required test scenarios to /e-invoicing/simulation/compliance/invoices:

1Standard B2B Tax Invoice (Clearance)
2Standard Credit Note referencing invoice UUID
3Standard Debit Note
4Simplified B2C Tax Invoice (Reporting)
5Simplified Credit Note
6Simplified Debit Note

Step 4: Promote to Simulation Production CSID

Once all sample documents pass validation, execute the promotion call:

http|Technical Specification / Reference
Verified Schema
PATCH /e-invoicing/simulation/production/csids HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Accept-Language: en
Accept-Version: V2
Content-Type: application/json
Authorization: Basic <Base64(Simulation_BinarySecurityToken:Simulation_Secret)>
json|Technical Specification / Reference
Verified Schema
{
  "compliance_request_id": "501928"
}

ZATCA returns your Simulation Production CSID, authorizing your software to test live simulated clearance and reporting calls.

Comprehensive Simulation Test Matrix for Enterprise QA

Enterprise Quality Assurance (QA) teams should execute the following test scenarios to verify operational resilience:

Test Case IDTransaction TypeVerification ObjectiveExpected Response
TC-SIM-01Standard B2B InvoiceNormal B2B sale with 15% VAT; clearance stamp returned.HTTP 200 OK / status: CLEARED
TC-SIM-02Simplified B2C InvoiceNormal retail cash receipt; 9-tag QR code generated.HTTP 200 OK / status: REPORTED
TC-SIM-03Zero-Rated Export InvoiceCross-border supply with VAT Category Z (0%).HTTP 200 OK / status: CLEARED
TC-SIM-04Exempt Supply InvoiceFinancial services supply with VAT Category E.HTTP 200 OK / status: CLEARED
TC-SIM-05B2B Partial Credit NoteReturns 25% of goods; links original UUID via BillingReference.HTTP 200 OK / status: CLEARED
TC-SIM-06Out-of-Sequence ICV TestDeliberately skip an ICV counter number (Negative Test).HTTP 400 Bad Request / BR-KSA-53
TC-SIM-07Broken Hash Chain TestInject incorrect PIH hash string (Negative Test).HTTP 400 Bad Request / BR-KSA-51
TC-SIM-08Gateway Timeout TestSimulate network drop; verify ERP retry and idempotency.Transaction queued locally; zero data loss

Negative Testing: Stress-Testing Edge Cases

A major advantage of the Simulation Sandbox is the ability to deliberately break rules to ensure your ERP fails gracefully:

Statutory Safeguards & Rights Protection

Mandatory protections enforced by MHRSD & Saudi Labor Law

1
Arithmetic Stress TestIntentionally submit an invoice where line items sum to SAR 100.00 but TaxTotal declares SAR 15.01 to verify that your ERP captures Schematron arithmetic rejections before going live.
2
Re-Submission Idempotency TestSubmit the identical invoice UUID twice. The simulation gateway will reject the duplicate with 'INVOICE_ALREADY_EXISTS', confirming your ERP deduplication logic.
3
Cryptographic Signature Tamper TestModify a single character in the XML after calculating the digital signature. The sandbox will reject with 'SIGNATURE_VERIFICATION_FAILED', proving tamper detection.
4
Concurrency Load TestFire 50 simultaneous clearance requests to ensure your database row-locking handles concurrent ICV generation without duplicate key violations.

Real-World Case Study: Jeddah Retail E-Commerce Marketplace

In October 2025, a Jeddah-based e-commerce platform processing 45,000 orders weekly prepared for Phase 2 Wave 9 compliance:

The Staging Strategy: The engineering team integrated its checkout microservice with the ZATCA Simulation Sandbox 6 weeks prior to their mandatory enforcement deadline.
Bugs Discovered in Sandbox:

* The checkout engine was using system UTC timestamps (14:00:00Z) rather than local Saudi Arabia time (17:00:00), failing Schematron rule BR-KSA-31.

* Promotional discount codes were generating negative line items, which is prohibited under ZATCA rules.

The Remediation: The developers patched the pricing engine to distribute discounts proportionally across item prices and aligned timestamps with local Saudi time.
Production Cutover: When the live enforcement date arrived, the platform swapped its Simulation CSID for a live Production CSID in 2 minutes, achieving zero clearance failures on launch day.

Common Simulation Errors & Immediate Developer Fixes

Gateway Error MessageRoot CauseRemediation Protocol
`401 Unauthorized: Invalid Certificate`Using a Production CSID on the Simulation gateway, or vice versa.Keep simulation and production credentials in separate configuration environments.
`400 Bad Request: Invalid OTP`Attempted to use a Production OTP on the /simulation/compliance endpoint.Generate a dedicated Simulation OTP from the Fatoora Portal under the 'Simulation' tab.
`BR-KSA-09: Invalid UUID`Random string used instead of RFC 4122 Version 4 UUID.Generate strict UUIDv4 tokens (e.g., using crypto.randomUUID() in Node.js or uuid4() in Python).
`Invalid QR Code Base64`QR code string has formatting breaks or missing TLV tags.Validate TLV binary byte structure using the Java SDK QR parser tool before sending.

Frequently Asked Questions (FAQ)

Do invoices issued in the ZATCA Simulation Sandbox create legal tax liabilities?

No. The Simulation Sandbox is an isolated staging environment. Invoices cleared or reported in simulation have zero legal standing, do not appear on your company's official tax balance sheet, and do not impact quarterly VAT returns.

Can I test with dummy company VAT numbers in the Simulation Sandbox?

On the Simulation Gateway (/e-invoicing/simulation), you must onboard using your real commercial Tax Registration Number (TRN) and a portal OTP. If you need to test with dummy data without an active Saudi VAT number, use the Developer Portal Sandbox (/e-invoicing/developer-portal).

How long does a Simulation CSID certificate remain valid?

Simulation CSIDs remain active as long as the test environment is maintained, but ZATCA periodically purges staging ledgers during major Schematron version upgrades. If a Simulation CSID stops working, generate a fresh OTP and re-onboard in 5 minutes.

Does the Simulation Sandbox support both Standard B2B and Simplified B2C testing?

Yes. The Simulation Sandbox provides full functionality for both real-time B2B clearances (/simulation/invoices/clearance/single) and asynchronous B2C reporting (/simulation/invoices/reporting/single).

Can third-party ERP vendors provide pre-tested sandbox environments?

Yes. Many ZATCA-accredited solution providers maintain permanent sandbox simulation instances where businesses can test invoicing workflows without configuring OpenSSL keypairs or Fatoora portal credentials manually.