Announcing the launch of the Saudi Zatca-2 E-Invoicing app on FrappeCloud

[Support-at-ERPgulf]

ERPNext implementation for ZATCA advance invoices . Full documentation here

here

Advance Sales Invoice submission to ZATCA from ERPNext

[shaileshsaini]

Now Working

[UsmanSanawar]

Hello @Support-at-ERPgulf Team,

We encountered multiple problems in the advance payment → final Sales Invoice workflow while testing on our demo server.

The documentation/video example using full-payment cases masks this issue; partial payments as advances are where the behavior fails.

Below is a detailed summary of what we observed in the code, how we tested, the issues we saw, and questions / next steps. Please review and advise.

Summary

• Taxes on Advance Sales Invoices are not consistently applied through the workflow, so final Sales Invoices do not deduct advance taxes correctly. This leads to incorrect outstanding amounts on final SIs.

• Additional concerns: Advance Sales Invoice appears not to create expected GL entries; a Pre Payment Invoice flag on Payment Entry appears unused; several code sections are commented out; UI shows unexpected values (e.g., “Advance Amount” displayed as 115,000 instead of 11,500).

What we noticed in code

• Advance Sales Invoice code:

  • Many validation, GL, and tax-related code blocks are commented out in advance_sales_invoice.py. It’s unclear whether this is intentional for regional customization or an incomplete change.

  • Tax helper methods and apply flow are present but in some runs not executed (comment/uncomment status inconsistent).

  • Some fields (e.g., a company_currency usage) appear to be referenced without guaranteed initialization in all code paths.

• Advance fetcher:

  • The logic that returns advances to the final Sales Invoice appeared to rely on a limited data fetch (returned paid_amount only in some implementations) instead of always reading the Advance SI computed tax fields.

• Payment Entry UI:

  • There is a checkbox Pre Payment Invoice (or pre_payment_invoice) visible, but we did not find code applying any behavior based on its value.

• UI / list rendering:

  • The advances listing sometimes shows a value equivalent to the Sales Order total (115,000), suggesting the wrong field is bound or the display label is confusing.

Exactly how we tested (step-by-step with values)

1. Create Sales Order / Sales Invoice baseline:

   • Base amount: 100,000 SAR

   • VAT: 15% → 15,000 SAR

   • Grand total expected: 115,000 SAR

     

2. Create Advance Sales Invoice (for the Sales Order):

   • Paid Amount = 10,000 SAR (we entered the cash amount only)

   • Tax row added:

     • Charge Type = “On Paid Amount”

     • Rate = 15

     • Add/Deduct = “Add”

     • (Expected tax on advance = 1,500 SAR)

   • Save Advance SI, observed an error initially (AttributeError referencing company_currency) in some runs.

   • Expected on Advance SI: total_taxes_and_charges = 1,500 and tax row tax_amount = 1,500.

     

3. Create Final Sales Invoice and apply advance:

   • Expected final outstanding = 115,000 − (10,000 + 1,500) = 103,500 SAR.

   • Observed final outstanding = 105,000 SAR (only 10,000 deducted).

     

4. UI checks:

   • Advances pane showed a row with “Advance Amount” = 115,000 (likely wrong field).

   • In Payment Entry and Advance SI the Paid Amount field was the base cash amount (10,000), which we believe is correct behavior, tax should be computed and tracked separately.

     

5. Other observations:

   • When editing the tax row manually (entering 1,500 into the tax amount), some UI total columns still showed 115,000 which looked like cumulative or wrong-field values.

Problems observed

• Advance tax not deducted in Final SI: Final SI deducted only base paid amount (10,000); advance tax (1,500) was ignored.

• Advance SI GL behavior unclear: Advance SI does not appear to post tax GL entries; unclear if intended (we need confirmation whether tax GLs should be created at advance time).

• Pre Payment Invoice flag unused: The flag exists in UI but we did not find supporting behavior in the codebase.

• Wrong value shown in Advances list: UI shows 115,000 where it should show advance-specific values such as 10,000 (cash) and 1,500 (tax) or combined 11,500.

• Partial vs full advance case: Documentation/video example uses full advance equal to SO amount (ex. Sales Order 900, Advance 900), this does not reveal the partial-advance bugs we observed. The partial-advance case demonstrates the real issue.

• Incomplete initialization: Some fields like company_currency appeared referenced before guaranteed initialization, causing save-time AttributeErrors.

• Large commented sections: A lot of AdvanceSalesInvoice logic is commented out; this makes it hard to reason about intended behavior.

What we think is likely (our understanding, may be wrong)

• The final deduction should include both cash advance and computed taxes on that cash advance (i.e., deduction = paid_amount + total_taxes_and_charges). If GL entries for tax are not to be created at advance time, tracking taxes on Advance SI and including them in Final SI deduction is still required so outstanding amounts are correct.

Questions for you / requests

1. Accounting intent: When an advance is received, should tax GL entries be posted at Advance SI time, or only when Final SI (or Payment Entry) is submitted/allocated? Please confirm desired accounting flow.

2. Is the large number of commented code blocks in AdvanceSalesInvoice intentional or accidental, including many validation/GL methods are commented out, was this intentional for regional behavior or temporary debugging?

3. The Pre Payment Invoice checkbox on Payment Entry: is there intended behavior wired in another app/module?

Thanks & Best regards,

[Husna]

Hi ,

Are you getting any error messages while submitting this example advance sales invoice and final invoice to Zatca?

Thanks and Regards,

Husna

[UsmanSanawar]

Hi,

We haven’t submitted the invoices to ZATCA yet, as the values currently displayed are not accurate. We are testing this in the demo environment, and once everything is confirmed, it will be implemented on the production servers.

Could you please test the scenario of creating an Advance Sales Invoice with a partial amount (less than 100% payment)? This should help clarify the requirement and the issues we’re currently facing.

Thank you.

[Ashique-tridz]

Hi everyone,

I need help regarding ZATCA integration re-setup for an existing company in ERPNext.

Environment

• ERPNext: v15.62.0

• Frappe Framework: v15.69.1

• Zatca Erpgulf App: v2.1.1 (main branch)

Scenario

We had ZATCA already integrated and working for an existing company (Phase-2).
Later, due to some code-base changes and testing, we:

1. Uninstalled the Zatca Erpgulf app

2. Made required code changes

3. Reinstalled the ZATCA app again

4. Tried to reconfigure ZATCA for the same company / same VAT number

Now, during ZATCA Compliance Check / Invoice submission, we are getting authentication and certificate-related errors.

Error Details (from ZATCA API response)

• X509Certificate (CCSID / PCSID) used for signing is not valid certificate for this VAT Registration Number

• User only allowed to use the VAT number that exists in the authentication certificate

• Reporting Status: NOT_REPORTED

• Status: ERROR

Warnings also include:

• BR-KSA-98 (Simplified invoice submission within 24 hours)

• BR-KSA-F-08 (Buyer ID / CRN value seems incorrect)

But the main blocking issue is certificate / authentication (when running the setup wizard in the simulation envirolment).

What I suspect

Since ZATCA was already onboarded earlier:

• The old certificate / OTP / CSR might still be linked at ZATCA side

• Reinstalling the app and regenerating certificates may have caused a mismatch between VAT number and signing certificate

• Possibly the correct re-onboarding steps were not followed after reinstall

My Questions

1. What is the correct procedure to re-integrate ZATCA for an already onboarded company after uninstalling the app?

2. Should we:

   • Reuse the old Production CSID / PCSID?

   • Or request a new OTP and regenerate CSR?

3. Is there any cleanup required in ERPNext (certificates, ZATCA settings, credentials) before re-onboarding?

4. Has anyone faced this issue after reinstalling ZATCA app and successfully resolved it?

I have attached screenshots of:

• ZATCA Compliance Check dialog

• Full ZATCA API error response

Any guidance from someone who has done ZATCA re-integration for an existing company would be greatly appreciated.

@Support-at-ERPgulf @Husna

[Support-at-ERPgulf]

1-If you are reinstalling app, backup all fields in the zatca configuration page. ( copy to a safe place I mean ) . then after reinstalled, copy it back to the same fields.
2- You can enroll devices as many times to ZATCA portal , its not a problem. Please dont forget to start from create-CSR . Normally everyone miss that step. Clear all fields on the zatca setup page ( except CSR configuration, and star from Create-CSR )

[UsmanSanawar]

@Husna @Support-at-ERPgulf Can you please update us on our issues reported?

[hereabdulla]

ZATCA Advance Invoice

there is a documentation and video tutorial available for ZATCA Advance Invoice but the related doctype is not there in repository @Husna

[Husna]

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.

[Mohamed_AbdelSabour]

Don’t add item tax template on sales order and submited correctly

[UsmanSanawar]

@Husna @Support-at-ERPgulf Hi Team,

I’ve created a pull request to improve the Advance Sales Invoice feature for ZATCA compliance. During implementation, I faced and resolved several key issues:

Issues Faced:

1. Tax calculations not auto-filling - Advance SI was showing paid_amount with tax included, making proportional calculations incorrect

2. Difference amount showing non-zero - Fields were being overwritten by set_amounts() method

3. Sales Order advance tracking missing - SO’s advance_paid field wasn’t updating when Advance SI was created/submitted

4. Code duplication - Duplicate functions and unused code in overrides and hooks

Solutions Implemented:

1. Fixed paid_amount auto-fill - Now uses SO total WITHOUT tax (items only), tax is calculated and added proportionally

2. Fixed field overwriting - Set received_amount AFTER set_amounts() to prevent being overwritten

3. Added advance tracking - Implemented make_advance_payment_ledger_entries() and update_advance_paid() methods following ERPNext Payment Entry pattern

4. Code cleanup - Removed duplicate check_if_advance_entry_modified, unused override_whitelisted_methods, and dead code

Testing:

• Advance SI created from SO with correct proportional amounts

• Tax calculations show correctly

• Difference amount = 0 after save

• Sales Order advance_paid field updates automatically

• GL entries created with proper bank/deferred revenue/VAT splits

Please review the PR and let me know if you need any clarifications.

Thanks,

[hereabdulla]

is this app private, i cant able to find in the ZATCA_ERPGulf github page