Software Development Kit (SDK) : User Manual
Software Development Kit (SDK) : User Manual
(SDK)
User Manual
Table of Contents
1 General Information ........................................................................................................... 3
1.1 Introduction .................................................................................................................. 3
1.1.1 Objectives ............................................................................................................... 3
1.1.2 Purpose and Scope ................................................................................................. 3
1.1.3 Intended Audience ................................................................................................. 4
2 SDK Capabilities ................................................................................................................... 4
2.1 General Description and High Level User Journey ...................................................... 4
2.2 Prerequisites ................................................................................................................ 6
3 Description of the Compliance and Enablement Toolbox SDK ....................................... 7
3.1 Access and Download the Compliance and Enablement Toolbox SDK .................... 7
3.1.1 Summary ................................................................................................................. 7
Option 1: Access and Download from the ZATCA Website ................................................ 7
3.1.2.1 Detailed Description ........................................................................................... 7
3.1.3.1 Process Flow........................................................................................................ 7
Option 2: Access and Download from Developer Portal .................................................. 10
3.1.2.2 Detailed Description ......................................................................................... 10
3.1.3.2 Process Flow...................................................................................................... 10
3.1.4 Technical Aspects ................................................................................................. 11
3.2 Using the Command Line Interface (CLI) and Validating XMLs and the QR Code . 14
3.2.1 Summary ............................................................................................................... 14
3.2.2 Detailed Description ............................................................................................ 14
3.2.3 Process Flow ......................................................................................................... 15
3.2.4 Technical Aspect .................................................................................................. 15
4 Additional Information and Considerations ................................................................... 20
5 FAQs ................................................................................................................................... 21
5.1 Business FAQs................................................................................................................... 21
5.2 Technical FAQs ................................................................................................................. 22
6 Appendix ........................................................................................................................... 23
6.1 Glossary.................................................................................................................... 23
6.2 E-Invoice Specifications.......................................................................................... 23
1 General Information
1.1 Introduction
This User Manual contains the essential information required for the user to make full use
of the Compliance and Enablement Toolbox SDK, that will be available through the ZATCA
website and through ZATCA's Developer Portal at a later date. This manual includes a
description of the SDK functions, capabilities and contingencies, as well as a step-by-step
process for the SDK download and use.
The User Manual begins by setting out the objectives, purpose, scope and the intended
users of the manual, followed by a general description of the SDK and a high-level user
journey. A detailed description of the main functionalities of the SDK is provided with the
aim of taking users through all steps required for using the SDK, including how to access it,
download it and integrate it with the taxpayer / developer system in order to validate a test
XML standard or simplified invoice and validate a test QR code. Finally, this User Manual
concludes with additional information and a range of FAQs for addressing any potential
queries.
1.1.1 Objectives
This User Manual aims to provide the reader with a clear understanding of the SDK and its
functionalities from a user perspective. The intended users of this User Manual are the
developers of e-invoice generation solutions, developers representing taxpayers or
taxpayers; and this manual enables them to learn how to use the SDK, including how to
access it, download it and integrate it with the taxpayer / developer system in order to
validate a test XML standard or simplified invoice and validate a test QR code.
2 SDK Capabilities
2.1 General Description and High Level User Journey
The Compliance and Enablement Toolbox SDK is provided by ZATCA to taxpayers and
developers of taxpayer e-invoicing solutions and devices in order to allow them to check
the compliance of their e-invoice, credit and debit note XML files, as well as the respective
QR codes generated, against the e-invoicing standards, specifications and regulations
published by ZATCA, prior to the launch of the Generation and Integration phases. The
Compliance and Enablement Toolbox SDK enables solution developers to integrate it into
their Software Development Life Cycle (SDLC), with the validations performed being in line
with the regulations and requirements published by ZATCA, and that will later be used by
ZATCA to verify e-invoices, either during a tax audit or following the implementation of the
Integration Phase. In order to achieve this, ZATCA will be providing a Compliance and
Enablement Toolbox that comprises of a downloadable SDK that can be integrated with
taxpayer e-invoicing solutions to test the compliance of the e-invoice, credit and debit note
XML files, as well as the respective QR codes.
The Compliance and Enablement Toolbox SDK is a standalone application that will run very
similar validations as the ZATCA e-invoicing solution, and check the field specifications and
business rules expected from a compliant e-invoice, credit or debit note based on ZATCA's
published specifications on individual XML files. It also verifies the invoice hash or hashes
of a short sequence of such invoices. Since the Compliance and Enablement Toolbox SDK
will be standalone, compliance with it does not imply that the XML files have been
acknowledged, accepted or approved by ZATCA.
Based on the user journey displayed in the figure below, taxpayers or developers of
taxpayer e-invoicing solutions will be able to access the SDK through the ZATCA website or
must first register and login to the Developer Portal in order to be able to access and
download the SDK and start using it. Once the users have downloaded the Compliance and
Enablement Toolbox SDK, they can either test the compliance of their XML files and QR
codes via the command line or by integrating the SDK into their solutions.
In case the test is successful, the SDK returns an XML for a compliant e-invoice, credit or
debit note along with a QR code string. The taxpayer can request to have the SDK return an
XML for a compliant e-invoice, credit or debit note with a dummy cryptographic stamp if
they wish (i.e. optional to return the XML signed). In case the test is unsuccessful and
errors have been identified, the SDK returns an XML for a non-compliant e-invoice, credit
or debit note along with the specific error message(s), where the taxpayer/developer can
correct the error(s) identified and re-test the e-invoice, credit or debit note.
A similar process is followed for validating the QR code and the SDK returns successful /
error messages depending on the results of the test.
The Compliance and Enablement Toolbox SDK for the Generation Phase requirements,
allows taxpayers and developers to check the compliance of QR codes generated, against
the e-invoicing standards, specifications and regulations published by ZATCA, with regards
to the Generation Phase requirements. The users will be able to validate the content of
their QR codes generated and in particular compliance with regards to the five fields
required for the 4th of December 2021 (Generation Phase) being available and which are:
• Seller's Name
• VAT registration number of the seller
• Timestamp of the electronic invoice or credit/debit note (date and time)
• Electronic invoice or credit/debit note total (with VAT)
• VAT total
The users will be able to check the respective file and its compliance against Generation
Phase requirements for the QR code, where the SDK returns successful / error messages
depending on the results of the test. The CLI SDK is used to validate a Base 64 encoded
string or XML files as described below in section 3.2.4.
The Compliance and Enablement Toolbox SDK for the Integration Phase requirements,
allows taxpayers and developers of taxpayer e-invoicing solutions and devices to check the
compliance of their e-invoice, credit and debit note XML files, as well as the respective QR
codes generated, against the e-invoicing standards, specifications and regulations
published by ZATCA, with regards to the Integration Phase requirements. The Integration
Phase includes in the QR code four additional fields. Utilizing the CLI is the same process as
before.
Following the download of the Compliance and Enablement Toolbox SDK, it can then be
used to validate the XML files in line with ZATCA's published specifications and standards
in the following sequence:
It should also be noted that this will allow taxpayers and developers to check the
compliance of QR codes generated, against the e-invoicing standards, specifications and
regulations published by ZATCA, with regards to the Integration Phase requirements. The
users will be able to validate the content of their QR codes generated and in particular
compliance with regards to the nine fields required for the Integration Phase, which are:
• Seller's Name
• VAT registration number of the seller
• Timestamp of the electronic invoice or credit/debit note (date and time)
• Electronic invoice or credit/debit note total (with VAT)
• VAT amount
• Hash of XML electronic invoice or credit/debit note
• Cryptographic stamp
• The public key used to generate the Cryptographic stamp
• In the case of simplified tax invoices and their associated notes, the Authority’s
Portal Cryptographic stamp of the public key of the E-Invoice Solution
2.2 Prerequisites
2.2.1 Targeted users
Both the DLL and JAR are cross-platform and can run on any platform. The Java SDK (JAR)
will run on JDK versions >=11 and <15, to comply with secp256k1 as per ZATCA security
regulations.
This section details the process of downloading the Compliance and Enablement Toolbox
SDK from ZATCA Website to test the compliance of the e-invoice, credit and debit note XML
files, as well as the respective QR codes.
In the Systems Developers page the Taxpayer / Developer can view the following
functionalities: E-Invoice Specifications, Security Requirements and Compliance and
Enablement Toolbox.
• Taxpayer / Developer needs to click on "I accept the above terms and conditions"
• Afterwards, the "Download SDK" button will be activated and become available for
the user to click on
• The Taxpayer / Developer then clicks on "Download SDK" in order to download it
• In addition, the Taxpayer / Developer can click on "Download User Manual" to
download and view the User Manual for the SDK
Through the same screen, the Taxpayer / Developer can click on "Supporting Documents"
whereby they can click to download the following:
• "Download ByLaw"
• "Download Resolution"
Option 2: Access and Download from Developer Portal
This section details the process of downloading the Compliance and Enablement Toolbox
SDK that can be integrated with Taxpayer e-invoicing solutions to test the compliance of
the e-invoice, credit and debit note XML files, as well as the respective QR codes. Taxpayers
/ Developers will be able to access the Compliance and Enablement Toolbox SDK page
through the Developer Portal and view the different functionalities being available, such as
to download the Compliance and Enablement Toolbox SDK, view the SDK supporting
documentations and access the version history of the SDK published periodically
(Bitbucket). Taxpayers / Developers will also be able to access and download the
Compliance and Enablement Toolbox SDK through the ZATCA website.
The process for accessing and downloading the Compliance and Enablement Toolbox SDK
through the Developer Portal is as follows:
• The Taxpayer / Developer should be registered and logged into the Developer
Portal successfully
• Taxpayer / Developer should click on "Compliance and Enablement Toolbox SDK
Page" to view the SDK functionalities.
After the user has accessed the Compliance and Enablement Toolbox SDK Page, the user can
view the SDK documentation, which includes aspects such as how to use the SDK and how
it works, as well as the minimum software requirements and the instructions of relevance
to the each Operating System / environment. In addition, the user can download the SDK,
use the command line interface (CLI) and view the version history via Bitbucket.
In order to download the SDK to begin testing XML files and the QR code, the process is as
follows:
The DLL is a .NET tool that is used to assist developers with their compliance process. As
for the JAR, it will be used for cross-platform purposes. The CLI is a command line interface
that uses the SDK to help developers from this form of interface. As mentioned above, after
accepting the terms and conditions, the user is able to download the SDK as a DLL or JAR
file.
Minimum requirements for the SDK
The SDK components are lightweight, meaning almost any machine can run them. In
essence, if taxpayers / developers machine can run Java Version >=11 and <15, then it can
run the JAR SDK. The same applies to .NET, if the machine can run the latest .NET
Framework requirements then it can run the DLL SDK.
The skills required to run the SDK are two elements. The first is an understanding of the E-
Invoicing functionality. From validating an XML in terms of structure to its fields (for
example: VAT Number must be 15 characters or Seller Name is required). The other skills
required are basic computer skills such as excel, so a relatively competent computer user
would be able to run and use the SDK. Previous experience in CLI is helpful, otherwise
there is a small learning curve.
However, to use the validation library inside a solution, taxpayers / developers should have
intermediate knowledge of Java or .NET programming experience.
• Unzip the JAR file you have downloaded from the developer portal
• Open the Apps folder
• Right-click Install
The Command Line Interface (CLI) could be used by taxpayers / developers instead of
integrating with the Compliance and Enablement Toolbox SDK. It can allow them to test the
compliance of their XML files but does not require integration with the SDK.
3.2.3 Process Flow
The process below indicates how a taxpayer / developer can use the CLI instead of
integration with the SDK:
• Taxpayer / developer accesses the "Compliance and Enablement SDK Page" on the
Developer Portal
• Taxpayer / developer clicks on "Download SDK"
• Taxpayer / developer accepts the terms and conditions
• Following the above, the taxpayer / developer can download the SDK in JAR or DLL
The below are the functionalities of the SDK that are used from the CLI.
• To display (Version)
o fatoorah –v
• For help
o fatoorah –h
• CLI Information
o fatoorah –info
• To validate the XML invoice, credit or debit note for compliance with ZATCA
specifications and standards:
o fatoorah validatexml -f (invoicename.xml)
• Validate Stamp Certificate:
o fatoorah validatexml -f (Invoicename.xml) -s "new Certificate Path +
certificate Name"
• Validate previous hash
o fatoorah validatexml -f (NewInvoicename.xml) -p (Old Invoicename.xml)
• Validate QR code:
o fatoorah validateqr -qr
(XXY_QR_CODE_AS_BASE64_ENCODED_STRING_HERE)
• Generate Hash:
o fatoorah generatehash -f Invoicename.xml
• Generate Signature:
o fatoorah generate -f (Invoicename.xml) -x
• Generate QR code:
o fatoorah generate -f (Invoicename.xml) -q
Screenshots
• To display (Version)
o fatoorah –v
• For help
o fatoorah –h
• CLI Information
o fatoorah –info
There is a section in the XML (a tag) called invoicetypecode and it can be set to the
following:
• 01 : standard - 02 : simplified
• 383 : debit
• 381 : credit
• 388: tax
fatoorah validatexml -f (invoicename.xml)
• Success Example
• Fail Example 1
• Fail Example 2
Stamp Certificate, Previous Hash
Note:
• Generate Signature:
o fatoorah generate -x -f (Invoicename.xml)
Generate QR Code
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
• What are the QR fields that will be validated in the Integration phase?
o The users will be able to validate the following fields:
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. Cryptographic stamp
8. The public key used to generate the Cryptographic stamp
9. In the case of simplified tax invoices and their associated notes, the
Authority’s Portal Cryptographic stamp of the public key of the E-Invoice
Solution
Please refer to the E-Invoice specifications link below, for accessing the Electronic Invoice
data dictionary in addition to the electronic invoice xml implementation standard