ZATCA error and warning code explorer
Paste a code like BR-KSA-44, or the whole FATOORA response, and see what the rule means, which SAP Business One field usually causes it and how to fix it.
Tool
This explorer explains rules published by ZATCA (Zakat, Tax and Customs Authority). It is not an official ZATCA tool and does not replace FATOORA validation or ZATCA's documents, which always prevail. Rule texts are summarized from the XML Implementation Standard v1.2; check the current version on zatca.gov.sa. SAP Business One field mappings are typical mappings; confirm them with your localization. Kodenova is an independent SAP Business One, ERP and AI development studio; SAP and SAP Business One are trademarks of SAP SE.
How to read a ZATCA rejection
FATOORA validates every document against the business rules in ZATCA’s standard. ZATCA’s Detailed Technical Guideline describes three outcomes: valid, accepted with warnings, or rejected. An error means the document is rejected and is not cleared or reported. A warning means it was accepted, but the cause should be fixed for future documents. If one error is present, the whole document is rejected.
The response lists each problem with a code. That code is what this explorer looks up.
The ZATCA codes we see most from SAP Business One
| Code | What it means | Usual SAP B1 cause |
|---|---|---|
| BR-KSA-44 | Buyer VAT number must be 15 digits, starting and ending with 3 | Spaces or a CR number in OCRD.LicTradNum |
| BR-KSA-63 | Saudi buyer address needs street, building number, postal code, city and district | Incomplete BP address (CRD1 / INV12) |
| BR-KSA-37 | Seller building number must have 4 digits | Company address in Company Details |
| BR-KSA-66 / 67 | Seller / Saudi buyer postal code must have 5 digits | ADM1.ZipCode / CRD1.ZipCode |
| BR-KSA-40 | Seller VAT number must be 15 digits, starting and ending with 3 | OADM.TaxIdNum |
| BR-KSA-17 | Credit and debit notes need a reason | No reason captured on the credit memo |
| BR-KSA-56 | Credit and debit notes need the original invoice number | Credit memo not created from the invoice |
| BR-CO-15 | Total with VAT must equal total without VAT plus VAT | Rounding difference in the document total |
| BR-KSA-EN16931-11 | Line amount must equal quantity x price, plus charges, minus allowances | Prices with more decimals than the XML sends |
| BR-KSA-F-03 | No empty elements | Empty SAP fields written as empty XML tags |
The full table has 131 rules with the SAP Business One source and fix for each.
Rule groups explained
- BR: core EN 16931 rules, such as “an invoice shall have an invoice number”.
- BR-CO: calculation rules: line sums, document totals, VAT per category.
- BR-KSA: Saudi rules: VAT number format, national address, invoice counter, previous invoice hash, QR code, credit note reference.
- BR-KSA-DEC: decimals (two decimals for VAT amounts and rates).
- BR-KSA-CL: code lists (ISO currency, VATEX exemption codes, charge reason codes).
- BR-KSA-EN16931: Saudi versions of EN 16931 calculation rules.
- BR-KSA-F: format rules (dates, empty elements, positive amounts, field lengths).
Where these rules come from
Every rule in this explorer was read from ZATCA’s Electronic Invoice XML Implementation Standard, version 1.2 (2023-05-19), section 13, and each row cites its section and pages. The error/warning outcome is described in ZATCA’s E-invoicing Detailed Technical Guidelines, version 2 (November 2022).
What we left out: the VAT category rules (BR-S, BR-Z, BR-E, BR-O), the EN 16931 code list and decimal rules (BR-CL, BR-DEC), and BR-KSA-EN16931-06, whose wording we could not read unambiguously. The standard also does not say which rules FATOORA returns as errors and which as warnings, so we do not guess: your response says which it is.
Fixing a rejected invoice in SAP Business One
Fix the cause in SAP Business One first: the business partner, the company details, the VAT group or the rounding. ZATCA’s guidance treats a corrected document as a new submission with its own invoice counter value, UUID and hash; the rejected document is not edited and resent. Simplified (B2C) invoices that are rejected are corrected and reported again in the same way.
The SAP Business One fields in this table are a typical mapping. Localizations and add-ons store some values (UUID, counter, hash, QR, exemption codes) in their own tables or user-defined fields, so confirm the field with your localization.
To check a whole XML file before you send it, use the ZATCA Phase 2 invoice validator. For background, read ZATCA Phase 2 rejections and how to fix them.
ZATCA e-invoicing with SAP Business One
Kodenova connects SAP Business One to e-invoicing platforms and runs five live e-invoicing systems: ZATCA (Saudi Arabia), SRI (Ecuador), FEL (Guatemala), DTE (El Salvador) and Panama FE. See ZATCA e-invoicing for SAP Business One, our e-invoicing integration service and SAP Business One development.
Related pages
- ZATCA e-invoicing for SAP Business One
- E-invoicing integration
- SAP Business One development
- ZATCA Phase 2 invoice validator
- ZATCA Phase 2 rejections (insight)
- All free tools
This explorer explains rules published by ZATCA (Zakat, Tax and Customs Authority). It is not an official ZATCA tool and does not replace FATOORA validation or ZATCA's documents, which always prevail. Rule texts are summarized from the XML Implementation Standard v1.2; check the current version on zatca.gov.sa. SAP Business One field mappings are typical mappings; confirm them with your localization. Kodenova is an independent SAP Business One, ERP and AI development studio; SAP and SAP Business One are trademarks of SAP SE.
Three steps, no signup
Paste a code or a response
Type BR-KSA-63, search a word like "postal code", or paste the JSON or text your system got back from FATOORA.
Read the rule
Each code shows the rule from ZATCA's standard, a plain explanation in English and Arabic, and the section it comes from.
Fix it at the source
See the SAP Business One field that usually feeds it and what to change before you send a new document.
Questions about this tool
What does BR-KSA-44 mean?
BR-KSA-44 means the buyer VAT number on the invoice is not 15 digits starting and ending with 3. ZATCA applies it whenever a buyer VAT number is sent on a non-export invoice. In SAP Business One the usual cause is spaces, dashes or a commercial registration number in the business partner's tax ID field.
What is the difference between a ZATCA error and a warning?
ZATCA's technical guideline says an error is a validation failure that rejects the document, while a warning is attached to a document that was still accepted. One error is enough to reject the whole document. Warnings should be fixed for future invoices, but the accepted invoice itself stands.
Why does ZATCA reject my invoice for the buyer address?
For Saudi buyers, BR-KSA-63 requires the street, building number, postal code, city and district, and BR-KSA-67 requires a 5-digit postal code. In SAP Business One these come from the business partner address. Add the full national address to the bill-to address and make sure it is copied to the invoice.
Can I correct and resend a rejected ZATCA invoice?
Not as the same document. Fix the cause in SAP Business One, then submit a corrected document with its own invoice counter value, UUID and hash, as ZATCA's guidance describes. The rejected document's counter and hash are not changed or reused, and the previous invoice hash chain continues from it.
Where do these ZATCA rule codes come from?
From ZATCA's Electronic Invoice XML Implementation Standard, version 1.2, dated 19 May 2023, section 13. Each row in the explorer cites the section and pages. We only list rules we could verify in that document, and we mark the SAP Business One field as a typical mapping to confirm with your localization.
Does this tool send my invoice or response anywhere?
No. The search and the code extraction run in your browser, and nothing you paste is sent to Kodenova, ZATCA or anyone else. The tool explains codes; it does not validate a full invoice. For that, use our free ZATCA Phase 2 invoice validator or ZATCA's own compliance tools.
Built for SAP Business One teams
ZATCA rejections from SAP Business One?
We trace each code to the SAP Business One field, fix the master data and the XML mapping, and keep the hash chain intact. Tell us which codes you see.