E-Invoicing API Overview: The Fatoora Platform APIs

If you are a developer building an integration with the Fatoora platform, you are dealing with a set of APIs that handle signing invoices, clearing them, and reporting them to the Zakat, Tax and Customs Authority (ZATCA). This page is your starting point: a complete overview of the entire API layer before you dive into the details of each individual API. The goal is to leave it knowing what the four APIs are, how they sequence across your journey from the test environment to production, and where an accounting system like Qoyod fits into this ecosystem.

Here we take the practical angle: how you call the APIs, which Headers you need, and what the request and response look like. As for the full technical reference for the API specifications, you will find it on the Fatoora platform API integration page, which focuses on the specification (Spec) angle. This page complements it and focuses on day-to-day usage and practical recipes.

Read this page as a general map first. Then move on to the page dedicated to the step you are actually working on, whether that is authentication, endpoints, the Clearance API, the Reporting API, or setting up the simulation environment. Each of these pages details what this page summarizes, so there is no duplicated work and no skipping over an important step.

What is the e-invoicing API?

E-invoicing in Saudi Arabia went through two phases. The first phase (the Generation phase) became mandatory on 4 December 2021 and required issuing invoices through an electronic system in a structured format, instead of paper invoices and PDF files copied from editing software. The second phase (the Integration phase) started on 1 January 2023 in waves based on the establishment’s revenue size, and it is the phase that introduced direct integration with the Fatoora platform via APIs.

In the second phase, it was no longer enough to issue an electronic invoice locally. Your system now has to communicate with the Fatoora platform to clear business (B2B) invoices in real time, and to report consumer (B2C) invoices within 24 hours. Every invoice must carry a Cryptographic Stamp, a unique identifier (UUID), a Hash of the previous invoice to guarantee the integrity of the chain, and a QR code. The API is the bridge that carries out this dialogue between your system and the Fatoora platform.

The core idea you must grasp before anything else: the Fatoora platform does not merely receive your invoice, it validates it structurally and cryptographically, then returns the result of that validation to you. That is why the integration is not just sending data, but a dialogue of at least two steps for every invoice: you send, it is reviewed, then it is cleared or rejected with the reason stated. Building a sound integration means handling this dialogue in full, not just its first half.

This understanding leads to an important practical conclusion. Your system is not complete the moment it succeeds in sending its first invoice, but when it knows how to read the response and act on it in every case. An invoice may be accepted, accepted with warnings, or rejected for an error in a single field. A professional developer’s integration is the one that covers these three paths from day one, not the one that settles for the happy path and then gets surprised in production.

In practice, the API layer consists of four main APIs: the Compliance API, the Onboarding / Production CSID API, the Clearance API, and the Reporting API. These APIs work together to cover the developer’s journey from the first test request to the first cleared invoice in production. We will go through each one briefly on this page, then point to the page that details it.

Base URL and environments

The Fatoora platform runs on two completely separate environments. The simulation environment (Sandbox / Simulation) for development and testing with no real tax effect, and the Production environment for actual invoices with legal value. Each environment has an independent base URL, an independent certificate, and independent keys. The golden rule: never mix the two environments, and always start from the simulation environment.

The reason for the complete separation between the two environments is simple but decisive. A cleared invoice in production has a real tax effect that cannot be easily reversed, whereas an invoice in simulation is merely a test. Mixing production credentials with code that is still under development can generate unintended real invoices. That is why seasoned developers make sure to isolate the two environments at the level of settings, keys, and code all at once.

The base URL takes the following form, followed by the version path and then the specific API path:

https://gw-fatoora.zatca.gov.sa/e-invoicing/{environment}/{resource}

# environment = simulation | core (production)
# resource    = compliance
#             | production/csids
#             | invoices/clearance/single
#             | invoices/reporting/single

The actual value of the URLs may change between versions and environments, so always read the Authority’s official documentation before hard-coding any URL. Do not place production URLs directly in your code; make them Environment Variables that can be switched between simulation and production in a single line. This pattern protects you from deployment errors and makes it easy to test the integration in automated pipelines (CI/CD) without touching production keys.

An overview of the simulation environment

The simulation environment mimics the behavior of production without issuing invoices that have legal value. You use it to try out invoice scenarios, validate XML files, and test error handling before it costs you in production. Build all your cases here first: a standard tax invoice, a simplified invoice, a credit note, a debit note, and an invoice with a deliberate error so you can see what a rejection looks like.

The full details of configuring the simulation environment, how to obtain test credentials, and ready-made invoice examples are in the dedicated simulation-environment guide for developers within this section. Consider it the training ground where you master every scenario before you move to production, where there is no room for trial and error.

Map of the URL structure and environments

Before we move on to the four APIs, fix in your mind the shape of the URL and how its parts relate to one another. The following diagram summarizes how the base URL is built from a fixed root, then an environment path that specifies simulation or production, then an API path that specifies the required operation. Grasping this structure makes the rest of the page clearer, because every API we mention is nothing more than a different value in the last part of the path.

The four Fatoora platform APIs

The API layer is divided into four APIs, each with a specific role in the invoice lifecycle. Understanding this division is the most important step before writing any code, because it determines the order in which you call the APIs. The order is not optional: do not reach Clearance or Reporting before you have passed Compliance and obtained the production certificate.

1. Compliance API

This is the first API you deal with. Its job is to verify that your system is capable of producing invoices that comply with the second-phase specifications before it is allowed into production. You send it samples of invoices (a tax invoice, a simplified invoice, a credit note, a debit note), and it validates the XML structure, the Cryptographic Stamp, and the QR code. By passing this stage you obtain the Compliance CSID, which paves the way for obtaining the production certificate.

Think of the Compliance API as a quality gate. The Authority will not allow you to clear a single invoice in production unless your system proves that it produces invoices that are structurally and cryptographically sound. So dedicate enough time to this stage, and fix every error you uncover before you proceed.

2. Onboarding / Production CSID API

After passing Compliance, you request that this API issue the production Cryptographic Stamp Identifier (Production CSID). Note the correct acronym: CSID, not CCSI. This certificate is the one you use to sign your actual invoices in production, and it is tied to your establishment and its tax registration number. To go deeper into what the certificate is and its role, see the CSID certificate: the Cryptographic Stamp Identifier in the electronic invoice.

Obtaining the production certificate requires an activation code (OTP) from the Fatoora portal, which links your request to the registered establishment. This step is what turns your system from a tested system into a system certified for actual issuance. Store the production certificate and its secret key in a secure secrets store, as it is effectively your establishment’s digital signature.

3. Clearance API

This concerns standard tax business (B2B) invoices. You send the invoice to the Fatoora platform, which clears it (performs clearance on it) in real time and returns it signed by the Authority, and the invoice is not delivered to the buyer until it has been cleared. In other words, clearance is a precondition for delivery, not a step that follows it. For details on the clearance mechanism and its effect on the invoice cycle, see the Clearance in the electronic invoice.

4. Reporting API

This concerns simplified consumer (B2C) invoices. Here the invoice is issued and delivered to the buyer immediately, then reported to the Fatoora platform within 24 hours. The fundamental difference from clearance is that reporting happens after delivery, not before it, because the consumer scenario at the point of sale cannot tolerate waiting for real-time clearance that would hold up the queue.

This distinction between clearance and reporting is the heart of the second phase’s design. A business invoice can tolerate a moment of waiting in exchange for guaranteed prior clearance, whereas a consumer invoice requires speed of delivery with deferred reporting. Design your integration so that it distinguishes between the two paths automatically based on the invoice type, not manually.

The details of both the Clearance and Reporting APIs (the precise paths, response codes, and the rejection and acceptance-with-warnings cases) are explained on the pages dedicated to each API within this section, and in the full technical reference on the Fatoora platform API integration.

Map of the four APIs and the role of each

The following diagram brings the four APIs together in a single picture that shows the role of each API and its place in the invoice journey. Notice how the Compliance API paves the way for the Onboarding API, then the path splits into two branches based on the invoice type: Clearance for business invoices and Reporting for consumer invoices. This mental image is what separates an orderly integration from one that confuses the two paths.

The authentication model in brief

Every request to the Fatoora platform must carry proof of your system’s identity and authorization. Authentication relies on the Cryptographic Stamp certificate (CSID) and its secret key, where the credentials are passed via the Authorization header in Basic Auth style after Base64 encoding. Added to that are headers that specify the content type, the response language, the API version, and the required clearance status.

This is a simplified example of what the headers look like in an invoice-clearance request via the Clearance API:

POST /e-invoicing/simulation/invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic {base64(binarySecurityToken:secret)}
Content-Type: application/json
Accept: application/json
Accept-Language: en
Accept-Version: V2
Clearance-Status: 1

The value binarySecurityToken is derived from the CSID certificate, and the value secret is the secret key that accompanies it. The header Clearance-Status with a value of 1 means you are requesting actual clearance, not just validation. As for the header Accept-Language , it specifies the language of the validation messages in the response.

This is an overview only. The details of building the header, how to derive binarySecurityToken from the CSID certificate, and the difference between authentication in the simulation and production environments, are fully explained on the dedicated Authentication page within this section. Do not copy the keys directly into the code; store them in environment variables or a secrets store, and avoid recording them in the system Logs.

API Versioning via Accept-Version

The Fatoora platform manages the versions of its APIs via the Accept-Version header. With it you specify which version of the API you are addressing, and this protects you from an update to the API breaking your existing integration. The common value in the second phase is V2.

Accept-Version: V2

Make the version value a configurable variable in your code rather than a fixed value scattered across every request. This way you move to a newer version with a single change when the Authority announces a new version, and you avoid compatibility surprises. Pinning the version explicitly is a general engineering principle when integrating with any external API, and here it is mandatory because the API may evolve as the requirements of e-invoicing evolve.

Watch the Authority’s announcements of new versions, and test the transition to them in the simulation environment before enabling it in production. A new version may add mandatory fields or change validation behavior, so do not assume full compatibility without testing.

Request / Response structure

The Fatoora platform APIs exchange data in JSON format in the request envelope, while the invoice itself is embedded as XML encoded in Base64 inside the payload. That is, you send the invoice (UBL 2.1) encoded, alongside its Hash and its unique identifier (UUID). This wrapping allows a complete XML file to be transported inside a single JSON field without losing any character.

This is a simplified example of a request body for clearing an invoice via the Clearance API:

{
  "invoiceHash": "NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZj...",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}

The field invoiceHash is the invoice Hash, anduuid its unique identifier, andinvoice a complete XML file encoded in Base64. On successful clearance, the response comes back with the clearance status and the cleared invoice signed by the Authority, along with any warnings if present:

{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...",
  "validationResults": {
    "infoMessages": [
      { "type": "INFO", "code": "XSD_ZATCA_VALID",
        "message": "Complied with UBL 2.1 standards in line with specifications" }
    ],
    "warningMessages": [],
    "errorMessages": [],
    "status": "PASS"
  }
}

The field clearanceStatus tells you the result, andclearedInvoice carries the invoice signed by the Authority (which is the one you deliver to the buyer), andvalidationResults details the validation messages divided into information, warnings, and errors. Store the cleared invoice as it came back, because it is the version with legal value, not the version you sent.

These are illustrative examples of the general structure only. The actual values, the complete list of Validation Codes, and the differences between clearance and reporting responses are on the pages dedicated to endpoints and to each API individually, and in the technical reference on the Fatoora platform API integration.

Status codes and error handling

The Fatoora platform responds with standard HTTP status codes. The code 200 means full acceptance, and the code 202 means acceptance with warnings that you must handle before they escalate, while codes in the 400 range indicate a rejection due to an error in the invoice structure or the headers, and the 401 range indicates an authentication problem.

The practical rule: do not settle for reading the status code; always read the validationResults object. The code 202 means the invoice was cleared but there are warnings (warningMessages) that may turn into blocking errors in a later update from the Authority. Handle the warnings in the simulation environment before you move to production, because today’s warning may become tomorrow’s rejection.

A sound error-handling structure separates three levels: information messages (you only log them), warnings (you flag them and handle them), and errors (they prevent delivery and require correcting the invoice and resending it). Read each level from validationResults and deal with it separately. Also add retry logic for transient network errors, with a reasonable timeout, so that invoice issuance is not disrupted at the first temporary stumble.

Clearance vs. Reporting: when to use each?

The question that most confuses developers at the start of the integration: which API do I call for this invoice? The answer depends on the invoice type, not on your preference. A standard tax business invoice (B2B), where the buyer is an establishment registered for VAT, goes through the Clearance API and is cleared before delivery. A simplified consumer invoice (B2C), where the buyer is an individual, goes through the Reporting API and is delivered immediately, then reported within 24 hours.

The difference is not cosmetic; it is reflected in the user experience within your system. In the business scenario, the customer can tolerate a short moment of waiting in exchange for the guarantee that the invoice is officially cleared before it reaches them. In the point-of-sale scenario, however, it is unreasonable for the customer to wait in the queue until clearance completes, so the invoice is delivered immediately and reporting is deferred. Design your system so that it reads the invoice type and routes it automatically to the correct path, because an error here means either disrupting the point of sale or sending a business invoice without prior clearance.

Also pay attention to notes. A credit note and a debit note follow the same path as the original invoice: a note on a business invoice goes through Clearance, and a note on a consumer invoice goes through Reporting. Linking the note to its original invoice via the appropriate fields is part of the integrity of the integration, not a secondary detail.

The developer’s journey: from simulation to production

The four APIs sequence in a clear journey. You start by developing on the simulation environment, then you pass Compliance, then you issue the production certificate, then you begin actual clearance and reporting. These are the steps in order:

1. Set up the simulation environment and obtain the test credentials.
2. Produce invoice samples in XML format compliant with the second phase.
3. Call the Compliance API to validate your invoices and obtain the compliance certificate.
4. Request the production certificate (Production CSID) from the Onboarding API.
5. Clear business (B2B) invoices via the Clearance API in real time.
6. Report consumer (B2C) invoices via the Reporting API within 24 hours.
7. Monitor the status codes and validation results, and handle any warnings as they arise.

Each of these steps has a dedicated page within the Developer Center section that explains its details: authentication, endpoints, the Clearance API, the Reporting API, and the simulation-environment guide. Start from this page as a map, then move to the page that concerns the step you are working on.

The common mistake developers make is jumping to production before mastering simulation. Every minute you spend testing scenarios on simulation saves you hours of tracing errors in production, where every invoice is real and has a tax effect. Treat simulation exactly like production in the rigor of testing, and exempt it only in the absence of legal effect.

There are practices that make your integration more robust over the long term. Log every request and response in a log you can refer back to when auditing, without logging the secret keys. Keep a copy of the invoice signed as it came back from the Authority, not as you sent it. Monitor the validity of the CSID certificate and renew it before it expires so that issuance does not stop suddenly. And finally, test failure scenarios, not just success: what happens when the network drops in the middle of clearance? How does your system behave if the response comes back with an authentication error? A mature integration is the one that knows how to recover from errors, not the one that assumes they will never occur.

Step-by-step map of the developer’s journey

The final diagram arranges the seven steps in a single timeline that shows the transition from the simulation environment to production. Consider it a visual checklist you return to whenever you want to know where you are in the journey, and what the next step is that you must master before you move forward.

Where does Qoyod fit in the API layer?

If you are building your integration yourself, these four APIs are your daily world. But if you are an establishment owner who does not want to build all of this, then an accounting system like Qoyod handles the entire layer on your behalf. Qoyod signs every invoice with the Cryptographic Stamp, backs it with a UUID, keeps the Hash chain, performs real-time clearance for business invoices, reports consumer invoices within 24 hours, and manages the CSID certificate automatically.

This way you get full compliance with the second phase of e-invoicing without writing a single API request. All the dialogue we explained on this page (the headers, the encoding, the clearance, the reporting, the handling of warnings) happens behind the scenes with no intervention from you. You create the invoice as usual, and Qoyod takes care of the rest.

Your operational responsibility remains within your scope, not the accounting system’s: registering the establishment on the Fatoora platform, and filing the tax return and paying the tax through the Authority’s portal, as these are steps the establishment owner handles. As for the technical side of signing, clearance, and reporting, Qoyod takes care of it. This division matters: technical integration is one thing, and the establishment’s tax obligations are another that remain its responsibility.

For a broader picture of e-invoicing and its requirements, see the Electronic invoicing from Qoyod page, and for the full technical reference for the Fatoora platform APIs, see Fatoora platform API integration. From these two pages you move to the sub-pages for each API according to the step you are working on.