E-Invoicing for Saudi Arabia API References

Introduction

In Saudi Arabia, the e-invoicing mandate is a key part of the government's push to modernize the VAT system. The Zakat, Tax and Customs Authority (ZATCA) initiated the e-invoicing system, named "Fatoorah," in phases, starting in December 2021. The first phase required businesses to generate, store, and process electronic invoices and related credit and debit notes, although no specific format was mandated initially. However, the second phase, which began on January 1, 2023, introduced mandatory integration for certain businesses with ZATCA’s Fatoora portal using API for validation and approval of invoices, marking the start of the Continuous Transaction Controls (CTC) system. This phased approach is based on revenue size, with various waves affecting taxpayers with different turnover thresholds.

Here are key points about the e-invoicing process in Saudi Arabia:

Phase 1 (December 2021 onwards): All resident taxpayers were required to issue and store electronic invoices and related notes, though there were no strict format requirements.
Phase 2 (January 2023 onwards): Integration with ZATCA’s Fatoora API became mandatory for certain taxpayers, ensuring real-time verification and approval of B2B, B2C, and B2G transactions. This phase is part of the broader Continuous Transaction Controls (CTC) system.
Revenue-based Rollout: Implementation is happening in waves, with businesses required to join based on their annual turnover. Waves started with businesses over SAR 3 billion in turnover and will gradually include those with turnover as low as SAR 2.5 million by December 2024.
Technical Compliance: To comply, businesses must use authorized e-invoicing solutions that integrate with the Fatoora platform and meet the technical specifications laid out by ZATCA.

Common Structs

1. Onboarding Devices `devices[]`

This is an array of devices to be onboarded, including their localtion and organisational informations. One of such device should have below mentioned data points:

Name
device_name
Type
string
Description
The unique name of the device intended for onboarding.

Name
city
Type
string
Description
The city where the device will be placed at.

Name
city_subdiv
Type
string
Description
The specific district or subdivision within the city.

Name
street
Type
string
Description
The street address that represents the device's location.

Name
branch_name
Type
string
Description
The name of the branch or entity where the device is linked. NOTE: If you're onboarding a Group-VAT Member, this should contain a 10-digit TIN of the member.

Name
branch_industry
Type
string
Description
The industry category to which the branch belongs

Name
otp
Type
string
Description
The 6 Digit OTP obtained from Fatoora Portal.

Name
postal
Type
string
Description
The 5 digit postal zone or ZIP code associated with the device.

Name
plot
Type
string (optional)
Description
A 4 digit plot identifier for the device's plot or land.

Name
building
Type
string (optional)
Description
A 4 digit building number where the device's located.

2. Party Details `party_details`

This contains comprehensive information about the customer to whom the invoice is being issued, including their name, contact details, billing address, and other relevant particulars.

Name
party_name_en
Type
string (optional)
Description
The name of customer in English.

Name
party_name_ar
Type
string
Description
The name of customer in Arabic.

Name
party_vat
Type
string
Description
The Value Added Tax (VAT) Registration number for the customer.

Name
city_en
Type
string (optional)
Description
The name of customer in English.

Name
city_ar
Type
string
Description
The name of customer in Arabic.

Name
city_subdivision_en
Type
string (optional)
Description
The name of customer in English.

Name
city_subdivision_ar
Type
string
Description
The name of customer in Arabic.

Name
street_en
Type
string (optional)
Description
The name of customer in English.

Name
street_ar
Type
string
Description
The name of customer in Arabic.

Name
postal
Type
string
Description
The 5 digit postal zone or ZIP code associated with the customer's location.

Name
plot
Type
string (optional)
Description
The 4 digit plot identification number associated with the customer's location.

Name
building
Type
string (optional)
Description
The 4 digit building number associated with the customer's location.

Name
party_add_id
Type
key:value (optional)
Description
Party Additional ID is a key value optional tag that can be provided if you want or asked by the authority in special cases. IDs allowed include: tin, crn, mom, mls, sag, nat, gcc, iqa, oth or 700.

3. Line Items `lineitems[]`

This is an array of items inclduded in an invoice. One of such item should have below mentioned data points:

Name
name_en
Type
string (optional)
Description
The name of item in English.

Name
name_ar
Type
string
Description
The name of item in Arabic.

Name
quantity
Type
float
Description
The quantity of items included in Invoice.

Name
tax_exclusive_price
Type
float
Description
Tax Exclusive price of the item.

Name
tax_percentage
Type
float
Description
Percentage in decimal. (15% to be given as 0.15)

Name
tax_category
Type
string
Description
Specify the category of this item belongs to. It could be S, E & O.

Name
tax_reason_code
Type
string (optional)
Description
If your item is having a specific reason code as specified by ZATCA, it should be provided here.

Name
tax_reason_text
Type
string (optional)
Description
Such products with reason code, should have their reason text here.

Name
discounts
Type
array[] (optional)
Description
The discount item should contain two key values, amount and reason.

4. Advance Details `advance_details`

Details related to advance amount received against this particulat Final Invoice.

Name
advance_amount
Type
float
Description
Advance amount paid against this invoice.

Name
total_amount
Type
float
Description
Total Amount of this final invoice.

Name
advance_invoices
Type
array :advance_invoices[]
Description
The quantity of items included in Invoice.

5. Advance Invoices `advance_invoices[]`

Details related to advance invoices issued against this particulat Final Invoice. This should be categorised based on Tax Category.

Name
tax_category
Type
string
Description
Tax Category which the Invoice Items belongs to. It could be S, E or O.

Name
tax_percentage
Type
float
Description
Percentage in decimal. (15% to be given as 0.15)

Name
taxable_amount
Type
float
Description
Total Taxable Amount in those such Invoices

Name
tax_amount
Type
float
Description
Tax Amount in those such Invoices.

Name
invoices
Type
array[]
Description
It need to be the invoice identification details in an array. It should have details like: id, issue_date and issue_time.

6. Related Document Details `notes_details`

In case of Debit/Credit note, i.e when doc_type is "381" or "383", details about the invoice related to this note can be specified.

Name
related_doc_reference
Type
string
Description
ID of the Document it realtes to.

Name
reason_text
Type
string
Description
Text explaining the reason why the note is being generated.

POST/egs/onboard

Onboard New EGS Device

This endpoint allows you to onboard multiple EInvoicing Generation Solution (EGS) to Fatoora Portal. In this step, we will be generating a Compliance CSID (CCSID) in order to request for a Production CSID (PCSID) from ZATCA.

Request Body

Name
vat_name
Type
string
Description
Official VAT Registered Name of the Entity
Name
vat_number
Type
string
Description
15 Digit VAT Registration number, which starts and ends with 3.
Name
devices
Type
devices[]
Description
Details of each devices to be onboarded. Struct: devices[]

Sample Request

POST

/egs/onboard

curl --url https://sandbox-api.flick.network/egs/onboard \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{"vat_name": "Test Co.",
    "vat_number": "300000000000003",
    "devices": [
      {
        "device_name": "TestEGS1",
        "city": "Riyadh",
        "city_subdiv": "Test Dist.",
        "street": "Test St.",
        "plot": "1234",
        "building": "1234",
        "postal": "12345",
        "branch_name": "Riyad Branch 1",
        "branch_industry": "Retail",
        "otp": "123321"
      },
      {
        "device_name": "TestEGS2",
        "city": "Riyadh",
        "city_subdiv": "Test Dist.",
        "street": "Test St.",
        "plot": "1234",
        "building": "1234",
        "postal": "12345",
        "branch_name": "Riyad Branch 2",
        "branch_industry": "Retail",
        "otp": "321123"
      }
    ]
  }'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "response": {
      [
        {
          "uuid": "f902f9aa-3d25-4bf2-90c5-6ec4bbc122df",
          "device_name": "TestEGS1",
          "compliance_certificate": "-----BEGIN CERTIFICATE-----\nMIICRT
          ---
          2mx9I+et/byhTsH\n-----END CERTIFICATE-----"
        },
        {
          "uuid": "5cd9c201-1960-4bdd-9741-88a124c6a63b",
          "device_name": "TestEGS2",
          "compliance_certificate": "-----BEGIN CERTIFICATE-----\nMIICRT
          ---
          2mx9I+et/byhTsH\n-----END CERTIFICATE-----"
        },
      ]
    }
  }
}

GET/egs/compliance-check/${egs_uuid}

Complete Compliance Check

This get endpoint allows the onboarded EGS to do its Compliance Checks. Every EGS should undergo this compliance check in order to get the Production CSID from ZATCA. We use the previously generated Compliance CSID for the same.

Required Parameters

Name
egs_uuid
Type
string
Description
Unique identifier (UUID) for the EGS we have onboarded above.

Sample Request

GET

/egs/compliance-check/${egs_uuid}

curl 
  --url https://sandbox-api.flick.network/egs/compliance-check/{egs_uuid} \
  --header 'x-flick-auth-key: {token}'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "response": {
        {
          "uuid": "f902f9aa-3d25-4bf2-90c5-6ec4bbc122df",
          "device_name": "TestEGS1",
          "production_certificate": "-----BEGIN CERTIFICATE-----\nMIIFFTCCBLqgAwIBAgITGQAAE0B6Q1
          ---
          jxMYAEr29G\n-----END CERTIFICATE-----"
        }
    }
  }
}

POST/sa/einvoice/generate

Generate E-Invoice

To Generate a new E-Invoice, this endpoint can be used along with the EGS UUID to which it belongs to. Give your onboarded EGS UUID in header to ensure its reported under that specific device.

Request Body

Name
invoice_ref_number
Type
string
Description
Unique Invoice Reference Number. This should be made in sequence.
Name
issue_date
Type
date: YYYY-MM-DD
Description
Date on which the invoice was issued.
Name
issue_time
Type
time: HH-MM-ss
Description
Time at which the invoice was issued.
Name
doc_type
Type
string | 388 or 386 or 381 or 383
Description
Document Type to be specified. 388 is of Invoice, 386 for Advance Invoice, 381 for Credit Note and 383 for Debit Note.
Name
inv_type
Type
string | standard or simplified
Description
Type of Invoice. It could be either standard for B2B Invoices or simplified for B2C Invoices.
Name
currency
Type
string (Optional)
Description
Currency in which Invoice was issued. Default value: SAR.
Name
currency_exchange_rate
Type
float (Optional)
Description
If currency is other than SAR, then exchange rate for tax amount should be specified.
Name
party_details
Type
strcut: party_details
Description
Details of customers to which this Invoice is being issued to.
Name
delivery_details
Type
key:value (optional)
Description
Delivery Details regarding the Invoice. There are two keys to be given in YYYY-MM-DD formats. Those are actual_delivery and latest_delivery.
Name
has_advance
Type
boolean (optional)
Description
Whether this final invoice has an advance or not. Its available for doc_type 388.
Name
advance_details
Type
struct: advance_details (optional)
Description
Details about the advance invoices related to this final invoice.
Name
notes_details
Type
struct: notes_details (optional)
Description
In case of Debit/Credit note, i.e when doc_type is "381" or "383", details about the invoice related to this note can be specified.
Name
lineitems
Type
strcut: lineitems[]
Description
Details of line items in the invoice. At least one item is mandatory in an Invoice. Please refer struct: lineitems for detailed documentation.

Sample Request

POST

/sa/einvoice/generate

curl --url https://sandbox-api.flick.network/sa/einvoice/generate \
  --header 'x-flick-auth-key: {token}' \
  --header 'egs-uuid: {egs_uuid}' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "invoice_ref_number":"INV-4",
      "issue_date": "2024-02-01",
      "issue_time": "01:40:40",
      "doc_type": "388",
      "currency":"USD",
      "currency_exchange_rate": 3.75,
      "inv_type": "standard",
      "party_details" :{
        "party_name_ar": "شركة اختبار",
        "party_name_en": "Test Company",
        "party_vat": "301121921500003",
        "party_add_id": {
          "crn": "4123123431"
        },
        "city_ar": "جدة",
        "city_en": "Jeddah",
        "city_subdivision_ar": "البلد",
        "city_subdivision_en": "Al-Balad",
        "street_ar": "شارع فهد",
        "street_en": "Fahad St.",
        "building": "1234",
        "postal_zone": "12345"
      },
      "delivery_details": {
        "actual_delivery": "2024-01-01",
        "latest_delivery": "2024-01-31"
      },
      "has_advance": true,
      "advance_details": {
        "advance_amount": 575,
        "total_amount": 2875,
        "advance_invoices": [
          {
            "tax_category": "S",
            "tax_percentage": 0.15,
            "taxable_amount": 500,
            "tax_amount": 75,
            "invoices": [
              {
                "id": "ADV-INV-1",
                "issue_date": "2023-12-05",
                "issue_time": "12:34:23"
              }
            ]
          }
        ]
      },
      "lineitems": [
        {
        "name_en": "Laptop",
        "name_ar": "حاسوب محمول",
        "quantity": 1,
        "tax_category": "S",
        "tax_exclusive_price": 1750,
        "tax_percentage": 0.15
        },
        {
        "name_en": "Iphone",
        "name_ar": "ايفون",
        "quantity": 1,
        "tax_category": "S",
        "tax_exclusive_price": 750,
        "tax_percentage": 0.15
        }
      ]
    }'

Sample Response

200

Success

    {
    "status": "success",
    "message":{ 
      "invoice_hash": "3t5RAKudTQJGwZaqX7U2YIPaYYa9NOK1DWZSZRuDgx8=",
      "qr": "ARlBbCBTYWRoYW4gVHJhZGluZyBDb21w...."
    }
  }

POST/sa/einvoice/report

Report B2C E-Invoice

To Generate a new E-Invoice, this endpoint can be used along with the EGS UUID to which it belongs to.

Request Body

Name
invoice_ref_number
Type
string
Description
Unique Invoice Reference Number. This should be made in sequence.
Name
issue_date
Type
date: YYYY-MM-DD
Description
Date on which the invoice was issued.
Name
issue_time
Type
time: HH-MM-ss
Description
Time at which the invoice was issued.
Name
doc_type
Type
string | 388 or 386 or 381 or 383
Description
Document Type to be specified. 388 is of Invoice, 386 for Advance Invoice, 381 for Credit Note and 383 for Debit Note.
Name
inv_type
Type
string | standard or simplified
Description
Type of Invoice. It could be either standard for B2B Invoices or simplified for B2C Invoices.
Name
currency
Type
string (Optional)
Description
Currency in which Invoice was issued. Default value: SAR.
Name
currency_exchange_rate
Type
float (Optional)
Description
If currency is other than SAR, then exchange rate for tax amount should be specified.
Name
has_advance
Type
boolean (optional)
Description
Whether this final invoice has an advance or not. Its available for doc_type 388.
Name
advance_details
Type
struct: advance_details (optional)
Description
Details about the advance invoices related to this final invoice.
Name
lineitems
Type
strcut: lineitems[]
Description
Details of line items in the invoice. At least one item is mandatory in an Invoice. Please refer struct: lineitems for detailed documentation.

Sample Request

POST

/sa/einvoice/report

curl --url https://sandbox-api.flick.network/sa/einvoice/report \
  --header 'x-flick-auth-key: {token}' \
  --header 'egs-uuid: {egs_uuid}' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "invoice_ref_number":"INV-2",
      "issue_date": "2023-01-01",
      "issue_time": "01:40:40",
      "doc_type": "388",
      "inv_type": "simplified",
      "currency":"SAR",
      "lineitems": [
        {
        "name_en": "Laptop",
        "name_ar": "كمبيوتر محمول",
        "quantity": 1,
        "tax_category": "S",
        "tax_exclusive_price": 1750,
        "tax_percentage": 0.15
        }
      ]
    }'

Sample Response

200

Success

    {
  "status": "success",
  "data": {
    "uuid": "9d27f792-8c7a-4cc5-a123-4b11f70e4c51",
    "invoice_hash": "7BJPdjjvppWGYBzqd0pt4qWUWjN7l03sisQzuRxkKlk=",
    "qr_code": "AStNdXRhYmFxYW5pIE1lZGljYWwgU2VydmljZXMgQ29tcGFueSBMaW1pdGVkAg8zMDAwNTY0NTY3MDAwMDMDEzIwMjMtMDEtMDFUMDE6NDA6NDAEA05hTgUEMC4wMAYsN0JKUGRqanZwcFdHWUJ6cWQwcHQ0cVdVV2pON2wwM3Npc1F6dVJ4a0tsaz0HYE1FUUNJSHJSQWIzaUxPZXJBWjlpdkxlYW5ObCs3WS9GU0JsY2FaaUY2MWt3WUNCakFpQUN0MDZMNFhmRUJGWEFwdjViTVpZN3h0cnpRU0V6V3FzbWMwWVlKSS8wcGc9PQhYMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE6TVSj2rfiqqAaOmOWnm3uTjgDfi+w9rkXwuL0a6MFJK/0ahVmwFE8Za8xzKIq5aozQgfBmLJGSFhxbr/ONPiBQlHMEUCIQDnBfT2MKrpj4mkXNc/MfaPeSZxkz03vCAfj3NcPEFTDwIgEx9x6FbhkSkXFwFP92vZBW9BFtmK1onZoe6N6xysZ1Y="
  }
}

POST/sa/einvoice/generate/phase-one-qr

Generate Phase One QR Code

This endpoint is used to generate Phase One QR Code as Specified in E-Fatoora Guidelines. You can generating it by providing 5 mandatory TLVs [6 datapoints].

Request Body

Name
seller_vat
Type
string
Description
VAT Number of the Issuer of Invoice
Name
seller_name
Type
string
Description
Seller name in Arabic
Name
issue_date
Type
date: YYYY-MM-DD
Description
Date on which the invoice is being issued.
Name
issue_time
Type
time: HH-MM-ss
Description
Time at which the invoice is being issued.
Name
invoice_total
Type
number
Description
Total of invoice including any taxes and deducting any allowances.
Name
tax_total
Type
number
Description
Total of tax includede in the invoice_total above.

Sample Request

POST

/sa/einvoice/generate/phase-one-qr

curl --url https://sandbox-api.flick.network/sa/einvoice/generate/phase-one-qr \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "seller_vat":"300000000000033",
      "seller_name": "شركة اختبار",
      "issue_date": "2024-02-01",
      "issue_time": "01:40:40",
      "invoice_total": 1200,
      "tax_total": 200
    }'

Sample Response

200

Success

   {
    "status": "success",
    "data": {
      "seller_vat": "300000000000033",
      "invoice_total": 1200,
      "qr_code": "AQzYs9in2K/Yrdin2YYCDzMwMDAwMDAwMDAwMDAzMwMUMjAyNC0wMi0wMVQwMTo0MDo0MFoEBDEyMDAFAzIwMA=="
    }
  }

E-Invoicing for Saudi Arabia API References

Introduction

Common Structs

1. Onboarding Devices devices[]

2. Party Details party_details

3. Line Items lineitems[]

4. Advance Details advance_details

5. Advance Invoices advance_invoices[]

6. Related Document Details notes_details

Onboard New EGS Device

Request Body

Sample Request

Sample Response

Complete Compliance Check

Required Parameters

Sample Request

Sample Response

Generate E-Invoice

Request Body

Sample Request

Sample Response

Report B2C E-Invoice

Request Body

Sample Request

Sample Response

Generate Phase One QR Code

Request Body

Sample Request

Sample Response

1. Onboarding Devices `devices[]`

2. Party Details `party_details`

3. Line Items `lineitems[]`

4. Advance Details `advance_details`

5. Advance Invoices `advance_invoices[]`

6. Related Document Details `notes_details`