Sandbox Environment for Developers: Testing ZATCA E-Invoicing Integration

Before your business issues its first live invoice to the Fatoora platform, you need a safe place to test your integration with no legal or tax consequences. That place is the Sandbox environment provided by the Zakat, Tax and Customs Authority (ZATCA) as part of Phase Two of e-invoicing. The Sandbox is a technically identical copy of the production environment, yet completely isolated from it. Every invoice you send to it goes through the same compliance checks, is signed with the same cryptographic stamp mechanism, and comes back with the same responses. The only difference is that it is not recorded by the Authority as a legal invoice, and it carries no tax obligations whatsoever.

This guide is aimed at developers and integration teams connecting their systems to the Fatoora platform. It explains exactly what the Sandbox is, why the Authority requires it before moving to production, how to obtain its Compliance CSID, how to send test invoices, what checks the Authority runs on each invoice, and how to read its responses and handle its errors. The goal is for you to reach the production environment confident that your integration works without surprises.

What is the Sandbox environment?

The Sandbox is a test environment the Authority provides through the Fatoora platform, allowing your accounting system to behave exactly as it would in production, but without any legal outcome. Invoices are sent to it through the same APIs, and it returns the same responses you will later receive from production. This deliberate technical parity is what makes it a reliable tool: what works in the Sandbox usually works in production, and what fails in it exposes a defect before it costs you a rejected invoice in front of a real customer.

The platform runs on three separate environments, each with its own Endpoint and its own type of certificate:

• Developer Portal: For quick initial experiments and understanding the API structure. It does not require a full certificate.
• Simulation: The approved environment for testing full integration before production, and the focus of this guide.
• Production: The live environment where invoices are legally recorded with the Authority.

The Sandbox sits in the middle of this path. It is the step where you prove that your system is actually ready, not merely that it understands the APIs in theory. The difference between it and the Developer Portal matters: the Developer Portal is an initial playground for understanding the shape of requests and responses, whereas the Sandbox applies the full checks with a real certificate, accurately mirroring production behavior. Anyone who settles for the Developer Portal and assumes their system is ready is surprised by errors they only see in the Sandbox. That is why the Sandbox is the decisive stage before production, not a formality you can skip. For the API details themselves (submission requests, data format, response codes), see the guide API integration with the Fatoora platform.

Why does the Authority require going through the Sandbox?

The Authority does not allow any system to issue invoices in production until it proves its ability to produce valid invoices in the Sandbox. The reason is direct: an electronic invoice is a digitally signed legal document, and any error in its structure, stamp, or sequence corrupts a real tax record. The Sandbox moves the possibility of error from production to a safe space that leaves no trace.

This environment serves three clear objectives:

1. Structure validation: It confirms that your invoices follow the UBL 2.1 specification required by the Authority, and that every mandatory field is present in its correct format.
2. Signature validation: It tests that your system signs the invoice with the correct compliance certificate, and computes the Hash and invoice chain accurately.
3. Tax logic validation: It confirms that your VAT calculations and invoice types (simplified and tax invoices) comply with the Authority’s rules.

Passing these checks in the Sandbox is a technical prerequisite for obtaining the production certificate. In other words: the Sandbox is the gateway, and production is what comes after it.

The Compliance CSID and its place in the Sandbox

To work in the Sandbox, your system needs a special certificate called the Compliance CSID. This certificate is the identifier of the cryptographic stamp for the test environment; it is obtained by submitting a Certificate Signing Request (CSR) and a one-time password (OTP) from the platform portal. With it, your system signs its test invoices, and with it the Authority recognizes that this issuance is under verification and not yet in production.

It is important not to confuse two types of identifiers: the Compliance CSID for testing in the Sandbox, and the Production CSID for live operation. Neither is used in place of the other. The correct order: you obtain the Compliance CSID first, pass the Sandbox checks with it, then request the Production CSID on that basis.

We detail the mechanism of each certificate in two separate guides: see CSID: the cryptographic stamp identifier to understand the identifier in general and its lifecycle, and see Compliance CSID: the technical compliance certificate for the details of obtaining the test certificate via CSR and OTP step by step.

Prerequisites before starting in the Sandbox

Before you send your first test invoice, make sure these prerequisites are in place. Having them ready in advance saves you long correction cycles after starting:

• A valid tax registration number: The business must be registered for VAT with the Authority, as the tax number is a mandatory element in every invoice.
• A one-time password (OTP): You obtain it from the Fatoora platform portal and use it once when requesting the Compliance CSID. Its validity is short, so obtain it at the moment you need it.
• A Certificate Signing Request (CSR): Your system generates it to send to the Authority in exchange for the Compliance CSID. It contains the business data and the public key.
• A ready development environment: A tool to send HTTP requests, a library to generate the XML file per UBL 2.1, and a cryptography library to compute the hash and signature.

Generating the Certificate Signing Request and the OTP is what opens the door of the Sandbox to you. We do not repeat its details here, but refer you to the guide Compliance CSID which explains every field in the signing request and how to obtain the OTP step by step. What matters in this guide is what happens after you have the certificate: how to test with it, and how to read the results.

The mandatory elements in every Sandbox invoice

The Sandbox rejects any invoice missing a mandatory element. These elements are not specific to testing; they are the same ones required in production, which is why testing reveals their absence early. The key elements your system must generate accurately:

• The unique invoice identifier (UUID): A globally unique identifier for each invoice. Duplicating or omitting it corrupts the check immediately.
• The Invoice Hash: A digital fingerprint of the invoice computed with the SHA-256 algorithm. Any change to the invoice content changes it entirely.
• The Previous Invoice Hash: What links invoices into a connected chain, and prevents deletion or insertion from going undetected.
• The QR Code: Mandatory especially in the simplified invoice (B2C); it contains the invoice data and its signature encoded in TLV format.
• The Cryptographic Stamp: The digital signature that the Compliance CSID produces over the invoice content.

Order matters: you build the invoice first, then compute its hash, then sign it, then generate the QR Code from the signed data. Any flaw in this sequence produces an invoice that the signature check rejects.

How do you send a test invoice to the Sandbox?

After obtaining the Compliance CSID, your system becomes ready to send its first test invoice. The process goes through four sequential steps, all carried out through the platform’s APIs:

1. Building the invoice: Your system generates an XML file per the UBL 2.1 specification, containing the seller and buyer data, the line items, the VAT, and the unique invoice identifier (UUID).
2. Signing and stamping: Your system computes the invoice Hash, links it to the previous invoice’s hash to build the chain, then signs it with the Compliance CSID and adds the QR Code.
3. Sending to the appropriate API: The tax invoice (B2B) is sent to the Clearance API, and the simplified invoice (B2C) to the Reporting API.
4. Reading the response: You receive the Authority’s response indicating whether the invoice passed the checks or not, with the details of any error.

A simplified example of the structure of a tax-invoice clearance request to the Sandbox via the API:

POST /einvoicing/simulation/invoices/clearance/single
Host: gw-fatoora.zatca.gov.sa
Accept-Version: V2
Authorization: Basic {Compliance-CSID-credentials}
Content-Type: application/json

{
  "invoiceHash": "{base64-encoded-SHA256-hash}",
  "uuid": "{invoice-UUID}",
  "invoice": "{base64-encoded-signed-XML}"
}

Note that the path contains the word simulation explicitly, and this is what distinguishes a Sandbox call from a production call. Changing this part alone, along with switching the certificate, is what later moves you to the production environment. The full details of each API’s transactions are found in the guide API integration with the Fatoora platform.

What checks does the Authority run on each invoice?

When the test invoice is received, the Fatoora platform runs a series of checks before it responds. Understanding these checks helps you build valid invoices on the first attempt instead of correcting by trial and error. The checks fall into main categories:

• Schema validation: It verifies that the XML file matches the UBL 2.1 specification, and that all mandatory elements are present in their correct order and types.
• Business rules validation: It verifies the correctness of the calculations. The sum of the line items equals the total, the 15% VAT rate is computed accurately, and the exemption or zero-rated category is documented when used.
• Signature validation: It verifies that the invoice is signed with a valid compliance certificate, and that the digital signature is sound and the content has not been tampered with afterward.
• Invoice chain validation (Hash chain): It verifies that the previous invoice’s hash is stated correctly, to ensure an uninterrupted invoice sequence with no gaps or duplication.

The result of each check comes in the Authority’s response as a clear status. A successful invoice returns an acceptance status, and an invoice with a problem returns a list of warnings or errors that pinpoint the location of the flaw accurately.

How do you read the Sandbox responses and handle their errors?

The platform’s response comes as a structured object containing the invoice status and a list of notes. The notes fall into two types that must be clearly distinguished:

• Errors: They prevent the invoice from being cleared. As long as there is a single error, the invoice is rejected and not cleared. They must all be fixed.
• Warnings: They do not prevent clearance, but they point to matters that should be reviewed. The invoice is accepted with them present, but ignoring them may cause problems later in production.

A simplified example of the shape of a response containing the invoice status and its notes:

{
  "clearanceStatus": "NOT_CLEARED",
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-15",
        "message": "Invoice total does not match the sum of line items"
      }
    ],
    "warningMessages": []
  }
}

The practical rule when handling errors: read the error Code first, as it pinpoints the violated rule precisely, then read the Message to understand the cause. Do not fix symptoms; fix the source in the way the invoice is built inside your system. The difference between the two fixes is large: whoever treats the symptom corrects a single invoice, and whoever treats the source corrects all future invoices at once. Resend to the Sandbox until the invoice returns a clean acceptance status with no error. And the advantage of the Sandbox here is that it lets you repeat this without limit and at no cost, because it produces no legal record. Invest in this safe space before you move to production, where every error becomes a real record. Only then is your integration ready to move.

Common errors in the Sandbox and how to overcome them

Specific errors recur for most integration teams in their early days with the Sandbox. Knowing them in advance saves you hours of tracing. Here are the most prominent, their cause, and how to fix them:

• Total does not match the sum of line items: The most common error. It is usually caused by a rounding difference in the VAT calculation. The fix: unify the rounding precision across all fields, and compute the tax at the line-item level then sum.
• Invalid signature: It results from signing the invoice after modifying its content, or using an expired certificate. The fix: sign the invoice as the last step after all fields are complete, and make sure the Compliance CSID is valid.
• Broken invoice chain: It happens when sending an invoice with a wrong or missing previous hash. The fix: store the hash of every cleared invoice, and carry it into the next invoice in the correct order.
• Duplicate invoice identifier (UUID): It happens when resending the same invoice without generating a new identifier. The fix: generate a unique identifier for each new invoice, and do not reuse a previous invoice’s identifier.
• Missing or incorrect QR Code: Common in the simplified invoice. It is caused by incorrect TLV encoding. The fix: generate the code from the signed data, not from the raw data, and adhere to the field order the Authority requires.

The golden rule: every error is accompanied by a Code that points you directly to the violated rule. Do not guess the cause; look up the code in the Authority’s specifications, and it will lead you to the location of the flaw precisely. And because the Sandbox leaves no trace, you can safely repeat sending until all errors disappear.

A full test-invoice lifecycle

To cement the picture, let us trace the journey of a single tax invoice from the moment it is created until it is cleared in the Sandbox. This journey is the same one that will recur in production; the difference is only in the certificate and the endpoint:

1. Creating the data: Your system gathers the seller, buyer, line-item, quantity, and price data, and computes 15% VAT on each line item.
2. Generating the XML file: The system formats this data into an XML file per the UBL 2.1 specification, placing the unique invoice identifier (UUID) in its position.
3. Computing the hash: The system computes the invoice fingerprint with the SHA-256 algorithm, and links it to the hash of the previous cleared invoice.
4. Cryptographic signing: The system signs the invoice with the Compliance CSID, turning it into a signed document that cannot be modified without detection.
5. Generating the QR Code: The system builds the QR code from the signed data with TLV encoding.
6. Sending for clearance: The system sends the tax invoice to the Clearance API on the Sandbox path, and waits for the response.
7. Reading the result: If it returns with a clearance status, the journey is complete successfully. And if it returns with an error, the system fixes the cause and resends.

The simplified invoice (B2C) goes through the same steps, but it is sent to the Reporting API instead of Clearance, because the Authority requires it to be reported within 24 hours rather than cleared in real time. This difference between clearance and reporting is among the most important things to test in the Sandbox.

The difference between the Sandbox and the production environment

Many integration teams confuse the two environments, so the system builds an integration that works in the Sandbox but fails at the first production call. The difference is not in the way the invoice is built, but in the certificate used, the endpoint targeted, and the legal effect. The following table summarizes the differences:

The essential point: the checks are identical in both environments. What passes the Sandbox cleanly passes production. This is why the Sandbox is an honest test of your readiness, not a mere formal exercise. The details of working in the live environment and what is required to obtain the Production CSID are covered in the dedicated Production Environment guide.

Best practices for testing in the Sandbox

To reach production with the fewest number of attempts, follow these practices while working in the Sandbox:

• Test all invoice types: Tax invoice (B2B), simplified invoice (B2C), credit note, and debit note. Each type has slightly different validation rules.
• Test the edge cases: A zero-rated invoice, an exempt invoice, and an invoice with currencies or discounts. Do not settle for the simple ideal case.
• Verify the invoice chain: Send several consecutive invoices and make sure the previous invoice’s hash is carried correctly each time.
• Log every response: Keep a log of every request and response; it is your reference when tracing any recurring error.
• Handle every warning, not just errors: A warning you ignore in the Sandbox may become an operational problem in production.

After you pass all these cases with a clean acceptance status, you have proven that your integration is robust. Then you move to obtaining the Production CSID and switching the endpoint, entering the production environment with peace of mind.

Checklist for moving from Sandbox to production

When your test invoices pass the checks cleanly, you are on the threshold of production. Before you step forward, review this checklist to make sure you have not left a gap that shows up with the first real customer:

• A clean pass for all types: Make sure the tax invoice, the simplified invoice, and the credit and debit notes all returned an acceptance status with no errors.
• Handle all warnings: Verify that the warnings list is empty, not just the errors. A warning ignored today is a problem tomorrow.
• Chain integrity across a batch of invoices: You sent a series of consecutive invoices and verified that the previous hash was carried correctly at every step.
• Switch the certificate: Prepare to obtain the Production CSID to replace the Compliance CSID. Do not move the Sandbox certificate to production.
• Switch the endpoint: Change the Sandbox path to the production path in your system settings, and make sure no call remains directed to the Sandbox.
• Document the settings: Record the environment of each setting (certificate, endpoint, keys) so that the test and production environments do not get mixed up later.

After passing this checklist, your move to production is a matter of switching a certificate and an endpoint, no more, because the invoice-building logic has not changed. As for the details of obtaining the Production CSID and what distinguishes the live environment, we dedicate the separate Production Environment guide to them.

How does Qoyod simplify integration with the Fatoora platform?

Everything above — cryptographic signing, certificate management, building XML per UBL 2.1, and sending to the correct APIs — requires significant technical effort if built manually. The Qoyod e-invoicing software handles this layer entirely. It manages certificates automatically, signs every invoice, computes the hash and the chain, and sends the tax invoice for clearance and the simplified invoice for reporting, all in compliance with Phase Two of e-invoicing.

With this, the business obtains a passing result on the Sandbox checks without its team writing a single line of code, and moves to production with confidence. And if you face any obstacle, the Qoyod support team is available 24 hours a day, seven days a week to help you at every step.

Frequently asked questions about the Sandbox

Do the invoices I send in the Sandbox have any tax or legal effect?
No. Invoices in the Sandbox are not recorded with the Authority as legal invoices, do not enter into the VAT return, and carry no obligations. They are for testing only.

Can I skip the Sandbox and go straight to production?
No. The Authority requires passing the Sandbox checks with the Compliance CSID before it grants your system the Production CSID. Going through the Sandbox is a technical requirement, not an option.

What is the difference between the Compliance CSID and the Production CSID?
The Compliance CSID works in the Sandbox for testing, and the Production CSID works in the production environment for live operation. The Production CSID is obtained after passing the Sandbox.

Are the checks in the Sandbox identical to the production checks?
Yes. The structure, business rules, signature, and invoice chain checks are identical in both environments. This is why the Sandbox is an honest test of your actual readiness.

How many test invoices should I send before moving on?
There is no fixed number. The criterion is coverage, not count: test all invoice types and their edge cases until they all return a clean acceptance status with no errors.

Does Qoyod handle the Sandbox on my behalf?
Yes. Qoyod manages the signing, certificates, and submission automatically, so you pass the checks without writing code, while the support team helps you 24 hours a day, seven days a week.