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

“The following required fields must be completed accurately to ensure successful ZATCA integration. Each field is explained below for clarity.”

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

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

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)