The Developer Portal is a special portal offered by ZATCA for the developers of E-invoicing Generation Solutions (EGS). In addition to the above, the Developer Portal has a third tool intended for intermediate or non-technical users to validate XML-based e-invoice, credit or debit memo files directly from the portal. Finally, the Developer Portal has a dedicated support page with a list of frequently asked questions (FAQs) to help developers troubleshoot issues during the development and testing of their EGS units and to provide advice on e-invoicing requirements in general.
The primary objective of the Developer Portal is to support the Developer community in building EGS entities that conform to ZATCA's XML implementation standards, as well as security features and implementation standards. This user manual acts as a guide for Developers to help them access and use the features and functionalities of the Developer Portal. It explains in detail the user journey including the steps, requirements and processes required to access the Developer Portal.
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.
Accessing the Developer Portal
Creating a Developer Portal Account
In case the user has not set up an account and needs one, the user can click on the Sign In option to create a new account and proceed to the process described in section 2.3.2 of the user manual. for registration. After filling in all the information, the user must click on the Login button to return to the main dashboard, where the user can now also access the Compliance and Enablement Toolbox SDK page and the Integration Sandbox page. A logged in user can log out at any time by clicking the logout option at the top.
The user can also change the password at any time by clicking the arrow next to the user profile icon in the header.
Accessing the Compliance and Enablement Toolbox SDK Page
Access the SDK support, which covers aspects such as using the SDK and how it works, as well as the minimum software requirements and the instructions relevant to each operating system. Access to documentation such as the XML Implementation Standards (XML Implementation Standard for E-Invoices), Security Features and Implementation Standards (Security Features and Implementation Standards for E-Invoices), and Data Dictionary (Data Dictionary for E-Invoices).
Downloading the SDK
Using the SDK (outside of the Developer Portal)
Accessing the Web Based Validator for Non-Technical Users
In the Web-based Validator for Non-Technical Users, users can view information about an explanation of the Web-based Validator and what it is intended to do. Additionally, users can click "Access the Web-based Validator for Taxpayers without a Development Environment" to begin testing and validating their XMLs.
Using the Web Based Validator for Non-Technical Users
The non-technical user is expected to share the validation results with the Solution Developer to take necessary action.
Accessing the Integration Sandbox Page
Developers should also consider that documents or requests submitted on the Core e-Invoicing solution will be subject to additional validations such as security features, prohibited functionalities, additional business rule validations and/or reference checks based such as the validation of the Seller/Buyer - information entered. in the documents, validations based on previously submitted documents. On the left navigation bar of the page, the user has access to the links to the API documentation maintained as Swagger files (each API call is described in section 2.3.10 below along with the possible outcomes).
Accessing the API and associated Documentation (Swagger Files)
Step by step guide to make a successful call to APIs
Compliance CSID
Compliance Invoice API
Note: This step must be repeated for the number of invoices to be sent as part of the compliance checks. For production, run the Compliance CSID API to obtain the “binarySecurityToken” to use as the username and “secret” as the password. For the Sandbox, use the sample dummy username and password given to you on the authorization screen.
Note: V2 refers to the version of the APIs used and must be mentioned in the API calls (V2 is currently the only valid version).
Production CSID (Onboarding) API
Production CSID (Renewal) API
REPORTING
CLEARANCE
API Summary
Feb- ruary
Current - April 2022)
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/login. This page allows the user to 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 general queries they may have about the Developer Portal tools and functionalities, as well as more specific questions about testing the compliance of their XMLs.
Users can also find support contact details that they can access if they need any support. The user can access the support page of the developer portal from the main page of the developer portal. A search bar is also available for users to easily find and retrieve relevant information.
The user can see a contact section at the bottom of the support page in case of any problem and in case the user wants to take contact center support.
Security Requirements
- Developer Portal Business FAQs4.1 Business FAQs
Frequently Asked Questions (FAQs)
- SDK Business FAQs
- Web Based Validator Business FAQs
- Integration Sandbox Business FAQs
- Developer Portal Technical FAQs4.2 Technical FAQs
- SDK Technical FAQs
- Web Based Validator for Non-Technical Users Technical FAQs
- Integration Sandbox Technical FAQs
- Glossary
However, users who wish to access the SDK and integration sandbox must register by entering the information requested on the page. Developers should also use the SDK for offline testing to reduce the load on the integration sandbox. What are the QR code fields that will be validated in the integration phase from January 1, 2023 onwards.
The Integration Sandbox (ISB) is a test platform developed by ZATCA to simulate some of the basic functionalities of the e-invoicing platform (FATOORA) that will be available in the production system. The integration sandbox allows for testing the integration of the obligor's e-invoicing solutions with the sandbox environment using test APIs to send requests and documents in a similar way as it would be done on the underlying e-invoicing platform. The SDK requires XML files/QR code strings as input, while the integration sandbox requires an API request as input.
If my invoices are compliant according to the Compliance and Enablement Toolbox, they will also pass the integration sandbox. XMLs validated by Toolbox are also expected to receive successful responses on the Integration Sandbox, unless there are issues with the API request itself. Passing the integration sandbox means that the e-invoice generation solution can be used by a taxpayer to submit invoices to ZATCA.
10 Once an invoice has been approved by the Integration Sandbox, it can be issued to a buyer. The Integration Sandbox is not intended to validate actual invoices and is for testing purposes only. The successful validation of an XML using the Integration Sandbox should not be considered as any form of acceptance or approval by ZATCA.
Yes, the registration and login process is common to both Compliance and Enablement Toolbox SDK and Integration Sandbox. In the Sandbox, compliance checks are not required, and the purpose is therefore to test the integration calls to obtain Compliance and Production CSIDs.
Appendix
- Developer Portal Security Information
- Generate CSR
- Initiate a CSR configuration file (Open SSL Config. File)
- Generate a Certificate Signing Request
- Testing the certificate
The taxpayer shall provide for each solution unit: A unique name or number for tracking the assets of the solution unit. As part of the initial inclusion and renewal process, the taxpayer's EEC units must submit a CSR to the e-invoicing platform when the OTP is entered into the EEC unit. The CSR is the coded text that the EEC entity(ies) submits to the e-invoicing platform and the ZATCA CA to receive a compliance CSID, which is a self-signed certificate issued by the e-invoicing platform that allows customers to continue the onboarding process. The certificate signing request is an encoded text that service providers/.
The digital certificate will be stored on the taxpayer's device/s and the EGS identification data will rely on the data provided by the taxpayer through the ZATCA Portal without further verification and therefore, the taxpayer is fully responsible for the accuracy and legitimacy of the data offered. Also, the CSR contains the public key that will be included in the certificate, the private key is usually generated at the same time that the service providers/solutions generate the CSR themselves. Taxpayer's VAT Registration Number (taxpayer's / taxpayer's device to ensure this to allow checking if the OTP is correctly linked to this TIN).
In the case of VAT groups, this field must contain the 10-digit TIN number of the individual group member whose EGS unit is being onboarded. The address of the branch or location where the device or solution unit is primarily located (can be a website address for e-commerce). Furthermore, reasonable techniques will be used to validate the suitability of the generated key pair.
Validation of keys will be done according to ECC Full Public Key Validation routine or ECC Partial Public Key Validation routine. Keys must be marked as non-exportable in order to prevent the key from being exported by the security module where the key was generated. The compressed public key will be generated by extracting it from the private key, extracting the ECDSA keys with P-256 (secp256k1) curve, the PublicKey.pem file will be the extracted public key, rename the file to YourPublicKey.pem.
The service providers/proprietary solution must run the following command to generate the certificate signing request. The command includes the request to generate the certificate with -sha256. The service providers/proprietary solution must add the generated CSR to the body of the request:.
