Before you start: what do you need?
Integrating with the FATOORA platform is a small project with defined steps, shared between the accountant and the system administrator. Before you start, confirm four things: that the business knows its wave date, that the technical solution in use supports the Phase 2 requirements, that you have a login to ZATCA's e-services portal with the right permissions, and that you have listed your generation units (EGS Units), meaning every device, branch or point of sale that issues invoices.
Step 1: verification code and certificate
- Log in to the FATOORA portal through ZATCA's e-services.
- Choose to generate a one-time verification code (OTP), and specify the number of units you want to onboard; each unit has its own code.
- Enter the code in the unit's technical solution; the solution creates a certificate signing request and sends it to the platform.
- The platform issues an initial compliance certificate, then the solution runs the compliance checks, and once they pass it obtains the production certificate (Production CSID) used to stamp the actual invoices.
Step 2: test every document type
One successful invoice is not enough. You must confirm that the solution issues every type of document the business actually uses. The following table is a typical test matrix for a business that sells to both individuals and businesses:
| # | Document | Type | Mechanism | Example value |
|---|---|---|---|---|
| 1 | Invoice | Tax | Clearance | 10,000 + 1,500 VAT |
| 2 | Credit note (return) | Tax | Clearance | 2,000 + 300 VAT |
| 3 | Debit note (price difference) | Tax | Clearance | 500 + 75 VAT |
| 4 | Invoice | Simplified | Reporting | 460 including VAT |
| 5 | Credit note | Simplified | Reporting | 115 including VAT |
| 6 | Debit note | Simplified | Reporting | 57.50 including VAT |
For the notes, make sure they refer to the original invoice number and the reason for issue, and that the amounts are calculated correctly: the credit note in line 5, for example, equals 100 SAR before VAT and 15 SAR VAT.
Step 3: go-live and monitoring
Once you have the production certificate, real issuing begins. Every invoice carries an invoice counter (ICV) and the hash of the previous invoice (PIH), so the invoices form a connected chain. Example: the invoice with counter 101 carries the hash of invoice 100, and invoice 102 carries the hash of invoice 101. That is why deleting or editing any invoice after issue is prohibited.
Check the status dashboard in the technical solution daily:
- Cleared / reported: No action needed.
- Accepted with warnings: The invoice is valid, but fix the cause of the warning in future invoices.
- Rejected: Needs immediate action.
- Pending submission: Usually due to a lost connection; make sure it is sent within the time limit.
Handling rejected invoices
A rejected tax invoice is not a valid invoice and is not delivered to the customer. Common causes: an incorrect buyer VAT number, an incomplete national address, a VAT calculation error at line level, an illogical date, or an expired certificate. The practical procedure:
- Read the error message returned by the platform and identify the field causing it.
- Correct the master data (the customer record, for example), not just the invoice, so the error does not recur.
- Reissue the invoice, send it for Clearance, and then deliver it to the customer.
- Log the case in a tracking file; repeated rejections of a certain type point to a setup problem.
Roles in the integration team
In small businesses one person plays several roles, but it helps to make responsibilities clear:
- Accountant: Identifies the document types in use, checks that VAT is correct on test invoices, and reconciles the first sales report after go-live with the records.
- System administrator or provider: Enters the verification codes, keeps track of the certificates, and resolves connection errors.
- Branch or sales manager: Makes sure business customer details are up to date, and trains cashiers to choose the right invoice type.
- The person with authority on the ZATCA portal: Generates verification codes when needed and follows ZATCA's notifications.
Make the first week after go-live a week of close monitoring: review each day the number of invoices issued, the number cleared and reported, the number rejected, and the reasons for rejection. For example, if a branch issued 300 invoices in a day and 6 were rejected, the rejection rate is 2%, and it is important to find out whether the six share one cause that can be fixed once.