Test in sandbox

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

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.

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 has the steps.

Send a test document

1. In the Invoice Portal, select the country and Sandbox, then onboard the company with its source.
2. Send a document with "environment": "sandbox". Send your first invoice walks you through one request. The API playground builds the request for any country and always sends it to sandbox.
3. Run your mapping against its test cases in Test your mapping or a testbed.
4. Follow each document to its final status with its documentId, as described in Submit and retrieve. 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.

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.

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.

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 explains the checks.

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 and the examples for the UAE, Belgium and Germany. Replace the sample source with your own.
• Use a new documentNumber for every document you send. A number already used returns 422 with GETS-HEAD-010.
• 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.

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 in production: the message reads “Complete all required default mapping testbed scenarios before submitting production invoices.” If your workspace uses the Default GETS Mapping, its required test cases for that country must pass before you can send production documents. Run them as described in Test your mapping, then send the document again.