ZATCA E-Invoicing

Shaari integrates with Saudi Arabia's ZATCA (Zakat, Tax and Customs Authority) Phase 2 e-invoicing system, also known as the Integration Phase. When enabled, your sales invoices are electronically submitted to ZATCA for validation, ensuring full compliance with Saudi tax regulations.

ZATCA Phase 2 Overview

ZATCA Phase 2 requires businesses to connect their invoicing systems directly to the ZATCA platform. Unlike Phase 1 (which only required generating invoices in a specific format), Phase 2 requires real-time or near-real-time electronic submission of every invoice to ZATCA's servers.

Shaari handles the entire submission process automatically once you complete the onboarding setup.

info

ZATCA Phase 2 must be enabled for your tenant before invoices can be submitted. Your account administrator can enable this in Settings > Integrations > ZATCA Settings. The onboarding process involves registering your solution unit with ZATCA and obtaining compliance certificates.

B2B Clearance vs B2C Reporting

ZATCA distinguishes between two types of transactions, each with a different submission process:

B2B Clearance

Business-to-business invoices go through the clearance process:

1. You create and approve an invoice in Shaari.
2. Shaari sends the invoice to ZATCA before it reaches the buyer.
3. ZATCA validates the invoice, applies a cryptographic stamp, and returns it.
4. The cleared invoice (with ZATCA's stamp) is then delivered to the buyer.

The buyer cannot receive the invoice until ZATCA has cleared it. This process typically completes in seconds.

B2C Reporting

Business-to-consumer invoices go through the reporting process:

1. You create and approve an invoice in Shaari.
2. The invoice is delivered to the customer immediately.
3. Shaari reports the invoice to ZATCA within 24 hours.
4. ZATCA validates the reported invoice asynchronously.

B2C invoices do not need to wait for ZATCA approval before being shared with the customer.

note

The transaction type (B2B or B2C) is determined by the customer record. Customers with a valid VAT registration number are treated as B2B. Customers without a VAT number are treated as B2C.

QR Code Generation

Every ZATCA-compliant invoice includes a QR code in the 9-tag TLV (Tag-Length-Value) format. Shaari generates this QR code automatically when an invoice is approved. The QR code encodes:

Tag	Field
1	Seller's name
2	VAT registration number
3	Invoice timestamp
4	Invoice total (with VAT)
5	VAT amount
6	Hash of the invoice XML
7	ECDSA digital signature
8	Public key
9	Certificate signature

The QR code appears on the printed PDF and can be scanned by any ZATCA-compatible reader to verify the invoice's authenticity.

Submitting Invoices to ZATCA

The submission process is automatic for approved invoices:

1. Invoice approved -- the invoice moves to APPROVED status.
2. XML generation -- Shaari generates a ZATCA-compliant XML representation of the invoice (UBL 2.1 format).
3. Digital signing -- the XML is signed using your tenant's ZATCA compliance certificate.
4. Submission -- the signed XML is sent to the ZATCA API.
5. Response -- ZATCA returns a clearance (B2B) or reporting acknowledgment (B2C).
6. Status update -- the invoice status updates to CLEARED or REPORTED.

You can monitor the submission status of every invoice in the invoice list view. A status badge shows whether the invoice is pending ZATCA processing, cleared, reported, or has encountered an error.

Clearance and Reporting Status

Each invoice shows one of the following ZATCA statuses:

Status	Meaning
Pending	The invoice has been approved but not yet submitted to ZATCA.
Processing	The invoice has been sent to ZATCA and is awaiting a response.
Cleared	(B2B) ZATCA has validated and stamped the invoice.
Reported	(B2C) ZATCA has acknowledged receipt of the invoice report.
Rejected	ZATCA rejected the invoice due to validation errors.
Error	A technical error occurred during submission.

Error Handling and Retry

When ZATCA rejects an invoice or a technical error occurs, Shaari provides detailed error information:

• Validation errors -- ZATCA returns specific error codes and messages indicating what is wrong (e.g., missing VAT number, invalid date format, incorrect tax calculation). These are displayed in the invoice detail view.
• Technical errors -- network timeouts, API unavailability, or certificate issues. Shaari automatically retries technical errors with exponential backoff.

To resolve a rejected invoice:

1. Open the invoice and review the ZATCA error details.
2. If the error is in the invoice data, issue a credit note for the rejected invoice and create a corrected invoice.
3. If the error is technical, click Retry Submission to resubmit.

caution

Do not ignore ZATCA rejections. Rejected invoices are not compliant and may result in penalties during ZATCA audits. Address rejections promptly.

Requirements for ZATCA Compliance

To use ZATCA Phase 2 in Shaari, ensure the following are in place:

Tenant Setup

• ZATCA Phase 2 is enabled for your tenant.
• Your solution unit is registered with ZATCA and has a valid compliance certificate.
• The onboarding process is completed (all 5 steps).

Seller Information

• Your organization's legal name (in Arabic and English).
• Valid VAT registration number (15 digits).
• Commercial Registration (CR) number.
• Complete national address (building number, street, district, city, postal code).

Customer Information (for B2B)

• Customer's legal name.
• VAT registration number.
• National address.

Invoice Data

• Every line item must have a tax category and rate.
• Invoice dates must be accurate and not back-dated beyond ZATCA's allowed window.
• Amounts must be in SAR with correct decimal precision.

tip

Run a test invoice through the ZATCA sandbox environment before going live. This lets you verify that your configuration is correct without creating real tax obligations. The sandbox option is available during the ZATCA onboarding process.