ZATCA Phase 2 E-Invoicing Integration

Overview

The ZATCA Phase 2 e-invoicing integration enables businesses in Saudi Arabia to automatically generate, sign, and submit compliant electronic invoices to ZATCA's Fatoorah platform. This integration ensures full compliance with Saudi Arabia's e-invoicing regulations.

Key Features

• Automatic Invoice Submission: Invoices are automatically submitted to ZATCA when created and submitted
• XML Generation: Automatic generation of ZATCA-compliant XML invoices
• Digital Signing: Automatic signing of invoices using ZATCA CLI
• QR Code Generation: Automatic QR code generation for invoices
• Compliance & Production Modes: Support for both compliance testing and production environments
• Queue Management: Built-in queue system for batch processing
• Integration Logging: Comprehensive logging of all ZATCA operations

Prerequisites

Before starting the ZATCA integration setup, ensure you have:

1. ZATCA Account: An active account on the Fatoorah platform (https://fatoorah.gov.sa)
2. VAT Registration: Valid VAT registration number
3. Company Information: Complete company details including:
   • Legal company name
   • VAT registration number
   • Company address (street, building number, city, postal code, district)
   • Commercial registration details (if applicable)
4. System Requirements:
   • Java 11 or higher (for ZATCA CLI)
   • Internet connection for API communication
   • Valid SSL certificates

Initial Setup

Step 1: Enable ZATCA Integration

1. Navigate to Settings → ZATCA Settings
2. Check the "Enable ZATCA Integration" checkbox
3. Click "Save Settings"

Once enabled, additional configuration options will become available.

Step 2: Configure Basic Settings

Fatoora Server Environment

Select the appropriate environment:

• Sandbox: ZATCA test environment (for initial testing)
• Simulation: Test environment requiring OTP from Fatoorah platform
• Production: ZATCA production environment (for live operations)

Type of Business Transactions

Choose your business transaction type:

• Let the system decide (both): Automatically determines B2B or B2C based on customer VAT registration
• B2B: Business-to-Business transactions only
• B2C: Business-to-Consumer transactions only

Currency

Select the currency for your invoices (typically SAR for Saudi Arabia).

Validate Generated XML

• Enabled: Validates XML during creation (recommended for testing/troubleshooting)
• Disabled: Skips validation for better performance (recommended for production)

Configuration

Seller Details Configuration

Navigate to the "Seller Details" tab in ZATCA Settings:

Required Fields

1. Company: Enter your legal company name as it should appear on invoices
2. Company Unit: The name of the onboarded EGS (Electronic Generation System) unit on Fatoorah platform
3. Company Unit Serial: Unique identifier for your EGS unit
   • Format: 1-Solution Provider Name|2-Model or version|3-Serial
   • Example: 1-ERPNext|2-15|3-1
   • Use the "Auto Generate" button to automatically generate this value
4. Company Category: Select from:
   • Services
   • Goods
   • Both
5. Country & Country Code:
   • Country: Saudi Arabia
   • Country Code: SA
6. Company Address: Complete address details:
   • Company Address (full address)
   • Street
   • Building Number
   • City
   • Postal Code
   • District

Seller ID Configuration

Required Fields

1. Seller Name: Your registered seller name
2. VAT Registration Number: Your 15-digit VAT registration number

Branch Configuration (Optional)

If you have multiple branches with different commercial registration numbers:

1. Enable "Enable Branch Configuration"
2. Configure Accounting Dimensions for company branches
3. Set up branch-specific VAT registration numbers

Additional IDs (Optional)

Add additional identification numbers if required:

• Commercial Registration Number (CRN)
• MOMRAH License
• MHRSD License
• 700 Number
• MISA License
• Other ID

CLI Setup

The ZATCA CLI (Command Line Interface) is required for:

• Generating Certificate Signing Requests (CSR)
• Validating XML invoices
• Signing invoices digitally

Automatic Setup (Recommended)

1. Select "CLI Setup" → "Automatic"
2. The system will automatically:
   • Download ZATCA CLI from GitHub
   • Download Java 11 runtime (if needed)
   • Configure paths automatically

Manual Setup

If you prefer manual setup:

1. Select "CLI Setup" → "Manual"
2. Download ZATCA CLI from: https://github.com/zatca/fatoora
3. Install Java 11 or higher
4. Configure paths:
   • CLI Path: Full path to zatca-cli executable
     • Example: /home/user/zatca-cli/bin/zatca-cli (Linux/Mac)
     • Example: C:\zatca-cli\bin\zatca-cli.bat (Windows)
   • Java Home: JAVA_HOME path (leave blank to use system default)

Override Download URLs (Advanced)

If you need to use custom download sources:

• Override CLI Download URL: Custom URL for CLI zip file
• Override JRE Download URL: Custom URL for Java runtime

Onboarding Process

The onboarding process establishes your connection with ZATCA and obtains the necessary credentials for invoice submission.

Step 1: Generate Certificate Signing Request (CSR)

1. Ensure all Seller Details are correctly filled
2. Navigate to ZATCA Settings → Onboarding tab
3. Click "Generate CSR" or "Check CLI" first to verify CLI is working
4. The system will:
   • Generate a CSR using your company details
   • Display the CSR in the settings page
   • Save the CSR for later use

Step 2: Submit CSR to Fatoorah Platform

1. Copy the generated CSR from the settings page
2. Log in to Fatoorah platform: https://fatoorah.gov.sa
3. Navigate to Onboarding → CSR Submission
4. Paste the CSR and submit
5. You will receive an OTP (One-Time Password) via email/SMS

Step 3: Complete Onboarding

1. In ZATCA Settings, click "Start Onboarding"
2. Enter the OTP received from Fatoorah platform
3. Click "Verify OTP and Generate CSR"
4. The system will:
   • Verify the OTP with ZATCA
   • Receive compliance credentials (Request ID, Security Token, Secret)
   • Save credentials automatically

Step 4: Compliance Testing

Before going to production, you must pass compliance testing:

Manual Compliance Check

1. Create test invoices in your system
2. Ensure invoices have all required ZATCA fields
3. In ZATCA Settings, click "Perform Compliance Check"
4. Enter invoice names (comma-separated): SINV-0001, SINV-0002
5. Click "Submit to ZATCA"
6. Review the results:
   • Accepted: Invoice passed compliance
   • Accepted with warnings: Invoice passed but has warnings
   • Rejected: Invoice failed compliance (check errors)

Automated Compliance Check

The system can automatically create and test various invoice types:

1. Click "Automated Compliance Check"
2. Fill in required parameters:
   • Company: Your company name
   • Item: Select an existing item
   • Simplified Customer (B2C): Customer without VAT registration
   • Standard Customer (B2B): Customer with VAT registration
3. Click "Start Automated Compliance"
4. The system will create and test:
   • Standard invoices (B2B)
   • Simplified invoices (B2C)
   • Credit notes
   • Debit notes

Step 5: Production Onboarding

Once compliance testing is successful:

1. Log in to Fatoorah platform
2. Navigate to Production Onboarding
3. Submit your compliance test results
4. Receive production credentials:
   • Production Request ID
   • Production Security Token
   • Production Secret
5. Enter these credentials in ZATCA Settings → Integration tab
6. Save settings

Sales Invoice Additional Fields

When ZATCA integration is enabled, each Sales Invoice automatically creates a Sales Invoice Additional Fields document containing ZATCA-specific metadata.

Accessing Additional Fields

1. Open any Sales Invoice
2. Navigate to the "ZATCA" tab or section
3. View the Sales Invoice Additional Fields link
4. Click to open the additional fields document

Key Fields in Additional Fields Document

Details Tab

• Sales Invoice: Link to the parent invoice
• Integration Status: Current status of ZATCA integration
  • Ready For Batch: Ready for submission
  • Resend: Needs to be resent
  • Corrected: Invoice was corrected
  • Accepted: Successfully accepted by ZATCA
  • Accepted with warnings: Accepted but has warnings
  • Rejected: Rejected by ZATCA
  • Clearance switched off: Clearance mode disabled
  • Duplicate: Duplicate submission detected
• Last Attempt: Timestamp of last submission attempt
• Invoice Doctype: Type of invoice (Sales Invoice, POS Invoice, Payment Entry)
• Is Latest: Indicates if this is the latest version
• UUID: Unique identifier assigned by ZATCA
• Invoice Type Code: ZATCA invoice type code
• Invoice Type Transaction: Transaction type (B2B/B2C)
• Tax Currency: Currency code (typically SAR)
• Invoice Counter: Sequential counter for invoice hashing
• Invoice Hash: Cryptographic hash of the invoice
• Previous Invoice Hash: Hash of the previous invoice (for chaining)

Buyer Tab

• Buyer VAT Registration Number: Customer's VAT number (if B2B)
• Other Buyer IDs: Additional buyer identification numbers
• Buyer Address Details: Complete buyer address information

Invoice Tab

• Allowance Indicator: Indicates if allowances are applied
• Charge Indicator: Indicates if charges are applied
• Fatoora Invoice Discount Amount: Discount amount
• Sum of Charges: Total charges
• Invoice Line Charge Percentage: Percentage-based charges
• Invoice Line Charge Amount: Amount-based charges
• Prepayment VAT Category: Prepayment VAT details

XML Tab

• Invoice XML: Generated ZATCA XML (hidden by default)
• Download XML: Button to download the XML file
• QR Code: QR code image for the invoice

Integration Status Meanings

Invoice Submission Workflow

Automatic Submission

When ZATCA integration is enabled, invoices are automatically submitted to ZATCA when:

1. A Sales Invoice is created and submitted (not saved as draft)
2. The invoice has all required fields
3. ZATCA credentials are configured

Submission Process Flow

1. User creates and submits Sales Invoice
2. System creates Sales Invoice Additional Fields document
3. System generates ZATCA-compliant XML
4. System validates XML (if validation enabled)
5. System signs XML using ZATCA CLI
6. System calculates invoice hash and counter
7. System submits signed XML to ZATCA API
8. System receives response from ZATCA
9. System updates Additional Fields with:
   • UUID (if successful)
   • QR Code
   • Integration Status
   • Errors/Warnings (if any)
10. System creates ZATCA Integration Log entry

Manual Submission

If automatic submission fails or you need to resubmit:

1. Open the Sales Invoice Additional Fields document
2. Check the Integration Status
3. If status is "Resend" or "Failed":
   • Review errors in the Errors and Warnings field
   • Fix any issues in the parent Sales Invoice
   • Click "Resend to ZATCA" action button (if available)

Submission Types

Reporting Mode

• Standard submission mode
• Invoices are reported to ZATCA for record-keeping
• Used for most invoice types

Clearance Mode

• Real-time clearance required
• Invoices must be cleared by ZATCA before being considered valid
• Used for specific invoice types or high-value transactions

Invoice Counter and Hash Chain

ZATCA requires invoices to be cryptographically chained:

1. Invoice Counter: Sequential number starting from 1
2. Invoice Hash: SHA-256 hash of invoice data
3. Previous Invoice Hash: Hash of the immediately preceding invoice

This creates an unbreakable chain ensuring invoice integrity and preventing tampering.

ZATCA Queue System

The ZATCA queue system manages invoice submissions in batches, ensuring reliable processing and retry mechanisms.

ZATCA Staged Invoice

Each invoice submission creates a ZATCA Staged Invoice record that tracks:

• Invoice: Link to the Sales Invoice
• Status: Current processing status
  • Pending: Waiting to be processed
  • Validated: XML validated successfully
  • Signed: XML signed successfully
  • Submitted: Submitted to ZATCA
  • Failed: Submission failed
• Integration Type: Reporting or Clearance
• Submission Mode: Sandbox, Simulation, Production, or Compliance
• Invoice Counter: Sequential counter
• UUID: ZATCA-assigned unique identifier
• Invoice Hash: Cryptographic hash
• Previous Invoice Hash: Hash of previous invoice
• QR Code: Generated QR code
• Warnings/Errors: Any issues encountered
• Last Attempt At: Timestamp of last attempt
• Attempt Count: Number of submission attempts
• XML Paths: File paths for request XML, signed XML, and response JSON

Queue Processing

The queue system processes invoices in the following order:

1. Pending invoices are picked up
2. XML is validated
3. XML is signed using ZATCA CLI
4. Invoice is submitted to ZATCA API
5. Response is processed and status updated

Batch Processing

Invoices with status "Ready For Batch" are automatically processed in batches:

1. System collects all invoices with status "Ready For Batch"
2. Processes them sequentially (maintaining hash chain)
3. Updates status after each submission
4. Retries failed submissions automatically

Retry Mechanism

Failed submissions are automatically retried:

• Attempt Count tracks retry attempts
• System waits between retries to avoid rate limiting
• Maximum retry attempts are configurable
• After max retries, status changes to "Failed"

Integration Logs

All ZATCA operations are logged in ZATCA Integration Log for audit and troubleshooting.

Accessing Integration Logs

1. Navigate to ZATCA → ZATCA Integration Log
2. View list of all ZATCA operations
3. Filter by status, invoice, or date range

Log Fields

• Invoice: Link to the Sales Invoice
• Submission Type: Reporting or Clearance
• Status: Success, Warning, or Failed
• UUID: ZATCA-assigned unique identifier
• QR Code: Generated QR code
• Invoice Hash: Cryptographic hash
• Request XML Path: Path to request XML file
• Signed XML Path: Path to signed XML file
• Response JSON Path: Path to ZATCA response
• Message: General message from ZATCA
• Warnings: Any warnings received
• Errors: Any errors encountered
• Created On: Timestamp of log entry

Resending Failed Submissions

If a submission failed:

1. Open the ZATCA Integration Log entry
2. Check the Errors field for details
3. Click "Resend to ZATCA" action button
4. System will retry the submission

Troubleshooting

Common Issues and Solutions

1. CLI Not Found or Not Working

Symptoms:

• Error: "CLI path is not configured"
• Error: "CLI verification failed"

Solutions:

• Verify CLI is installed: Click "Check CLI" in settings
• For Automatic setup: Ensure internet connection and try again
• For Manual setup: Verify CLI path is correct and executable
• Check Java installation: Ensure Java 11+ is installed and JAVA_HOME is set

2. Onboarding Failed

Symptoms:

• Error: "OTP verification failed"
• Error: "CSR generation failed"

Solutions:

• Verify all Seller Details are correctly filled
• Ensure OTP is entered correctly (check for typos)
• Verify OTP hasn't expired (OTPs are time-limited)
• Check internet connection
• Verify CSR format is correct

3. Invoice Submission Failed

Symptoms:

• Integration Status: "Rejected" or "Failed"
• Errors in Integration Log

Solutions:

• Check Errors field in Integration Log for specific issues
• Verify invoice has all required fields:
  • Customer VAT number (for B2B)
  • Complete address information
  • Valid items with prices
  • Tax calculations
• Check invoice counter and hash chain
• Verify ZATCA credentials are valid
• Check if invoice exceeds ZATCA limits

4. XML Validation Errors

Symptoms:

• Error: "XML validation failed"
• Error: "Invalid XML structure"

Solutions:

• Enable "Validate Generated XML" in settings for detailed errors
• Check invoice data completeness
• Verify all required ZATCA fields are present
• Review XML file directly (download from Additional Fields)

5. Hash Chain Broken

Symptoms:

• Error: "Previous invoice hash mismatch"
• Error: "Invoice counter invalid"

Solutions:

• Verify invoices are submitted in order
• Check if any invoices were deleted or modified
• Reset invoice counter if necessary (contact support)
• Ensure no manual invoice counter changes

6. Credentials Not Working

Symptoms:

• Error: "Authentication failed"
• Error: "Invalid credentials"

Solutions:

• Verify credentials are correctly entered
• Check if credentials have expired
• Ensure correct environment (Sandbox/Simulation/Production)
• Re-run onboarding if credentials are invalid

7. QR Code Not Generated

Symptoms:

• QR Code field is empty
• QR Code image not displayed

Solutions:

• Verify invoice was successfully submitted
• Check if UUID was received from ZATCA
• Ensure invoice status is "Accepted" or "Accepted with warnings"
• Try resubmitting the invoice

Debugging Tips

1. Enable XML Validation: Turn on "Validate Generated XML" to catch issues early
2. Check Integration Logs: Always check logs for detailed error messages
3. Review XML Files: Download and review XML files for structure issues
4. Test in Sandbox First: Always test in Sandbox before Production
5. Monitor Queue Status: Check ZATCA Staged Invoice for processing status

Best Practices

Configuration Best Practices

1. Start with Sandbox: Always begin testing in Sandbox environment
2. Complete Seller Details: Ensure all seller information is accurate and complete
3. Use Automatic CLI Setup: Prefer automatic setup unless you have specific requirements
4. Keep Credentials Secure: Never share ZATCA credentials
5. Regular Backups: Backup ZATCA settings and credentials

Invoice Creation Best Practices

1. Complete Customer Information: Ensure customer addresses are complete for B2B invoices
2. Verify VAT Numbers: Validate customer VAT registration numbers
3. Accurate Tax Calculations: Ensure tax calculations are correct
4. Proper Item Descriptions: Use clear, descriptive item names
5. Correct Invoice Types: Use appropriate invoice types (Standard/Simplified)

Submission Best Practices

1. Submit Immediately: Submit invoices as soon as they're created
2. Monitor Status: Regularly check integration status
3. Address Warnings: Don't ignore warnings - address them promptly
4. Maintain Hash Chain: Never skip or delete invoices in the chain
5. Regular Audits: Periodically review Integration Logs

Production Best Practices

1. Complete Compliance Testing: Pass all compliance tests before going live
2. Monitor First Invoices: Closely monitor first production invoices
3. Set Up Alerts: Configure alerts for failed submissions
4. Regular Testing: Periodically test in Sandbox to ensure system works
5. Keep Documentation: Maintain records of all ZATCA operations

Security Best Practices

1. Secure Credentials: Store credentials securely
2. Limit Access: Restrict ZATCA Settings access to authorized personnel
3. Regular Updates: Keep ZATCA CLI updated
4. Monitor Logs: Regularly review logs for suspicious activity
5. Backup Regularly: Regular backups of all ZATCA data

Additional Resources

ZATCA Official Resources

• Fatoorah Platform: https://fatoorah.gov.sa
• ZATCA CLI GitHub: https://github.com/zatca/fatoora
• ZATCA Documentation: https://zatca.gov.sa

Support

For technical support or questions:

• Customer Support: https://helpdesk.botsolutions.tech/login#login
• Documentation: https://docs.botsolutions.tech

Glossary

• B2B: Business-to-Business transaction
• B2C: Business-to-Consumer transaction
• CLI: Command Line Interface
• CSR: Certificate Signing Request
• EGS: Electronic Generation System
• OTP: One-Time Password
• QR Code: Quick Response Code (for invoice verification)
• UUID: Universally Unique Identifier
• VAT: Value Added Tax
• XML: eXtensible Markup Language
• ZATCA: Zakat, Tax and Customs Authority (Saudi Arabia)