🧾 ZATCA / Fatoora — sources and test stands

← Localizations

A workspace script cannot access the network — and that is the only thing left on the platform host. Everything Saudi lives in the LocalizationSaudiArabia model: the QR format, the certificate profile, the Fatoora headers, the channel addresses and the onboarding exchange itself. The kernel holds only what cannot live in a script: the transport (IOutboundGateway for documents, IOutboundCall for synchronous exchanges) and the key (ICredentialSigner).

User: how to turn the e-invoice on. Business: ZATCA, KSA localization.

The parties' master data (no HTTPS)#

Fatoora's UBL requires the seller's VAT or CRN (the VAT vs CRN scheme), a KSA national address (Country + District + a 4-digit Building) and a sequential ICV.

What lives where#

SaudiEInvoice computes the invoice hash through IZatcaXades.InvoiceHash (C14N 1.0 minus UBLExtensions / cac:Signature / the QR) and assembles the QR through IZatcaQr. The ICV and the previous hash come from the host: IKeyedCounterService.TakeAsync("zatca-icv", legalEntity) atomically increments the (name, scope) row through ISqlDialect.TakeKeyedCounterSql (OUTPUT / RETURNING), and then SetTokenAsync stores the hash that the next Take will return as the PIH. The kernel signs: ICredentialSigner.SignHash(credentialRef, hashBase64) returns the signature, the SPKI, the certificate's signature and the certificate's DER — or null, and then the QR carries tags 1–6, which is still valid for an invoice. After the hash, the QR is embedded into Payload (AdditionalDocumentReference / ID=QR); if there is a CertificateDer, the same service adds XAdES-BES (ds:Signature). SignatureValue is a second signature: ECDSA over SHA-256(C14N(SignedInfo)), not over the invoice hash (tag 7). The queue: {uuid, invoiceHash, invoice: base64} onto fatoora-clearance (Standard — the buyer has a VAT) or fatoora-reporting (Simplified — no VAT). After release the envelope is Issued. Cleared/Reported is set by ApplyChannelOutcomesAsync: the ApplyFatooraOutcomes job every minute and a piggyback on the next posting. IsMockReject on the connection still rejects immediately. A Standard invoice (InvoiceType) must not be handed to the buyer until the envelope is Cleared: ISaudiEInvoice.BuyerReleaseBlockAsync. The print forms ZatcaInvoiceZr / ZatcaCreditNoteZr / ZatcaDebitNoteZr call it directly. InvoiceZr / CreditNoteZr / DebitNoteZr call the country-blind IEInvoiceRelease (Tax; SA wraps it and delegates to ISaudiEInvoice) — Sales does not depend on SA. A Simplified one is handed over at once.

The 500-character limit and the cryptographic stamp collide in practice. Tags 2–9 are all but fixed and leave about 30 bytes for the seller's name, while Arabic takes two bytes per character. ZatcaQr truncates tag 1: tags 7–9 cannot be cut (the signature would stop verifying), and throwing an exception is even less acceptable — the caller is in the middle of the posting, the envelope is already saved and the ICV is spent. Whether a truncated seller name is permitted by the specification is not recorded in our sources; the other two options are wrong for certain.

Onboarding#

Four web services of the model plus the bundle of the six kinds, all isDevOnly; CSR / Compliance CSID / sample invoices / Production CSID also carry requireExplicitRoles — the first two and the last hand out a key or a secret, and the sample invoices give access to Fatoora:

• POST /api/rest/ZatcaCsr — PKCS#10 + PKCS#8. Sandbox: PREZATCA-Code-Signing; simulation/production: ZATCA-Code-Signing.
• POST /api/rest/ZatcaCompliance — the OTP as a header on this call. It deliberately does not go into the signing profile: a signed and logged OTP would be replayed, and it is single-use. Channel fatoora-compliance.
• POST /api/rest/ZatcaComplianceInvoices — one sample invoice (uuid + invoiceHash + XML) onto the fatoora-compliance-invoices channel.
• POST /api/rest/ZatcaComplianceSamples — all six kinds (standard/simplified × invoice/credit/debit) in one call. Synthetic UBL: the QR is embedded, XAdES when there is a PEM CSID; it does not touch the live ICV. The live Fatoora service will not accept them without a real CSID; the stub on the stand accepts all six. The ERP document SalesDebitNote (UBL 383) is a separate path, not these samples.
• POST /api/rest/ZatcaProductionCsid — Basic credentials from the Compliance CSID (fatoora-csid), channel fatoora-production-csid. On live Fatoora the compliance sample invoices have to come first.

The exchange does not go through the queue: the answer carries a single-use secret, an outbox row would log it, and a retry an hour later would present a spent OTP. So onboarding calls IOutboundCall — a synchronous call by CHANNEL NAME, with the URL and the credential resolved by the host.

The secret from the answer is carried over by the operator into Integration__Credentials__fatoora-csid or fatoora-pcsid as token:secret. It does not go into git.

On the docker stand the fatoora channels are overridden by the configuration and point at api/rest/FatooraStub*. That is by design: the configuration wins over the model's metadata, and it is the only way to redirect a stand without editing someone else's model. Hence the rule — the platform's appsettings.json must not hold a single business channel, or it will shadow the model for ever.

There is no live HTTPS to gw-fatoora.zatca.gov.sa from CI.

Known defects#

Checked against the code, not against comments.

Open#

The submission outcome is written by Tax, not by the country package#

ApplyChannelOutcomesAsync does not set the subtype and does not write the journal itself — it calls ITaxDocumentOutcome.ApplyAsync. What is left with Saudi is exactly what belongs to it: which channel means Cleared and which means Reported.

If every package applied the outcome itself, nobody would fill in TaxDocument.Authority and TaxDocument.RejectionReason — they would stay declared and dead. The reason for a refusal would live only in TaxSubmission and in the queue row, and an accountant who opened a rejected envelope would see a subtype without a single word of why.

The write order is essential. Cleared and Reported are isReadOnly, and the guard lets through only Subtype and StatusValue. So the fields are written BEFORE the transition, while the envelope is still Issued. Reverse this order and no exception is thrown — Authority simply stays silently empty on every accepted envelope.

Idempotency rests on the subtype, not on a flag: Cleared/Reported/Rejected can be entered only from Issued, and the queue delivers at least once. An over-long reason is truncated to the column — losing the whole outcome because of it would be worse; the full text stays in the queue row.

InDoubt is NOT acknowledged: the request went onto the wire, no answer came back, and acknowledging such a message would mean hiding it instead of investigating it.

Test: TaxDocumentOutcomeTest.

XML, posting and print rules#

Do not do the left-hand thing. The right-hand column is the live contract.

Specifications (official ZATCA PDFs / pages)#

Test and production servers#

ZATCA documents different API base addresses for each environment (.../developer-portal, .../simulation, .../core), but on a stand all five Saudi OutboundChannel objects (fatoora-clearance, fatoora-reporting, fatoora-compliance, fatoora-compliance-invoices, fatoora-production-csid) declare the same baseUrl (https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal) and differ only by path. The environment is not part of the URL. It is a logical field, TaxAuthorityConnection.Environment (Sandbox/Simulation/Production). Switching the environment in production means editing the channel baseUrl/path for the specific stand, not choosing a row from this table. The paths from the portal manual are compliance, compliance/invoices, production/csids, invoices/reporting/single, invoices/clearance/single.

A CSID from one environment does not carry over to another. The OTP and the certificate do not go into git — only Integration__Credentials__<name>.

Checking the XML/QR offline, without a network: the SDK. We do not call live HTTPS from our CI.

Same topic for other readers: Analyst · User

Where next#

• business setup for analysts
• screen steps for users
• Saudi Arabia