Saudi Arabia only. This module implements the KSA ZATCA "Fatoorah" model (a central clearance/reporting authority). UAE e-invoicing is a separate module (the Peppol "5-corner" model via an accredited service provider) — see your UAE rollout. Each VAT-registered Saudi taxpayer onboards its own company with its own Fatoora OTP; ColorsX74 never holds your OTP or keys.
How it fits together
A draft is not a tax document. An e-invoice is created when you issue an invoice — never when you save a draft. A draft carries a provisional DRFT- reference, posts nothing, and produces no e-invoice, no invoice counter and no hash-chain entry. Issue it and exactly one e-invoice is created, carrying the invoice's final number. Abandon or delete the draft and nothing was ever consumed — so your reported sequence stays gapless.
ZATCA e-invoicing is a gated add-on. When enabled for a company, the module lives under E-Invoicing (ZATCA) in the sidebar (/einvoicing-zatca); its API is served at /api/v1/einvoicing-zatca. It builds each invoice into the mandatory ZATCA UBL 2.1 XML, computes the invoice hash and maintains the per-EGS counter + previous-invoice-hash chain, cryptographically signs it (XAdES) with your company's certificate, and submits it to ZATCA.
Jump to: The two phases · Enabling the module · Onboarding with your Fatoora OTP · Environments & the safety gate · Signing & submitting invoices · Invoice statuses · Operator notes.
The two ZATCA phases
Phase 1 (Generation). Every invoice carries the mandatory Base64 TLV QR code — shown as a scannable QR image right in the documents table (scan it with any phone camera or the ZATCA app to verify seller, VAT number, KSA-time timestamp, and totals) — and is stored as a structured e-invoice. No ZATCA account is needed — this works the moment you enable the module.
Phase 2 (Integration). Each invoice is rendered as ZATCA UBL 2.1, hash-chained (ICV + previous-invoice-hash), cryptographically signed with your company's CSID certificate, and submitted to ZATCA for Clearance (standard/B2B — cleared before it is shared with the buyer) or Reporting (simplified/B2C — reported within 24 hours; the sale is not blocked). Phase 2 needs your company's CSID, which you obtain by self-onboarding below.
Enabling the module
In E-Invoicing (ZATCA) → Settings: tick Enable ZATCA e-invoicing, choose your Environment (start with Sandbox), and optionally override the seller name / VAT number (otherwise they come from the company record). Save. From this point every sales invoice automatically gets its Phase-1 QR + e-invoice document.
Your company's VAT/TIN must be a 15-digit number that starts and ends with "3" — ZATCA requires this on the certificate request.
Onboarding with your Fatoora OTP (self-service)
To sign and submit (Phase 2) your company needs a CSID (cryptographic stamp identifier) from ZATCA. You obtain it yourself, from your own Fatoora portal:
- Log in to the Fatoora portal (fatoora.zatca.gov.sa) for your VAT-registered company and generate an OTP for onboarding an e-invoicing solution. The OTP is valid for about an hour.
- In the ERP, open E-Invoicing (ZATCA) → Link CSID (Onboarding), paste the OTP, and click Request CSID. The OTP is sent once, used immediately, and never stored or shown again.
- The system runs the full ZATCA flow automatically: it generates a certificate request, fetches your Compliance CSID, runs ZATCA's compliance checks, then fetches your Production CSID. The status timeline shows each step.
- When it reads Onboarded, your company's certificate is active and stored encrypted. The cert thumbprint and expiry are shown on the page.
That's the whole "ready the moment you enter your Fatoora details" step — no involvement from ColorsX74 staff, and your OTP/keys stay with your company.
Environments & the safety gate
ZATCA has three environments, each with its own credentials and base URL:
- Sandbox — open developer testing; accepts dummy data. No legal effect. Use it to try the flow.
- Simulation — pre-production with a real Fatoora simulation OTP. No legal effect.
- Production — real, legally-binding e-invoices.
The hard environment gate. A certificate obtained in Sandbox or Simulation can never be used to submit to Production — the system refuses any mismatch. And the first real Production submission must be explicitly armed by an operator ("Arm live Production submission" on the onboarding screen), so a correctly-onboarded Production company still won't transmit to ZATCA until you turn it on. Onboard in the environment you intend to use.
Signing & submitting invoices
Once a Production CSID is linked, each e-invoice can be submitted to ZATCA (the "Submit to ZATCA" action on the documents list, or automatically as part of your invoice flow):
- Standard / B2B (Clearance). The invoice is cleared by ZATCA before it is shared with the buyer. If ZATCA rejects it, the invoice is not legally issuable — fix and resubmit. A cleared invoice gets ZATCA's returned cleared document.
- Simplified / B2C (Reporting). The point-of-sale receipt is issued immediately with its QR; the invoice is reported to ZATCA within 24 hours. Reporting never blocks the sale.
Submission is idempotent and retry-safe: a transient network failure can be retried without breaking the hash chain (ZATCA de-duplicates on the invoice UUID), and an already-cleared/reported invoice is never re-sent.
Invoice statuses
GeneratedLocal / UblGenerated — Phase-1 QR + UBL produced. Signed — XAdES-signed with your certificate. Submitting — in flight to ZATCA. Cleared — B2B accepted by ZATCA (the legal document). Reported — B2C reported. ClearanceRejected / ReportingRejected — ZATCA rejected it (see the message). SubmissionFailed — transient/blocked (e.g. not armed, wrong environment) — safe to retry once resolved.
Operator notes
- One company, one CSID. Each company onboards separately with its own OTP. Switch into the company first, then onboard.
- Secrets stay encrypted. The private key, CSID and secret are encrypted at rest and never displayed, logged, or returned by the API — only the non-secret thumbprint/expiry are shown.
- Certificate renewal. CSIDs expire (≈1 year). The onboarding page shows the expiry; re-onboard before it lapses.
- Credit notes are typed and submitted automatically as the ZATCA credit-note document.
- If generating an e-invoice is declined, the message now says why. Generation can be declined for four different reasons — the invoice is still a draft, the invoice has been voided, e-invoicing is not enabled for the company, or the invoice no longer exists. These used to be reported with a single message naming only the last two, so an operator whose invoice was simply not issued yet went looking for a settings problem that did not exist. Each reason is now named exactly.