IntegrationsSaudi Arabia — e-invoicing

Saudi e-invoicing (Fatoora Phase 2)

Fatoora Phase 2 requires every Saudi invoice to be cryptographically signed and either reported (B2C) or cleared (B2B) before issuance. Novex handles the signing, reporting, QR code, and PDF stamp once you upload your CSID certificate and pick the environment.

Prerequisites

  • A registered Saudi taxpayer record with the Zakat, Tax and Customs Authority.
  • A Fatoora onboarding session completed — you must have generated your Compliance Certificate (CSID) via the Fatoora portal.
  • Decided whether you’re starting in sandbox or going straight to production.

One-time setup

The Saudi e-invoicing connector before setup: status NOT CONFIGURED, "Never validated", and step 1 of 3 asking for the Fatoora certificate in an empty PEM box.

  1. In Novex, go to Settings → Compliance → Saudi e-invoicing.
  2. Pick the environment: sandbox (for testing) or production (live).
  3. Upload your CSID certificate (.crt or .p12 — both accepted).
  4. Upload (or enter) your private key — encrypted at rest with the tenant secret-vault key.
  5. Set your registered taxpayer info: VAT number, CR number, registered name (Arabic + English), branch ID, national address.
  6. Save. Novex performs a synthetic ping to the authority to validate the cert is accepted before persisting.

Sandbox vs production

SandboxProduction
Fatoora endpointgw-fatoora-sb.zatca.gov.sagw-fatoora.zatca.gov.sa
Invoices issuedTest only — never real tax liabilityReal invoices; final
Cert validityIssued by the sandbox UIIssued via Fatoora onboarding
QR codesStamped, valid sandbox-sideStamped, full TLV-encoded

Start in sandbox. Send 3-5 test invoices end-to-end. Once you’ve verified the stamped PDFs and the Fatoora portal shows them under your sandbox account, swap the environment to production.

How signing works (under the hood)

When you click Issue on a KSA invoice:

  1. Novex builds the UBL 2.1 XML payload per the Fatoora spec.
  2. Computes the invoice hash (SHA-256) and the previous-invoice hash (chain).
  3. Signs the canonicalised XML with your private key (ECDSA over the cert’s SECP256R1 curve).
  4. POSTs to the Fatoora endpoint with mTLS + Basic auth (the CSID-derived credentials).
  5. Receives a cleared XML + QR string back.
  6. Embeds the QR as a 2D barcode + the cleared-stamp metadata into the PDF.

Troubleshooting

  • 403 from the authority — Most often a cert mismatch (sandbox cert hitting prod, or vice versa). Check Settings → Compliance → Saudi e-invoicing → environment matches the cert you uploaded.
  • 400 with VR-01 / VR-02 — Validation rule failure. The error detail lists which field. Common cause: missing nationalAddress on the buyer (for B2G invoices it’s required).
  • Cert about to expire — the authority emails 30 days in advance. Re-onboard via the Fatoora portal, re-upload to Novex. The chain breaks if the cert lapses mid-month.
  • “Previous-invoice hash mismatch” — The chain depends on the previous cleared invoice’s hash. If you ever manually restored from a backup you may need to re-anchor; email support@nov3x.com.

What Novex does NOT do

  • Help you onboard with the authority. That’s a one-time interaction with their own portal — we can’t automate it.
  • Store your CSID private key in plaintext. It’s encrypted at rest via the tenant secret-vault.
  • Cross the prod/sandbox boundary. Each tenant picks one environment; switching rotates the credential set.

Next

Connectors overviewWhatsApp Business