Integration with ZATCA Fatoora Platform

Objectives

This guide provides step-by-step instructions on integrating Lexzur with the ZATCA Fatoora platform, covering:

• Prerequisites
• Enabling integration
• Testing the Environment
• Moving to production.

Steps:

Prerequisites and Requirements 

Before starting the integration process, ensure the following requirements are met for seamless invoice generation and integration with the Fatoora portal:

• Hosting Requirements: Your instance must be hosted on the KSA cloud. If it is not, contact support for the necessary migration.

• KSA Instance Configuration: Your instance should be categorized as a KSA instance with e-invoicing enabled.

• ZATCA Invoice Templates: Ensure you have your own ZATCA-compliant invoice templates available.

• Entity Details: All entity details within Lexzur must be completed, including addresses and tax numbers, as required by ZATCA. 

• Client Information:

  • Company Clients: Must have a tax number or commercial registration number.

  • Individual Clients: Must have a national ID number, residency permit number, or passport number.

  • Foreign Clients: Must provide a commercial registration number.

  • Government Entities: Must have a tax number.

  • NGOs under Government Entities: Must provide the ministry’s tax number and the associated 700 number.

Required Fields for Entity or Contact Details

• Company Name: Enter the official registered name as per the commercial registration document.

  • Example: "Advanced Solutions Ltd."

• VAT Registration Number: A unique 15-digit number issued by ZATCA for VAT-registered entities. (Must contain exactly 15 digits - It generally starts with “3”- must be numeric - no spaces or special characters)

  • Example: 355555555500003

• Building Number: A 4-digit numeric identifier for the company’s location.  (Must be exactly 4 digits - must be numeric - leading zeroes are acceptable)

  • Example: 2525

• City: The city where the company is located. Enter the city name in lowercase (It must be a text - should not include numbers or special characters)

  • Example: riyadh

• ZIP Code: A 5-digit numeric postal code. (Must be exactly 5 digits - must be numeric - leading zeroes are acceptable)

  • Example: 89567

Enable and Start the Integration 

To comply with e-invoicing regulations, Lexzur allows seamless integration with the Fatoora platform. This ensures that new invoices generated in Lexzur are directly added to the ZATCA system.

Steps to Enable Integration

• Navigate to the Billing Module in Lexzur.

• Open Settings under Configuration, then go to Setup Entities.

• Choose the entity for which you want to activate the integration. 

• Click Activate Integration.

Generate OTP Code

Generate an OTP code from the ZATCA Fatoora platform:

• Log in to your ZATCA account.

• Click on 

  • • Fatoora Simulation Portal ( if you are using the testing integration type "Fatoora Simulation")

    • Fatoora Portal (if you are using the Production Integration type "Fatoora Production")

• Select Onboard New Solution Unit/Device.

• Enter the number of OTP codes required (e.g., 1) and generate the code.

• Copy the generated OTP code.

Complete the Integration in Lexzur 

• Enter the OTP Code obtained from the ZATCA Fatoora platform.

• Select the Integration Type:

  • Fatoora Production (for live invoices)

  • Fatoora Simulation (for testing)

• Client: Specify any client to start the integration.

• Click Save to finalize the integration.

• Once the integration is successfully set up, open any invoice. From the options icon in the top right corner, select Fatoora Simulation to test the integration.

• A success message will confirm that the integration is working correctly.

Moving to Production 

Revoke Previous Integration

If you initially set up the integration for testing:

• Go to Billing Settings → Setup Entities and revoke the prior integration.

• Repeat the setup process, this time selecting Fatoora Production as the integration type. (Repeat the activate integration steps)

Submitting old Invoices to ZATCA

All invoices converted to "Open" after the integration is completed will be automatically reflected in the Fatoora platform.

To submit an old invoice to the ZATCA Fatoora platform, you must manually select each invoice by opening its page and clicking on the "Fatoora Production" option.

• Open any invoice that is not in draft status. (It should be in an open status)

• Click on the Action Wheel, then choose Fatoora Production.

• The invoice will be successfully sent to ZATCA, and its status will update accordingly.

Monitoring Integration Status

• Open the Invoice Grid in Lexzur.

• Add the Integration Type column to the grid.

• This will display which invoices have been successfully sent to ZATCA.

Common Errors and Troubleshooting

Here are some common errors you may encounter when activating the integration or sending invoices to the Fatoora platform, along with their possible causes and how to resolve them.

• Entity name exceeds 64 characters → Shorten the name.

• Client tax number is missing → Ensure all tax-related fields are filled out.

• Special characters in entity name → Remove special characters.

• Invoice is not reflecting in ZATCA → Ensure the invoice is in "Open" status before submitting.

For more information about LEXZUR, kindly reach out to us at help@lexzur.com.

Thank you!