Integration Logs
The ZATCA Integration Log records every API call between YousrERP and ZATCA's Fatoora portal. When something goes wrong, the logs are the first place to look.
Accessing Integration Logs
- Go to ZATCA > ZATCA Integration Log from the search bar.
- Each log entry represents one API call to ZATCA.
- The list shows the most recent calls first.
- Use filters to narrow down by date, status, or invoice.
Reading a Log Entry
Each log entry contains:
| Field | Description |
|---|---|
| Invoice Reference | The Sales Invoice number this log relates to |
| Integration Type | What was sent (Invoice, Credit Note, Debit Note) |
| Status | Success, Failed, or Pending |
| Request Time | When the request was sent to ZATCA |
| Response Time | When ZATCA's response was received |
| ZATCA UUID | The UUID assigned by ZATCA (if successful) |
| Request XML | The XML that was sent to ZATCA |
| Response XML | The XML response received from ZATCA |
| Error Message | Description of any error that occurred |
| Validation Warnings | Any warnings from ZATCA about the invoice |
Common Log Entries Explained
Success Log
Status: Success
Response: "Invoice cleared successfully"
ZATCA UUID: 4f8a3b2c-1d5e-... Action: None needed. Invoice is compliant.
Validation Error
Status: Failed
Error: "Invalid VAT registration number format"Action: Fix the VAT number on the invoice/customer and resubmit.
Network/Timeout Error
Status: Failed
Error: "Connection timeout - unable to reach ZATCA"Action: Check your internet connection. ZATCA servers may be down — try again later.
Certificate Error
Status: Failed
Error: "Invalid or expired CSID certificate"Action: Your CSID may have expired. Re-run the Onboarding Wizard.
Duplicate Invoice
Status: Failed
Error: "Invoice with this UUID has already been submitted"Action: The invoice was already successfully submitted. This is a duplicate attempt — no action needed.
Filtering Logs
To find specific issues:
- By Invoice: Enter the invoice number to see all API calls for that invoice
- By Status: Filter to see only failed entries
- By Date Range: Narrow down to a specific period
- By Integration Type: Filter by invoice type (Standard, Simplified, Credit Note)
Exporting Logs
To share logs with support:
- Select the relevant log entries.
- Click Export to download as Excel.
- Include the exported logs when contacting YousrERP support.
When to Check Logs
Check the logs when:
- An invoice shows Rejected or Pending for too long
- You see errors on the ZATCA Dashboard
- A customer reports their QR code isn't validating
- You're investigating a specific invoice's history
- After changing company settings (to verify invoices are flowing)
Difference Between Logs and Dashboard
| Integration Log | Dashboard |
|---|---|
| Detailed per-API-call view | Summary metrics and trends |
| Shows exact XML sent/received | Shows counts and percentages |
| Technical detail for debugging | Business-level overview |
| Every single API call recorded | Aggregated data |