Skip to content

From zero to a ZATCA-compliant invoice (demo narrative)

This page is a linear business story for sales and onboarding — the journey from a fresh tenant to a cleared, ZATCA-compliant invoice. For the copy-pasteable API detail behind each step, follow the links: the Quickstart for the end-to-end calls and the ZATCA integration guide for the compliance specifics.

1. Prerequisites

  • A dev or simulation tenant with an admin user and correct VAT registration data.
  • An understanding of branches: one legal entity can expose multiple branches (trade names, CSIDs, document prefixes). See Documents API → Branches.

2. Tenant and branch

  • Create or select a branch for the selling location.
  • Attach ZATCA (and VAT) settings to that branch — environment (ZATCA_ENVIRONMENT_PHASE2_SIMULATION vs production), address fields, and tax profile must match what ZATCA expects. Enabling a regulation for a tenant is an administrator step handled by the Invora team.

3. Onboarding (streaming)

  • Start onboarding with POST /api/v1/regulations/zatca/onboarding, which returns a server stream of steps (CSR generation, compliance CSID, production CSID).
  • Wait for a final success event before submitting live documents in production environments; if the stream drops, poll GET /api/v1/regulations/zatca/onboarding/progress.
  • Each failed step carries structured errors (code, category, message) — see the onboarding troubleshooting table in the ZATCA integration guide.

4. Invoice journey

  1. Create a document — the ergonomic Simple invoicing surface for invoices, credit notes, and debit notes, or the full Documents API for raw UBL.
  2. Optionally set autoCalculate or call Calculate so totals, taxes, and allowances match Invora's rules.
  3. Validate the document and fix any reported field errors.
  4. Freeze it (or pass freezeImmediately: true on create) so it becomes immutable and the regulation pipeline runs.

5. Compliance

  • Clearance vs reporting (and simplified vs standard) is chosen automatically from the invoice content and branch configuration: B2B clears synchronously, B2C reports asynchronously.
  • Read the document's ZATCA regulation metadata for status, the QR payload, and authority references — the artifact bytes are not inline on the document.

6. Artifacts

  • Download the signed XML or QR code with GetArtifact (GET /api/v2/regulations/zatca/documents/{documentKey}/artifact), or fetch them all at once with ListDocumentArtifacts (response uses items).

7. PDF

  • For customer-visible output, generate or preview a branded PDF through the PDF service (/api/v2/pdf), which can embed the logo, QR code, stamp, and signature.

8. Troubleshooting

  • Map ZATCA rejections to the onboarding stream errors or the document's regulation diagnostics; use the field-level violations to fix the data. See Error handling for the status-code and error-detail model.
  • For gateway or auth failures, verify your access-token scopes and that the token carries the Invora project audience (see Authentication).