Understanding responses

Every create call returns a clear HTTP status and a small set of compliance fields. Learn how to tell a clean ZATCA accept from an accept-with-warnings — and when not to resubmit.

HTTP status

Esnad signs and persists the invoice first (ICV/PIH advance), then tries Fatoora inline.

HTTP	Meaning	What you do
200	Fatoora finished in this request. Invoice `status` is `reported` (B2C) or `cleared` (B2B).	Read compliance fields below before treating as fully clean.
202	Accepted and queued. Fatoora was slow or unavailable.	Poll GET /v1/invoices/:id or wait for a webhook.
4xx	Esnad rejected the request before calling Fatoora (auth, EGS, structural payload).	Fix using the error catalog. Do not retry blindly if `retryable: false`.

Accepted ≠ fully compliant

ZATCA often returns REPORTED / CLEARED with validation warnings. Esnad keeps invoice status as reported/cleared (ICV/PIH already advanced). You must read the compliance fields on create, GET, list, and webhooks.

Situation	status	zatca_compliant	resubmit	Action
Clean accept	reported / cleared	true	true	Deliver / archive as usual
Accept with warnings	reported / cleared	false	false	Do not resubmit the same invoice_number/uuid. Fix issues on the next document.
Request validation	—	—	—	HTTP 400 error body — see Errors

Never flip reported/cleared to failed for warnings

Resubmitting the same number/UUID after a warning accept creates a duplicate chain entry. Treat resubmit: false as a hard client rule.

Compliance fields

zatca_compliant — false when Fatoora returned any validation warnings.
zatca_warning_count / zatca_warnings — ZATCA codes (e.g. BR-KSA-37) and messages.
resubmit — false only when accepted with warnings; otherwise true.
message — human guidance when warnings are present.

Examples

Clean accept (HTTP 200)

{
  "invoice_id": "inv_...",
  "uuid": "…",
  "status": "reported",
  "zatca_compliant": true,
  "zatca_warning_count": 0,
  "zatca_warnings": [],
  "resubmit": true
}

Accepted with warnings (HTTP 200) — do not resubmit

{
  "invoice_id": "inv_...",
  "uuid": "…",
  "status": "reported",
  "zatca_compliant": false,
  "zatca_warning_count": 1,
  "zatca_warnings": [
    {
      "code": "BR-KSA-37",
      "message": "The seller address building number must contain 4 digits.",
      "category": "KSA"
    }
  ],
  "resubmit": false,
  "message": "ZATCA accepted this document (reporting/clearance succeeded) but it is NOT fully compliant. Do not resubmit this invoice_number/uuid — that would create a duplicate. Review zatca_warnings, fix the underlying issues on the next document, then issue a new invoice."
}

Next: Errors · Invoices · API objects