Saudi ZATCA Phase II (Clearance Model) introduces an important workflow requirement that differs from traditional invoice issuance.
For B2B tax invoices, an invoice should not become an officially issued tax invoice until it has successfully passed the clearance process and the clearance response has been received from ZATCA. In other words, regulatory approval is part of the invoice issuance process itself rather than a subsequent step.
This creates a practical challenge for the current Manager workflow, where the sales invoice already exists before the clearance process can be completed.
Before discussing the requested features, I would like to briefly thank @Mabaega for the excellent work on the Saudi Phase II integration extension, and @lubos for supporting and encouraging this effort through Manager’s extension framework. The extension demonstrates what is already possible, while also highlighting several areas where native application support would simplify the workflow and enable more complete compliance.
1. Draft Sales Invoices and Invoice Approval
Draft Sales Invoices have previously been requested as a general accounting feature. However, with Saudi ZATCA Phase II, they have become a practical requirement for implementing the clearance workflow correctly.
This request is fundamentally different from the existing Quotes and Sales Orders features, which serve different business purposes and cannot replace a draft invoice within the clearance process.
A Draft Sales Invoice should represent a completed invoice that is awaiting regulatory approval before becoming an officially issued tax invoice.
Once the clearance process succeeds, the draft should be approved and converted into a Sales Invoice without recreating the transaction.
2. Supporting Invoice Clearance During the Issuance Process
The most important missing capability is performing the complete B2B clearance workflow before the invoice becomes an officially issued document.
This could potentially be achieved in either of two ways.
Option 1
Enhance the existing extension so that invoice validation, XML generation, digital signing, clearance submission, and receipt of the clearance response all occur during the invoice issuance process rather than after the invoice has already been created.
Option 2
Introduce Draft Sales Invoices, allowing the extension to complete the entire clearance process while the document remains in draft status. The invoice would only become an official Sales Invoice after receiving a successful clearance response from ZATCA.
This approach may provide a cleaner workflow while reducing complexity for both users and extension development.
3. Native Storage of the Phase II QR Code
The Phase II QR Code should ideally be stored internally as part of the invoice record rather than as an image placed inside a custom field.
A native implementation would provide better integrity, easier API access, improved reporting capabilities, and reduce the possibility of accidental modification.
4. Access to the Original Invoice Creation Timestamp
During the development of the Saudi integration, another limitation became apparent.
The original invoice creation timestamp does not appear to be available through API4 as an immutable value separate from modification timestamps.
This information is important for regulatory integrations and would be valuable if exposed through the API.
5. Auto-Increment Custom Fields and Immutable Internal Document Reference
A new Auto-Increment custom field type would be extremely useful for many business scenarios.
In addition, Manager would benefit from generating an immutable internal document reference that is automatically assigned, cannot be edited, never reused, and remains permanently associated with the document.
This reference would be particularly valuable for integrations such as ZATCA.
Unlike the current invoice reference, which can be manually edited or configured differently, this identifier should always remain fixed throughout the document’s lifetime.
This proposal is separate from the existing UUID, as both identifiers serve different purposes.
6. Improved Advance Payment Allocation
Another feature that would significantly improve the Saudi workflow is better handling of customer advance payments.
Users should be able to record advance receipts, allocate them against outstanding invoices while viewing invoice balances, and support the corresponding advance payment invoice and settlement workflow required under Saudi VAT regulations.
Conclusion
The existing Saudi Phase II extension has demonstrated that integration with ZATCA is achievable.
Adding native support for Draft Sales Invoices, invoice approval, internal clearance workflow, immutable document references, improved API metadata, and enhanced advance payment allocation would make compliance considerably easier while improving the overall architecture of Manager’s integration capabilities.
Thank you again to @Mabaega for the significant effort invested in developing the Saudi Phase II integration extension and to @lubos for supporting that initiative.