Connect a sales journal to ZATCA

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

• The company's country is Saudi Arabia and its package is the Saudi one (see 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

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

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

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.

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 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

The journal has no ZATCA tab.

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

The ZATCA tab is empty.

Its messages and buttons show only to the Administrator role.

Can I go back to Sandbox after Production?

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