Connecting to ZATCA

Every receipt HarakahTec prints already carries the QR code, the chained invoice numbering and the fields ZATCA requires — that happens on every sale, with nothing to set up, and section 27 covers it.

This section is the other half: sending those invoices to ZATCA, which is what Phase 2 means. It is not automatic, because it cannot be. ZATCA issues a certificate to each till individually, and only you can get one, using an OTP from your own Fatoora portal account.

#What you are actually connecting

Not your company. Not your branch. Each till, one at a time.

ZATCA treats every till as its own invoicing device, with its own certificate and its own unbroken invoice chain. Connect three tills and you have done the exercise three times, with three OTPs. A till you add next year is a fourth.

A connection request is per branch, because each till is registered against that branch's national address. The system refuses a request whose tills are not all in the same branch.

#The three environments

This is the part worth reading twice. ZATCA runs three separate gateways, and they are not three degrees of the same thing — they behave differently, and one of them will tell you everything is fine when it is not.

You choose one under Settings → ZATCA Connection, in the field marked Target ZATCA Environment.

Careful: The sandbox accepts invoices that production would reject, and answers as though they were perfect. So a successful sandbox run is not evidence that you are ready — it is the most common way to believe you are ready when you are not. If you only ever test in the sandbox, the first invoice ZATCA ever judges properly will be a real one.

This is why simulation exists, and why it is worth the OTP it costs.

#The order to do it in

1. Simulation. Connect your tills to the rehearsal gateway and ring up real-shaped sales on them: a simplified invoice to a walk-in, a standard invoice to a company customer, and a refund of each. Nothing filed here has tax effect.
2. Look at the results, not just the ticks. Every document type should come back accepted with no errors. If any of them does not, that is the whole point of doing this — fix it here, where it costs nothing.
3. Production. Only then. The same exercise, a fresh OTP, and from that moment the invoices are real.

The selector opens on Simulation for this reason. Moving it to Production is a deliberate act, and the screen asks you to confirm it.

#Before you raise a request

A request that is missing any of this will be sent back, so it is quicker to check first:

• Your VAT number is the real one, fifteen digits beginning with 3 — §3
• Your unified number (the 700 number) is in — §3
• The branch has a complete national address: building number, additional number, street, district, city and postal code. Not one of them is optional here, because the certificate carries the address — §4
• The tills exist and are active — §14
• You can sign in to the Fatoora portal and generate an OTP

The OTP

Six digits, from your own Fatoora portal account, and one per till. ZATCA gives each one sixty minutes.

That hour is the thing that catches people out. Generate the OTPs when you are sitting down ready to use them — not the night before, and not while you are still filling in the address. If you are connecting four tills, generate four and spend all four inside the hour.

#Raising the request

From the back office, under Settings → ZATCA Connection:

1. Pick the branch.
2. Tick the tills you are connecting. Already-connected tills cannot be asked for again, and neither can ones already on an open request.
3. Choose the environment — simulation first, as above.
4. Choose what these tills issue: simplified invoices, standard ones, or both. A shop counter is usually both.
5. Enter the OTP for each till.
6. Confirm the details are right, and send it.

HarakahTec reviews it, and the request moves through pending, under review, then approved and in progress while the certificates are issued, and finally completed. If something is unclear you will see information requested with a note saying what is needed.

#Once a till is connected

Four things change, and all four are worth knowing before they surprise you.

Invoices are signed and sent. Each one is signed with that till's own certificate and submitted — cleared or reported, depending on the type. The cashier does not do anything differently.

A filed invoice cannot be voided. Before, a mistake could be voided. Once ZATCA has it, the only document that withdraws an invoice is a credit note, so the till will refuse the void and tell you to refund it instead. That is not the system being awkward — it is the rule.

Selling still works with no internet. The till keeps trading offline and marks those sales as still owing a submission; they are sent when the line is back. You do not have to stop selling, and you do not have to remember.

Certificates expire. You are warned thirty days ahead, on the ZATCA screen. Renew before the date rather than after — an expired certificate means invoices stop being cleared.

#When something is refused

Two different things, and they are not treated the same:

• An invoice ZATCA judged and rejected is a real answer. Something in it is wrong, and it will not be retried until that is fixed.
• A timeout, an authentication failure or an error on ZATCA's side is not a verdict on the invoice. It says nothing about whether the invoice was good, so it is retried rather than abandoned.

If a whole batch is rejected in simulation, read the first one properly rather than retrying all of them — they usually share one cause.

#What to do next

Section 29 is the going-live checklist, and it assumes this is done.