Skip to content

ZATCA Sending Options – Technical Diagrams ​

This document provides a set of diagrams using Mermaid (wrapped with ::: mermaid blocks) so they render directly in VS Code Markdown preview, without needing a PlantUML server.

You can still copy the logical flows into any diagram tool if needed.


📋 Executive Summary ​

Core Behavior Rules ​

🤖 Automatic Mode ​

When SendingMode = AUTOMATIC, the system sends documents to ZATCA automatically based on the configured trigger:

  • ON_SAVE: Document sends immediately when user clicks Save

  • ON_POST: Document sends immediately when user clicks Post

  • ON_FIRST_PRINT: Document sends on first print (with fallback to Post if never printed)

🖱️ Manual Mode ​

When SendingMode = MANUAL, user must explicitly click the [Send to ZATCA] button.

🔒 Edit and Post Restrictions Based on Status ​

| ZatcaStatus | Can Edit? | Can Post? | Can Send? | User Message |

|-------------|-----------|-----------|-----------|--------------|

| NOT_SENT | ✅ Yes | ✅ Yes | ✅ Yes | - |

| SENDING | ❌ No | ❌ No | ❌ No | "العملية قيد الإرسال" (Operation in progress) |

| SENT_SUCCESSFULLY | ❌ No | ❌ No | ❌ No | "تم الإرسال بنجاح" (Sent successfully) |

| SEND_FAILED | ✅ Yes | ✅ Yes | ✅ Yes (Retry) | Error details shown |

🔄 Retry Logic ​

  • Failed documents can be edited to fix validation errors

  • Failed documents can be retried without editing (manual or automatic based on configuration)

  • Multiple retry attempts allowed until successful

🎯 Configuration Per Document Scope ​

Each document type has independent configuration:

  • ERP Sales Invoice

  • ERP Credit Note

  • ERP Advanced Payment

  • ERP Project Invoice

  • VAN Sales Invoice

  • VAN Credit Note


🎯 Quick Reference: ZATCA Flow Decision Tree ​


1. High-Level Context Diagram ​


2. Configuration Screen – Class & Data Model ​


10. Edit Lock Logic – Activity Diagram (User Story 7) ​


11. Default Seeding on ZATCA Activation – Activity Diagram (User Story 8) ​


12. Complete ZATCA Flow - Edit, Post, and Send Logic ​


13. ZATCA Status Lifecycle and Permissions ​


14. Automatic Sending Configuration Matrix ​


15. Send Retry Logic (Failed Status Handling) ​


3. ZATCA Status State Diagram (Simple) ​


4. Document Scope Enumeration ​


5. Manual Send – User Story 2 ​


6. Automatic Send on Save – User Story 3 ​


7. Automatic Send on Post – User Story 4 ​


8. Automatic Send on First Print + Fallback on Post – User Story 5 ​


Use and customize these diagrams to fit your exact architecture (sync vs async send, message bus, microservices, etc.).

Internal Documentation — Microtec