Zatca
The ZATCA Connector enables seamless integration with ZATCA’s e-Invoicing system, facilitating compliance with Saudi Arabian tax regulations. It provides functionalities such as onboarding, renewal, validation, reporting, and clearance of invoices.
Integration Overview
This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the ZATCA custom connector.
- Onboarding Integration. Generates cryptographic stamps (CSID) for new systems.
- Renewal Integration. Renews expiring cryptographic stamps.
- Validation Integration. Validates XML invoices and QR codes.
- Reporting Integration. Submits simplified invoices for reporting.
- Clearance Integration. Submits standard invoices for clearance with ZATCA’s backend.
Detailed Integration Documentation
Onboarding Integration
| Purpose | Generates a compliance cryptographic stamp identifier (CSID) required for authentication within the ZATCA ecosystem. |
|---|---|
| Input details | Required: Certificate Signing Request (CSR); VAT Registration Number. Configuration: ensure JDK (>=11, <15) is installed on the server for generating and signing CSRs. |
| Output | Successful: returns test CSID and Request ID. Failure: indicates an invalid CSR or missing parameters. |
| Workflow example | 1. Generate a CSR using the JDK. 2. Use Onboarding to obtain the CSID. 3. Use the CSID for subsequent integrations. |
Renewal Integration
| Purpose | Renews the compliance CSID to maintain integration capabilities. |
|---|---|
| Input details | XML Invoice (Base64 encoded). Supported types: Standard and Simplified Tax Invoices. |
| Workflow example | 1. Pre-process invoices with the connector. 2. Use this integration to renew before the CSID expires. |
Validation Integration
| Purpose | Validates XML invoices for compliance with ZATCA standards. |
|---|---|
| Input details | XML Invoice (Base64 encoded). Supported types: Standard and Simplified Tax Invoices. |
| Output | Valid: confirms invoice compliance. Invalid: returns validation errors and recommendations. |
| Workflow example | 1. Pre-process invoices with the connector. 2. Use this integration to check compliance before submission. |
Reporting Integration
| Purpose | Submits simplified invoices for reporting to ZATCA. |
|---|---|
| Workflow example | 1. Validate the invoice using Validation. 2. Submit the validated invoice for reporting through the connector. |
Clearance Integration
| Purpose | Submits standard invoices for clearance and stamping by ZATCA. |
|---|---|
| Workflow example | 1. Validate the invoice and generate the hash. 2. Use Clearance to submit the invoice. 3. Retrieve the stamped invoice for record-keeping and compliance. |
Example Workflow: Submitting a Standard Invoice
| Prepare invoice | Generate the invoice in XML format. |
|---|---|
| Validate | Use Validation to ensure compliance and address any issues from the feedback. |
| Submit for clearance | Encode the XML in Base64 and use Clearance to submit for stamping; retrieve the stamped invoice. |
| Monitor | Monitor submission health via Google Cloud Logging. Each integration requires a valid CSID and ZATCA-schema-compliant payloads. |
Use Case
A Saudi-based ERP provider integrates the ZATCA Connector with GCP to ensure e-invoicing compliance for local clients. Using endpoints such as onboarding, validation, reporting, and clearance, the system handles cryptographic CSID issuance, invoice validation, and real-time submission to ZATCA. Standard and simplified invoices are encoded in Base64 and processed through GCP workflows. Validated and stamped XMLs are archived in Cloud Storage, and integration health is monitored via Google Cloud Logging, ensuring uninterrupted tax reporting and regulatory adherence.
For technical support, contact custom-connectors-support@isolutions.sa.