# ZATCA Phase 2 integration (Saudi Arabia)

Integrate with ZATCA through the Complyance API: set up a Saudi Arabian company, prepare its GETS invoice data and check the result of submission to ZATCA. Start with a workspace that includes Saudi Arabia.

Saudi Arabia e-invoicing uses ZATCA. In Complyance, first [onboard the company](https://docs.complyance.io/countries/sa/onboarding/), then send its invoice data in GETS through [Unify](https://docs.complyance.io/api-reference/unify/). Test in the [ZATCA sandbox](https://docs.complyance.io/get-started/sandbox/#saudi-arabia-zatca-sandbox) before sending production documents, then follow the [go-live checklist](https://docs.complyance.io/countries/sa/go-live/).

- [Onboard a company](https://docs.complyance.io/countries/sa/onboarding/): Register the company and its e-invoicing identity.
- [Check invoice fields](https://docs.complyance.io/countries/sa/fields/): Find the GETS fields accepted for Saudi Arabia.
- [Send an invoice](https://docs.complyance.io/countries/sa/examples/): Standard, simplified and export invoices, with ZATCA's result.
- [Go live](https://docs.complyance.io/countries/sa/go-live/): Check everything before you send production invoices.

## ZATCA Phase 2

ZATCA, Saudi Arabia’s Zakat, Tax and Customs Authority, introduced e-invoicing in two phases. Phase 1, the generation phase, has applied since 4 December 2021: invoices are issued from a compliant electronic solution. Phase 2, the integration phase, started on 1 January 2023 and reaches taxpayers in waves: the solution connects to ZATCA’s systems and sends each invoice in ZATCA’s format. See [What is e-invoicing](https://zatca.gov.sa/en/E-Invoicing/Introduction/Pages/What-is-e-invoicing.aspx) on ZATCA’s site, and check there when your wave starts.

Complyance is the connection to ZATCA for Phase 2. Each company you onboard gets its own e-invoicing identity with ZATCA, and every invoice you send through Unify is submitted under it.

## Clearance and reporting

ZATCA treats the two kinds of tax invoice differently:

| Document | Usually issued to | What ZATCA does | `documentType.base` | `government.status` when accepted |
| - | - | - | - | - |
| Standard tax invoice, credit and debit note | A business (B2B) or government | **Clearance**: ZATCA checks each invoice and returns it stamped as cleared. | `tax_invoice`, `credit_note`, `debit_note` | `CLEARED` |
| Simplified tax invoice, credit and debit note | A consumer (B2C) | **Reporting**: you give the invoice to the customer, and it is reported to ZATCA afterwards. ZATCA rule BR-KSA-98 asks for the report within 24 hours of issue. | `simplified_invoice`, `simplified_credit_note`, `simplified_debit_note` | `REPORTED` |

You send both kinds the same way. Complyance clears or reports each one according to its `documentType`, and the result appears in the document’s status. [Saudi Arabia examples](https://docs.complyance.io/countries/sa/examples/) has a request for each, with ZATCA’s answer.

## What you send and what is added for you

A Phase 2 invoice carries fields that prove it was issued by a registered solution and has not been changed. You send the invoice content. Complyance adds the security fields when it builds the XML for ZATCA.

| Field | What it is | Who provides it |
| - | - | - |
| UUID (KSA-1) | A unique identifier for each invoice. | You, in `header.uuid`. Use a new UUID for every invoice. |
| Invoice counter value, ICV (KSA-16) | The invoice’s position in the sequence of invoices your system issues. Digits only. | You, in `extensions.sa_icv`. |
| Previous invoice hash, PIH (KSA-13) | The hash of the company’s previous invoice, which chains each invoice to the one before it. | Complyance. Leave `extensions.sa_pih` out. |
| Invoice hash and cryptographic stamp (KSA-15) | The invoice’s hash, signed with the company’s cryptographic stamp from onboarding. | Complyance. Leave `extensions.sa_digitalSignature` out. |
| QR code (KSA-14) | A code printed on the invoice, built from its data, hash and stamp. | Complyance, or ZATCA on a cleared invoice. Leave `extensions.sa_qrCode` out. |

The stamp comes from the CSID (cryptographic stamp identifier) that ZATCA issues when you [onboard the company](https://docs.complyance.io/countries/sa/onboarding/). Complyance keeps it for you; you never handle the certificate or its key.

## Arabic on the invoice

ZATCA requires every field shown on the human-readable invoice, the copy a person reads, to be in Arabic. The invoice can be bilingual, with English as well. See ZATCA’s FAQ [Should invoice be in English or Arabic?](https://zatca.gov.sa/en/E-Invoicing/Introduction/FAQ/Pages/FAQ_056.aspx).

GETS has no separate Arabic fields for Saudi Arabia, such as an Arabic seller or buyer name. Send names and descriptions as they appear on your invoice.

## What to check before sending

Use the [Saudi Arabia field reference](https://docs.complyance.io/countries/sa/fields/) for the document type you are sending. The required data can differ between a tax invoice and a credit or debit note. Submit the values from the source document; do not fill missing amounts or identifiers with guesses.

After a successful request, [follow the document](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#follow-the-document) until `isTerminal` is `true`. `final_valid` means ZATCA cleared the invoice or accepted its report. `final_invalid` means ZATCA rejected it; [Saudi Arabia validation rules](https://docs.complyance.io/countries/sa/validation-rules/) explains how to read the reason.

Source: https://docs.complyance.io/countries/sa/