ZATCA E-Invoicing API: A Developer’s Guide to Complyance Unify API

ZATCA E-Invoicing API: A Developer’s Guide to Complyance Unify API

Ajith Kumar

Updated on Nov 3, 2026

Subscribe to our newsletter

Learn how to integrate with the ZATCA e-invoicing API using Complyance Unify API. Explore Saudi Arabia onboarding, invoice mapping, validation, submission, sandbox testing and production deployment.

Introduction

Saudi Arabia’s e-invoicing system, managed by the Zakat, Tax and Customs Authority (ZATCA), requires businesses to generate and process electronic invoices according to defined technical and regulatory requirements.

For developers, integrating with ZATCA involves more than sending invoice data to an endpoint. The integration must account for company onboarding, invoice data mapping, validation, document submission and status tracking.

Complyance Unify API provides a unified integration interface for connecting business systems to e-invoicing workflows across supported countries, including Saudi Arabia. Developers can use it to validate invoice data, submit documents and retrieve their processing status through a consistent API structure.

This guide explains the current integration workflow using the Complyance Unify API and links to the documentation needed for implementation.

What Is the ZATCA E-Invoicing API?

A ZATCA e-invoicing API enables software systems, such as ERP platforms, accounting applications and custom business applications, to exchange invoice data through an integration layer.

For Saudi Arabia, the integration must support the applicable ZATCA requirements for standard and simplified tax invoices, as well as related credit notes and debit notes.

Complyance Unify API provides a common request structure for submitting documents to supported country workflows. Developers can use the same overall integration approach while supplying country-specific invoice data and configuration.

Explore the Complyance API documentation for the current API reference and supported integration options.

Why Use Complyance Unify API?

A direct integration with a tax authority requires developers to account for invoice formats, validation rules, authentication, technical requirements and document processing outcomes.

Complyance provides an integration layer that helps teams manage these requirements through a unified API workflow.

Key benefits include:

• Unified API structure: Integrate through a consistent request format for supported countries.
• Invoice validation: Check invoice data before submitting documents for processing.
• Source and mapping configuration: Map data from an ERP or other business system to the required invoice structure.
• Document submission and tracking: Submit invoices and retrieve their processing status.
• Sandbox testing: Test supported integration workflows before moving to production.
• Country-specific guidance: Use Saudi Arabia documentation to understand the required fields, validation rules and onboarding steps.

The exact requirements depend on the document type, country configuration and integration setup.

How to Get Started with ZATCA API Integration

The current Complyance workflow separates workspace configuration, Saudi company onboarding, source and mapping setup, invoice processing and production deployment.

Step 1: Set Up API Access

Start by accessing your Complyance workspace and obtaining an API key for the environment you intend to use.

Keep API credentials securely on your backend. Do not expose them in browser-side code, public repositories or client applications.

Begin with the Complyance API playground and review the Unify API reference before building your integration.

Step 2: Onboard Your Saudi Company

Complete the Saudi Arabia onboarding process in the Complyance workspace.

Depending on the onboarding flow, you will need to provide the required company, tax, E-Invoice Generation Solution (EGS) and source details. The process also uses a six-digit one-time password (OTP) from the ZATCA FATOORA portal for the relevant environment.

Sandbox and production onboarding are separate. Completing sandbox onboarding does not register the company for production.

Follow the Saudi Arabia onboarding guide for the current requirements and steps.

Step 3: Configure Your Source and Invoice Mapping

Identify the system that will send invoice data to Complyance, such as an ERP, accounting platform or custom application.

Configure the relevant source and mapping in the Integration Engine. The source value used in API requests must match the registered source name and version in the name:version format.

Your mapping must transform the source system's invoice data into the structure expected by the selected Saudi document type.

If you need to submit a sample payload for mapping, the Unify API supports purpose: "mapping". This saves the sample payload for mapping purposes; it does not replace the configuration of the mapping itself.

Refer to the Unify API documentation for the current request fields and mapping workflow.

Step 4: Validate Invoice Data in Sandbox

Before submitting invoices, test your integration with the sandbox environment.

The Unify API supports purpose: "validate", which checks the submitted payload without storing or submitting it for processing.

Use validation results to identify missing fields, incorrect formats and other invoice data issues. Correct these findings in your source data or mapping before proceeding.

For Saudi-specific field requirements, consult the Saudi Arabia documentation and validation rules.

Step 5: Submit an Invoice Through Unify API

Once the source and mapping are configured and the invoice data is ready, submit the document through the Unify endpoint.

Endpoint

POST https://prod.gets.complyance.io/api/v3/unify

For JSON requests, include the following headers:

• Authorization: Bearer YOURAPIKEY
• Content-Type: application/json
• new-api: true

The request body uses a common structure with fields for the country, environment, purpose, source, document type and invoice payload.

The following example illustrates the request structure. It is not a complete invoice payload and should not be used as-is for a production submission.

{
  "country": "SA",
  "environment": "sandbox",
  "purpose": "validate",
  "source": "your-erp:1.0.0",
  "documentType": {
    "base": "tax_invoice",
    "modifiers": []
  },
  "payload": {
    "...": "Your mapped invoice data"
  }
}

For this example:

• country identifies Saudi Arabia using the ISO alpha-2 code SA.
• environment identifies the target environment. It must match the API key.
• purpose specifies the intended operation.
• source identifies the registered source and version.
• documentType identifies the base document type and applicable modifiers.
• payload contains the invoice data in the structure expected by your configured mapping.

For invoice submission, change purpose to invoicing and supply the complete mapped invoice payload.

The Unify API also supports XML requests. Follow the current documentation for the appropriate content type and request format.

See Submit and Retrieve for the latest endpoint details and request examples.

Step 6: Retrieve and Monitor Document Status

A successful API response does not necessarily mean that ZATCA has accepted the invoice.

After submitting a document, save the returned documentId and use the documented retrieval workflow to check its processing status. Continue monitoring until the document reaches a terminal state, indicated by isTerminal: true.

Review the final status and any returned errors before treating the invoice as successfully processed.

This distinction is important for building reliable integrations. Your application should handle validation errors, processing delays and unsuccessful outcomes instead of assuming that every successful HTTP response represents final acceptance.

Step 7: Move from Sandbox to Production

Once the integration passes the required tests, prepare for production deployment.

Before going live:

1. Complete the production onboarding process separately.
2. Obtain and configure the production API key.
3. Verify that the production source and mapping are configured correctly.
4. Test the required Saudi invoice types and business scenarios.
5. Confirm that your application can submit documents and retrieve their final statuses.
6. Implement secure credential handling, error logging and operational monitoring.

Use the Saudi Arabia go-live checklist to confirm the current production requirements.

Understanding ZATCA Clearance and Reporting

Saudi Arabia has different processing requirements for standard and simplified tax invoices.

Standard tax invoices: These, along with their related credit notes and debit notes, follow the clearance workflow. The document must receive the required clearance outcome before it is treated as cleared.

Simplified tax invoices: These, along with their related credit notes and debit notes, follow the reporting workflow. Simplified invoices must be reported to ZATCA within 24 hours of issuance.

In the Complyance workflow, developers should distinguish between the API submission response and the final Saudi processing result. A standard invoice may reach a CLEARED status, while a simplified invoice may reach a REPORTED status.

The applicable workflow depends on the invoice type and Saudi requirements. Refer to the Saudi Arabia documentation for the current country-specific rules.

Common API Integration Issues

Developers can reduce integration errors by checking the following areas during testing.

Authentication errors: Verify that the API key is valid, the authorization header is correctly formatted and the key belongs to the intended environment.

Validation errors: Review the response details and compare the payload with the Saudi field reference and validation rules. Check mandatory fields, data formats, totals and document-specific requirements.

Source or mapping errors: Confirm that the source name and version match the registered configuration and that the invoice payload follows the expected mapping.

Incorrect document configuration: Check the documentType values and applicable modifiers against the current API documentation.

Unexpected processing outcomes: Do not rely only on the initial HTTP status. Retrieve the document status and inspect the final result and associated errors.

Sandbox and production mismatches: Keep environment configuration and API credentials aligned. Remember that sandbox onboarding and production onboarding are separate processes.

For complete request and response examples, use the Complyance API playground and the Unify API reference.

Migrating from the Legacy API v2

Complyance API v2 is a legacy integration path and is no longer under active development. New integrations should use the current Unify API and the relevant Saudi Arabia documentation.

Teams maintaining existing v2 integrations should review the Unify migration guide before changing their requests.

Do not copy older authentication, onboarding or invoice-submission examples into a new Unify integration without checking the current request format and workflow. The API structure and setup steps differ.

Conclusion

Integrating with ZATCA requires more than submitting invoice data. Developers must configure API access, onboard the Saudi company, set up the source and mapping, validate invoice data, submit documents and monitor the final processing status.

Complyance Unify API provides a unified integration approach for supported e-invoicing workflows. By following the current API documentation and completing sandbox testing before production deployment, development teams can build an integration that is easier to test, monitor and maintain.

Ready to start? Explore the Complyance API documentation, review the Saudi Arabia integration guide and test your requests using the API playground.

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

Connect on LinkedIn