Seller and Buyer VAT should not be same. Thats internal invoicing and need not submit to ZATCA
How can I exclude such transactions when submitting the invoice so that this error does not appear?
I have set the system to send invoices to ZATCA automatically after submission.
On the new update, internal invoices will not submit to ZATCA. Pls update your app.
This is our new update ,that already mentioned in post about the same vat for customer and company is Intra-Company Transfer Handling
These invoices are not submitted to ZATCA; they remain in ERPNext as normal submissions without generating XML or QR codes.
- We implemented logic that automatically detects when a company sells to itself (i.e., the Company Tax ID and Customer Tax ID are the same) and marks the invoice as an intra-company transfer.
- When the company and customer tax IDs match, the invoice’s ZATCA status and full response are updated accordingly:
ZATCA Status:Intra-company transfer
ZATCA Full Response:Intra-company transfer
1 Like
Hi @Support-at-ERPgulf,
We are using your app for zatca and followed all the requirements stated in this forum, but still wont be able to get compliance check in place for standard invoice under company>Zatca doctype.
We tried customer address in place, VAT Rules, Sandbox CSR provided as well as live CSR,
Upon generating final CSID, we receive:
Message
Error in production:
Error in production CSID formation: Error in production:
Appreciate your support. Thank you!
We have contacted the Zakat, Tax and Customs Authority, and they confirmed that simplified invoices are issued between a company and an individual, while standard invoices are issued between two companies
1 Like
I encountered an issue while sending a Sales Invoice to the ZATCA through the ERPgulf integration with ERPNext.
The UUID was successfully received from ZATCA; however, the QR code was not generated or displayed in the invoice within the system.
Could you please advise what should be done in this case?
Is there a button or script that can be used to fetch the QR code again based on the existing UUID?
If there is an API endpoint or a specific method to re-request the QR from ZATCA, please share the details.
Thank you for your assistance.
which type of invoice simplified or standard?Was the invoice submitted to ZATCA without any errors? Also, is the XML attached to the invoice?
Type: Standard Invoice
Was the invoice submitted to ZATCA without any errors? Yes, without any errors.
Is the XML file attached to the invoice? No.
“SUCCESS: Status Code: 200ZATCA Response: {“validationResults”:{“infoMessages”:[{“type”:“INFO”,“code”:“XSD_ZATCA_VALID”,“category”:“XSD validation”,“message”:“Complied with UBL 2.1 standards in line with ZATCA specifications”,“status”:“PASS”}],“warningMessages”:,“errorMessages”:,“status”:“PASS”},“clearanceStatus”:“CLEARED”,"…………….
What should I do in this case?
**We have explained the procedure here
How to recover ZATCA QR code and XML from Zatca reponse - in case you missed it**
1 Like
Two new major addition on ZATCA ERPGulf module.
1- ZATCA Debit Note Handling in Sales Invoices
This update introduces Debit Note handling within Sales Invoices for ZATCA compliance.A Debit Note (Invoice Type Code 383) can now be submitted through the same process as Sales Invoices, with proper reference to the original invoice and inclusion of explanatory fields.
2- Revised ZATCA ERPgulf Event Log – API Response Handling
The ZATCA ERPgulf Event Log Doctype is designed to manage and track all ZATCA API submissions for Sales Invoices, Credit Notes, and Debit Notes. It supports Standard, Simplified, Credit Note, and Debit Note types and records submissions across background jobs, batches, and live API calls. The Doctype captures response status, titles, API messages, and submission timestamps for auditing, monitoring, and troubleshooting purposes
Pls update from our GitHub Repo
Dear ERPGulf Team,
I am writing to inquire if the ZATCA Phase 2 Advance Payments workflow is currently handled and fully implemented in the ERPGulf solution, specifically as detailed in the ZATCA guidelines (ZATCA Advance Payment (2).pdf).
If this feature is already available, could you please provide details or documentation on how to map the following required fields in ERPNext/ERPGulf Zatca app? specifically:
-
Advance Invoice Generation:
- Does/How the system allow us to generate an invoice with Invoice Type Code (BT-3) = 386 (Prepayment Invoice)?
-
Subsequent (Final) Invoice Adjustment:
-
referencing: How do we link the previous Advance Invoice to the Final Invoice? Does the system automatically populate the AdditionalDocumentReference with the Advance Invoice’s IRN (BT-1), Issue Date, and set the Document Type Code (KSA-30) to 386?
-
Prepaid Amount (BT-113): Is there a specific field to enter the total prepaid amount (Inclusive of VAT)?
-
VAT Breakdown (KSA-31 & KSA-32): The standard requires a consolidated breakdown of the adjusted advance amount per VAT category (Taxable Amount and Tax Amount). Is this calculated automatically when we link an advance payment?
-
If this is not yet implemented, could you please let us know the expected timeline for this feature?
Thank you for your support.
Subject: ZATCA Phase 2 Advance Payment Sales Invoice – ERPNext/ERPGulf
Dear Usman,
Regarding your inquiry about handling ZATCA Phase 2 Advance Payments in ERPGulf, here is the workflow and XML mapping:
1. Advance Sales Invoice Creation
-
During the creation of an Advance Sales Invoice, the invoice is submitted to ZATCA as a prepayment invoice.
-
The total prepaid amount is automatically captured in the XML using:
<cbc:PrepaidAmount currencyID="currency">amount</cbc:PrepaidAmount>
2. Linking Advance Invoice to Final Invoice (Subsequent Adjustment)
- When generating the final invoice, the system automatically fetches the details of the previously created advance invoice and links it using:
<cac:DocumentReference>
<cbc:ID>[Advance Invoice ID]</cbc:ID>
<cbc:UUID>[Advance Invoice uuid]</cbc:UUID>
<cbc:IssueDate>[Advance Invoice Date]</cbc:IssueDate>
<cbc:DocumentTypeCode>386</cbc:DocumentTypeCode>
</cac:DocumentReference>
- This ensures the final invoice correctly references the prepayment and complies with ZATCA requirements.
3. VAT Breakdown (KSA-31 & KSA-32)
-
ERPNext/ERPGulf automatically calculates VAT per item, for both advance and final invoices.
-
The VAT amounts are included in the XML under
<cac:TaxTotal>and<cac:TaxSubtotal>. Example:
<cac:TaxTotal>
<cbc:TaxAmount currencyID="SAR">tax amount of item</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="SAR">item taxable amount</cbc:TaxableAmount>
<cbc:TaxAmount currencyID="SAR">tax amount of item</cbc:TaxAmount>
<cac:TaxCategory>
<cbc:ID>tax id</cbc:ID>
<cbc:Percent>tax rate</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>
Summary:
-
Advance invoice: captures
<cbc:PrepaidAmount>automatically. -
Final invoice: links to the advance invoice via
<cac:DocumentReference>. -
VAT: automatically calculated per item and reflected in
<cac:TaxTotal>and<cac:TaxSubtotal>.
This workflow ensures full compliance with ZATCA Phase 2 for advance payments and final invoice adjustments.
Best regards,
Husna
Project Manager ERPGulf
Dear ERPGulf Team,
Thank you for your previous clarifications and the detailed explanation regarding the Advance Payment workflow.
While implementing this workflow, I analyzed the zatca_erpgulf codebase—particularly create_xml_final_part.py and advance_payment.py—and found a few technical blockers that I need clarification on:
1. Missing DocType: “Advance Sales Invoice”
The code in advance_payment.py explicitly tries to fetch a DocType named “Advance Sales Invoice”, but:
-
This DocType is not included in the open-source repository.
-
It is not created automatically during installation.
-
I do not see any JSON definition for it in the app.
2. Missing Hook for Advance Payment Logic in zatca_erpgulf
In hooks.py, I only see the trigger for standard invoice signing:
"Sales Invoice": "zatca_erpgulf.events.sign_invoice"
But nothing appears to invoke advance_payment.py.
-
The
hooks.pyfile inzatca_erpgulfdoes not contain anyon_submitevent for “Advance Sales Invoice”. -
Dependency Findings: I see that the “claudion4saudi” app supplies both this DocType and the necessary hook (which points back to
zatca_erpgulf.zatca_erpgulf.advance_payment.zatca_background_on_submit).
3. Dependency on the “claudion4saudi” App
I also noticed that key parts of the Advance Payment logic are wrapped in conditions like:
if "claudion4saudi" in frappe.get_installed_apps():
This includes:
-
XML generation for linking the final invoice to the advance payment
-
Handling the
<cac:DocumentReference>for prepayments -
Reading values from child tables (e.g., custom_advances_copy)
Questions:
-
Is installing the claudion4saudi app mandatory for Advance Payment support?
-
If I choose to keep using only the open-source zatca_erpgulf, is it valid to:
-
Manually create the Advance Sales Invoice DocType, and
-
Add the custom_advances_copy child table in Sales Invoice, so that the workflow can function without the dependency?
-
Or does claudion4saudi contain additional hidden logic needed for this workflow that would cause a manual setup to fail?
Looking forward to your clarification so I can complete the implementation correctly.
-
Best regards,
The doctype coming other app called advance-payment. We kept it seperate as almost noone use this feature, and it will make things complicated to ZATCA regular installations. @Husna
will publish after sometime. some issue with doc