ZATCA environments (developer portal, simulation, production)
ZATCA has three environments: developer portal for testing, simulation with real taxpayer data and no legal effect, and production. Each issues its own CSIDs.
ZATCA runs three API gateways, and each issues its own certificates, so a CSID from one does not work on another:
Developer portal (developer-portal): for testing; it accepts a published test OTP, so you can run the whole onboarding without a taxpayer account. Simulation (simulation): the taxpayer's real details and an OTP from their account, with no legal effect; its certificate template is PREZATCA-Code-Signing. Production (core): legal invoices, template ZATCA-Code-Signing.
What goes wrong: most often, a certificate from one environment used against another gateway, or a CSR with the wrong template for the environment. Test fixtures with old dates raise BR-KSA-98, since the rule compares the issue date with the current time.
On Matheel you pick the environment with the environment field: sandbox (the developer portal), simulation or production, and the CSID must come from the same one. On sandbox without seller and csid, Matheel files the invoice as a shared test taxpayer and returns ZATCA's real answer. The developer portal and simulation are free on Matheel; production needs a plan.
Example
"sandbox" => "https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal"
"simulation" => "https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation"
"production" => "https://gw-fatoora.zatca.gov.sa/e-invoicing/core"
FAQ
Can I use a simulation certificate in production?
No. Each environment issues its own certificates; onboard the device again in production with a new OTP.
What is the difference between the developer portal and simulation?
The developer portal is for testing with a published OTP value; simulation uses your real business details and an OTP from your account. Neither has legal effect.
Related ZATCA rules
Related terms
- Fatoora portal
- OTP (Fatoora portal one-time password)
- CSR (Certificate Signing Request)
- CSID (Cryptographic Stamp Identifier)
- Production CSID
Let Matheel handle this for you
Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.
Try Matheel, no signup Matheel API docs