# Connect a sales journal to ZATCA

Prepare the company, choose the API mode, then onboard each sales journal with a one-time password from the Fatoora portal, and renew or redo the connection when its certificate expires.

Until a sales journal is onboarded, it has no ZATCA certificate and none of its invoices can be confirmed. Follow these steps once for each sales journal: each has its own certificate and invoice chain.

## Before you start {#before-you-start}

- The company's country is Saudi Arabia and its package is the Saudi one (see [Accounting settings](/docs/accounting-start-here/accounting-settings)).
- You need the **Administrator** role (**Role** on the user's **Access Rights** tab) and the **Administrator** access right on **Accounting**.
- Onboarding asks for a one-time password (OTP) generated on ZATCA's Fatoora portal.

## Complete the company {#company}

Open **Settings/Users & Companies/Companies** and the company. With **Saudi Arabia** as country, the form shows the Saudi address: street, district (second line), city, state, **Building Number** and **Plot Identification**, then **Identification Scheme** and **Identification Number** (a commercial registration number, for example), printed under the company address on invoices.

- **Tax ID** holds the VAT number: 15 digits, the first and the last being 3. Invoices are refused otherwise.
- When the name, VAT number, street, city, state or country is missing, onboarding fails and the journal's **ZATCA** tab lists them after **Please set the following on** and the company name.
- Each value sent to ZATCA, such as the company name or the journal code, name and company name joined together, must not exceed 64 bytes; an Arabic letter takes two, so a long Arabic name can block onboarding.

## Choose the API mode {#api-mode}

Open **Accounting/Configuration/Settings**. Right after **Fiscal Localization**, the group **Saudi Arabia Electronic Invoicing** appears when the current company is in Saudi Arabia. Its setting **ZATCA API Modes** recalls the three steps, and **API Mode** sets where invoices go:

- **Sandbox** (the default): ZATCA's shared test environment. **Onboard** fills in the OTP for you.
- **Simulation (Pre-Production)**: a test environment of the company's own.
- **Production**: the live environment; a warning recalls that every invoice submitted there counts in the VAT liability.

Click **Save**. Changing the mode later disconnects every journal of the company: each must be onboarded again, and each sales journal records **ZATCA API Mode changed to** and the new mode in its chatter. After the first invoice accepted in **Production**, the change is refused. A test copy of the database is put back to **Sandbox**.

## Onboard the journal {#onboard}

1. Open **Accounting/Configuration/Accounting/Journals** and the sales journal. The **ZATCA** tab follows **Journal Entries** and **Advanced Settings**.
2. The tab reads **Onboard this Journal**. Click **Onboard**.
3. In **Enter the OTP**, type the code from the Fatoora portal in **OTP** and click **Confirm**.

In one go, Jaah creates the company's private key if needed, requests a certificate with the OTP, passes ZATCA's six compliance checks (standard and simplified invoice, credit note and debit note), receives the production certificate and starts the journal's invoice chain. The tab then reads **Success: Journal is onboarded and valid until** with the end date, and the chatter records **Journal onboarded with ZATCA successfully**. You can now [send invoices](send-an-invoice-to-zatca).

When ZATCA refuses, the tab reads **Error: Journal is not onboarded** with the reason. Correct it and click **Onboard** again.

## Renew or start again {#renew}

- **Renew** takes a new OTP once the certificate has expired, and is refused before. Outside **Sandbox**, an expired journal stops its invoices with **The Journal is not valid anymore. Please Renew it.**
- **Re-Onboard** asks **Do you really want to re-onboard this Journal with ZATCA?**; **Yes** runs the whole onboarding again with a new OTP, restarts the chain and records **Journal re-onboarded with ZATCA successfully**.
- **Onboard** and **Re-Onboard** are refused while an invoice of the journal is still waiting for ZATCA's answer: send it first.

## FAQ {#faq}

### The journal has no ZATCA tab. {#no-tab}

The tab exists only on a journal of type **Sales** of a company in Saudi Arabia.

### The ZATCA tab is empty. {#empty-tab}

Its messages and buttons show only to the **Administrator** role.

### Can I go back to Sandbox after Production? {#back-to-sandbox}

Not once an invoice has been accepted in **Production**: the mode is then fixed for the company.

---

- Source: https://jaah.app/docs/e-invoicing-zatca/connect-a-sales-journal-to-zatca
- Updated: 2026-10-23
- Version: E-invoicing (ZATCA) 19.0.0.3