FATOORA

‫فــاتورة‬

User Manual
Developer Portal Manual
Version 3

Nov 2022

1
Contents

1. General Information 05

1.1 Introduction 05

1.1.1 Objectives 05

1.1.2 Scope 06

1.1.3 Intended Audience 07

1.1.4 Recommended Reading 07

2. Developer Portal Overview 08

2.1 Pre-requisites 08

2.2 Structure / Sitemap 09

2.3 User Journeys 10

2.3.1 Accessing the Developer Portal 11

2.3.2 Creating a Developer Portal Account 12

2.3.3 Accessing the Compliance and Enablement Toolbox SDK Page 14

2.3.4 Downloading the SDK 16

2.3.5 Using the SDK (outside of the Developer Portal) 17

2.3.6 Accessing the Compliance and Enablement Toolbox Portal Based Validator 17

2
2.3.7 Using the Compliance and Enablement Toolbox Portal Based Validator 19

2.3.8 Accessing the Integration Sandbox Page 21

2.3.9 Accessing the API and associated Documentation (Swagger Files) 23

2.3.10 Step by step guide to make a successful call to APIs 24

2.3.11 API Summary 62

2.3.12 Accessing the Developer Portal Support Page 66

3. Security Requirements 68

4 Frequently Asked Questions (FAQs) 69

4.1 Business FAQs 69

4.1.1 Developer Portal Business FAQs 69

4.1.2 SDK Business FAQs 71

4.1.3 Web Based Validator Business FAQs 75

4.1.4 Integration Sandbox Business FAQs 76

4.2 Technical FAQs 80

4.2.1 Developer Portal Technical FAQs 80

4.2.2 SDK Technical FAQs 80

4.2.3 Compliance and Enablement Toolbox Portal Based Validator Technical FAQs 82

4.2.4 Integration Sandbox Technical FAQs 83

5 Appendix 87

3
5.1 Glossary 87

5.2 Developer Portal Security Information 89

5.3 Generate CSR 89

5.3.1 Initiate a CSR configuration file (Open SSL Config. File) 89

5.3.2 Generate public/private key pair 92

4
1. General Information
1.1 Introduction
The Developer Portal is a dedicated portal provided by ZATCA for the developers of E-invoicing Generation
Solutions (EGS). It contains two development tools aimed at supporting developers build compliant EGS
units which are:
● The Compliance and Enablement Toolbox Software Development Kit (SDK): an offline downloadable
tool which can be used to validate an XML based e-invoice, credit or debit note files in accordance
with the ZATCA published requirements, standards and guidelines. It also allows validation of the QR
codes as per the prescribed structure. Developers can integrate their EGS units with the SDK locally
(offline) or also test using a Command Line Interface (CLI).
● Integration Sandbox: a test ZATCA backend system which EGS units can integrate with to make API
calls to simulate and test the Onboarding process followed by the submission of test e-invoices, credit
and debit notes for Reporting and Clearance in accordance with the ZATCA published requirements,
standards and guidelines.
In addition to the above, the Developer Portal has a third tool aimed at intermediate or non-technical users
to validate an XML based e-invoice, credit or debit note files from the portal directly. This is referred to as
the Compliance and Enablement Toolbox Portal Based Validator.
Finally, the Developer Portal has a dedicated support page containing a list of Frequently Asked Questions
(FAQs) to help developers troubleshoot during development and testing of their EGS units as well as
provide guidance on E-invoicing requirements in general.

1.1.1 Objectives
The primary objective of the Developer Portal is to support the Developer community in building EGS units
that are compliant with ZATCA's XML implementation standards as well as the Security Features and
Implementation Standards.

5
● The objective of the SDK is to ensure that XML e-invoices, credit or debit notes being generated by the
EGS units are compliant
● The objective of the Web based validator is to allow less or non-technical users to be able to independently
validate the compliance of XML e-invoices, credit or debit notes and share the results with their developers.
● The objective of the Integration Sandbox is to test the EGS units / solutions / applications are able to
integrate with a test ZATCA backend system via APIs covering the following:
● Submit a test Certificate Signing Request (CSR) to obtain a test Compliance Cryptographic
Stamp Identifier (CCSID) and test Request ID
● Submit a test Request ID to obtain a test Production CSID
● Submit test Standard Documents using the test Clearance API (or using a variant of the test
Reporting API to mimic the process when Clearance is turned off)
● Submit Simplified Documents using the Reporting API

1.1.2 Scope
This user manual acts as a guide for Developers in order to help them access and use the Developer
Portal features and functionalities. It explains in detail the user journey including steps, requirements and
processes needed for accessing the Developer Portal. Moreover, it provides guidance for the relevant
technical aspects and methods to be used to solve common issues that might be faced by the Portal users.
This document covers the following functionalities that are of relevant to the Developer Portal:

● Accessing the Developer Portal

● Website address and browsers supported
● Main dashboard elements

● Registration for the Developer Portal

● Functionalities that require registration
● Authentication and verification process

● Log in to the Developer Portal

● Entering user credentials
● Password reset / Forget Password
● Successful log in

6
● Accessing and downloading the Compliance and Enablement Toolbox SDK
● Understanding of the SDK and how to use it
● Downloading the SDK

● Accessing and using the Web Based Validator

● Understanding of and the use of the Web Based Validator
● Validating XMLs directly on the Web Based Validator

● Accessing and using the Integration Sandbox APIs

● Accessing documentation for the APIs
● Using the APIs to integrate with the test ZATCA backend system
● Test the integration calls for Onboarding, Renewal, Reporting, Clearance

1.1.3 Intended Audience

This document is intended to be used by:
● Solution Developers
● Taxpayers
● Other users of relevance

1.1.4 Recommended Reading

Although not a pre-requisite for accessing and using the Developer Portal functionalities, it is strongly
advised that users go through the following documentation:
1. XML Implementation Standards (E-Invoice XML Implementation Standard)
2. Security Features and Implementation Standards (E-Invoice Security Features and Implementation
Standards)
3. Data Dictionary (E-Invoice Data Dictionary)
4. E-Invoicing Resolution (E-Invoicing Resolution)

7
2. Developer Portal Overview
2.1 Pre-requisites
The Developer Portal itself is a web-based application and can be run from any modern browser such as
Google Chrome, Microsoft Edge or Apple Safari.
The SDK is a Java based JAR file that can run on all leading platforms including Windows, Linux and
Mac. The Java SDK (JAR) will run on JDK versions >=11 and <15, to comply with secp256k1 as per ZATCA
security regulations.
The Integration Sandbox APIs can be accessed from all leading platforms as those mentioned above.
REST APIs can be accessed from any Rest Client tools (Postman) for testing or using any coding languages
(java, .Net, PHP, Nodejs, etc.) to call the rest services using HTTPs Protocol.

8
2.2 Structure / Sitemap
The Developer Portal is comprised of the following:

Developer Portal

Access Portal Based Access Developer Portal

Login
Validator Support Page

Access SDK Page Access Integration Sandbox Page

● Download SDK ● Access API Documentation

● SDK Support (Swagger Files)

Validate XMLs Access FAQs
● SDK Documentation ● Test APIs for Onboarding,

● SDK Version History Renewal, Reporting and Clearance

Outside Developer Portal

Using the SDK Using the Integration Sandbox (APIs)

● Test APIs to obtain Compliance

CSID and Production CSID (as part of

Onboarding process)
● Test compliance of XML
● Test APIs to obtain new Compliance
● Test compliance of QR
CSID and Production CSID (Test the
Code (Generation Phase)
Renewal process)
● Test Compliance of QR
● Test API to submit documents for
Code (Integration Phase)
Reporting

● Test API to submit documents for

Clearance

9
2.3 User Journeys
The recommended steps for Solution Developers are:
1. Read the XML Implementation Standards, Security Features Implementation Standards and Data
Dictionary
2. Access the Developer Portal
3. Create a Developer Portal Account
4. Login to the Developer Portal as a Registered User
5. Access the SDK Page
6. Read the SDK Support and Documentation
7. Download the SDK
8. Test XML compliance using the SDK via CLI / local integration
9. Access the Integration Sandbox Page
10. Go through the API Documentation on Swagger
11. Test the APIs through Swagger
12. Test the APIs via integration
13. Leveraging the Developer Portal Support page FAQs for troubleshooting

The recommended steps for Non-technical users are:

1. Access the Developer Portal
2. Accessing the Compliance and Enablement Toolbox Portal Page
3. Test XML compliance
4. Provide the error messages / responses (if any) to Solution Developers
5. Leveraging the Developer Portal Support page FAQs for troubleshooting

10
2.3.1 Accessing the Developer Portal
The process for accessing the Developer Portal is as follows:
1. Access the Developer Portal through the following weblink (https://sandbox.zatca.gov.sa/).
2. The user is directed to the Developer Portal main dashboard / landing page
1. In this page the user can access the below sections without registration or login:
1. Developer Portal Support Page which includes the FAQs.
2. Web Based Validator for Non-Technical Users.
2. The following sections would require the user to create a Developer Portal account:
1. Compliance and Enablement Toolbox SDK Page.
2. Integration Sandbox Page.

Note: The User can chose to toggle the language between English and Arabic by using the icon on the
top right-hand side of the page.

Developer Portal main landing page

11
2.3.2 Creating a Developer Portal Account
As mentioned above, a Developer Portal account is required for accessing the Compliance and Enable-
ment Toolbox SDK page and the Integration Sandbox page. You can ignore this step if you only wish to
access the Web Based Validator or the Developer Portal Support page.

Once the user is on the main dashboard of the Developer Portal, they can click on the "Sign up" button at
the top right-hand side as seen in the Figure below.

● Email ID
● First Name
● Last Name
● Company Name (optional field)
● Password
● Confirm Password

In the Sign Up page (as seen in the Figure below), the user will be prompted to create a new account by
providing the following details:
The email must be a valid email and the password must be at least 8 characters comprising of at least one
number, one letter each in lower and upper case, and one symbol.
After completing all the necessary fields, the user should click on the CAPTCHA verification followed by
the Sign up button.

12
 Login Page

After the user has signed up and created their account credentials, they can proceed to the Login page
where they will be prompted to:
● Fill in the User Name and Password (as created by the user).
● Click the CAPTCHA.
● In addition, the user can click "Forgot Password"
● In the case where the user does not have an account set up and requires one, the user can click on the
Sign Up option, in order to create a new account and proceed to the process described in this Section
2.3.2 of the User Manual for registration.
● After filling in all the information, the user should click on the Login button in order to proceed to the
main dashboard again where the user will now also be able to access the Compliance and Enable-
ment Toolbox SDK page and the Integration Sandbox page.
● A logged in user can logout at any time by clicking on the logout option on the header. The user can
also change the password at any time by clicking on the arrow next to the user profile icon in header.

13
2.3.3 Accessing the Compliance and Enablement Toolbox SDK Page
The Compliance and Enablement Toolbox (SDK) which is an offline downloadable tool that can be used to
validate an XML based e-invoice, credit or debit note files in accordance with the ZATCA published XML
Implementation Standards. It also allows validation of the QR codes as per the prescribed structure. Developers
can integrate their EGS units with the SDK locally (offline) or also test using a CLI.

The process for accessing and downloading the Compliance and Enablement Toolbox SDK through the
Developer Portal is as follows:
● The user should be registered and logged into the Developer Portal successfully
● The user should click on "Compliance and Enablement Toolbox and SDK" to view the SDK functionalities.

14
 Accessing the Compliance and Enablement Toolbox (SDK)

After the user has accessed the Compliance and Enablement Toolbox SDK Page, the user can:
● Access the SDK support, 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 each Operating System/
environment.
● Access documentation such as the XML Implementation Standards (E-Invoice XML Implementation
Standard), Security Features and Implementation Standards (E-Invoice Security Features and
Implementation Standards) & Data Dictionary (E-Invoice Data Dictionary)
● Download the SDK after accepting the terms and conditions.
● View the version history which contains earlier releases of the SDK.

15
 Accessing the E-Invoicing specification documents

2.3.4 Downloading the SDK

In order to download the SDK, the process is as follows:
● The user clicks on "Download SDK"
● The user has to click on "I accept the above terms and conditions"
● As the above is clicked, the "Download SDK" button will be activated and become available for the user
to click on

downloading the SDK

16
2.3.5 Using the SDK (outside of the Developer Portal)
Please refer to the ZATCA E-Invoice Java SDK (CLI) Manual on the below link by downloading the SDK
and then navigate to readme folder.

https://zatca.gov.sa/ar/E-Invoicing/SystemsDevelopers/ComplianceEnablementToolbox/Pages/Down-
loadSDK.aspx.

2.3.6 Accessing the Web Based Validator for Non-Technical Users

The user can test - using a web portal - the compliance of the XMLs of standard e-invoices, credit or debit notes
generated so that they can know if they are in line with the ZATCA e-invoicing specifications and regulations
or so that they can be alerted to any errors which are causing non-compliance with the ZATCA specifications
and regulations. It is aimed at intermediate or non-technical users to validate XML based e-invoices, credit
or debit note files from the portal directly, i.e. without the need to download the SDK or possess the technical
know-how to run it.
This section details the process of accessing the "Web Based Validator for Non-Technical Users" in order to
test the compliance of the e-invoice, credit and debit note XMLs. Users can access the "Web Based Validator
for Non-Technical Users" Page through the Developer Portal (no prior registration or login is required). On this
page, users can view information related to what the Web Based Validator aims to achieve and the user can
access this and begin uploading the XMLs that they would want to test and validate.

The process for accessing the "Web Based Validator for Non-Technical Users" page is as follows:
● The User accesses the "Web Based Validator for Non-Technical Users" on the Developer Portal (no prior
registration or log in required).

17
 Accessing the web based validator

● On the "Web Based Validator for Non-Technical Users", users can view information related to an
explanation of the Web Based Validator and what it aims to do

● In addition, users can click on "Access the Web Based Validator for taxpayers without a development
environment" in order to begin testing and validating their XMLs.

Web based validator Page

● Once users have chosen to "Access the Web Based Validator for taxpayers without a development
environment", a disclaimer is shown detailing that:

18
The portal validation page is a standalone application and compliance does not necessarily imply the
e-invoices, credit or debit notes have been accepted by ZATCA. All Taxpayer E-invoicing solution unit will
need to pass the testing requirements as part of Registration/Taxpayer Onboarding prior to submitting
e-invoices, credit or debit notes to ZATCA.

● The User has to acknowledge the disclaimer in order to proceed to test their XML files.

Web based validator Disclaimer

2.3.7 Using the Web Based Validator for Non-Technical Users

An XML file can be validated according to its structure (schema), fields, or ZATCA requirements (i.e. The VAT
registration number must be 15 numeric digits). The way this works is that the user submits an XML and the
portal will read it, analyze it, and return the status of the validation.
Note that the Web Based Validator can be used to validate up to 5 XMLs and if more than 1 XML is provided, the
validator also checks for the sequence in terms of Previous Invoice (Document) Hash. Note that for a single
XML the Previous Document Hash check is always considered as valid or True.

19
The process for validating XMLs from the Web Based Validator for Non-Technical Users page is as follows:

Click on “Upload XML file” and choose a file, then click “Validate."

Uploading an XML file on the web based validator

If the XML is compliant, you will receive a “Valid”: true message.

Web based validator - XML validation complete and no errors found

20
If not compliant, the following message is shown.

Web based validator - XML complete and errors found

The non-technical user is expected to share the validation outcomes with the Solution Developer to take
necessary action.

2.3.8 Accessing the Integration Sandbox Page

The Integration Sandbox as covered in this user manual comprises of two components - the Sandbox specific
front-end web pages (which is part of the Developer Portal and access to which requires a Developer Portal
registered user account) and an API based Sandbox backend to integrate with.
A registered and logged in user can access the Integration Sandbox page from the main dashboard while a
non-registered and non-logged in user is taken to the login screen. Once on the Integration Sandbox page
the user is given a high level summary of the current version release of the Sandbox as well as links to any
previous releases.
The ZATCA e-invoicing integration Sandbox is meant to be used for testing purposes only. Any inputs
submitted on the Sandbox are not considered as acknowledged, approved or accepted by ZATCA. Taxpayers
will be required to login using SSO credentials for the Taxation portal (ERAD) prior to officially be able to submit
official documents. Test CSIDs provided by the Sandbox cannot be used in the Core E-invoicing Solution.

21
Developers must also take into account that documents or requests submitted on the Core E-invoicing Solution
will be subjected to additional validations such as security features, prohibited functionalities, additional
business rule validations and/or referential checks based such as validating Seller/Buyer information entered
in the documents, validations based on previously submitted documents.

API Integration sandbox landing page

On the left navigation bar of the page the user is able to access the links to the API documentation which
are maintained as Swagger files (each API call is described in section 2.3.10 below along with the possible
outcomes).

22
2.3.9 Accessing the API and associated Documentation (Swagger Files)
Access to the Swagger files is provided from the Integration Sandbox page. API documentation is provided
covering all the API calls that can be tested on the Sandbox such as:
● Test request for Compliance CSID as part of a new onboarding (requires a signed test CSR to be submitted
- details provided in the Swagger files)
● Test request for Production CSID as part of a new onboarding (requires a test Compliance CSID to be
submitted)

Note: The Core E-invoicing Solution will require specific compliance checks to be completed in between
the Compliance CSID and Production CSID requests and the latter will return an invalid response until these
compliance checks are completed. This invalid response can be tested in the Sandbox by providing a specific
input which is covered in the Swagger files below.
● Test request for a new Production CSID as part of renewal (requires a test Compliance CSID to be sub-
mitted)
● Test submission of documents for Clearance (requires a test Production CSID)
● Test submission of documents for Reporting (requires a test Production CSID)

Although the Sandbox uses test CSIDs, it is important to note that the VAT Registration number used to obtain
the test CSID must match with the VAT Registration number in the Renewal CSR and/or e-invoices, credit
notes, debit notes and QR codes submitted in all subsequent calls made using that specific test CSID. In other
words for every VAT Registration Number that is used in the Sandbox integration, a separate CSID will have
to be requested. Of course the VAT Registration Numbers can be dummy inputs.
● Please refer to the API Documentation through the following LINK.

Note: Please make sure to log-in in order to view the API documentation

23
2.3.10 Step by step guide to make a successful call to APIs

1. For Reporting and Clearance (testing the submission of E-invoices, credit and debit notes)
● The users' E-Invoice Generation Solution (EGS) needs to generate compliant XML documents. For
more details on generating compliant XML documents please refer to the XML Implementation
Standards and the Data Dictionary (E-Invoice specifications (zatca.gov.sa). It is also recommend to
test the compliance using the Compliance and Enablement Toolbox SDK (Download SDK (zatca.
gov.sa) or Portal based validator for non-technical users (Compliance and Enablement Toolbox
portal).
● For Simplified documents (and optionally for Standard documents), the EGS also needs to generate
compliant QR codes. For more details on generating compliant QR codes please refer to the
Security Features and Implementation Standards (E-Invoice Security Features and Implementation
Standards).

24
 ● Note that EGS must obtain a test Cryptographic Stamp Identifier (CSID) first, by using the test
integration calls for Onboarding or Renewal.
2. For Cryptographic Stamp Identifier (testing the Onboarding and Renewal processes).
● The users' EGS needs to generate a compliant CSR to obtain a test CSID. For more details on
generating a compliant CSR and CSID specifications please refer to (E-Invoice Security Features and
Implementation Standards).
● Note that EGS must obtain a test Cryptographic Stamp Identifier (CSID) first, by using the test
integration calls for Onboarding, in order to test the integration call for Renewal which requires a test
CSID to be included in the request.

2.3.10.1 Compliance CSID

● Step 1: Navigate to Developer Portal link
● Step 2: Login with correct credentials
● Step 3: Navigate to API Integration Sandbox

25
 ● Step 4: Click on API documentation guides

● Step 5: Click on Compliance CSID API drop-down

26
 ● Step 6: Click on try it out

● Step 7: Insert valid OTP and fill the request body (CSR)
● Step 8: Click on Execute

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls
(V2 is currently the only valid version).

27
 ● Result (200)

2.3.10.2 Compliance Invoice API

● Step 1: Navigate to Developer Portal link
● Step 2: Login with correct credentials
● Step 3: Navigate to API Integration Sandbox

28
 ● Step 4: Click on API documentation guide

● Step 5: Click on Authorize Compliance Invoice API

Note: This step is to be repeated on the number of invoices to be sent as part of the compliance
checks.

29
● Step 6:

For the Sandbox, use the sample dummy Username and Password provided to you on
the Authorization screen.
For Production, run the Compliance CSID API to obtain the “binarySecurityToken” to be used
as the Username and “secret” as the Password.

Please refer to Chapter 3 of this document for further details.

30
● Step 7: Click on Compliance Invoice API drop-down

31
 ● Step 8: Click on Try it out button

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls
(V2 is currently the only valid version).

32
 ● Step 9: Fill the request body (invoice hash, UUID, encoded XML invoice)
● Step 10: Click on Execute

● Result (200)

33
2.3.10.3 Production CSID (Onboarding) API
● Step 1: Navigate to Developer Portal link
● Step 2: Login with correct credentials
● Step 3: Navigate to API Integration Sandbox

● Step 4: Click on API documentation guide

34
 ● Step 5: Click on Authorize Production CSID (Onboarding) API

35
● Step 6:

For the Sandbox, use the sample dummy Username and Password provided to you on
the Authorization screen.
For Production, run the Compliance CSID API to obtain the “binarySecurityToken” to be used
as the Username and “secret” as the Password.

Please refer to Chapter 3 of this document for further details.

36
● Step 7: Click on Production CSID (Onboarding) API drop-down

● Step 8: Click on Try it now button

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls (V2 is
currently the only valid version).

37
 ● Step 9: Fill the request body (compliance request ID)
● Step 10: Click on Execute button

38
 ● Result (200)

39
2.3.10.4 Production CSID (Renewal) API
● Step 1: Navigate to Developer Portal link
● Step 2: Login with correct credentials
● Step 3: Navigate to API Integration Sandbox

● Step 4: Click on API documentation guide

40
 ● Step 5: Click on Authorize Production CSID (Renewal) API

41
● Step 6:

For the Sandbox, use the sample dummy Username and Password provided to you on
the Authorization screen.
For Production, run the Compliance CSID API to obtain the “binarySecurityToken” to be used
as the Username and “secret” as the Password.

Please refer to Chapter 3 of this document for further details.

42
● Step 7: Click on Production CSID (renewal) API drop-down

● Step 8: Click on Try it now

43
 ● Step 9: Insert valid OTP

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls (V2 is
currently the only valid version).

44
 ● Step 10: Fill the request body (CSR)
● Step 11: Click on Execute button

● Result (200)

45
2.3.10.5 REPORTING
● Step 1: Open CMD and Generate simplified invoice
● Step 2: On SDK, sign the XML invoice and get the hash value using the following:
● fatoora -sign -qr -invoice invoiceName.xml -signedinvoice signedinvoiceName.xml (hash is
returned and signed invoice is generated)
● fatoora -generateHash -invoice invoiceName.xml (optional)
Afterwards, validate the XML invoice.

46
 ● Step 3: Encode the Signed XML invoice using Base 64
● Step 4: Open Developer Portal and choose integration sandbox

47
 ● Step 5: Click on API documentation guides

● Step 6: Click on Authorize Reporting API

48
● Step 7:

For the Sandbox, use the sample dummy Username and Password provided to you on
the Authorization screen.
For Production, run the Compliance CSID API to obtain the “binarySecurityToken” to be used
as the Username and “secret” as the Password.

Please refer to Chapter 3 of this document for further details.

49
 ● Step 8: Click on Reporting API drop-down

● Step 9: Click on try it out

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls (V2 is
currently the only valid version).

50
 ● Step 10: Replace the Invoice hash in xml and encode the xml using Base 64

● Step 11:Fill the request body (invoice hash, UUID, Base 64 encoded XML invoice)

51
 ● Step 12: Execute

52
 ● Result (200)

● Result (400)

53
2.3.10.6 CLEARANCE
● Step 1: Open CMD and Generate standard invoice

● Step 2: On SDK, get the hash value using the following:

- fatoora -generateHash -invoice invoiceName.xml
Afterwards, validate the XML invoice.

● Step 3: Encode the XML invoice using Base 64

54
 ● Step 4: Open Developer Portal and choose integration sandbox

55
 ● Step 5: Click on API documentation guides

● Step 6: Click on Authorize Clearance API

56
● Step 7:

For the Sandbox, use the sample dummy Username and Password provided to you on
the Authorization screen.
For Production, run the Compliance CSID API to obtain the “binarySecurityToken” to be used
as the Username and “secret” as the Password.

Please refer to Chapter 3 of this document for further details.

57
 ● Step 8: Click on Clearance API drop-down

58
 ● Step 9: Click on try it out

Note: V2 refers to the Version of the APIs used and should be mentioned in the API calls
(V2 is currently the only valid version).

59
 ● Step 10: Replace the Invoice hash in xml and encode the xml using Base 64

● Step 11: Fill the request body (invoice hash, UUID, Base 64 encoded XML invoice)

60
 ● Step 12: Execute

● Result (200)

61
 ● Result (400)

2.3.11 API Summary

Table 1
The following table gives a more detailed summary of the differences between the Integration Sandbox
releases in terms of the APIs as well associated components. The current release also indicates the new
additions/changes made in comparison to the previous release.

Release 1 (No- Release 1.5 (Feb-

Function- Release 2 (Current -
Description vember ruary
ality April 2022)
2021) 2022)
Invoices APIs:
● Reporting API Invoices APIs:
● Clearance API
Invoices APIs:
● Reporting API
● Clearance API
● Reporting API Onboarding APIs:
The list of APIs that are Onboarding APIs:
● Clearance API ● Compliance CSID
covered in each release ● Compliance CSID API
API
including
● Production CSID API ● Production CSID API (for On-
APIs Onboarding APIs:
references to the boarding)
● CSID API (for ● (for Onboarding)
functionalities they are ● Production CSID API (for Re-
part of
● Onboarding) ● Production CSID API newal)
● CSID API (for (for Renewal)
● Compliance Checks APIs (for
● Renewal) ● Compliance Checks Onboarding / Renewal)
APIs (for Onboard-
ing / Renewal)

62
 ● As per updated data dictionary,
● As per updated data XML Implementation Stan-
The treatment of dictionary, XML dards and Security Features
validations and Implementation and Implementation Standards
● As per original
exceptions as part Standards and (including updates to CSR and
(published) data
of the Reporting Security Features CSID standards)
dictionary, XML
and Clearance and Implementation ● Seller Address field will be
Implementation
process. Standards (includ- accepted with warning for Tax-
Standards and
Exceptions here ing updates to CSR payer devices / solution units to
Security Features
refer to warnings and CSID standards) differentiate Between a warning
and Implementation
Validation which are similar to ● Seller Address field and an error response
Standards
Engine errors but do not will be accepted ● Two variants of the Reporting
● No exceptions
(For Invoices) cause the with warning for and Clearance APIs which are
(Invoices are
submitted Taxpayer devices / configured with Clearance
either accepted or
invoices/documents to solution units to dif- disabled is being provided -
rejected)
be rejected but are still ferentiate between ● NEW
● Not possible to test
indicated in a warning and an ● Note: In the Core Einvoicing
for Sandbox behav-
the response so error response Solution there will only be one
ior When Clearance
that they can be ● Not possible to test API each for Reporting and
is disabled
corrected in future for Sandbox behav- Clearance which at any point of
submissions. ior when Clearance time willeither be configured
is disabled to Clearance being enabled or
disabled

The formats and fields

for the Certificate Signing As per the original (pub-
CSR and CSID Request (CSR) and the lished) Security Features As per the updated Secu- As per the updated Security Features
(For resultant Cryptographic and Implementation rity Features and Imple- and Implementation Standards
Onboarding) Stamp Identifier (CSID) Standards mentation Standards
that is used as part of the
Onboarding process.

● Covers the APIs

● Covers the Reporting and Clear-
mentioned
ance APIs above with provision
● Provision for 1
for 1 Exception
Exception (Non-
● Covers the Reporting and
compliance in the
Clearance APIs above with pro-
● Covers the APIs Seller’s Address
vision for turning off Clearance
mentioned above field is accepted as
Swagger The API documentation (through two additional variants
● No provisions for a warning)
Files (API associated with the of the Reporting and Clearance
Exceptions or turn- ● No provisions for
Specifications) Swagger files. APIs) -
ing off Clearance turning off Clear-
● NEW
ance
● Covers the two separate APIs
● Covers the two
for Compliance and Production
separate APIs for
CSIDs
Compliance and
Production CSIDs

63
Table 2
The following table provides a summary description of the APIs including the key outputs and inputs/pre-
requisites for each API.

API Name Description Output Pre-requisites

This API should be used to test submitting
Simplified e-invoices, credit or debit note to
the ZATCA backend system as part of the
Reporting process ● If no errors or warnings:
When Clearance is disabled, this API can ● A test Production CSID obtained
Accepted
also be used to test submitting Standard from API #5 or #6 below
● If error in Seller Address:
e-invoices, credit or debit notes for Report- ● Simplified invoice, credit or debit
Accepted with warning
ing note in XML format
Reporting API message
Note: In the Integration Sandbox there will ● Standard invoice, credit or debit
be two variants of the Reporting API, one ● If errors other than Seller
note in XML format when Clear-
which is configured to Clearance being Address: Rejected with
ance is disabled
enabled (i.e. it will not accept Standard error messages
documents) and one which is configured
to Clearance being disabled (i.e. it will also
accept Standard documents to be submitted
for Reporting)

This API should be used to test submitting

● If no errors or warnings:
Accepted and document
test Standard e-invoices, credit or debit note
is returned with test ZAT-
to the ZATCA backend system as part of the
CA stamp and QR code
Clearance process
When Clearance is disabled, this API will ● If error in Seller Address:
return a 303 Response indicating that the Accepted with warning
Reporting API be used to submit Standard message and document
● A test Production CSID obtained
documents as well is returned with test ZAT-
from API #5 or #6 below
Note: In the Integration Sandbox there will CA stamp and QR code
Clearance API ● Standard invoice, credit or debit
be two variants of the Clearance API, one ● If errors other than Seller
note in XML format
which is configured to Clearance being en- Address: Rejected with
abled (i.e. it will validate and clear Standard error messages
documents) and one which is configured to
● Response 303 when
Clearance being disabled (i.e. it will return
Clearance is disabled
response 303 stating that Clearance is
asking the Reporting
currently disabled and the Reporting API
API to be used to submit
must be used to submit Standard documents
Standard documents
as well)

64
 ● Valid request: Test Com-
This API should be used to test submitting ● Public Private Key pair
pliance CSID and a test
Compliance test CSRs (Certificate Signing Requests) to
Request ID are obtained ● Signed CSR
CSID API the ZATCA backend system as part of the
Onboarding and renewal process
● Invalid request: Error
message(s)

● Valid request: Test Pro- ● A test Compliance CSID obtained

Production This API will be used to submit a test Re- from APIs #3 above
duction CSID is obtained
CSID API (for quest ID to a test ZATCA backend system as
● Invalid request: Error ● A test (dummy) request ID
Onboarding) part of the Onboarding process
message(s)

● Valid request: Test Pro- ● A test Compliance CSID obtained

Production This API will be used to submit a test Re- from APIs #3 above
duction CSID is obtained
CSID API (for quest ID to a test ZATCA backend system as
● Invalid request: Error ● A test (dummy) request ID
Renewal) part of the Onboarding process
message(s)

These APIs should be used to test the

compliance check for the device / solution
unit (EGS) as part of the Onboarding and/or
Renewal processes ● All Compliance checks ● A test Compliance CSID obtained
Compliance passed from APIs #3 above
Checks APIs The compliance checks include checking ● One or more compliance ● Standard and/or Simplified invoic-
(for Onboard- compliance of Standard and/or Simplified checks failed with error es, credit or debit notes in XML
ing / Renewal) documents when Clearance is enabled messages format
(Compliance Invoice API) or when Clear-
ance is disabled (Compliance Invoice
Clearance Disabled API);

65
2.3.12 Accessing the Developer Portal Support Page
The Developer Portal Support Page can be accessed from the main dashboard of the Developer Portal and
does not require any prior registration / log in. Through this page, the user can view the different types of
support available which includes the Toolbox and Sandbox documentation. In addition, the user can view the
FAQ section to find readily available answers to common inquiries they may have on the Developer Portal
tools and functionalities as well as more specific questions on testing the compliance of their XMLs. Users can
also find the support contact information that they can access should they require any support. This includes
phone number / hotline, international phone number and the email address. Users could also provide any
suggestions or complaints they may have.

The user can access the Developer Portal Support Page from the main Developer Portal page.

The following categories are available to users:

● General support
● SDK support
● Integration Sandbox support
● Compliance and Enablement Toolbox support

66
A search bar is also readily available for users to search and obtain the relevant information easily. The user
can view common enquiries in the FAQ page. The user can see a contact section at the bottom of the support
page in case of experiencing any issues and in the event that the user would want to receive the support of the
contact center.

67
3. Security Requirements
ZATCA uses Basic Authentication for its E-invoicing security solution.

Basic Authentication

The solution will include a Basic Authentication header with the CSID as the Username and
Description a Secret Value as the Password. Secret value will be issue with the CSID. An additional ac-
cept-version: v2 header must be added to V2 API calls.

CSID and Secret are issued for the compliance checks, CSID should be used as the user and the
Onboarding
Secret as the password

Production CSID and Secret issued and all eInvoicing calls (reporting and clearance) should
E-invoicing include the Basic Authentication header with CSID as the user and Secret as the password. An
additional accept-version: v2 header must be added to V2 API calls

Basic Authentication Format:

● Authorization: Basic {Base64 Encoded String}
● {Base64 Encoded String} = A script containing the CSID, a Colon and the Secret encoded with Base64
(CSID:Secret)

68
4. Frequently Asked Questions (FAQs)
4.1 Business FAQs
4.1.1 Developer Portal Business FAQs

# Question Answer

The Developer Portal is a dedicated Portal provided by ZATCA

to the e-invoice generation solution developers and the
developers community. It provides tailored information in line
with e-invoicing requirements and in particular it provides
1 What is the Developer Portal? access to a Software Development Kit (SDK) and a Portal-
based validator which allows for checking the compliance
of specific XML electronic invoices with the e-invoicing
requirements. It also provides access to ZATCA's Integration
Sandbox.

Through the Developer Portal, users can access:

● A Support page, which includes guidance and support
information on the Developer Portal functionalities

● The SDK page, used for testing the compliance of XML files
What are the main tools or
with the e-invoicing requirements
2 functionalities provided by the
● The Portal-based validator page, which enables non-
Developer Portal?
technical users to check the compliance of XML files by
uploading them to the Portal

● The Integration Sandbox, which allows developers to test the

integration of their systems with a Sandbox environment

69
 # Question Answer

The Developer Portal is publicly available to everyone.

The users can access the Compliance and Enablement
Toolbox (SDK and Web-based Validator) and Support
What are the requirements for
3 pages without the need for prior registration. However,
using the Developer Portal?
users who desire to access the SDK and the Integration
Sandbox must register by providing the details requested
on the page.

Developers of e-invoice solutions or developers

representing taxpayers' in-house teams or non-technical
Who are the intended users to users representing taxpayers (such as tax or accounts
4
register for the Developer Portal? teams) who would like to validate the compliance of
specific document files (e.g. XML files) with the e-invoicing
requirements.

70
4.1.2 SDK Business FAQs

# Question Answer

The SDK is an offline downloadable tool which can be used

What is the Compliance and to validate the XMLs files in accordance with the E-Invoicing
1
Enablement Toolbox SDK? requirements. It also allows validation of the QR codes as
per a prescribed structure.

The SDK can be found by navigating to the "Systems Developers"

page on the ZATCA website, followed by the "Compliance and
2 Where can I find the SDK? Enablement Toolbox" page. Through the "Compliance and
Enablement Toolbox" page, users can download the SDK after
accepting the disclaimer.

It is not mandatory for Taxpayers to use the SDK. However,

ZATCA encourages developers to use the SDK to ensure
compliance with the E-Invoicing requirements for the QR
3 Do I have to use the SDK? Code (required from 4 December, 2021) and XML (required
starting from 1 January, 2023 onwards).
Developers should also use the SDK for offline testing to reduce
load on the Integration Sandbox.

The purpose of the SDK is to assist the developers to check

if the QR Code structure and XML file meets the E-Invoicing
Once the XML validation is
requirements and to return specific error messages for
4 successful, is it deemed to be
correction. Successful validation of XMLs using the SDK should
accepted by ZATCA?
not be deemed as any form of acceptance or approval by
ZATCA.

71
 The users will be able to validate the following fields:
1. Seller's Name.

2. VAT registration number of the seller.

What are the QR code fields

3. Timestamp of the electronic invoice or credit/debit note
(date and time).
that will be validated in the
5 Generation phase and which 4. Electronic invoice or credit/debit note total (with VAT).
are required for the 4th of 5. VAT total.
December 2021?
Additional fields from the specification and otherwise may
be included, but will be disregarded by ZATCA for the 4th of
December requirements.

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).

What are the QR code fields that
will be validated in the Integration 5. VAT amount.
6
phase starting from 1 January 6. Hash of XML electronic invoice or credit/debit note.
2023 onwards? 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. 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).

72
 9. For Simplified Tax Invoices and their associated notes,
the ECDSA signature of the cryptographic stamp’s public
key by ZATCA’s technical Certificate Authority (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.

6 Continue
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
*/

73
 public static byte[] extractS(String digitalSignature) throws
Exception {
MessageDigest digest = MessageDigest.
getInstance("SHA-256");
byte[] hash =
6 Continue
digest.digest(Base64.getDecoder().
decode(digitalSignature.getBytes(StandardCharsets.
UTF_8)));
return Arrays.copyOfRange(hash, 32, 64);

74
4.1.3 Web Based Validator Business FAQs

# Question Answer

The Web-based validator can be accessed by anyone

What is the Web Based from the Developer Portal. It is mainly built to enable
1 Validator for Non-Technical non-technical users, (such as some tax and accounting
Users? teams,) to test and validate XMLs as per e-invoicing
requirements.

The intended users of the Web Based Validator are

the non-technical users such as tax teams or accounts
Who is eligible to use the Web
2 teams for taxpayers. Anyone can accesses the
Based Validator?
Developer Portal (publicly available) to use the Web
Based Validator.

In case an XML has error(s), specific error messages

will be displayed. XMLs can be validated either via
3 What if XML has error(s)?
the Portal-based validator or the SDK again after the
error(s) are fixed.

It is not mandatory for Taxpayers to use the SDK or the

Is it mandatory to use the Web Based Validator. However, ZATCA encourages
Compliance and Enablement the technical and non-technical users (such as tax
4
Toolbox SDK or Web Based teams or accounts teams) to use the SDK and Web
Validator? Based Validator to ensure compliance with e-invoicing
requirements.

75
4.1.4 Integration Sandbox Business FAQs

# Question Answer

The Integration Sandbox (ISB) is a test platform developed

by ZATCA to simulate some of the core e-invoicing platform
(FATOORA) functionalities that will be available in the
What is the Integration production system. Its primary objective is to allow Solution
1
Sandbox? Developers to build compliant E-invoice Generation Solutions
that can submit requests to the ISB and obtain relevant
responses to indicate if their integration calls have been
successful or if they have any errors.

The Compliance and Enablement Toolbox (CET)

comprises of:

1. 1. An offline SDK tool to validate QR Code and XMLs; and

2. 2. A Portal-based Validator for non-technical users
(such as tax or accounts teams) to validate XMLs.
What is the difference
between the Compliance and The Integration Sandbox allows testing integration of
2
Enablement Toolbox and the taxpayer's E-invoicing solutions with a sandbox environment
Integration Sandbox? using test APIs to send requests and documents in a similar
manner to how it would be done on the core e-invoicing
platform. This sandbox will perform validations that are part
of the SDK and some additional checks that cannot be done
offline or are specific to API requests. The SDK requires
XML files / QR code strings as inputs while the Integration
Sandbox requires an API request as input.

76
 If my invoices are compliant XMLs validated by the Toolbox are expected to receive
as per the Compliance and successful responses on the Integration Sandbox also
3 Enablement Toolbox, will unless there are issues with the API request itself.
they also pass the Integration However, the Sandbox can also run some additional
Sandbox? validations.

The intended users of the Integration Sandbox are e-invoicing

solution developers. Developers can register by providing
Will the Integration Sandbox be
4 the requested information and access the API documentation
available to Taxpayers only?
on the Developer Portal. VAT Registration details are not a
pre-requisite to register and access the Integration Sandbox.

No. Taxpayers who are required to integrate with ZATCA

Does passing the Integration will have to undergo an Onboarding and Compliance
Sandbox mean the E-invoice process to be able to submit electronic documents to ZATCA
5 Generation Solution can be used starting from 1 January 2023 onwards. E-invoice Generation
by a Taxpayer to submit invoices Solutions which undergo adequate testing on the Sandbox
to ZATCA? will have a higher probability of completing that onboarding
and compliance process smoothly.

Can multiple invoices be

Yes. However, each invoice, credit or debit note should be
6 submitted to the Integration
part of a separate API call.
Sandbox?

Do invoices need to be submitted

The Integration Sandbox does not mandate that the invoices
7 in sequence to the Integration
should be submitted in sequence.
Sandbox?

Does ZATCA store the invoices

8 submitted to the Integration No.
Sandbox?

77
 Does the Integration Sandbox No, dummy information can be provided as long as they
9 require actual taxpayer details meet the syntax and content specifications and the XML
on the XML files? implementation standards and validation rules.

No. The Integration Sandbox is not intended to validate actual

If an invoice has been cleared by
invoices and is for testing purposes only. The successful
10 the Integration Sandbox, can it be
validation of an XML using the Integration Sandbox should not
issued to a buyer?
be deemed as any kind of acceptance or approval by ZATCA.

Can I use the same username and

password that I used to access
Yes, the registration and login process is common for both
the Compliance and Enablement
11 the Compliance and Enablement Toolbox SDK and the
Toolbox SDK on the Developer
Integration Sandbox.
Portal to log into the Integration
Sandbox?

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
What is a Cryptographic Stamp
12 key.
Identifier (CSID)?
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.

78
 A Compliance CSID is an intermediate CSID provided in
response to the CSR submission from an EGS or other solution.
In the Core E-invoicing Solution, the Compliance CSID is
What is the difference between required to complete some compliance checks before the EGS
13 a Compliance and Production or other solution is able the Production CSID which is required
CSID? for authenticating the EGS or other solution to ZATCA. In the
Sandbox, the compliance checks are not required, and the
purpose is to therefore to test the integration calls of obtaining
the Compliance and Production CSIDs.

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
Can I use the same CSID for any Number is required. Note that the VAT Registration number can
14
invoice submission? be any dummy number that meets the syntax specifications
(15 digits, starting with 3 and ending with 3).
Only a test Production CSID can be used for submitting
invoices, credit or debit notes as well as QR codes.

Errors are associated with invalid invoices, credit or debit

notes causing the rejection of such submissions. Warnings are
What is the difference between associated with accepted documents which are still not fully
15
an error and warning? compliant with the specifications and standards. Currently the
only warning case is an error with the Seller Address and is
meant for EGS units to be able to read warning messages.

Can anyone access sandbox and No, Sandbox can be accessed by anyone, but FATOORA
16 FATOORA portal? production system can be accessed only by taxpayers using
Taxpayer portal credentials (ERAD credentials).

Can FATOORA portal and

Yes, both FATOORA and Sandbox can be accessed from
17 Sandbox be accessed from
anywhere globally, not only from KSA
anywhere or only from KSA?

79
4.2 Technical FAQs
4.2.1 Developer Portal Technical FAQs

# Question Answer

Where can I find more

User manuals contains detailed information on SDK,
information on the Compliance
Portal-based validator and the Integration Sandbox.
1 and Enablement Toolbox SDK,
These can be found in the dedicated pages on the
the Portal based validator and
Developer Portal.
the Integration Sandbox?

4.2.2 SDK Technical FAQs

# Question Answer

An XML is a way to present information in a structured

and machine readable format. The ZATCA e-invoice
1 What is an XML?
format is based on XML and several other XML-based
standards.

A CLI is a way to access and utilize a software application

using commands and it is text-based. CLI tools like the
FATOORA tool can be used in scripts to create automations.
Sample: fatoora validatexml -f (invoicename.xml)
What is Command Line
2 In this example, we are naming an application called
Interface (CLI)?
"fatoora", in which we want to use the validatexml feature
with a-f command.
The second part that we add is: (invoicename.xml) which is
the path and filename of the XML to be validated.

80
 Java is a programming language that runs on different
operating systems (OS), such as Windows and Linux. A JAR is
3 What is a Java and JAR? a package file format that is generally used to aggregate many
Java class files and associated metadata and resources (text,
images, etc.) into one file for distribution.

Can I validate the Arabic language No, since the CLI does not support Arabic characters
4
fields in a QR code within the CLI? display.

What JAVA version should I The prerequisite is using the Java SDK (JAR) versions
5
install before using the SDK? >=11 and <15.

What should the user do when When faced with a JAVA error, the user needs to install JAVA
6
faced with a JAVA error? (versions >=11 and <15) before running and using the SDK.

Where can I find examples of Sample XML files are included in SDK. You can download the
7
XML files? latest SDK from Developers portal (Sandbox).

81
4.2.3 Web Based Validator for Non-Technical Users Technical FAQs

# Question Answer

A QR code is a coded representation of readable text. In the

1 What is a QR code? context of e-invoicing, the QR code should contain specific
information in a specific format.

In the context of e-invoicing, users should scan the QR

How can the users access
code on e-invoices, debit notes and credit notes by using
2 information contained in the QR
the ZATCA VAT app. This app is available on the Google
code?
Playstore and iOS App Store free of charge.

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
What can I do if an XML has
3 mandatory field is missing or a value is in an incorrect format.
error(s)?
The user may require the assistance of a technical expert to
solve the error(s).

82
4.2.4 Integration Sandbox Technical FAQs

# Question Answer

The "Reporting API" reports a single simplified invoice,

credit note, or debit note. Specifically, it accepts a simplified
invoice, credit note, or debit note encoded in base64 and
validates it to ensure:

1. Compliance to the UBL2 XSD.

1 What is the “Reporting API”?
2. EN 16931 Rules subset.
3. KSA Specific Rules set. KSA Rules set will override EN
16931 Rules set in case the same rule exists in both sets.

4. QR Code validation
5. Cryptographic Stamp validation

The user will need to do a POST Method on endpoint /

invoices/reporting/single and pass it on "authentication-
How can the user access
2 certificate" and accept-language as a parameter in the
"Reporting API"?
header. More information can be found on the Integration
Sandbox section of the Developer Portal.

The body object should Contain 2 Values: the first one is

called "invoiceHash" and the second one is called "invoice".
Example:
What's the Request Body the {
3 user should send while calling "invoiceHash": "string",
"Reporting API"? "invoice": "string"
}
More information can be found on the Integration Sandbox
section of the Developer Portal.

83
 The response will be 200 HTTP Ok with a Retrieved
object containing 4 values : "invoiceHash","Status"
,"Warnings", "errors" .
Retrieved object Example:
{
What should the user expect
"invoiceHash": "TODO Add Invoice Hash",
4 as a response if calling the
"status": "Reported",
"Reporting API" was a success?
"warnings": null,
"errors": null
}
More information can be found on the Integration
Sandbox section of the Developer Portal.

The "Clearance API" clears a single standard invoice, credit

note, or debit note. Specifically, it accepts standard invoice,
credit note, or debit note encoded in base64 and validates it
to ensure:

1. Compliance to the UBL2 XSD.

5 What is the “Clearance API”? 2. EN 16931 Rules subset.
3. KSA Specific Rules set. KSA Rules set will override EN
16931 Rules set in case the same rule exists in both sets.

On successful validation, the api then applies a

cryptographic stamp from ZATCA side and generates a
QR Code string. After that the XML is returned back.

The user will need to do a POST Method on

endpoint /invoices/clearance/single and pass it on
How can the user access "authentication-certificate" and accept-language
6
"Clearance API"? as a parameter in the header. More information can
be found on the Integration Sandbox section of the
Developer Portal.

84
 The body object should Contain 2 Values: the first one is
called "invoiceHash" and the second one is called "invoice".
Example:
What's the Request Body the {
7 user should send while calling "invoiceHash": "string",
"Clearance API"? "invoice": "string"
}
More information can be found on the Integration Sandbox
section of the Developer Portal.

The response will be 200 HTTP Ok with a Retrieved

object containing 4 values : "invoiceHash","Status"
,"Warnings", "errors" .
Retrieved object Example:
{
What should the user expect as
"invoiceHash": "TODO Add Invoice Hash",
8 a response if calling "Clearance
"status": "Reported",
API" was a Success?
"warnings": null,
"errors": null
}
More information can be found on the Integration
Sandbox section of the Developer Portal.

Code - Description

● 200- HTTP OK
● 202- Accepted with Errors, simplified invoice accepted
What are the Response causes
with warning errors
(Code & Description) that can
9 ● 303- HTTP See Other. Returned when the submitted
appear while calling "Reporting
invoice is a Standard Invoice while clearance is activated
single API"?
● 400- HTTP Bad Request. Returned when the submitted
request is invalid
● 500- HTTP Internal Server Error. Returned when the
service faces internal errors

85
 Code - Description

● 200- HTTP OK
● 202- Accepted with Errors, clearance invoice accepted
What are the Response causes with warning errors
(Code & Description) that can ● 303- HTTP See Other. Returned when the submitted
10
appear while calling "Clearance invoice is a Standard Invoice while clearance is
single API"? activated
● 400- HTTP Bad Request. Returned when the submitted
request is invalid
● 500- HTTP Internal Server Error. Returned when the
service faces internal errors

A certificate signing request (CSR) is one of the first steps

towards getting a Cryptographic Stamp Identifier for a device
/ solution unit. The CSR contains information (e.g. common
name, organization, country) the ZATCA Certificate Authority
11 What is a CSR ?
(CA) will use to create your CSID. It also contains the public
key that will be included in your CSID and is signed with the
corresponding private key. Please refer to the CSID API
Swagger files for more details

86
5. Appendix
5.1 Glossary

ZATCA ZAKAT, Tax and Customs Authority

XML Extensible Markup Language

SDK Software Development Kit

QR Code Quick Response Code

SDLC Software Development Life Cycle

CN Credit Note

DN Debit Note

CLI Command Line Interface

The Integration Sandbox should

enable solution developers to
Integration Sandbox
simulate the integration calls/
requests

CET Compliance and Enablement Toolbox

87
 ISB Integration Sandbox

EGS E-invoice Generation Solution

CRM Customer Relationship Management

PKI Public Key Infrastructure

JAR JAVA Archive

API Application Programming Interface

CSID Cryptographic Stamp Identifier

CSR Certificate Signing Request

88
5.2 Developer Portal Security Information
The Developer Portal uses HTTPS, as a secure method of communication between the browser and the
server. The user account is protected by a username and password. The session stays alive for 8 hours
after which the user will need to sign in again.

5.3 Generate CSR

5.3.1 Initiate a CSR configuration file (Open SSL Config. File)
As a part of the first-time onboarding and renewal process, the Taxpayer's EGS Unit(s) must submit a
CSR to the E-invoicing Platform once an OTP is entered into the EGS unit. The CSR is an encoded text
that the EGS Unit(s) submits to the E-invoicing Platform and the ZATCA CA in order to receive a Com-
pliance CSID, which is a self-signed certificate issued by the E-invoicing Platform allowing clients to
continue the Onboarding process.The certificate signing request is encoded text that service providers/
own solution will submit it to ZATCA CA. The digital certificate will be stored in the taxpayer device/s
and EGS identification data will rely on the data provided by the taxpayer through ZATCA Portal without
further validation and therefore, the taxpayer is fully responsible for the accuracy and legitimacy of the
data provided. Also, CSR contains the public key that will be included in the certificate, the private key is
usually created at the same time that service providers/ own solution create the CSR by their selves.
The CSR inputs (Open SSL Config. File) are as follows:

CSR Inputs Business Term Description Specification

Provided by the Taxpayer for

Name or Asset
Common each Solution unit: Unique
Tracking Number for Free text
Name Name or Asset Tracking
the Solution Unit
Number of the Solution Unit

Automatically filled and not by the

taxpayer: Unique identification code
Free text
Manufacturer or for the EGS.
Validate the format
Solution Provider Manufacturer serial number for
EGS Serial with a Regular
Name, Model or each solution unit including
Number Expression (1-...| 2-...
Version and Serial
| 3-....)
Number 1. Manufacturer or Solution
Provider Name | 2-Model or
Version | 3-SerialNumber

89
 VAT Registration Number of the
VAT or Group Taxpayer (Taxpayer / Taxpayer
Organization 15 digits, starting and
VAT Registration device to provide this to allow
Identifier ending with 3
Number to check if the OTP is correctly
associated with this TIN)

If 11th digit of
Organization Identifier
The branch name for taxpayers.
is not = 1 then Free
In case of VAT Groups this field
text
Organization should contain the 10-digit TIN
Organization Unit
Unit Name number of the individual group
If 11th digit of
member whose EGS Unit is
Organization Identifier
being onboarded
= 1 then needs to be a
10 digit number

Organization
Taxpayer Name Organization/Taxpayer Name Free text
Name

Country Name Country Name Name of the country 2 letter code

The document type that the

Taxpayer’s solution unit will be
Invoice Type issuing/generating. It can be one 4-digit binary number
(Functionality Functionality Map or a combination of Standard Tax (0s and 1s only, cannot
Map) Invoice (T), Simplified Tax Invoice all be 0s)
(S), Buyer QR code (C), Seller’s
QR code in self-billing (Z).

90
 The input should be using the
digits 0 & 1 and mapping those to
“TSCZ” where:

0 = False/Not supported

1= True/Supported 4-digit binary

Invoice Type number (0s and 1s
(Functionality Functionality Map
Map) For example: 1000 would mean only, cannot all be
Solution will be generating 0s)
Standard Invoices only. 0100
would mean Solution will be
generating Simplified invoices
only. and 1100 means Solution
will be generating both Standard
and Simplified invoices

The address of the Branch or

location where the device or
Location of Branch
Location solution unit is primarily situated Free Text
or EGS Unit
(could be website address for
e-commerce)

Organization
Taxpayer Name Organization/Taxpayer Name Free text
Name

Industry or sector for which the

Industry Industry or Location device or solution will generate Free Text
invoices

The screenshot below represents the information the user must use to generate a CSR (using Open SSL
Command Tool) and its configuration file as shown below. For further information, please see link: /
index.html (openssl.org)

91
5.3.2 Generate public/private key pair
● According to security implementation document the Key pair shall be generated according to FIPS
186. Further, reasonable techniques shall be used to validate the suitability of the generated key
pair.
● The suitability of keys shall be done according to either the ECC Full Public Key Validation Routine or
the ECC Partial Public Key Validation Routine. [Source: Sections 5.6.2.3.2 and 5.6.2.3.3, respective-
ly, of NIST SP 56A: Revision 2].
● Keys must be marked as non-exportable in order to prohibit key export out of the security module
where the key was generated
● A hardware or software based security module can be used to generate and store the key pair as
long as the above requirements are met.

92
5.3.2.1 Generate Private Key
The service providers/ own solution need to keep the private key secret. The created certificate will
only work with a particular private key that was generated. So if the private key lost, the certificate
will no longer work. we are generating a pair of ECDSA keys with the P-256 (secp256k1) curve, the
PrivateKey.pem file will be the generated private key, change the file name to YourPrivateKey.pem.
the following command show how to generate a private key using OpenSSL:

Sample contents of the PrivateKey.pem private key in PEM format:

5.3.2.2 Generate Public Key

The compressed public key will be created by extracting it from the private key, extracting ECDSA
keys with the P-256 (secp256k1) curve, the PublicKey.pem file will be the extracted public key,
change the file name to YourPublicKey.pem. The following command show how to extract a public

key using OpenSSL:

By using the compressed public key only X values will be used in the elliptic curves:

93
The base64 public key will be use to validate the signature for the standard invoice:

Sample contents of the PublicKey.pem public key in PEM format:

5.3.3 Generate a Certificate Signing Request

The service providers / own solution need to run the following command in order to generate the
certificate signing request, the command include the request to generate the certificate with -sha256.

Sample contents of the CSR:

94
5.3.4 Testing the certificate
The service providers/own solution can test the compliance of the generated CSR using the requests
that can be found in the below Postman collection:

The service providers/own solution needs to add the generated CSR in the body of the request:

95
 External Document

This guide has been prepared for educational and awareness purposes only,
its content may be modified at any time. It is not considered in any way binding
to ZATCA and is not considered in any way a legal consultation. It cannot be
relied upon as a legal reference in and of itself, It is always necessary to
refer to the applicable regulations in this regard. Every person subject to
zakat, tax and customs laws must check his duties and obligations, he is
solely responsible for compliance with these regulations. ZATCA shall not
be responsible in any way for any damage or loss The taxpayer is exposed
to that results from non-compliance with the applicable regulations.

scan
‫تحديـث‬ this code
‫عـلــــى آخر‬ ّ to view
‫لالطالع‬ the
‫الـكــود‬ last‫امـسـح‬
‫هـــــذا‬
version and
‫المـنـشـورة‬ all published
‫المستنــــدات‬ ‫ وكـافة‬documents
‫لـهــذا المستنـد‬
or visit the website zatca.gov.sa
zatca.gov.sa ‫أو تـفضل بزيـارة الموقع اإللكتروني‬

96