YousrERP User Guide
Introduction Setup
Accounting Buying Selling & CRM Stock / Inventory Manufacturing Assets Quality Projects ZATCA E-Invoicing
YousrERP.com Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ©

ZATCA Troubleshooting

Common issues users encounter with ZATCA e-invoicing and how to resolve them.

Invoice Stuck on "Pending"

Symptom: Invoice shows "Pending" status for more than a few minutes.

Possible Causes & Solutions:

  1. ZATCA server is slow or down

- Check the ZATCA portal status.

- Wait and check again β€” ZATCA may have processing delays.

- No action needed on your side.

  1. Internet connectivity issue

- Verify your internet connection is stable.

- Check if other internet services work.

- If connection is down, invoices will queue and submit when it's restored.

  1. Batch mode delay

- If using Batch mode, invoices are processed at scheduled intervals.

- Check ZATCA > E-Invoicing Sync for the batch queue.

- Click Sync Now to trigger immediate processing.

  1. Queue backlog

- During peak times, the submission queue may have a backlog.

- Monitor the ZATCA Dashboard for queue status.

- Usually resolves automatically.

CSID Certificate Expired

Symptom: All new invoices fail with "Invalid certificate" or CSID shows "Expired" on dashboard.

Solution:

  1. Go to ZATCA > ZATCA Business Settings.
  2. Click the Onboarding button.
  3. Run the onboarding wizard to generate a new CSID.
  4. After new CSID is generated, pending/failed invoices will be submitted with the new certificate.
  5. Verify by checking a new invoice submission.

EGS Unit Errors

Symptom: Invoices fail with "EGS unit not authorized" or similar.

Solutions:

  1. EGS Unit not active

- Go to ZATCA > ZATCA EGS.

- Check if the EGS unit status is Active.

- If inactive, click Re-activate or re-run onboarding for this device.

  1. Wrong EGS unit selected

- The device generating the invoice must match a registered EGS unit.

- Ensure the correct EGS unit is selected in business settings.

  1. New device not registered

- If you've set up a new computer, register it as a new EGS unit.

- Go to ZATCA Business Settings > Onboarding > Onboard New EGS Unit.

VAT Number Validation Fails

Symptom: Invoice rejected with "Invalid VAT number" or similar.

Solutions:

  1. Company VAT number wrong

- Verify in ZATCA Business Settings that your VAT number is exactly 15 digits and starts with 3.

- It must match ZATCA's records exactly.

  1. Customer VAT number wrong

- Open the Customer record.

- The Tax ID field should contain the 15-digit VAT number starting with 3.

- For consumers (B2C), use a Simplified Invoice β€” no buyer VAT needed.

- Set the Customer's Tax Category to "Consumer" for B2C transactions.

  1. Customer not registered for Phase 2

- Not all businesses are in Phase 2 yet.

- Check with the customer about their ZATCA registration status.

Invoice Shows "Error" Status

Symptom: Invoice status is "Error" (red) instead of "Accepted" or "Rejected".

Solutions:

  1. Check ZATCA Integration Log for the specific error.
  2. Common causes:

- Network timeout to ZATCA β€” try again later.

- XML generation error β€” contact support if persistent.

- Server resource issue β€” may resolve automatically.

  1. Resubmit the invoice:

- If the error is transient, the system will automatically retry.

- For manual retry, use the Resend option on the invoice.

QR Code Not Appearing on Print

Symptom: Printed invoice doesn't show the ZATCA QR code.

Solutions:

  1. Ensure the invoice was accepted by ZATCA (status = "Accepted").
  2. Check that the correct Print Format is selected:

- Standard invoices: "ZATCA Phase 2 Print Format"

- Simplified invoices: "Simplified Invoice Print Format"

  1. The print format may need to be manually selected if the auto-detection isn't working.
  2. If the QR code still doesn't appear, contact support.

Batch Processing Not Working

Symptom: Invoices queue up but aren't being processed in batch mode.

Solutions:

  1. Go to ZATCA > E-Invoicing Sync.
  2. Click Sync Now to manually trigger processing.
  3. Check the Integration Log for errors during batch processing.
  4. Verify that batch processing is enabled in ZATCA Business Settings.
  5. If sync fails, try switching to Live mode temporarily to process outstanding invoices.

Common Error Messages Reference

Error Message Quick Fix
"Connection refused" Internet or ZATCA server issue β€” wait and retry
"Unauthorized β€” check credentials" CSID expired β€” re-run onboarding
"XML Schema Validation Failed" System issue β€” contact support
"Invoice hash mismatch" Data changed after submission β€” amend and resubmit
"Request timeout" ZATCA servers busy β€” auto-retry will handle it
"Rate limit exceeded" Too many requests β€” slow down submissions
"Invalid electronic address" Customer address missing/incorrect β€” update Customer master

When to Contact YousrERP Support

Contact support (helpdesk.botsolutions.tech) when:

  • Rejection errors persist after fixing the identified issue
  • XML validation or schema errors occur
  • CSID generation fails during onboarding
  • Certificate errors that re-onboarding doesn't fix
  • Any error you can't resolve using this guide

When contacting support, include:

  • Your company name
  • The invoice number(s) affected
  • The exact error message from the Integration Log
  • Screenshots of the ZATCA status and error
  • When the issue started