ZATCA API Integration for Your Billing System (Phase 2)

ZATCA API integration means your own billing system sends every e-invoice to the Fatoora platform in the format ZATCA requires. B2B invoices are cleared before you share them with the buyer. B2C invoices are reported to ZATCA after issue.

If you run a custom ERP or in-house billing tool in Saudi Arabia, this work falls on you or your developer. The latest announced wave, Wave 25, has an integration date of 1 February 2027. From today (10 November 2026) that is about 12 weeks away.

What does ZATCA API integration involve?

It involves four things: registering your system with ZATCA, producing invoices in the required format, stamping them, and sending them through ZATCA's APIs.

ZATCA says Phase 2 (Integration) adds three requirements. You integrate your e-invoicing solution with Fatoora. You issue invoices in a specific format. You include additional fields.

Phase 1 (Generation) started on 4 December 2021. Phase 2 started on 1 January 2023 and rolls out in waves. Phase 1 was about creating invoices electronically. Phase 2 is about connecting to ZATCA.

For a developer, the practical pieces are:

• A structured XML invoice, not just a PDF.
• A cryptographic stamp and a QR code on the invoice.
• A unique invoice ID and a running sequence.
• Calls to ZATCA's APIs for onboarding, clearance and reporting.
• Handling the response from ZATCA and storing it against the invoice.

Always build from the current technical specification on ZATCA's site, not from a blog post, including this one. Field names and versions change.

What is the difference between clearance and reporting?

Clearance applies to standard (B2B) invoices. Reporting applies to simplified (B2C) invoices. The Fatoora Developer Community explains both flows.

The design impact is big. Clearance sits inside your sales flow. If ZATCA does not respond, your invoice is not ready to send. Reporting can run in the background, so a shop counter or delivery driver is not waiting.

Say a Jeddah trading company issues 60 B2B invoices a day from its ERP and a few hundred cash sales from its showroom. The ERP needs a live clearance call on the 60. The showroom system needs a reliable queue for the rest. Those are two different jobs, even if they share one codebase.

How do you onboard your system with Fatoora?

You onboard by registering each solution unit with ZATCA, proving it can produce valid invoices, and then getting production credentials. The exact steps are in ZATCA's documents. The usual order looks like this:

1. Check your wave and date. ZATCA notifies each business directly. Confirm it on the Fatoora portal.
2. Log in to the Fatoora portal with your taxpayer account and start the onboarding of your solution. The Fatoora Portal User Manual walks through the portal screens and links to the API documentation.
3. Generate your keys and certificate request in your system, following ZATCA's specification.
4. Get the compliance credentials from ZATCA and run the compliance checks. You send sample invoices of each type you issue.
5. Fix every validation error until the samples pass.
6. Request production credentials and switch your system from simulation to production.
7. Go live and monitor the first days of real invoices closely.

Use the non-production environments first. The Developer Portal Manual describes the sandbox, the SDK and the validator. The Fatoora Portal manual lists the simulation and production endpoints. Check the current version of both documents, as the manuals we reviewed are dated 2022 and 2023.

Who has to integrate and by when?

Phase 2 rolls out in waves based on VAT-subject revenue. ZATCA says it announces waves gradually and notifies each business directly, at least six months before the integration date.

We could not open a ZATCA page for Wave 25 when we wrote this. The Wave 25 details come from secondary reporting that agrees across several sources. It says Wave 25 was announced on 24 July 2026 and is the first wave to use 2025 revenue. One year above the line is enough.

Your own notification from ZATCA is the thing that counts. Check it, and check your Fatoora portal account, before you plan around any date in a blog.

What should your developer check before go-live?

Most failed integrations fail on data, not on the API call. Run through this list with whoever owns your billing system.

• Seller and buyer data. Your VAT number, address and the customer's VAT number must be complete. A Riyadh buyer with a missing VAT number on a B2B invoice will cause a rejection.
• Invoice types. List every type you issue: tax invoice, simplified invoice, credit note, debit note. Each needs testing.
• Tax calculations. Rounding and line-level VAT must match the totals. Small differences get flagged by the validator.
• Sequence and hash chain. Invoices must follow in order. A deleted or skipped invoice number is a problem to design around, not to hide.
• Failure handling. What does your system do when ZATCA returns an error, or does not answer? It needs a queue, a retry and a clear message to the user.
• Storage. Keep the XML and ZATCA's response with each invoice. Check ZATCA's retention rules.
• Multiple devices. If you issue from several tills, branches or warehouses, each one needs its own registration.
• Credentials. Keep keys and certificates out of source code. Plan for renewal.

Penalties for non-compliance exist. We did not verify the amounts against an official page, so check ZATCA directly rather than trusting a figure you see on a blog.

Build it yourself, use your vendor, or hire a developer?

It depends on who owns your billing code.

If you need custom work, Quickship's software development service builds integrations on quote. We are a technology company, so we write and test software. We do not issue invoices for you or act as your tax agent. A good first step is a short scoping call with the ZATCA documents and your invoice samples on the table.

Common mistakes to avoid

• Starting after the wave deadline, when the compliance tests need weeks of fixes.
• Testing only one invoice type, then finding credit notes fail on go-live day.
• Treating clearance like reporting, and not blocking the buyer copy until ZATCA responds.
• Hard-coding values from an old version of the specification.
• Forgetting branches, tills or second billing systems.
• Leaving the cutover to a Thursday evening before a weekend.

If your date is 1 February 2027, work back from it. Allow time for onboarding, test fixes and a quiet week of monitoring.