Automate ZATCA E-Invoicing: Streamline Your ERP-to-FATOORA Workflow
Learn how API integration and workflow automation support ZATCA Phase 2 e-invoicing through data mapping, validation, clearance, reporting, status tracking, and sandbox testing.
Table of Contents
Saudi Arabia’s ZATCA Phase 2 e-invoicing framework requires in-scope taxpayers to integrate their Electronic Generation Solution (EGS) with ZATCA’s FATOORA platform according to the applicable rollout wave. For businesses, that integration involves more than sending invoice data through an API. Source data must be mapped to the required invoice structure, the correct clearance or reporting workflow must be followed, and the processing outcome must be tracked.
Automation can reduce repetitive data entry and help teams manage these steps consistently. It does not guarantee compliance on its own. Businesses remain responsible for accurate invoice data, appropriate tax treatment, EGS onboarding, recordkeeping, and following the requirements that apply to their documents.
1. How ZATCA Phase 2 integration works
An ERP, accounting platform, billing system, or custom application holds the business data used to create invoices. An e-invoicing solution connects to that source, maps the data to ZATCA’s required structure, applies the relevant validation and security requirements, and submits the document through the appropriate workflow.
The key steps are:
- Retrieve or receive invoice data from the source system.
- Map the data to the required Saudi document type and XML structure.
- Validate the payload and correct errors before submission where possible.
- Submit the invoice or note through the applicable clearance or reporting workflow.
- Retrieve and record the processing status and any errors returned.
- Reconcile the result with the source system and retain the required records.
The exact implementation depends on the taxpayer’s systems, document types, and integration design.
2. Automate ERP-to-e-invoicing data exchange
API integration can transfer invoice data between an ERP and an e-invoicing solution without requiring staff to re-enter the same information manually. It can also standardise how invoice details, customer and supplier information, tax values, and document references move between systems.
Before building the integration, identify the source fields available in your ERP and map the data to the applicable Saudi document type and ZATCA’s required XML structure. Record how each field maps, identify missing or inconsistent source data, and define how errors will be returned to the system or team responsible for correction.
Automation is most useful when the source data is reliable and the mapping is tested against representative invoices and notes.
3. Map and validate invoice data before submission
Incorrect or incomplete source data can cause validation errors and interrupt processing. A well-designed workflow validates invoice data against the applicable document requirements before sending it onward.
Pre-submission checks can help identify missing mandatory fields, invalid formats, inconsistent totals, or other data issues. Validation does not replace the authority’s checks, and passing a platform validation does not guarantee that ZATCA will accept the document.
Complyance’s Unify API provides payload validation and returns field-level validation errors before or during the invoicing workflow. Confirm whether your chosen validation flow stores or submits the payload, and use the appropriate validation mode or sandbox workflow for testing. Review the returned errors and correct the underlying data or mapping before retrying.
See the Complyance Unify API reference and Saudi Arabia validation rules.
4. Generate the required invoice representation
ZATCA’s Phase 2 technical requirements include structured XML. ZATCA’s readiness guidance also describes storing invoices in XML or PDF/A-3 with embedded XML, including the mandatory fields. PDF/A-3 should not be treated as a universal substitute for the required structured data or as a format that must be distributed in every workflow.
Automation can help create the required XML and, where applicable, a human-readable PDF/A-3 representation with embedded XML. The format and handling must follow the current technical requirements for the document and workflow.
Consult ZATCA’s Phase 2 readiness guidance and technical resources for developers.
5. Follow the correct clearance and reporting workflow
The timing and handling depend on the invoice type:
- Standard tax invoices and related notes: These require clearance before they are shared with the buyer.
- Simplified tax invoices and related notes: These must be reported to ZATCA within 24 hours of generation or issuance.
An automated workflow should route each document to the appropriate process, capture the response, and make the outcome available to the business system or responsible team. API integration can trigger status checks and surface processing outcomes to the ERP or operations team; the update frequency depends on the integration design, the provider’s workflow, and ZATCA’s response.
Do not treat a successful initial API response as confirmation of final clearance or reporting. Retrieve the document status and confirm the final outcome.
6. Track status, handle errors, and prevent duplicate processing
Status tracking helps teams identify documents that have cleared, been reported, failed validation, or require further attention. Store the document identifier returned by the integration and use the documented status-retrieval process to check progress.
Design error handling before going live. For example:
- Log request identifiers, document identifiers, timestamps, and error details.
- Distinguish validation errors from submission failures and final authority outcomes.
- Correct the underlying data or configuration before retrying.
- Check the current document status before resending after a timeout or uncertain response.
- Follow the documented retry process to avoid duplicate processing.
A timeout does not always mean that a document was not received or stored. Retry behaviour should follow the API documentation and the state of the document, rather than resending blindly.
Complyance documentation explains the submit-and-retrieve workflow and document status.
7. Test with ZATCA’s Integration Sandbox
Use ZATCA’s Integration Sandbox and developer resources to test onboarding, XML generation, submissions, and response handling before moving to production. Test representative standard and simplified invoices, related notes, error scenarios, and status retrieval.
Sandbox testing helps identify integration issues before they affect live processing. However, successful sandbox tests do not complete production onboarding. Businesses must still complete the required production setup and onboarding steps for their EGS.
Start with ZATCA’s developer resources and simplified technical guide. For Complyance testing, see the sandbox guide.
8. Monitor operations and reconcile results
After go-live, monitor validation errors, submission outcomes, unresolved documents, and differences between the ERP and e-invoicing system. A reconciliation process helps confirm that source documents and their processing outcomes remain aligned.
Define ownership for reviewing failures and establish an escalation path for unresolved issues. Keep mappings and tests updated when source-system fields or applicable ZATCA requirements change. Retain invoices and related processing records in accordance with the applicable recordkeeping rules.
Automation can make these controls easier to operate, but teams should regularly review whether they are working as intended.
How Complyance can support your integration
Complyance provides the Unify API and Saudi Arabia-specific documentation for integrating source systems with the platform, validating invoice data, submitting documents, and tracking status. Implementation requirements depend on the source system, mapping, document types, and taxpayer onboarding.
To plan your integration, review:
Automation can help reduce repetitive work and improve visibility across the invoice lifecycle. To support ZATCA compliance, it must be implemented alongside accurate source data, correct document handling, production onboarding, status monitoring, and ongoing review of applicable requirements.
References
Frequently Asked Questions
Businesses can automate data transfer from source systems, invoice mapping, pre-submission validation, document submission, status retrieval, error logging, and reconciliation. The exact capabilities depend on the systems and integration design.
No. APIs can support consistent data exchange and workflow handling, but compliance also depends on correct invoice data, tax treatment, technical requirements, EGS onboarding, clearance or reporting, and recordkeeping.
Standard tax invoices and related notes require clearance before being shared with the buyer. Simplified tax invoices and related notes must be reported to ZATCA within 24 hours of generation or issuance.
Not necessarily. Retrieve the document status and review the final outcome. An initial response alone should not be treated as confirmation of final clearance or reporting.
Do not assume PDF/A-3 is the universal output format. ZATCA’s readiness guidance describes XML or PDF/A-3 with embedded XML for generation and storage, while the applicable technical requirements and workflow determine how each document must be handled.
Yes. ZATCA provides an Integration Sandbox and developer resources for testing. Sandbox testing does not replace the production onboarding process.
About the Author
Ajith Kumar
Im a skilled content writer and SEO expert crafting engaging articles that rank. Passionate about making complex topics clear, discoverable, and valuable to readers.Dedicated to driving organic growth through high-quality, search-optimized content
