The Developer Portal includes range of tools that can be used for the development of compliant e-invoicing solutions
i. SDK
ii. Web Based Validator for XML files
iii. API integration Sandbox
1.1.a Confirming compliance
For confirming compliance, the following capabilities are offered in the developer portal through the Compliance and Enablement Toolbox:
- Generate CSR & private key
- Generate valid invoice XML
- Generate invoice hash
- Sign invoices
- Validate invoice XML
Below is an overview of the high-level user journey when using the Compliance and Enablement toolbox:
The Compliance and Enablement Toolbox will run all the production-level validations. Production-level validations as field specifications and business rules of a ZATCA compliant e-invoice, credit or debit note that can be performed on individual XML. In addition to the embedded functionalities that taxpayers can use like CSR generation and invoice signing.
1.1.b Confirming integration
For confirming integration, the following capabilities are offered in the developer portal through the Integration Sandbox:
- Sandbox APIs (inputs & outputs)
- Execute sandbox APIs (predefined & custom)
Below is an overview of the high-level user journey when using the Integration Sandbox:
The Integration Sandbox originates from the Developer Portal and requires the user to be registered and logged in.
A registered user then can access the integration related information and specifications, simulate any API request without having to follow any sequence. No data is stored on the system.
- Developer portal tools
2.1. Software Development Kit (SDK)
The SDK is provided by ZATCA on the developer portal and its optional to use. 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 requirements, standards, and guidelines. It also allows the generation of the CSR, signing invoices and the validation of the QR codes as per the prescribed structure.
• Generate CSR & Private Key
Using the command line or openssl, users can generate the CSR and the private key. And 1st step towards generating the CSR will be populating the CSR config file, all related information is available on the SDK and technical guidelines.
• Validate the XML Invoice
Using the command line or integrating with the available libraries on the SDK, users can validate the XML invoices and make sure they are compliant before moving into the APIs.
• Sign the XML Invoice
Using the command line or integrating with the available libraries on the SDK, users can sign the XML simplified invoices and generate a complaint QR code. Signed invoices can be used for compliance checks and reporting.
Please if you are using the .NET library for signing, generate the CSR and key using openssl.
2.2. Web Based Validator
The Web Based Validator for Non-Technical Users is aimed at non-technical users who have access to an XML of standard e-invoices, credit or debit note, and allows users to check the compliance of the files 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.
Please note that the portal validation page is a standalone and offline application and compliance does not necessarily imply the e-invoices, credit or debit notes have been accepted by ZATCA. All Taxpayer solutions and devices will need to pass the testing requirements as part of Registration/Taxpayer Onboarding prior to submitting e-invoices, credit or debit notes to ZATCA
2.3. API Integration Sandbox
The API Integration Sandbox is an optional tool offered to developers or solution providers of taxpayers to help them understand and test the integration of their systems within the Sandbox environment by simulating the use of several APIs end-to-end.
Please note that the ZATCA e-invoicing API Integration Sandbox is meant to be used for testing purposes only. Any e-invoices or their associated notes submitted on the Sandbox are not considered as acknowledged, approved or accepted by ZATCA. Taxpayers will be required to register for e-invoicing on the ZATCA e-invoicing production system (FATOORA) in order to officially be able to submit their e-invoices to ZATCA.
Developers must also take into account that e-invoices, credit and debit notes submitted on the production system will be subjected to additional validations such as security features, prohibited functionalities and additional business rule validations as part of the Clearance process.
API call steps:
- On selecting target API call from the API documentation guide on the left, related API data will be reflected in the URL and Schemas
- Access the authorize button and fill provided username (CSID) & password (Secret) then authorize before posting the API call
- Expand the API dropdown to check the request headers and body
- Upon calling the API a code is returned with the response. And this code will be the status of the call, for more details check the sandbox
Note: APIs can be executed out of sequence and the certificates provided are sample responses
The following list of APIs can be found in the Integration Sandbox and used to test and confirm the ability to integrate with ZATCA:
|
# |
API Name |
Description |
|
|
1 |
Compliance CSID API |
This APl will be used to submit test CSRS (Certificate Signing Requests) to a test ZATCA backend system as part of the Onboarding and/or renewal process |
|
|
2 |
Compliance Checks APls |
These APls are used to test the compliance of the test device / solution unit (EGS) as part of the Onboarding and/or Renewal processes |
|
|
3 |
Production CSID API (for Onboarding) |
This API will be used to submit a test Request ID to a test ZATCA backend system as part of the Onboarding process |
|
|
4 |
Production CSID API (for Renewal) |
This APl will be used to submit a test Request ID to a test ZATCA backend system as part of the Renewal process |
|
|
5 |
Reporting API |
This API will be used to submit test Simplified e-invoices, credit or debit note to a test ZATCA backend system as part of the Reporting process |
|
|
6 |
Clearance API |
This APl will be used to submit test Standard e-invoices, credit or debit note to a test ZATCA backend system as part of the Clearance process |
|