TIN
Is the tax number or VAT number ( most users use this 90% of entry because zatca issue that number )
CRN.
The commercial registration number is rarely used around 5% of users use that.
A very important note on Phase 1 and also on phase2
The code responsible for generating the QR code in Phase 1
zatca_erpgulf/zatca_erpgulf/create_qr.py
contains
vat_amount = str(doc.total_taxes_and_charges)
This means that the field “Total Taxes and Charges” is considered the tax amount.
In most cases, this field is the tax amount, but it is incorrect to rely on it because the “Total Taxes and Charges” field is used for tax + fees. In other words, in some cases, it may contain additional fees or deductions on the invoice.
A more accurate solution is to rely on the “Sales Taxes and Charges” subtable
and rely on the contents of “Account Head” and “Rate”
so that the system selects only the VAT item from the table.
This should include a warning message if an item contains a percentage but does not contain VAT, informing the customer that they must add the VAT suffix to the account name, or the system will consider the tax to be zero if they continue.
To achieve this
replace
"vat Amount
vat_amount = str(doc.total_taxes_and_charges)
tag = bytes([5]).hex()
length = bytes([len(vat_amount)]).hex()
value = vat_amount.encode(“utf-8”).hex()
tlv_array.append(“”.join([tag, length, value]))
"
With this code
"# VAT Amount - Detect single tax line that contains ‘VAT’, ‘TAX’, or ‘ضريبة’
matched_taxes =
for tax in doc.get(“taxes”, ):
description = (tax.get(“description”) or “”) + " " + (tax.get(“account_head”) or “”)
description_lower = description.lower()
if any(keyword in description_lower for keyword in [“vat”, “tax”, “ضريبة”]):
matched_taxes.append(tax)
if len(matched_taxes) > 1:
frappe.throw(
_(“
Multiple tax lines found matching ‘VAT’, ‘TAX’, or ‘ضريبة’.\n”
“Only one tax line should match these keywords to ensure correct VAT calculation in the QR Code.”)
)
elif len(matched_taxes) == 1:
vat_amount = str(matched_taxes[0].get(“tax_amount_after_discount_amount”, 0.0))
else:
vat_amount = “0.00”
frappe.msgprint(
_(“
No tax line found containing ‘VAT’, ‘TAX’, or ‘ضريبة’.\n”
“VAT amount has been set to 0.00 in the QR Code.\n”
“To resolve this, add one tax line that includes one of these keywords in its description or account head.”),
alert=True
)
tag = bytes([5]).hex()
length = bytes([len(vat_amount)]).hex()
value = vat_amount.encode(“utf-8”).hex()
tlv_array.append(“”.join([tag, length, value]))
"
The same applies to data that must be sent to Phase 2 on files (tax_data, tax_data_with_template, tax_data_nominal,sign_invoice_first.py).
Note that if the customer does not use the Item Tax Template, the tax value will be zero when reading the QR code. The system must check the tax table before giving a zero value.
This way, the system will also become more intelligent.
There’s no need to add the “ZATCA Tax Category” field, as the system can read the rate from the same table.
Also, based on the result, if the rate is zero, the system can make the “Exemption Reason Code” field mandatory, as it is actually required if the rate is zero or if there is no tax in the table.
Incorrect tax value when scanning the QR code If there is a discount
Incorrect Vat detected in the tax amount listed in the QR Code.
If there is Discount :
Apply Additional Discount On (Additional Discount Amount)
The system calculates the tax value while ignoring the deduction.
Dear ERPGulf Team,
I hope you’re doing well.
We are currently using the ZATCA ERPgulf app, and we’ve encountered a recurring issue when attempting to customize the Sales Invoice form, the system throws the following error:
Sales Invoice: Options Zatca Multiple Setting must be the same as doctype name ZATCA Multiple Setting for the field Zatca POS Machine name
Please note:
- We are not creating or modifying these fields.
- We are simply using Customize Form to hide some of the ZATCA-related checkboxes that are not relevant for most users.
Could you kindly advise if there’s a safe way to hide these fields without triggering this error?
Alternatively, if these fields are system-protected, would it be possible for you to expose them as customizable so we can safely control their visibility?
Thank you in advance for your support.
In the Sales Invoice Doctype, the field ZATCA POS Machine name (fieldname: custom_zatca_pos_name) is a Link field that allows selecting a record from another Doctype.
This field is explicitly configured to link only to the Doctype named ZATCA Multiple Setting.
If a user attempts to link a record from a different Doctype, or if the Doctype name ZATCA Multiple Setting is renamed or altered, the system will raise an error — because it expects a valid reference to that specific Doctype.
Hello,
why getting this message when I prepare POS invonice and close the shift, there no discount in the invoice:
Errors:
BR-S-06: In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ‘Standard rated’ the Document level allowance VAT rate (BT-96) shall be greater than zero.
BR-KSA-84: The Document level allowance VAT rate (BT-96), Document level Charge VAT rate (BT-103), VAT category rate(BT-119), Invoiced item VAT rate (BT-152), Prepayment VAT rate(KSA-34) must be limited to one of the following values (5 or 15) when the relevant Document level allowance VAT category code (BT-95), Document level Charge VAT category code(BT-102), VAT category code(BT-118), Invoiced item VAT category code(BT-151), Prepayment VAT Category Code (KSA-33) is “S“- “Standard rated”. In other words, for Standard Rate VAT Category the rate can either be 15% or 5%.
Warnings:
BR-CO-17: VAT category tax amount (BT-117) = VAT category taxable amount (BT-116) x (VAT category rate (BT-119) / 100), rounded to two decimals.
BR-S-09: The VAT category tax amount (BT-117) in a VAT breakdown (BG-23) where VAT category code (BT-118) is ‘Standard rated’ shall equal the VAT category taxable amount (BT-116) multiplied by the VAT category rate (BT-119).
Thanks
