Try in playground

Go live in Saudi Arabia

Work through this checklist before you send Saudi invoices to ZATCA in production. You need Saudi documents that already pass in sandbox and access to the company's account on ZATCA's FATOORA portal.

Open in Claude Open in ChatGPT

Onboard the company in production

A company onboarded in sandbox is not registered in production, and its sandbox EGS has no production CSID.

  1. In the Invoice Portal, select Saudi Arabia and Production.
  2. Follow Onboard a Saudi Arabian company with the company’s real details. Add an EGS unit for each system or branch that issues invoices.
  3. In Business Details, select every kind of invoice the company issues: Standard B2B, Simplified B2C or both, plus any additional requirements such as Export.
  4. At Enter OTP, enter a code the company generates on the FATOORA portal.

You should see the screen that confirms the registration. Complyance now holds the company’s production CSID, which signs its invoices.

Move your integration to production

  • Create a key under Production API keys with Write access. See Create an API key.
  • With Production selected, link the source you added during onboarding to your mapping and the company’s branch. See Manage sources and their links.
  • Send "environment": "production" and the production source’s name:version in every Unify request. If you use an SDK, change its environment setting; each SDK guide shows where.
  • Check the production credit balance in Credits, and create a separate production webhook if you receive webhooks. See Credits and Set up a webhook.

Check the required test cases

If your workspace uses the Default GETS Mapping, the test cases for Saudi Arabia must show Passed in Test your mapping. Until they do, Unify refuses invoices with 412 and failed_precondition, in sandbox and in production.

Send the first production invoice

Send one real invoice and follow it with its documentId until isTerminal is true. See Submit and retrieve.

  • final_valid with government.status CLEARED means ZATCA cleared the standard invoice.
  • final_valid with government.status REPORTED means ZATCA accepted the report of a simplified invoice.
  • final_invalid means ZATCA rejected it, and rejected means it failed validation before it reached ZATCA. Read errors and government for the reason.

Saudi checks

  • Production documents go to ZATCA’s production system. They are real tax invoices: correct one with a credit or debit note rather than sending it again.
  • Use the company’s own VAT number in the seller’s details. It must match the company you onboarded.
  • Send each simplified invoice as soon as you issue it: ZATCA rule BR-KSA-98 asks for the report within 24 hours.
  • Check each document type against the Saudi Arabia field reference and the validation rules.

If something goes wrong

The OTP is rejected: generate a new code on the FATOORA portal for this company and enter it before it expires.

403 with permission_denied: the key is a sandbox key. Use a production key with "environment": "production".

404: the source is not in production. Check its name and version in Source management with Production selected.

412 with failed_precondition: the required test cases for Saudi Arabia have not all passed. Run them, then send the document again. Unify errors lists each reason.

ZATCA rejects the document: read the rule identifier in the status, such as a BR-KSA-* rule, and look it up in Saudi Arabia validation rules.