Skip to content

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

This page is a linear business story for sales and onboarding. For protocol and API details, see ZATCA integration guide.

1. Prerequisites

  • A dev or simulation tenant with an admin user and correct VAT registration data.
  • Understanding of branches: one legal entity may expose multiple branches (trade names, CSIDs, document prefixes).

2. Tenant and branch

  • Create or select a branch for the selling location.
  • Attach ZATCA (and VAT) settings via RegulationConfig for that branch — environment (PHASE2_SIMULATION vs production), address fields, and tax profile must match what ZATCA expects.

3. Onboarding (streaming)

  • Call the ZATCA onboarding RPC that returns a server stream of steps (OTP, CSR, compliance CSID, production CSID).
  • Wait for a final success event before submitting live documents in production environments.
  • Interpret errors via categories in the stream payload (see ZATCA-Specific Errors in error-handling.md).

4. Invoice journey

  1. Create a draft financial document (typed UBL fields or XML interop, depending on client).
  2. Optionally run auto_calculate / Calculate so totals, taxes, and allowances match Invora rules.
  3. Validate embedded in the document service; fix ValidationError entries if any.
  4. Freeze the document (optionally with freeze_immediately where supported) so it becomes immutable for submission.

5. Compliance

  • Choose clearance vs reporting (and simplified vs standard) per branch configuration.
  • Read ZatcaRegulationMetadata on the document for status, QR payload, and authority references — not raw bytes on the main document message.

6. Artifacts

  • Download PKCS/XML/PDF artifacts with GetArtifact or list them with ListDocumentArtifacts (response uses items).

7. PDF

  • If the demo includes customer-visible output, generate or preview PDF through the product path your deployment exposes (gateway route as per environment).

8. Troubleshooting

  • Map ZATCA rejections to stream or RPC errors; use ValidationError fields (field, code, message) for data fixes.
  • For gateway or auth failures, verify Zitadel token scopes and Config Sync revision for the environment.