Before creating invoices, users need to configure the business settings for each company on the instance. The ZATCA business settings include the following tabs:

Seller Details:

Select the Company for Integration with ZATCA:
- Choose the company that will be integrated with ZATCA for invoicing purposes.
Address (with Required Fields):
- Select the company’s address and ensure all necessary address details are filled in.
Company Unit (Fetched from Address Title):
- The company unit information will be automatically fetched from the address title provided.
Company Unit Serial (Format: 1-Solution Provider Name|2-Model or Version|3-Serial):
- Specify the company unit serial using the format: 1-Solution Provider Name|2-Model or Version|3-Serial.
- Example: 1-ERPNext|2-15|3-1.
- The unit serial is like the identifier of the unit you are onboarding to ZATCA platform
Company Category (Business Category):
- Define the business category for the company.
Country (Auto-Fetch from the Company):
- The country will be automatically fetched from the company details.
Country Code (Auto-Fetch from the Country):
- The country code will also be automatically fetched.
- Make sure the code is "SA"
Enabled ZATCA Integration (Enable/Disable):
- Set this field to true to enable the ZATCA integration.
Sync with ZATCA (Synchronization Mode):
- Choose between two synchronization modes:
- Live: Send transactions immediately to ZATCA, primarily for B2B transactions.
- Batches: Send batches of transactions every 2 hours, mainly for B2C transactions.

Seller ID

Seller Name (Name in the Registration License):
- Enter the seller’s name as it appears in the registration license.
VAT Registration Number (Registration Number in the VAT License):
- Provide the VAT registration number associated with the company.
Additional IDs (At Least One Required):
- You must provide at least one additional ID, such as:
- CRN (Commercial Registration Number)

VAT Account Configuration

This tab is to automatically Creates tax account under Duties and Taxes.
Creates Tax Category, Sales Taxes and Charges Template and Item Tax Template.

The user enters

The name of the account
The account number
The tax rate
The tax category

This feature can only be used on the creating of ZATCA business settings after that it will be read-only to prevent manipulating.

CLI

CLI Setup:

The ZATCA CLI is an open-source tool used to generate CSRs, validate, and sign XML sales invoices sent to ZATCA. It offers two setup options:

Automatic:
- One-click setup downloads the CLI and Java 11 runtime from GitHub by default (configurable). It will display a button to download and set up ZATCA CLI.
- Override CLI Download URL: If left empty, the CLI will be downloaded from here.
- Override JRE Download URL: If left empty, JRE 11 will be downloaded from here.
Manual:
- Manually deploy the CLI on the server as well as a Java 11 runtime and configure the path to the deployed CLI.

I have fixed this manually. ✅

Setting Up ZATCA CLI with OpenJDK 11

📥 Step 1: Download and Extract ZATCA CLI

Download in the Home Folder

Run the following command to download the ZATCA CLI:

wget https://github.com/lavaloon-eg/zatca-cli/releases/download/2.5.0/zatca-cli-2.5.0.zip

Extract the ZIP File

unzip zatca-cli-2.5.0.zip -d zatca-cli-2.5.0
rm -f zatca-cli-2.5.0.zip
cd /home/frappe/zatca-cli-2.5.0

📥 Step 2: Download and Extract OpenJDK 11

Download OpenJDK 11

wget https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.23+9/OpenJDK11U-jre_x64_linux_hotspot_11.0.23_9.tar.gz

Extract OpenJDK 11

sudo tar -xvzf OpenJDK11U-jre_x64_linux_hotspot_11.0.23_9.tar.gz -C /home/frappe/zatca-cli-2.5.0

⚙️ Step 3: Set Up JAVA_HOME and PATH

Configure Environment Variables

Run the following commands to set up Java:

export JAVA_HOME=/home/frappe/zatca-cli-2.5.0/jdk-11.0.23+9-jre
export PATH=$JAVA_HOME/bin:$PATH

Verify Java Environment Variables

echo $JAVA_HOME
ls -l $JAVA_HOME/bin/java

🚀 Step 4: Test Java Installation

Run the following command to check if Java is installed correctly:

java -version

Expected Output:

openjdk version "11.0.23" 2024-XX-XX
OpenJDK Runtime Environment (Adoptium 11.0.23+9) (build 11.0.23+9)
OpenJDK 64-Bit Server VM (Adoptium 11.0.23+9) (build 11.0.23+9, mixed mode)

🔧 Step 5: Make JAVA_HOME Permanent

If Java is working correctly, save this configuration so it persists after reboot:

echo 'export JAVA_HOME=/home/frappe/zatca-cli-2.5.0/jdk-11.0.23+9-jre' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

For Ubuntu Servers (Using /etc/environment Method)

echo 'JAVA_HOME="/home/frappe/zatca-cli-2.5.0/jdk-11.0.23+9-jre"' | sudo tee -a /etc/environment
source /etc/environment

📌 Path Information

CLI Path:

/home/frappe/zatca-cli-2.5.0/zatca-cli-2.5.0/bin/zatca-cli

Java Home:

/home/frappe/zatca-cli-2.5.0/jdk-11.0.23+9-jre

Integration:

Validate Generated XML:
- If enabled, validates the generated ZATCA XML when creating Sales Invoice Additional Fields. This has a performance impact, so it is recommended to enable this only for testing or troubleshooting problems.
  - Block Invoice on Invalid XML
    - If enabled, submission of sales invoices that produce invalid XML will be blocked.
      Requires ZATCA CLI 2.1.0 or later (In case of Rejection or Accepted with warnings)
Fatoorah Server URL (ZATCA Server URL for Production):
- The user selects which environment he uses
  - Sandbox: ZATCA test environment
  - Simulation: Test environment requires OTP from Fatoorah platform
  - Production: ZATCA production environment requires OTP from Fatoorah platform

By following these settings and configurations, the system will be properly integrated with ZATCA, ensuring compliance with regulatory requirements for invoicing.

ZATCA Business Settings