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
Hello,
Thank you for your message.
Kindly share the invoice data details along with the generated invoice XML. This will help me review the issue accurately and understand how the error is occurring. Only then will it be possible to provide you with a proper and effective solution.
Best regards,
Husna
Project Manager
Bug Fix: Negative <cbc:TaxAmount> in Credit Notes for ZATCA XML
Hi team,
We recently fixed a bug in our ZATCA e-invoicing integration (ERPNext) where return invoices (credit notes) were generating negative <cbc:TaxAmount> values in the XML.
As per ZATCA requirements, all monetary amounts — including tax values — must remain positive. The credit nature of the document is already represented by the document type (e.g., 381 for credit notes), so the tax amount itself should not be negative.
Fix Summary:
- Ensured
<cbc:TaxAmount>,<cbc:TaxInclusiveAmount>, and other related fields always use positive values. - Adjusted logic to rely on the invoice type to indicate return/credit instead of using negative amounts.
Thanks!
Hello,
We are facing an issue with the ERPgulf app where we are unable to make any modifications to the Sales Invoice fields.
Whenever we try to save, we receive the following message:
“Sales Invoice: Options Zatca Multiple Setting must be the same as doctype name ZATCA Multiple Setting for the field Zatca POS Machine name.”
This error appears even if we simply open the Sales Invoice customization screen and click Update without making any changes.
Please advise on how to resolve this issue.
Thank you,
We cannot replicate this error. Please send your contact details to support@erpgulf.com , someone from our team will contact you for remote access.
ZATCA validating CRN , TIN , VAT etc. Make sure you have 10 Digits number.
If B2C and no customer information, select OTH.
Please test and reply
ZATCA validating CRN , TIN , VAT etc. Make sure you have 10 Digits number.
If B2C and no customer information, select OTH.
Please test and reply
Thanks for your fast reply.
Could you connect my system by any desk app to make sure?
Or guide me in more detail on which doctype to check.
ON Customer doctype you can set it
It’s worked for some
Could you explain to me what happened and why this error appears at this time, not before
This is the activity history of changes in the customer
ZATCA started to validate Customer-ID from yesterday.
What does it mean?
Did the system work well and still and the issue from the ZATCA?