bench get-app https://github.com/fuhaed/zatca_high_speed

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=fuhaed%2Fzatca_high_speed)](https://frappegems.com/gems/apps/fuhaed/zatca_high_speed)

ZATCA High Speed

ERPNext-native ZATCA e-invoicing for Saudi Arabia.

ZATCA High Speed is designed for ERPNext v15 teams that want a simpler, cleaner, and more reliable Saudi Phase 2 e-invoicing flow. The app uses ERPNext's existing Company, Customer, Address, Tax Category, Item Tax Template, Mode of Payment, Sales Invoice, Purchase Invoice, Payment Entry, and Journal Entry data wherever possible, and adds only the fields needed for ZATCA onboarding, signing, submission, tracking, printing, reporting, and validation.

Current Release

Version: 1.1.16 Branch: production
Status: production-ready for ERPNext v15, with Sandbox-tested ZATCA Phase 2 flows.

Recent production updates include:

• new ZATCA Pre-Production Audit prepared report for companies, branches, EGS devices, tax setup, payment methods, and VAT customers
• improved ZATCA Monitoring Center with need-action counts, last attempt, last accepted invoice, last error invoice, and average send time
• new Refresh Data and Resend action for rejected or failed submitted Sales Invoices before ZATCA acceptance
• scenario unit tests for normal invoices, simplified invoices, standard tax invoices, credit notes, debit notes, discounts, prepayments, branch selection, and customers without VAT numbers
• branch-aware ZATCA setup for companies with multiple seller branches, each with its own address, identifiers, and optional EGS
• branch filters in VAT return, submission status, sales summary, and error/warning reports
• new ZATCA Sales Summary prepared report for invoice totals by branch, invoice type, mode, and ZATCA status
• new ZATCA Error and Warning Log prepared report with rejection/warning messages and suggested fixes
• new ZATCA Monitoring Center prepared report for all submitted invoices, ZATCA status, response messages, suggested fixes, late simplified invoices, and period totals
• safer live submission handling to prevent duplicate sends when a user clicks send while a live background job is already processing the same invoice
• branch-aware live/batch/manual sync mode selection when a branch-specific EGS exists
• serialized ZATCA submission processing per EGS to keep invoice counters and previous invoice hashes ordered
• stricter payment means validation using UN/EDIFACT 4461 codes
• smarter credit invoice payment means handling: unpaid credit invoices use code 30 automatically, while paid/POS invoices still require mapped payment means
• improved payable rounding handling for ZATCA monetary totals
• stronger VAT and tax-category calculations for discounted invoices
• prepayment invoice support through customer receipt Payment Entries
• final invoice support for accepted prepayments with payable amount, prepayment references, and QR adjustment
• improved customer and invoice readiness validation before save, submit, and send
• Arabic UI translation improvements for app-specific labels, actions, messages, reports, and ZATCA statuses
• refined A4 and thermal invoice formats with compact bilingual layout, item code, discount, VAT rate, QR block, and ZATCA metadata
• ZATCA Submission Status report and VAT Return report links in the workspace
• download actions for signed XML, unsigned XML, and invoice PDF from ZATCA Invoice Submission

Highlights

• Company-based ZATCA setup instead of a disconnected settings model.
• Guided activation wizard for readiness checks, OTP/CSID onboarding, temporary compliance invoice checks, and production linking.
• Temporary compliance checks that do not leave test Sales Invoices, GL Entries, VAT balances, or ZATCA submissions behind.
• Live, Batch, and Manual submission modes for Sales Invoices.
• Sales Invoice and Payment Entry actions for direct ZATCA sending.
• Workspace dashboard with connection status, unsent invoice status, submission counters, and quick access links.
• Optional branch-aware operation for companies with multiple seller branches.
• Customer and invoice readiness checks before saving, submitting, and sending.
• Warnings on new Sales Invoices when a VAT customer is missing required ZATCA data.
• ZATCA Invoice Submission document with XML payload, response data, UUID, invoice hash, QR data, chain data, warnings, and rejection reasons.
• Download actions for signed XML, unsigned XML, and invoice PDF.
• A4 and thermal print formats for tax invoices, simplified tax invoices, credit notes, debit notes, and prepayment-aware invoices.
• Phase 2 QR rendering based on ZATCA response data.
• Prepayment support for customer receipt Payment Entries and final invoices linked to accepted prepayments.
• ZATCA VAT Return prepared report covering sales, returns, purchases, purchase returns, journal entries, payment entries, and prepayment VAT.
• ZATCA Submission Status report for accepted, accepted with warnings, rejected, failed, pending, and ready submissions.
• ZATCA Sales Summary prepared report for branch, invoice type, invoice mode, and status analysis.
• ZATCA Error and Warning Log prepared report for ZATCA warnings, rejection messages, and suggested fixes.
• ZATCA Monitoring Center prepared report for full invoice-level monitoring, totals, warnings, rejections, suggested fixes, and late simplified invoice checks.
• ZATCA Pre-Production Audit prepared report for production readiness checks before moving a company or branch to live ZATCA submission.
• Arabic translation file covering app UI, workspace blocks, wizard messages, reports, validation messages, and ZATCA statuses.
• Built-in ZATCA tax categories, exemption reason codes, payment means codes, custom fields, number cards, workspace, reports, and print formats installed through app hooks.

Requirements

• Frappe Framework v15
• ERPNext v15
• Python 3.10+
• Node/Yarn as required by Frappe Bench
• A working ERPNext company in Saudi Arabia
• ZATCA/Fatoora portal access for OTP generation
• ZATCA CLI and Java runtime

The app includes an automatic CLI setup helper that downloads a supported ZATCA CLI build and Java runtime into the site folder. You can also configure the CLI path and Java Home manually from ZATCA High Speed Settings.

Installation

From your bench directory:

bench get-app https://github.com/fuhaed/zatca_high_speed --branch production
bench --site your-site.local install-app zatca_high_speed
bench --site your-site.local migrate
bench build --app zatca_high_speed
bench restart

For an existing bench where the app is already present:

cd /path/to/frappe-bench/apps/zatca_high_speed
git pull origin production
cd /path/to/frappe-bench
bench --site your-site.local migrate
bench build --app zatca_high_speed
bench --site your-site.local clear-cache
bench restart

Initial Setup

1. Open Company.
2. Enable ZATCA Integration in the ZATCA High Speed section.
3. Confirm the company has:
   • Saudi Arabia as country
   • SAR as default currency
   • 15-digit VAT number in ERPNext's standard tax_id
   • commercial registration in ERPNext's Company registration details
   • linked Saudi address with city, postal code, building number, and district
4. Open the ZATCA High Speed workspace.
5. Click Start Activation Wizard.
6. Choose Sandbox, Simulation, or Production.
7. Run readiness checks.
8. Enter OTP from the ZATCA/Fatoora portal.
9. Request Compliance CSID.
10. Run temporary invoice checks.
11. Request Production CSID when ready.

Company Modes

The Company form includes the ZATCA High Speed section:

• Enable ZATCA Integration
• ZATCA Environment: Sandbox, Simulation, Production
• ZATCA Invoice Mode: Auto, Simplified, Standard
• ZATCA Sync Mode:
  • Live: create, sign, validate, and submit after Sales Invoice submit
  • Batch: create submissions and send later from the workspace
  • Manual: user controls creation and sending
• Validate Generated XML: run local CLI validation before sending
• Block Invoice on Invalid XML

Auto invoice mode uses the customer tax identity:

• customer with VAT/Tax ID: Standard invoice
• customer without VAT/Tax ID: Simplified invoice

Branch Support

For companies that operate multiple seller branches, the app can use ERPNext Branch as the ZATCA branch selector instead of creating a separate disconnected settings document.

Branch support includes:

• Enable Branch for ZATCA on the Branch form.
• ZATCA Company on the Branch form for company mapping.
• Branch Seller Address used in the generated ZATCA XML.
• Branch Seller Identifications for CRN, license, national ID, or other branch-level identities.
• ZATCA Branch on Sales Invoice to select the branch for the invoice.
• branch-specific EGS selection when a ZATCA EGS is linked to the same company and branch.
• branch filters in ZATCA reports.

If no branch is selected, the app continues to use the company-level ZATCA address, identities, and default enabled EGS.

Guided Activation

The activation wizard validates the main ZATCA requirements before linking:

• company data
• seller address
• server tools and ZATCA CLI
• EGS device
• tax setup
• payment means
• temporary invoice checks

The wizard can request Compliance CSID, run temporary invoice checks, request Production CSID, confirm link status, and reset the link when needed.

Temporary Compliance Checks

Temporary compliance checks are designed to keep ERPNext clean:

• temporary Sales Invoices are created inside a database transaction
• required XML is generated, signed, and submitted to compliance endpoints
• summarized results are saved on the EGS
• the transaction is rolled back

This means onboarding tests do not pollute real Sales Invoices, GL Entries, VAT reports, customer balances, or ZATCA submissions.

Customer and Invoice Validation

The app validates customer and invoice readiness before ZATCA use:

• VAT number must be 15 digits and start/end with 3.
• VAT-registered customers should have a billing address.
• Standard invoices require customer VAT and address data.
• Customer address must include the required Saudi address fields.
• Company address must be valid for ZATCA.
• Sales Invoice must have valid items, quantities, taxes, totals, and VAT setup.
• New Sales Invoices show warnings when the selected customer has missing ZATCA data.
• Customer form shows readiness messages and a shortcut to complete the billing address.

These checks help users fix data before submission instead of discovering issues after ZATCA rejection.

Sending Invoices

Submitted Sales Invoices can be sent from:

• the Sales Invoice form using Send to ZATCA
• the ZATCA High Speed workspace using Send All Unsent
• the ZATCA Invoice Submission form using Send to ZATCA

Batch sending runs as one ordered background job to keep invoice chain data consistent.

The workspace highlights unsent submitted invoices so the user can decide when to send them.

Invoice Status

The app writes ZATCA summary fields back to Sales Invoice:

• ZATCA Status
• ZATCA Submission
• ZATCA Response Status
• HTTP status code
• last attempt
• accepted at
• warning or error message

Supported visible states include:

• Not Sent
• Ready
• Pending
• Accepted
• Accepted With Warnings
• Rejected
• Validation Failed
• Signing Failed
• Failed
• Cancelled

Accepted invoices are treated as locked for compliance. Corrections should be issued through Credit Notes or Debit Notes.

ZATCA Invoice Submission

The ZATCA Invoice Submission document stores and displays:

• reference document
• invoice type and invoice mode
• selected EGS
• generated XML
• signed XML
• UUID
• invoice hash
• QR data
• chain data
• request payload
• ZATCA response
• warnings and rejection reasons
• HTTP status and attempt count

It also includes download actions for:

• signed XML
• unsigned XML
• invoice PDF

Prepayments

The app supports ZATCA prepayment handling through customer receipt Payment Entries:

• Customer receipt Payment Entries can be sent as ZATCA prepayment invoices.