BOT Solutions

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

Support

For technical support or questions:

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)