Finance & ZATCA

Follow the ZATCA fiscal-document lifecycle

Distinguish tax determination, local fiscal preparation and actual regulator evidence.

Current source · source reviewed · 7 min read

Before you begin

Evidence-backed tax determination and legal recipient.
Taxpayer/unit onboarding and environment-qualified credential references.

1. Review tax and legal facts

Confirm taxable base, treatment, rate, tax amount and legal recipient against the source-backed determination. Unknown treatment must remain unresolved until reviewed.

2. Prepare the appropriate fiscal document

The code exposes ZATCA document operations and a Fatoora unit/document API. Use the enabled deployment’s fiscal workflow, linking the invoice and onboarding record.

3. Follow signing and submission

Inspect sign, submit, clear or report operations and their evidence. The service deliberately separates local state from connector transport and does not invent a clearance response.

4. Inspect accepted artifacts and recovery

Where available, use the fiscal invoice-xml and invoice-pdf endpoints. For rejection, follow the channel-specific regeneration/recovery workflow and retain the predecessor relationship.

Readiness is taxpayer-specific

A wave/configuration row or a route’s existence does not prove onboarding, working credentials or compliance. Production requires the qualified taxpayer/unit, current credentials, SDK/validation proof and actual external evidence.

Do not reuse NPHIES retry semantics

NPHIES transport retries preserve message identity. The code explicitly treats rejected ZATCA-document recovery as different; apply the fiscal integration’s state machine.

Troubleshooting

The document cannot advance to cleared or reported

Check the configured connector response, signed-payload hash, taxpayer onboarding, environment and credential qualification. A local draft alone cannot be marked accepted.

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.