The second step of the Taxpayer's E-Invoicing Journey involves onboarding the Taxpayers' EGS units and devices with the FATOORA Platform. After successful completion and entry of Taxpayer's EGS, Taxpayers can start submitting documents to ZATCA for customs clearance or reporting.
Additional Step - Compliance and Enablement Toolbox
For more details and information about the Compatibility and Activation Toolbox and how to access and use it through ZATCA's Developer Portal, please refer to the Developer Portal Guide (Link). For more details and information about the Compatibility and Activation Toolbox and how to access and use it through the ZATCA Developer Portal, please refer to the Developer Portal User Manual (Link).
Additional Step - Integration Sandbox
To do that, taxpayers and their system developers can use the Compliance and Enablement Toolbox accessible through ZATCA's Developer Portal or ZATCA's website. To monitor integration, taxpayers can use the Integration Sandbox, which can also be accessed through ZATCA's Developer Portal.
Introduction and Objectives of the Onboarding Functionality
The onboarding functionality was developed by ZATCA to enable taxpayers using the e-Invoice Generation Solution Unit(s) (EEC Unit(s)) to obtain the necessary Cryptographic Stamp Identifiers (CSID(s)) that enable, upon initial onboarding to EEC unit(s). It allows taxpayers to initiate the onboarding and recovery process by generating a one-time password (OTP) used for their EEC units, in addition to accessing a list of all their onboarded EEC units, which is also the starting point for canceling any CSID(s).
Onboarding
Onboarding Overview
- Onboarding of a new EGS Unit(s)
- Renewal of existing CSID(s) for EGS Unit(s)
- Revocation of CSID(s) for one or more EGS Unit(s) by the Taxpayer
The first method involves the Taxpayer obtaining an OTP through the FATOORA Portal, which would be manually entered into the Taxpayer's EGS Unit(s). If the Taxpayer believes that the private key or the EGS Unit itself has been compromised.
Description of the Onboarding Process
- Taxpayer accessing and logging into the FATOORA Portal using Single Sign On (SSO) using the existing credentials of FATOORA Portal (ERAD)
- Process Flow
Taxpayer is redirected to SSO Portal FATOORA (ERAD) in order to provide his/her FATOORA Portal (ERAD) credentials and login. After successful login (authentication) and fulfillment of the authorization criteria, the Taxpayer is again redirected to the landing page of the FATOORA Portal.
Onboarding and Renewal
Generating an OTP to obtain a CSID for the first time or renewing an existing CSID (Manual OTP entry)
- Description
The process for generating the OTP code(s) on the FATOORA Portal and entering them manually is as follows
- Process Flow
The taxpayer chooses to generate OTP code(s) for single or multiple EGS unit(s) by entering the number of OTP codes he wants to generate (the user must enter 1 or more (maximum 100 per application) based on the number of EGS unit(s) they want to have on board). The FATOORA Portal generates the OTP code(s) (valid for 1 hour), which are displayed on the Portal and can be copied or downloaded into a file.
The process for generating an OTP code on the FATOORA Portal through automatic entry is as follows
- Sending a Certificate Signing Request (CSR) in order to receive a Compliance CSID
- Description
- Process flow
- Completion of the Compliance checks by the EGS Unit 1. Description
- Process Flow
- Generating a new CSID for the EGS Unit or Renewing the existing CSID 1. Description
- Process Flow
- View List of EGS Unit(s) 1. Description
- Process Flow
Once a CSR has been successfully submitted and the compliance CSID has been obtained, the taxpayer's EGS unit(s) must undergo compliance checks to ensure that the EGS unit is capable of generating compliant invoices. If the compliance checks have been successfully completed and passed, the EGS unit will receive a production CSID. In the event that one or more tests are failed or not completed, the taxpayer's EGS unit will have to restart the onboarding/renewal process, starting from the issuance of a new OTP and a CSR, and undergo the compliance tests again .
Note that achieving compliance checks implicitly means that the EGS unit has successfully obtained a compliance CSID. However, for renewal, the existing CSID of the EGS unit is revoked and a new one is issued. The FATOORA portal has a tile that can be accessed from the dashboard that contains a summary list of the reported Taxpayer's onboarded EGS Unit(s).
The FATOORA platform forwards the new CSID(s) to the EEC tax unit that originally submitted the CSR to the FATOORA platform. The taxpayer will be able to view a list that includes a summary of all EEC units that the taxpayer has included in accordance with the above information.
Revocation of an existing CSID
Manual revocation of an existing CSID by the Taxpayer 1. Description
- Process Flow
The taxpayer can see which devices are active and select the EGS unit(s) to be withdrawn. 4. The status of the devices' CSID can be seen as 'Revoked' in the Watch List.
Automatic revocation of CSID(s) due to VAT Deregistration or Suspension 1. Description
- Process Flow
VAT Group Onboarding Scenarios
- Specific tax group Onboarding Scenarios
- VAT Group Onboarding Roles
The responsibility is on the group and the tax group representative to ensure that the shared device issues correct invoices on behalf of the group. If the device is owned by an individual specific member of the group, the group representative will need to board the device associated with this specific member. The liability is on the group representative to ensure that the shared device issues correct invoices on behalf of the tax group.
If the device is owned by an individual group member, the group representative will need to revoke the device associated with this specific member. ZATCA automatically cancels any existing CSIDs associated with the group (whether for shared devices or devices associated with individual members of the group). Click on new onboard device Yes (only the group representative can initiate the onboarding of devices, . including those of members) No.
Yes (must mention the TIN to be linked to the entity; Organization . The name of the entity must be the TIN of the tax group member). Show list of devices Yes Yes (only for the first 90 days (can be set) from the date they join the group).
Common Onboarding/CSID related scenarios faced by Taxpayers
- Centralized Server - On Premise or Cloud
- Branch Based Smart POS Devices Issuing and Sending Invoices
- Branch Based Standard POS Devices with Branch Servers and Centralized Sending Server
- POS Devices Unable to Sign Invoices
In the case of dumb POS terminal devices that issue invoices and send them to a Taxpayer server, which will send the invoices to the ZATCA electronic invoicing APIs for clearance - then the server must stamp the invoices and apply the QR code before presenting the bill to customers from the POS. In this case, the POS device does not need to have its own CSID, and the CSID can be on the server that stamps and applies the QR code to simplified (B2C) receipts. It is important to note that the standard (B2B) documents are still expected to be submitted before the transaction is completed as the Buyer is expected to receive a valid document which has been cleared by ZATCA.
Reporting and Clearance of e-invoices
- Introduction and Objectives of Reporting and Clearance
- Reporting and Clearance Overview
- Description of the Reporting and Clearance Processes
- Reporting
- Clearance
The sharing of e-invoices, credit or debit notes between Seller and Buyer occurs outside of this interaction, which is not controlled by ZATCA. Exception handling that provides some tolerances to the results of the validations by treating some errors as warnings without rejecting the submitted document completely. In addition, for invalid documents, the FATOORA platform generates a hash of the entire document including UBL extensions and stores this as a reference and as a comparison point.
A document's previous document hash (PDH) must always be equal to the hash of the last document generated before submission. Accordingly, ZATCA's e-invoicing rules allow the taxpayers (sellers) to submit their simplified (B2C) documents within 24 hours of the transaction being completed. Seller must include its cryptographic stamp and QR code as part of the submission.
Accepted with one or more warnings and the Fotoora platform Stamps the documents and includes/updates the QR code as part of the API response along with list and details of the warnings. Seller may optionally include its cryptographic stamp and QR code as part of the submission.
Signing Process
- SHA-256 Hash - Hashing algorithm
- Signing steps
Generate Invoice Hash
Generate Digital Signature
Generate Certificate Hash
Populate the Signed Properties Output 1. Open the original invoice (not updated in Step 1)
Generate Signed Properties Hash
Populate The UBL Extensions Output 1. Use the invoice XML file acquired from Step 4
- QR code
- TLV - TAG - LENGTH - VALUE construction and file format
- Creation of TLV QR code
Generate the public key: openssl ec -in PrivateKey.pem -pubout -conv_form compressed -out PublicKey.pem. It is mandatory to generate and print the QR code encoded in Base64 format with up to 700 characters that must contain the fields specified in the table below according to Appendix (2) of the Controls, Requirements, Technical Specifications and Procedural Rules for the Implementation of the Provisions of E-Invoicing Regulation. The QR code fields will be encoded in Tag-Length-Value (TLV) format with the tag values specified in the "Tag" column of the adjacent table.
Length: The length of the byte string is the result of the UTF8 encoding of the field value. Type/Tag-Length-Value (TLV) is an encoding scheme used in many communication protocols to encode data. The tag/type and length are fixed sizes of 1 byte, and the value is of variable size.
XML Elements for QR code
The hex representation
Common mistakes in building the QR code
Manual decoding a TLV QR Code
If you use a TLV decoder to split the record, the hex values are displayed. These can then be decoded using a hex-to-string decoder.
Creation of QR code in JAVA - Javascript - nodeJS
Once all the messages are added to the builder, convert them to bytes (see 1), which gives you a Uint8List (Darts byte[] method), then encode the list to Base64 using an instance of the Base64Encoder class (see 2).
SDK validation
Business FAQs
The hash value of the previous document as the hash value of the document that was created immediately before the resubmitted document, rather than the document that was. In this case, the hash value of the previous document of the resubmitted document must be the hash value of document 3. Taxpayers can also use the portal to view a summary list of all their built-in EEC units together with specific information about the EEC unit available as part of the certificate.
In the case of VAT groups, the Organizational Unit Name which is a field in the Certificate Signing Request (CSR) must contain the 10-digit TIN number of the individual. Please refer to Section 3.3.3 of the Taxpayer User Manual for more details on the CSR fields and the. Possible CSR failure situations including inserting the wrong algorithm, providing invalid values, missing information, entering the wrong format or including expired/invalid OTP (note that the OTP is provided in the API header) .
Furthermore, the compliance CSID is generated by the e-invoice platform itself and not by ZATCA CA, as it is only used to ensure EGS compliance with ZATCA. All data fields visible on the human-readable form of the invoice must be in Arabic.
Appendix
Glossary
