Learn E-Invoicing KSA API Basics

General
What are e-invoicing enforcement dates?
​E-invoicing will be implemented in two phases: 
Phase One, known as the Generation phase, is enforceable as of December 4, 2021.
Phase Two, known as the Integration phase, is enforceable starting from January 1, 2023 and implemented in waves by targeted taxpayer groups. Taxpayers will be notified by ZATCA on the date of their integration at least 6 months in advance.
What are the requirements for each phase?
The requirement phasing is summarized in the “How to get ready” section below. 
For additional details, please check the simplified guideline​​ https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-Invoicing_Detailed__Guideline.pdf
Some requirements are technical, how can I prepare for e-invoicing?
The technical requirements are typically implemented by solution providers (e.g. cash register vendors, software vendors) or the internal technical teams for in-house built solutions. Taxpayers may approach a solution provider or their internal technical teams to acquire or upgrade to a compliant electronic system; and ensure they are generating compliant invoices starting from December 4th, 2021.​
Is e-invoicing mandatory? 
E-invoicing applies to all persons subject to VAT and any other parties issuing tax invoices on behalf of suppliers subject to VAT. 
Non-resident taxable persons for VAT purposes are excluded.​​ 
Phase 1
How will my invoicing practices change starting from December 4, 2021?
All persons subject to the E-Invoicing Regulation must use compliant electronic systems to generate invoices starting from December 4th, 2021. Manual invoices will no longer be considered compliant invoices.
E-invoices must include the minimum additional fields (see next question).
E-invoicing compliant electronic systems should be able to generate QR codes.
E-invoicing compliant electronic systems must not allow for the prohibited functions specified by ZATCA.
Please approach your solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA’s website for viewing all requirements (business, technical, security, etc.).
What does an e-invoice look like and how is it different from current invoices?
E-invoices for Phase 1 (4 December 2021) are similar to current invoices, with minimum additional fields: 
For simplified tax invoices and their associated notes (usually issued for B2C transactions) a mandatory QR code. 
For tax invoices and their associated notes (usually issued for B2B transactions), an optional QR code and mandatory VAT number of the buyer if the buyer is a registered VAT taxpayer.
There is no specific file format mandated for Phase 1, however, invoices must include the mandatory fields and be issued from an electronic system meeting ZATCA’s requirements. In addition, electronic copies of all issued invoices must be stored by the taxpayer.​​
Does my invoicing system need to be constantly connected to the internet for Phase One (December 4, 2021)? 
Yes, the system or solution used for generating and storing the invoices must be able to have internet connectivity for both phases.​​
Do I need to integrate my invoicing system/solution with ZATCA on December 4, 2021?
No, integration with ZATCA is not required for Phase One starting December 4, 2021.​​
Does my solution need to be able to generate QR codes on invoices on December 4, 2021? 
Yes, QR codes are mandatory for simplified tax invoices (usually issued for B2C transactions) and optionally for tax invoices (usually issued for B2B transactions). QR code is not provided by ZATCA and shall be generated by the electronic system. Please approach your solution provider or technical teams to acquire or upgrade to a compliant electronic system.​​
What are the minimum requirements that must be shown after scanning a QR Code?
As part of Phase 1 (Generation Phase), the below fields are the minimum required fields that must be shown after scanning a QR code in a simplified tax invoice: 
1.Seller’s name 
2.VAT registration number of the seller 
3.Timestamp of the Electronic Invoice or Credit/Debit Note (date and time) 
4.Electronic Invoice or Credit/Debit Note total (with VAT) 
5.VAT total​
Do my e-invoices need to be approved by ZATCA before sharing them with the buyer or reported to ZATCA after issuing them? 
No, for Phase 1 (December 4, 2021), taxpayers are not required to approve, clear, or report invoices to ZATCA.​​
What are some of the prohibited functionalities for Phase 1 (Generation Phase) that are not allowed to be part of the E-invoicing system? 
Lack of user management capabilities (uncontrolled access) for example: 
Anonymous Access 
Absence of user session management 
Tampering with e-invoices or their associated notes or logs 
Multiple Electronic Invoice sequences 
For additional details on the prohibited functionalities, please refer to Annex (1) “Technical Requirements of E-invoice Generation Solutions” in the resolution.​
What should taxpayers do if they are unable to issue e-invoices due to any incidents, technical errors, or emergency matters? 
Taxpayers should take steps to ensure their E-Invoicing solutions are properly functioning at all times (e.g. battery back-up). 
However, if despite taking necessary steps the taxpayer faces incidents, technical errors, or emergency matters which hinder the generation of electronic invoices or electronic notes, the taxpayer must: 
Communicate immediately with their solution provider and technical teams to resolve the issue, and keep evidence of their communication (e.g. e-mail).
Notify ZATCA immediately of the failure through this link. https://zatca.gov.sa/en/E-Invoicing/FailureNotifications/Pages/VerifyTaxpayer.aspx
Upon resolution of the issue, the taxpayer shall notify ZATCA via the above link and resume the generation of e-invoices for all transactions conducted during the interruption period​​.
Should taxpayers always notify ZATCA if one of their solutions fails or only if they are not able to generate e-invoices due to failure? 
Taxpayers should notify ZATCA only of incidents in which they are no longer able to generate e-invoices. A taxpayer with multiple E-Invoicing solutions is not required to notify ZATCA of the failure of a single solution in case they are still able to generate e-invoices using another e-invoicing solution.​
What should taxpayers do during the interruption period? 
After notifying ZATCA, taxpayers may continue to conduct business during solution failure to their customers. Any invoices or notes related to transactions conducted during the solution failure must be generated electronically promptly as soon as the failure incident is resolved​.
What is Phase 1? When will it be enforced and to whom does it apply? 
Phase 1 known as the Generation phase will require taxpayers to generate and store compliant tax invoices and notes using compliant electronic systems. 
Phase 1 is enforceable as of December 4th, 2021 for all Persons subject to the E-Invoicing Regulation. 
Phase 2 
How do I know about my Phase 2 wave? 
The enforcement date for the first target group will not be earlier than January 1, 2023. And ZATCA will notify taxpayers of their Phase 2 wave at least six months in advance​.​
What are the requirements for Phase 2? 
Phase 2, which will be implemented in waves by target taxpayer groups starting from Jan 1st, 2023, entails additional technical requirements that e-invoicing electronic systems must comply with, the integration of taxpayer electronic systems with ZATCA, and the issuance of electronic invoices in a specific format.
Due to the technical nature of the published requirements, it is recommended for taxpayers to approach a solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA's website for viewing all requirements (business, technical, security, etc.).Further details on the integration mechanisms and specifications will be published by ZATCA on the developer page on ZATCA's website.
What are some of the prohibited functionalities that are not allowed to be part of the E-invoicing system related to Phase 2? 
All prohibited functionalities that are part of Phase 1 
Export of stamping key 
Time change 
For additional details on the prohibited functionalities, please refer to Annex (1) “Technical Requirements of E-invoice Generation Solutions” in the resolution​​.​​
What are the e-invoicing changes that will be implemented starting from January 1, 2023, for enforced taxpayers? 
Please refer to the e-invoicing simplified guideline​ for information about the integration wave. https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing_Simplified%20GL.pdf
Can a taxpayer use the same e-invoicing solution that was used for the generation phase (Phase one)? 
A taxpayer can use the same e-invoicing solution that was used for Phase 1, by updating the e-invoicing solution to comply with the Phase 2 requirements.​
Should a taxpayer continue following Phase 1 requirements until Phase 2 applies to them? 
Yes, a taxpayer should continue following Phase 1 requirements until the integration enforcement date of the taxpayer’s wave, in which the taxpayer is required to start following Phase 2 requirements.​
If a taxpayer is complaint with Phase 1 requirements and was not yet notified by ZATCA to integrate, is the taxpayer required to implement Phase 2 requirements? 
The taxpayer is not required to implement Phase 2 requirements until notified by ZATCA about the integration enforcement date of the taxpayer’s wave, in which the taxpayer is required to start following Phase 2 requirements. ​
How can a taxpayer integrate their e-invoicing solution with ZATCA’s systems? 
Taxpayer accesses FATOORA portal​ (https://fatoora.zatca.gov.sa/) using Taxpayer Portal credentials (ERAD), Then follow the EGS onboarding process and for more details please refer to the Fatoora portal user manual​. https://zatca.gov.sa/ar/E-Invoicing/Introduction/Guidelines/Documents/Fatoora_Portal_User_Manual.pdf
How can a taxpayer verify that their e-invoicing solution has been successfully integrated? 
After successful onboarding of each EGS, the taxpayer will be notified indicating whether the e-invoicing solution has been successfully integrated. Also, taxpayers can use the FATOORA Portal​ in order to view a summary list of all their integrated e-invoicing solutions.​
What is Phase 2? When will it be enforced and to whom does it apply? 
Phase 2, known as the Integration phase, where subjective taxpayers must comply with Phase 2 business and technical requirements for the electronic invoices and electronic solutions, and the integration with ZATCA's system. 
Phase 2 is enforceable starting from January 1, 2023, and implemented in waves by targeted taxpayer groups. Taxpayers will be notified by ZATCA on the date of their integration at least 6 months in advance.​ 
Others 
Should my electronic system be certified by ZATCA or a 3rd party for Phase 1? 
No, ZATCA may enforce such requirements in the future.​
When to issue a simplified e-invoice (or note) vs a standard e-invoice (or note)? 
Please refer to the “Invoicing and records guideline” section 4.1.2 here​​ https://zatca.gov.sa/en/HelpCenter/guidelines/Documents/Invoicing%20and%20Records.pdf 
Please also note that e-invoices are not required for the following transactions: 
Exempt supplies 
Import of goods​ 
Supplies subject to reverse charge mechanism​
Are VAT individual taxpayers subject to issuing e-invoices? ​
Yes, however, Non-resident taxable persons for VAT purposes are excluded.​​
Is it necessary to use a cloud invoicing system in order to be compliant with the E-invoicing regulation? 
No, Persons subject to the E-Invoicing Regulation may use any invoicing system, provided that it complies with the requirements of the Authority.
For how long do I need to store the electronic invoices? 
Is there a specific period? The period for storing/keeping invoices does not differ from the period specified according to the statutory requirements in the Implementing Regulations of the Value-Added Tax Law.​​
Is there any data residency or Datacenter legal requirement? 
Yes, in accordance with article 66 in the Implementing Regulations of the Value-Added Tax Law. In case a cloud e-invoicing solution or a cloud data center located outside the kingdom is used, an extension or access to data must be available in the branch that is located in the kingdom, and it should allow access to all related records. Additionally, non-tax-related regulations may apply to the taxpayer entity, such as National Cybersecurity Authority and/or National Data Management Office published laws and any other applicable regulations or controls.​​
Do I have to issue an electronic invoice if I received an advanced payment from my client? Or a receipt voucher can be sufficient? 
Receiving an advance payment should result in the issuance of an electronic invoice and not only a receipt voucher, as per Para (1) of Article 53 of VAT Implementing Regulations.​​
How do I share the invoice with the client or buyer? 
Persons subject to the E-Invoicing Regulation must provide a copy of the tax invoice or its related credit/debit note that is electronically generated with the clients.
A printed copy of the simplified tax invoice or its related credit/debit note must be provided to the clients/buyers, however, and based on mutual agreement between the seller and client/buyer, the invoice can be shared electronically or through any other way where the client/buyer can read it.​
After issuing and sharing an electronic invoice with the client or buyer, can modify or cancel the invoice if it contained any errors? 
No, based on the VAT regulation, after issuing an invoice, it is prohibited to modify or cancel the invoice. and according to the regulation, debit/credit notes must be generated to modify or cancel the generated invoice. Therefore the supplier should issue an electron credit/debit note linked to the original modified invoice.​​
A given company deals with individuals and companies, which tax invoice type should the company issue? Moreover, can the company use the same invoicing system to generate the invoices? 
The generated tax invoice type depends on the transaction type. For transactions between a company and an individual, a simplified tax invoice must be generated. On the other hand, if the transaction is between two companies, a tax invoice usually will be generated based on the value of the supply. And the same invoicing system can be used to issue both types of tax invoices provided that it covered the requirements for each tax invoice.​​
If a VAT-registered Saudi Company issues an invoice to a non-resident foreign company, what is the e-invoice generation mechanism? 
For exports, an electronic invoice must be generated in accordance with the E-invoicing Regulation. 
For imports, it is not subject to the E-invoicing Regulation.
After the implementation of E-invoicing, is there an impact on the tax declaration process? 
No, there is no impact or change on the declaration process​​.
Can a different invoice reference number format be used for government-issued invoices, Riyadh branch invoices, and other branch invoices? 
Yes, according to Paragraph (5/b) of Article 53 of the VAT implementing regulation, an invoice reference number must be visible on the invoice to identify the tax invoice. The regulation does not specify the format of this number. Taxpayers can use different formats for the invoice reference number so long as it uniquely identifies the tax invoice.​
It is prohibited to issue multiple invoice sequences for e-invoices and notes, but I have multiple branches across KSA and each branch has its own invoice sequence. Am I required to unify invoice sequences across all my branches? 
The invoice sequence mentioned within the prohibited functions under Paragraph (2/E) of Article 3 in the Controls, Requirements, Technical Specifications, and Procedural Rules for Implementing the Provisions of the E-Invoicing Regulation does not refer to the invoice reference number that identifies the tax invoice.
The invoice sequence mentioned under the prohibited functions refers to the technical ability of the e-invoicing solution to issue invoices using multiple sequence counters.​
How to get ZATCA’s Approval on Special billing arrangements (Self-billing and Third-party billing)? 
To get ZATCA’s approval on Special billing arrangements please follow the link and complete the application. https://s2c.gazt.gov.sa/A/705d6b48
ZATCA will review and notify the Taxpayer of the results.
What are some examples of e-invoicing systems? 
Online cash registers, virtual cash registers on tablets, e-invoicing software installed on a computer, e-invoicing software installed on a phone or tablet and cloud-based solutions are examples of e-invoicing solutions. 
Such electronic systems must comply with the specifications published by ZATCA. 
Please approach your solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA’s website for viewing all requirements (business, technical, security, etc.).​
Technical 
What is a QR code?
A QR code is a coded representation of readable text. In the context of e-invoicing, the QR code should contain specific information in a specific format.
What are the QR code fields that will be validated in the Integration phase starting from 1 January 2023 onwards? 
1.Seller's Name 
2.VAT registration number of the seller 
3.Timestamp of the electronic invoice or credit/debit note (date and time) 
4.Electronic invoice or credit/debit note total (with VAT) 
5.VAT amount 
6.Hash of XML electronic invoice or credit/debit note 
7.Elliptic Curve Digital Signature Algorithm (ECDSA) signature 
8.ECDSA public key. The public key BLOB format contains only the public portion of an ECDSA key used to generate the Cryptographic Stamp. The length of the public key BLOB for a 256-bit key is 64 bytes (72 bytes including magic number and field length information on some systems). 
9.For Simplified Tax Invoices and their associated notes, the ECDSA signature of the cryptographic stamp’s public key by ZATCA’s technical CA is required.
An ECDSA signature is encoded according to IEEE P1363. This signature format encodes the (r, s) tuple as the concatenation of the big-endian representation of r and the big-endian representation of s. Each of these values is encoded using the number of bytes required to encode the maximum integer value in the key's mathematical field. For example, an ECDSA signature from 256-bit elliptic curves (like secp256k1) encodes each of r and s as 32 bytes, and produces a signature output of 64 bytes. Please find below an example.
public static byte[] extractR(String digitalSignature) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(Base64.getDecoder().decode(digitalSignature.getBytes(StandardCharsets.UTF_8)));
return Arrays.copyOfRange(hash, 0, 32);
}
​
/** 
* Extract S Component 
*
* @return 
* @throws Exception 
*/ 
public static byte[] extractS(String digitalSignature) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(Base64.getDecoder().decode(digitalSignature.getBytes(StandardCharsets.UTF_8)));
return Arrays.copyOfRange(hash, 32, 64); 
}
How can the users access information contained in the QR code? 
In the context of e-invoicing, users should scan the QR code on e-invoices, debit notes, and credit notes by using the ZATCA VAT app. This app is available on the Google Playstore and iOS App Store free of charge.
What can I do if an XML has an error(s)? 
If an XML has error(s), specific error message(s) will be displayed. Error(s) are likely to occur in cases such as when a mandatory field is missing or a value is in an incorrect format. The user may require the assistance of a technical expert to solve the error(s).
What is a Cryptographic Stamp Identifier (CSID)? 
The CSID is technically a cryptographic certificate, which is a credential that allows for authenticated signing and encryption of communication. The certificate is also known as a public key certificate or an identity certificate. It is an electronic document used as proof of ownership of a public key.
The CSID is used to uniquely identify an Invoice Generation Solution Unit in possession of a taxpayer for the purpose of stamping (technically cryptographically signing) Simplified Invoices and for accessing the Reporting and Clearance APIs using TLS authentication.
Can I use the same Cryptographic Stamp Identifier (CSID) for any invoice submission? 
Yes. As long as the VAT Registration number on the CSID matches the VAT Registration Number on the documents. In other words, for every VAT Registration Number being tested across any API call, a CSID with the same VAT Registration Number is required. Note that the VAT Registration number can be any dummy number that meets the syntax specifications (15 digits, starting with 3 and ending with 3).

E-Invoicing KSA API - Previous

Introduction to E-Invoicing KSA API

How to get E-Invoicing KSA Auth Token?

Last modified 2mo ago

Copy link

Outline

General

What are e-invoicing enforcement dates?

What are the requirements for each phase?

Some requirements are technical, how can I prepare for e-invoicing?

Is e-invoicing mandatory?

Phase 1

How will my invoicing practices change starting from December 4, 2021?

What does an e-invoice look like and how is it different from current invoices?

Does my invoicing system need to be constantly connected to the internet for Phase One (December 4, 2021)?

Do I need to integrate my invoicing system/solution with ZATCA on December 4, 2021?

Does my solution need to be able to generate QR codes on invoices on December 4, 2021?

What are the minimum requirements that must be shown after scanning a QR Code?

Do my e-invoices need to be approved by ZATCA before sharing them with the buyer or reported to ZATCA after issuing them?

What are some of the prohibited functionalities for Phase 1 (Generation Phase) that are not allowed to be part of the E-invoicing system?

What should taxpayers do if they are unable to issue e-invoices due to any incidents, technical errors, or emergency matters?

Should taxpayers always notify ZATCA if one of their solutions fails or only if they are not able to generate e-invoices due to failure?

What should taxpayers do during the interruption period?

What is Phase 1? When will it be enforced and to whom does it apply?

Phase 2

How do I know about my Phase 2 wave?

What are the requirements for Phase 2?

What are some of the prohibited functionalities that are not allowed to be part of the E-invoicing system related to Phase 2?

What are the e-invoicing changes that will be implemented starting from January 1, 2023, for enforced taxpayers?

Can a taxpayer use the same e-invoicing solution that was used for the generation phase (Phase one)?

Should a taxpayer continue following Phase 1 requirements until Phase 2 applies to them?

If a taxpayer is complaint with Phase 1 requirements and was not yet notified by ZATCA to integrate, is the taxpayer required to implement Phase 2 requirements?

How can a taxpayer integrate their e-invoicing solution with ZATCA’s systems?

How can a taxpayer verify that their e-invoicing solution has been successfully integrated?

What is Phase 2? When will it be enforced and to whom does it apply?

Others

Should my electronic system be certified by ZATCA or a 3rd party for Phase 1?

When to issue a simplified e-invoice (or note) vs a standard e-invoice (or note)?

Are VAT individual taxpayers subject to issuing e-invoices?

Is it necessary to use a cloud invoicing system in order to be compliant with the E-invoicing regulation?

For how long do I need to store the electronic invoices?

Is there any data residency or Datacenter legal requirement?

Do I have to issue an electronic invoice if I received an advanced payment from my client? Or a receipt voucher can be sufficient?

How do I share the invoice with the client or buyer?

After issuing and sharing an electronic invoice with the client or buyer, can modify or cancel the invoice if it contained any errors?

A given company deals with individuals and companies, which tax invoice type should the company issue? Moreover, can the company use the same invoicing system to generate the invoices?

If a VAT-registered Saudi Company issues an invoice to a non-resident foreign company, what is the e-invoice generation mechanism?

After the implementation of E-invoicing, is there an impact on the tax declaration process?

Can a different invoice reference number format be used for government-issued invoices, Riyadh branch invoices, and other branch invoices?

It is prohibited to issue multiple invoice sequences for e-invoices and notes, but I have multiple branches across KSA and each branch has its own invoice sequence. Am I required to unify invoice sequences across all my branches?

How to get ZATCA’s Approval on Special billing arrangements (Self-billing and Third-party billing)?

What are some examples of e-invoicing systems?

Technical

What is a QR code?

What are the QR code fields that will be validated in the Integration phase starting from 1 January 2023 onwards?

How can the users access information contained in the QR code?

What can I do if an XML has an error(s)?

What is a Cryptographic Stamp Identifier (CSID)?

Can I use the same Cryptographic Stamp Identifier (CSID) for any invoice submission?