ZATCA e-invoicing API integration: how Phase 2 works, step by step

ZATCA e-invoicing API integration in Phase 2 is the live connection between your invoicing system and the Fatoora platform of the Zakat, Tax and Customs Authority. Your system sends it every invoice in a set format. Standard invoices are cleared first, before the buyer gets them. Simplified invoices are issued at once and reported within 24 hours. If your software already does this, nobody on your team has to write code.

The word API sounds like a job for programmers, but it only names the way two systems talk. ZATCA defines that conversation, so Phase 2 systems follow the same rules. This guide explains the pieces in plain words, so a business owner or IT lead can judge whether to build the connection themselves or rely on ready software.

Before a system can send live invoices, it has to be registered with ZATCA. This is onboarding, and the taxpayer does it on the Fatoora portal, not the software vendor. You first get a one-time password (OTP) from the portal. Then you generate a certificate signing request (CSR), which asks ZATCA to issue a digital credential to your system.

ZATCA answers with a compliance CSID, used for testing only. Your system then sends sample invoices through compliance checks. When they pass, ZATCA issues a production CSID and live invoicing can begin. Software can guide you through these steps, but they belong to your business, not the software vendor, so record who did them and when.

For each invoice, the system builds a data file in XML, using a standard layout called UBL 2.1. Think of a form where every field has a fixed label, so ZATCA's computers can read it without guessing. Around that file, the system adds the items below, and each has a simple job. The list explains them so you know what your system needs.

Nobody types these by hand. The software should create them each time an employee presses issue, and because counters and hashes form a chain, it must also remember the last invoice it sent. That memory is one of the parts of a do-it-yourself build that need the most care, so do not overlook it.

• UUID: an identifier that no other invoice shares
• Counter value: a running count of invoices issued
• Previous invoice hash: a fingerprint of the last invoice, which chains them
• Cryptographic stamp: a digital seal tying the invoice to your system
• QR code: a scannable code carrying the invoice's key details
• Optional PDF/A-3 copy: a readable file that can hold the XML

Take a small cafe. The customer pays at the till, so the invoice is a simplified tax invoice. The till prints it at once and the system reports it to ZATCA within 24 hours. Because issuing comes first, a short internet drop does not stop the queue, as long as the invoice is sent inside that window.

Now take a wholesaler billing a shop. That is a standard invoice, so it is cleared: ZATCA receives it first, and the shop gets it only after ZATCA accepts it. If ZATCA does not accept it, the invoice must be corrected and sent again. Pick a system that shows rejections clearly, and name someone to check them daily, without delay.

Building suits a company with its own developers and unusual invoicing needs. The first version is the easy part. The ongoing work is keeping the connection correct when ZATCA changes its rules, testing each change in the simulation environment, and fixing faults at the busiest hour. Someone must own that work for as long as you invoice.

Ready software moves much of that upkeep to the vendor, who also answers when something breaks. You then depend on that vendor, so ask how updates arrive and how fast support replies. Either way your business still does its own onboarding. Put these questions to a developer or a vendor before you decide.

• Which Phase 2 steps does your system handle, and which are ours?
• How do ZATCA rule changes reach us, and who tests them?
• Can we rehearse in the simulation environment first?
• What happens to invoices when the internet or platform is down?
• Where do we see rejected or unsent invoices?

ZATCA rolls Phase 2 out in numbered waves, each chosen by VAT revenue in stated years. It notifies the taxpayers in a wave directly, at least six months before their integration date, and has announced 25 waves so far. Check your own wave and date with ZATCA before making any decision.

ZATCA has announced that Wave 24 covered taxpayers whose VAT revenue exceeded SAR 375,000 in 2022, 2023 or 2024, with a deadline no later than 30 June 2026, which has passed. Wave 25 covers taxpayers whose VAT revenue exceeded SAR 187,500 in 2022, 2023, 2024 or 2025, with a deadline no later than 1 February 2027.

Fatooraz supports ZATCA's e-invoicing requirements in both phases, Phase 1 and Phase 2. Onboarding is done by the taxpayer on the Fatoora portal, and Fatooraz guides you through it step by step inside your workspace. The free trial runs in ZATCA's simulation environment, so you can rehearse with your real cases before a single live invoice.