# Test in sandbox

Send test documents without touching your live invoices, and see what sandbox does with them in each country. You need a workspace and a sandbox API key.

Sandbox is the environment for testing, separate from production. Companies, sources, documents, credits and webhooks each belong to one environment, so nothing you set up or send in sandbox appears in production.

## Sandbox and production side by side

| | Sandbox | Production |
| - | - | - |
| API key | Created under **Mock API keys** | Created under **Production API keys** |
| `environment` in a Unify request | `sandbox` | `production` |
| Invoice Portal | **Sandbox** in the environment switcher | **Production** in the environment switcher |
| Companies and sources | Onboarded in sandbox | Onboarded again in production |
| Webhooks | A webhook created for **Sandbox** | A separate webhook created for **Production** |

Both environments use the same base URL, `https://prod.gets.complyance.io`. The API key and the `environment` field decide where a Unify request goes, and they must match. A sandbox key sent with `"environment": "production"` returns `403` with `permission_denied`. Other APIs choose the environment differently; see [Authentication and environments](https://docs.complyance.io/api-reference/authentication/).

## Get a sandbox API key

In **Developer portal**, open **API keys** and create a key under **Mock API keys**. The secret is shown only once, so copy it into your secret manager straight away. [Create an API key](https://docs.complyance.io/one-platform/developer-portal/api-keys/) has the steps.

## Send a test document

1. In the Invoice Portal, select the country and **Sandbox**, then [onboard the company](https://docs.complyance.io/get-started/company-onboarding/) with its source.
2. Send a document with `"environment": "sandbox"`. [Send your first invoice](https://docs.complyance.io/get-started/quickstart/) walks you through one request. The [API playground](https://docs.complyance.io/api/?operation=submitDocument&try) builds the request for any country and always sends it to sandbox.
3. Run your mapping against its test cases in [Test your mapping](https://docs.complyance.io/one-platform/developer-portal/integration-engine/test/) or a [testbed](https://docs.complyance.io/one-platform/developer-portal/testbeds/).
4. Follow each document to its final status with its `documentId`, as described in [Submit and retrieve](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#follow-the-document). To see it in the Invoice Portal, select **Sandbox** in the environment switcher.

## What happens to a sandbox document

Complyance checks a sandbox document against the same rules as production and produces the same e-invoice. What happens next depends on the country.

## Saudi Arabia: ZATCA sandbox

ZATCA, Saudi Arabia’s tax authority, runs a sandbox in its developer portal for testing e-invoicing solutions. See ZATCA’s [developer portal manual](https://sandbox.zatca.gov.sa/20220623_Developer%20Portal%20User%20Manual_vF.pdf).

When you send a Saudi document with `"environment": "sandbox"`, Complyance submits it to the ZATCA sandbox: standard (B2B) invoices for clearance and simplified (B2C) invoices for reporting. ZATCA’s own checks run, and its result appears in the document status. ZATCA does not record sandbox documents as tax invoices.

A pass in sandbox tells you that the invoice content is right. It does not confirm the company’s registration with ZATCA. That happens when you onboard the company in production; see [Go live in Saudi Arabia](https://docs.complyance.io/countries/sa/go-live/).

ZATCA also runs a separate simulation environment. For Saudi Arabia, the Invoice Portal’s environment switcher shows **Simulation** as well as **Sandbox** and **Production**. Unify requests accept only `sandbox` and `production`.

## Malaysia: MyInvois sandbox

LHDN, Malaysia’s Inland Revenue Board, runs a MyInvois sandbox, its pre-production environment, next to production MyInvois. The two are separate: documents in the sandbox never reach production. See LHDN’s [MyInvois SDK FAQ](https://sdk.myinvois.hasil.gov.my/faq).

When you send a Malaysian document with `"environment": "sandbox"`, Complyance submits it to the MyInvois sandbox. LHDN’s own validation runs, and its result appears in the document status. If LHDN rejects the document, the status gives the reason; [Malaysia validation rules](https://docs.complyance.io/countries/my/validation-rules/) explains the checks.

## Oman: sandbox only

Oman is available in sandbox only: you cannot send Omani invoices in production. When you send an Omani document with `"environment": "sandbox"`, Complyance validates it against the PINT OM rules, produces the e-invoice and delivers it over Peppol to the buyer’s access point. Its answer appears in the document status: `final_valid` means the buyer’s access point accepted the e-invoice. The sandbox does not report invoices to the Oman Tax Authority. See [Oman examples](https://docs.complyance.io/countries/om/examples/).

## United Arab Emirates, Belgium and Germany

These countries exchange e-invoices over Peppol, the network for exchanging structured business documents. In sandbox, Complyance validates the document against the country’s rules, produces the e-invoice and reports its status. Treat a sandbox document as a test: an invoice your buyer must receive and pay is sent from production.

The Peppol participant IDs in the country examples are checksum-valid samples. They are not registered recipients.

## Test data

- Start from the complete requests in [Send your first invoice](https://docs.complyance.io/get-started/quickstart/) and the examples for the [UAE](https://docs.complyance.io/countries/ae/examples/), [Saudi Arabia](https://docs.complyance.io/countries/sa/examples/), [Oman](https://docs.complyance.io/countries/om/examples/), [Malaysia](https://docs.complyance.io/countries/my/examples/), [Belgium](https://docs.complyance.io/countries/be/examples/) and [Germany](https://docs.complyance.io/countries/de/examples/). Replace the sample `source` with your own.
- Use a new `documentNumber` for every new document. A number already used returns `422` with `GETS-HEAD-010`. To resend a document that failed validation, keep its number; see [Retries and duplicates](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#retries-and-duplicates).
- Test every document type you will send, such as credit notes, with the values your source system really produces. The field reference for each country shows which fields each type needs.
- Use made-up names, addresses and amounts, such as the sample company Acme Trading LLC. In Saudi Arabia and Malaysia sandbox documents go to the tax authority’s sandbox, so never send real customers’ personal data.
- Onboarding asks for the company’s own identifiers in some countries, even in sandbox. The onboarding page for each country says which.

## Move to production

When your documents pass in sandbox, work through the go-live checklist for each country you send from. Oman is sandbox only, so it has no checklist.

- [United Arab Emirates](https://docs.complyance.io/countries/ae/go-live/): Production onboarding, ASP authorization and the first live invoice.
- [Saudi Arabia](https://docs.complyance.io/countries/sa/go-live/): Production onboarding with a ZATCA OTP and the first cleared invoice.
- [Malaysia](https://docs.complyance.io/countries/my/go-live/): Production onboarding and the first invoice validated by LHDN.
- [Belgium](https://docs.complyance.io/countries/be/go-live/): Peppol registration and the first delivered invoice.
- [Germany](https://docs.complyance.io/countries/de/go-live/): Peppol details, buyer references and the first delivered invoice.

## If something goes wrong

**`403` with `permission_denied`:** the key belongs to a different environment from `environment`. Use a sandbox key with `sandbox` and a production key with `production`.

**The document is not in the Invoice Portal:** check the environment switcher. Sandbox documents appear only when **Sandbox** is selected.

**`412` with `failed_precondition`:** the required test cases for that country have not all passed. Unify refuses invoices with this error in sandbox as well as in production; with the **Default GETS Mapping**, the message reads “Complete all required default mapping testbed scenarios before submitting production invoices.” Run the test cases as described in [Test your mapping](https://docs.complyance.io/one-platform/developer-portal/integration-engine/test/), then send the document again. [Unify errors](https://docs.complyance.io/api-reference/unify/errors/) lists each reason.

> **What you have now**
>
> A sandbox key, a sandbox company and documents that pass in sandbox. Next, open the go-live checklist for your country.

Last updated 16 October 2026

Source: https://docs.complyance.io/get-started/sandbox/