Fix ZATCA validation errors
Find the ZATCA rule behind a rejected Saudi invoice and correct it. Start with the document type you sent and the errors returned by Unify or ZATCA.
A Saudi invoice is checked three times: Unify checks the GETS request, then the e-invoice built from it, then ZATCA checks the e-invoice when it clears or receives the report. The rule IDs come from ZATCA’s XML Implementation Standard: BR-KSA-* rules are ZATCA’s own, and BR-* rules come from EN 16931, the European invoice standard ZATCA builds on.
Check the GETS request
Select Saudi Arabia and the document type in the field reference. The Requirement column shows which GETS fields are mandatory, optional or conditional. In List with sample request, choose the document type and inspect the fields for that selection. Use values from the invoice and the company’s registration records.
Read a 422 response
A 422 response from Unify lists each failed rule in errors. code is the rule ID, getsPath names the GETS field to correct and message describes the rule. Correct the source data, then send the document again. See Unify errors for the response format.
If the e-invoice built from your request fails a ZATCA rule, the 422 has validationStage set to xml and an empty errors list. Get the document by its documentId to see the rule IDs in its errors.
Read ZATCA’s result
After the 200, follow the document until isTerminal is true. final_valid means ZATCA cleared the standard invoice or accepted the report of a simplified invoice. final_invalid means ZATCA rejected it: government.status is REJECTED, and government also holds ZATCA’s validation messages with their rule IDs. Correct the invoice and send it as a new document.
Keep the original tax and amount values supplied by the issuer. Do not replace missing values with guessed ones.
Every rule Unify checks
These are the 87 rules Unify applies to a Saudi GETS request, with the message you get back and the field it points at. Applies to shows the document types, modifiers or variant each rule belongs to. Search by the code from a 422 response or by a word from the message. ZATCA’s own checks after submission follow the same BR-KSA-* rules.
87 of 87 rules
| Rule | What it checks | Field | Applies to |
|---|---|---|---|
BR-CL-KSA-14 | QR code field length must be between 1 and 1000 characters. | extensions.sa_qrCode | Every document type |
BR-KSA-03 | Invoice must contain a UUID (KSA-1) using letters, digits, and dashes. | header.uuid | Every document type |
BR-KSA-04 | Document issue date (BT-2) must be less than or equal to current date. | header.issueDate | Every document type |
BR-KSA-07 | Self-billing is not allowed for export invoices. | header.documentType | Modifier self_billed |
BR-KSA-08 | Seller identification (BT-29) must exist once, use one of CRN, MOM, MLS, SAG, OTH, 700, and be alphanumeric. | parties.seller.registrationNumbers | Every document type |
BR-KSA-09 | Seller address must contain street, building number, postal code, city, district, and country code. | parties.seller.address | Every document type |
BR-KSA-10 | If buyer country is not SA, buyer address must contain street, city, and country code; does not apply to simplified documents. | parties.buyer.address | Every document type |
BR-KSA-11 | If line VAT category is O, line VAT rate must be 0 if present. | lineItems | Every document type |
BR-KSA-12 | If document allowance VAT category is O, allowance VAT rate must be 0 if present. | allowancesAndCharges | Every document type |
BR-KSA-13 | If document charge VAT category is O, charge VAT rate must be 0 if present. | allowancesAndCharges | Every document type |
BR-KSA-14 | If buyer is not VAT registered, buyer identification (BT-46) is required with an allowed scheme from TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS, OTH. | parties.buyer.registrationNumbers | Every document type |
BR-KSA-16 | If payment means code (BT-81) exists, it must come from the allowed UNTDID 4461 subset. | payment.paymentMeans | Every document type |
BR-KSA-17 | Credit notes (381) and debit notes (383) must contain note issuance reason (KSA-10). | header.noteIssuanceReason | Credit note, debit note, simplified credit note, simplified debit note |
BR-KSA-18 | VAT category code must be one of S, Z, E, O. | taxTotals | Every document type |
BR-KSA-19 | Each document-level charge should have a charge reason code (BT-105). | allowancesAndCharges | Every document type |
BR-KSA-20 | Each line charge should have a charge reason code (BT-145). | lineItems | Every document type |
BR-KSA-21 | Each document-level charge should have a charge reason (BT-104). | allowancesAndCharges | Every document type |
BR-KSA-22 | Each line charge should have a charge reason (BT-144). | lineItems | Every document type |
BR-KSA-23 | Exempt from VAT VAT breakdowns should have VAT exemption reason code. | taxTotals | Every document type |
BR-KSA-24 | Not subject to VAT VAT breakdowns should have VAT exception reason code. | taxTotals | Every document type |
BR-KSA-27 | Simplified invoice documents must contain a QR code (KSA-14) encoded as base64 text. | extensions.sa_qrCode | Simplified invoice, simplified credit note, simplified debit note |
BR-KSA-31 | Self-billing is not allowed for simplified invoices and associated simplified notes. | header.documentType | Modifier self_billed |
BR-KSA-33 | Invoice must contain invoice counter value (KSA-16). | extensions.sa_icv | Every document type |
BR-KSA-34 | Invoice counter value (KSA-16) must contain digits only. | extensions.sa_icv | Every document type |
BR-KSA-35 | If supply end date (KSA-24) exists, supply date (KSA-5) must also exist. | header.invoicePeriod | Modifier continuous_supply |
BR-KSA-36 | If supply end date exists, it must be greater than or equal to supply date. | header.invoicePeriod | Modifier continuous_supply |
BR-KSA-37 | Seller building number must contain 4 digits. | parties.seller.address.additionalAddressData.buildingNumber | Every document type |
BR-KSA-39 | Invoice must contain seller VAT registration number or seller group VAT registration number (BT-31). | parties.seller.taxIds | Every document type |
BR-KSA-40 | If present, seller VAT registration number must contain 15 digits and start/end with 3. | parties.seller.taxIds | Every document type |
BR-KSA-42 | Buyer name must be present in tax invoices and associated notes. | parties.buyer.name | Every document type |
BR-KSA-44 | If present, buyer VAT number must contain 15 digits and start/end with 3. | parties.buyer.taxIds | Every document type |
BR-KSA-51 | Line amount with VAT (KSA-12) must equal line net amount plus line VAT amount. | lineItems | Every document type |
BR-KSA-52 | Line VAT amount (KSA-11) is mandatory for tax invoices and associated notes. | lineItems | Tax invoice |
BR-KSA-53 | Line amount with VAT (KSA-12) is mandatory for tax invoices and associated notes. | lineItems | Tax invoice |
BR-KSA-56 | Credit notes and debit notes must contain billing reference ID (BT-25). | header.referenceId | Credit note, debit note, simplified credit note, simplified debit note |
BR-KSA-60 | Simplified invoices and associated simplified notes must contain a cryptographic stamp (KSA-15). | extensions.sa_digitalSignature | Simplified invoice, simplified credit note, simplified debit note |
BR-KSA-63 | If buyer country code is SA, buyer address must contain street, building number, postal code, city, district, and country code. | parties.buyer.address | Every document type |
BR-KSA-66 | Seller postal code must be 5 digits. | parties.seller.address.postalCode | Every document type |
BR-KSA-67 | If buyer country code is SA, buyer postal code must be 5 digits. | parties.buyer.address.postalCode | Every document type |
BR-KSA-68 | Tax currency code (BT-6) must exist. | header.taxCurrency | Every document type |
BR-KSA-69 | Zero rated VAT breakdowns should have VAT exception reason code. | taxTotals | Every document type |
BR-KSA-71 | Simplified summary invoices must contain buyer name. | parties.buyer.name | Modifier summary |
BR-KSA-72 | Simplified summary invoices must contain supply date and supply end date. | header.invoicePeriod | Modifier summary |
BR-KSA-73 | If prepaid amount exists, invoice must provide prepayment line references including prepayment ID, issue date/time, and document type code 386. | extensions | Variant prepayment |
BR-KSA-74 | Prepayment document type code (KSA-30) on invoice-line document reference must be 386. | extensions.sa_prepaymentTypeCode | Variant prepayment |
BR-KSA-75 | If prepayment document type code exists, prepayment taxable amount, tax amount, tax category code, and tax rate are mandatory on that line. | extensions | Variant prepayment |
BR-KSA-76 | If prepayment VAT category is Zero rated, prepayment VAT rate must be 0. | extensions.sa_prepaymentTaxRate | Variant prepayment |
BR-KSA-77 | If prepayment VAT category is Exempt from VAT, prepayment VAT rate must be 0. | extensions.sa_prepaymentTaxRate | Variant prepayment |
BR-KSA-78 | If prepayment VAT category is Not subject to VAT, prepayment VAT rate must be 0. | extensions.sa_prepaymentTaxRate | Variant prepayment |
BR-KSA-79 | Prepayment VAT tax amount must equal taxable amount multiplied by prepayment VAT rate divided by 100. | extensions | Variant prepayment |
BR-KSA-80 | Prepaid amount must equal prepayment taxable amount plus prepayment tax amount. | totals.prepaidAmount | Variant prepayment |
BR-KSA-81 | For tax invoices and associated notes, if buyer VAT number is not provided, another buyer ID must be provided. | parties.buyer | Tax invoice |
BR-KSA-83 | Z, E, or O VAT breakdowns should have Saudi-specific VAT exemption/exception reason text. | taxTotals | Every document type |
BR-KSA-84 | Standard-rate VAT percentages may only be 5 or 15 across allowance, charge, subtotal, line, and prepayment contexts. | taxTotals | Every document type |
BR-KSA-87 | If tax exchange rate exists, source currency, target currency, and calculation rate must all be present. | header.exchangeRate | Every document type |
BR-KSA-88 | Source currency code (KSA-37) must match invoice currency code (BT-5). | header.exchangeRate.sourceCurrency | Every document type |
BR-KSA-89 | Target currency code (KSA-38) must match tax currency code (BT-6). | header.exchangeRate.targetCurrency | Every document type |
BR-KSA-90 | Tax exchange rate (KSA-39) may have at most 14 digits. | header.exchangeRate.rate | Every document type |
BR-KSA-92 | If transaction type is B2G, contract ID (BT-12) must be present in tax invoices and associated notes. | extensions.sa_contractReference | Modifier b2g |
BR-KSA-97 | If document currency is not SAR, total VAT amount and total VAT amount in accounting currency must not be equal. | totals | Every document type |
BR-KSA-98 | Simplified invoice should be submitted within 24 hours of issue date/time. | header.issueDate | Simplified invoice, simplified credit note, simplified debit note |
BR-KSA-99 | If buyer VAT number exists in tax invoices and associated notes, it should not be left empty. | parties.buyer.taxIds | Every document type |
BR-KSA-CL-03 | Mime code must be from the allowed IANA subset. | supportingDocuments | Every document type |
BR-KSA-CL-06 | Document-level and line-level charge reason codes must use UNTDID 7161. | allowancesAndCharges | Every document type |
BR-KSA-DEC-01 | Allowance percentages must be between 0.00 and 100.00 with at most two decimals. | allowancesAndCharges | Every document type |
BR-KSA-DEC-02 | VAT rates must be between 0.00 and 100.00 with at most two decimals. | taxTotals | Every document type |
BR-KSA-DEC-03 | Line VAT amount (KSA-11) must have at most two decimals. | lineItems | Every document type |
BR-KSA-DEC-04 | Line amount with VAT (KSA-12) must have at most two decimals. | lineItems | Every document type |
BR-KSA-EN16931-02 | VAT accounting currency code (BT-6) must be SAR. | header.taxCurrency | Every document type |
BR-KSA-EN16931-03 | Allowance/charge amount must equal base amount multiplied by percentage divided by 100 when both exist. | allowancesAndCharges | Every document type |
BR-KSA-EN16931-04 | Allowance/charge base amount must be present when percentage is present. | allowancesAndCharges | Every document type |
BR-KSA-EN16931-05 | Allowance/charge percentage must be present when base amount is present. | allowancesAndCharges | Every document type |
BR-KSA-EN16931-08 | Only one tax total with subtotals should be provided. | taxTotals | Every document type |
BR-KSA-EN16931-09 | Only one tax total without subtotals should be provided when tax currency exists. | taxTotals | Every document type |
BR-KSA-EN16931-11 | Invoice line net amount must reconcile from quantity, price, line charges, and line allowances. | lineItems | Every document type |
BR-KSA-EN16931-12 | Base quantity must be above zero. | lineItems | Every document type |
BR-KSA-F-01 | Dates must be formatted YYYY-MM-DD. | header.issueDate | Every document type |
BR-KSA-F-02 | Allowance/charge indicator must correctly use false or true. | allowancesAndCharges | Every document type |
BR-KSA-F-04 | Document amounts and quantities must be positive unless explicitly allowed otherwise. | totals | Every document type |
BR-KSA-F-06-C3 | Purchase order ID (BT-13) maximum length is 127. | extensions.sa_purchaseOrderReference | Every document type |
BR-KSA-F-06-C5 | Contract ID (BT-12) maximum length is 127. | extensions.sa_contractReference | Every document type |
BR-KSA-F-06-C14 | Payment terms (KSA-22) maximum length is 1000 characters. | payment.paymentTerms | Every document type |
BR-KSA-F-06-C15 | Payment account identifier (BT-84) maximum length is 127 characters. | payment.paymentMeans | Every document type |
BR-KSA-F-06-C33 | Document-level charge reason (BT-104) maximum length is 1000 characters. | allowancesAndCharges | Every document type |
BR-KSA-F-06-C34 | Line charge reason (BT-144) maximum length is 1000 characters. | lineItems | Every document type |
BR-KSA-F-06-C35 | Document-level allowance reason (BT-97) maximum length is 1000 characters. | allowancesAndCharges | Every document type |
BR-KSA-F-06-C36 | Line allowance reason (BT-139) maximum length is 1000 characters. | lineItems | Every document type |