ZATCA deep dive

Calling the ZATCA API, and handling what comes back.

Submission is the easy part. Building a pipeline that survives failures, retries safely, and never double-submits is where the real engineering is.

Response handling

Three outcomes

Every submission resolves to accepted, accepted-with-warnings, or rejected — each routed to a different downstream path in dsFatoora.

Failure classification

Not all failures are equal

Data errors, connectivity errors, and authority-side errors are classified separately so the right team (or automated fix) handles each.

Retry logic

Exponential backoff

Transient failures retry on an increasing delay, with a dead-letter queue catching anything that still fails after repeated attempts — nothing silently disappears.

Duplicate prevention

Idempotency keys

Every submission carries a unique key, so a retried request can never result in the same invoice being cleared twice.

Audit

Immutable logging

Every stage — submission, response, retry, resolution — is logged with a timestamp, satisfying both internal audit needs and ZATCA's own record-keeping expectations.

Reconciliation

ERP vs. ZATCA matching

A continuous reconciliation job compares ERP invoice records against ZATCA's cleared records, surfacing any gap before it becomes a compliance issue.