Path in the Application
To access ZATCA setup and settings, navigate to:
ZATCA ERPGulf → Setup ZATCA
For ongoing settings management, go to ZATCA ERPGulf → Zatca Erpgulf Setting (one record per company). For multi-POS deployments, use ZATCA ERPGulf → Zatca Multiple Setting (one record per POS machine). The ZATCA compliance dashboard is available at ZATCA ERPGulf → ZATCA Dashboard.
Prerequisites
Before running the ZATCA onboarding wizard, ensure the following are in place:
Your company is registered with ZATCA as a VAT-registered business in Saudi Arabia and has an active ZATCA taxpayer account.
The company record in iVendNext Desk has a Tax ID (VAT registration number) that is exactly 15 digits, begins with 3, and ends with 3.
The company address is fully populated, including Address Line 1, Address Line 2, a 4-digit Building Number, and a 5-digit Postcode.
You have obtained a one-time password (OTP) from the ZATCA taxpayer portal — this is required during the Compliance CSID step of the wizard.
The zatca_erpgulf module is installed on your iVendNext instance and all required Python packages (requests, pyqrcode, lxml, pikepdf) are present.
For multi-POS deployments, each POS machine name has been noted so it can be registered as a separate ZATCA device.
How to Create
The ZATCA onboarding wizard guides you through five steps to register iVendNext as an authorised e-invoicing device and obtain a Production CSID from ZATCA.
Go to ZATCA ERPGulf → Setup ZATCA. Select your Company from the drop-down and, if registering a POS machine, select the POS Machine field.
Click Generate CSR Config. iVendNext reads your company's Tax ID, Location, and Business Category and builds the CSR configuration string automatically. Review the pre-populated config — it includes csr.organization.name, csr.country.name, csr.invoice.type, csr.location.address, and csr.industry.business.category. Click Next.
Click Generate CSR. iVendNext submits the CSR to ZATCA and receives a Compliance CSID token. The token is stored in the Basic Auth (Compliance CSID) field of your Zatca Erpgulf Setting record. Click Next.
Click Run Compliance Test. iVendNext automatically tests all six ZATCA document types against the Compliance CSID: Standard Invoice, Standard Credit Note, Standard Debit Note, Simplified Invoice, Simplified Credit Note, and Simplified Debit Note. All six must pass. Use the Validation Type selector in Zatca Erpgulf Setting if you need to re-run a specific test type. Click Next.
Click Get Production CSID. iVendNext exchanges the Compliance CSID for a Production CSID and stores it in the Basic Auth (Production CSID) field. From this point, all invoices submitted for this company or POS machine will use the Production CSID. Click Finish.
Once onboarding is complete, ZATCA submission is active. For POS invoices, submission happens automatically on invoice submission. For Sales Invoices, submission can be triggered manually from the invoice form or processed by the background scheduler.
Features
ZATCA Settings per Company
Each company has a dedicated Zatca Erpgulf Setting record. The key fields are:
ZATCA Invoice Enabled — master on/off switch. Disable this for non-Saudi companies so they are unaffected.
Send Invoice to ZATCA — set to Automatically to submit on each transaction, or Background to defer submission to the scheduler.
Environment (custom_select) — choose Sandbox, Simulation, or Production. Each environment has its own URL field: Sandbox URL, Simulation URL, and Production URL. Sandbox is for development testing; Simulation mirrors the live ZATCA platform closely and is recommended for final validation before go-live.
PIH — the Previous Invoice Hash, maintained automatically by iVendNext after each successful submission. Do not edit this field manually.
Private Key and Certificate — the EC private key and ZATCA-issued X.509 certificate used for invoice signing. These are populated during the onboarding wizard and should not be modified.
For multi-POS environments, each POS machine has a Zatca Multiple Setting record with its own Production CSID, PIH, and background mode flag.
Sales Invoice Submission (B2B and B2C)
When you submit a Sales Invoice, iVendNext determines the compliance path from the customer record:
If the customer has a B2C set, iVendNext submits to the ZATCA reporting endpoint. On a successful response, ZATCA Status is set to REPORTED.
If the customer does not have a B2C set, iVendNext submits to the ZATCA clearance endpoint. The invoice is held until ZATCA returns a CLEARED response, at which point the cleared XML is attached and ZATCA Status is set to CLEARED.
In both cases, the ZATCA UUID, signed XML attachment, QR code PNG, and full ZATCA response are stored on the invoice record. The PIH is updated automatically after each successful submission.
POS Invoice Submission
POS Invoices are submitted to ZATCA automatically on the on_submit document event — no additional action is required from the cashier. The signed XML and QR code PNG are attached to the POS Invoice record. A loading spinner is displayed on the desk during the API call. The ZATCA Status badge on the POS Invoice form shows REPORTED, CLEARED, Pending, or Failed.
Invoice Immutability
Once an invoice reaches REPORTED or CLEARED status, iVendNext blocks any attempt to edit, cancel, or re-save it. If you need to correct a submitted invoice, issue a Credit Note or Debit Note against the original.
Manual Resubmission
To resubmit failed invoices in bulk, go to the POS Invoice or Sales Invoice list view, filter by ZATCA Status = Failed or Not Submitted, select the relevant records, and click Resubmit to ZATCA.
ZATCA Dashboard
The ZATCA Dashboard shows a per-company breakdown of invoice submission counts by status (Not Submitted, REPORTED, CLEARED, ERROR). Use this page to monitor compliance health across all companies from a single screen.