Introduction to ZATCA Sandbox Testing

For Saudi businesses transitioning to Phase 2 (Integration Phase) of e-invoicing, the stakes are high. Moving from manual or standalone systems to a fully integrated API-based workflow requires precision. This is where the ZATCA Sandbox (Developer Portal) becomes your most critical tool. Testing in the sandbox ensures that your ERP or accounting software communicates perfectly with the FATOORA portal without risking fines or compliance breaches in the production environment.

In this guide, we will walk you through the technical and procedural steps of sandbox testing, ensuring your business is ready for the ZATCA e-invoicing mandate.

What is the ZATCA Sandbox?

The Sandbox is a simulated environment provided by the Zakat, Tax and Customs Authority (ZATCA). It allows developers and business owners to:

Validate XML Invoices: Ensure your UBL 2.1 XML structure meets Saudi standards.
Test API Endpoints: Verify connectivity for Clearance (B2B) and Reporting (B2C) APIs.
Verify Security: Test the generation of Cryptographic Stamp Identifiers (CSIDs).
Error Handling: Identify and fix validation errors before they affect your live tax records.

Prerequisites for Sandbox Testing

Before you begin, ensure you have the following technical components ready:

CSR (Certificate Signing Request): A file used to request a digital certificate from ZATCA.
Private Key: Securely generated key for signing your invoices.
VAT Registration: A valid VAT number for the testing entity.
UBL 2.1 XML Knowledge: Understanding the structure of Saudi e-invoices.

💡 Tip: Use Qeemah’s ZATCA Readiness Checker to see if your current data is prepared for integration.

The Step-by-Step Testing Workflow

1. Onboarding and CSID Generation

The first step in the sandbox is obtaining a Binary Security Token. This is done through the Compliance API. You must submit your CSR to the sandbox endpoint to receive a Compliance CSID (CCSID). This token allows you to perform compliance checks on your invoice samples.

2. Compliance API Testing

You must send a variety of invoice types to the Compliance API to prove your system can handle different scenarios. This includes:

Standard Invoices (B2B)
Simplified Invoices (B2C)
Credit and Debit Notes
Invoices with different VAT rates (5%, 15%, Zero-rated, Exempt)

3. Understanding the Technical Keys

During testing, you must correctly implement these mandatory fields:

Field	Description	Importance
UUID	Universally Unique Identifier	Prevents duplicate invoice submission.
ICV	Invoice Counter Value	A sequence number that must be incremental.
PIH	Previous Invoice Hash	Links the current invoice to the previous one for tamper-proofing.
QR Code	TLV Encoded Data	Must contain the digital signature and ECDSA public key.

Common Sandbox Error Codes and Fixes

Testing often reveals errors. Here are the most common ones encountered in the ZATCA Sandbox:

401 Unauthorized: Usually means your CSID has expired or the signature is invalid.
400 Bad Request: Often caused by a schema validation failure (XML structure issues).
BR-KSA-31: Indicates the Previous Invoice Hash (PIH) does not match the record.
KSA-2: Indicates an issue with the VAT category code or rate logic.

Transitioning from Sandbox to Production

Once you have successfully passed the compliance tests for all invoice types, the sandbox will issue a Production CSID (PCSID). This is your ‘golden ticket’ to start issuing live, legally binding invoices.

⚠️ Warning: Never use sandbox CSIDs for live transactions. This will result in invalid invoices and potential ZATCA penalties.

Why Sandbox Testing is Non-Negotiable

Data Integrity: Ensures your accounting and finance records match what ZATCA receives.
Avoid Fines: Prevents the submission of incorrect tax data which can lead to hefty penalties.
Workflow Continuity: Ensures your sales team isn’t blocked by technical errors during peak hours.

How Qeemah Simplifies ZATCA Integration

Navigating the complexities of CSR generation, TLV encoding, and API handshakes can be overwhelming for SMEs. Qeemah is built to handle the heavy lifting for you.

Automated Onboarding: We handle the CSR and CSID process directly with ZATCA.
Real-time Validation: Our system pre-validates your invoices before they even reach the FATOORA portal.
Seamless Phase 2 Compliance: From UUID generation to PIH linking, Qeemah automates the entire sequence.
Integrated Modules: Whether it’s Sales & CRM or Inventory Management, every transaction is ZATCA-ready.

Don’t leave your compliance to chance. Join thousands of Saudi businesses who trust Qeemah for their e-invoicing needs.

Explore Qeemah Features | View Pricing Plans | Contact Our Experts

ZATCA Sandbox Testing: How to Test Your Integration Before Going Live