Invoice-to-Cash Workflow
Metadata
| Field | Value |
|---|---|
| Phase | Phase 2: Forge |
| FWCR Category | Invoice-to-Cash |
| Owner | Product Team |
| Status | Planned |
| Last Updated | May 2026 |
Overview
This workflow handles the complete sales order-to-ZATCA clearance cycle for Phase 2. It ensures every invoice is cryptographically stamped by ZATCA before delivery to the buyer, with AI-powered error resolution for failed submissions.
Goal: Achieve >65% FWCR for Invoice-to-Cash by end of Phase 2.
Actors
| Role | Description |
|---|---|
| Sales Rep | Creates quotations and converts to Sales Orders |
| Accountant | Reviews, adjusts pricing, submits invoices |
| System | Generates ZATCA XML, calls API, attaches stamps |
| AI Assistant | Translates ZATCA errors into actionable guidance |
| Customer | Receives stamped invoice via email/PDF |
Preconditions
- Customer master exists with ZATCA-compliant fields (CR number, VAT number, building number)
- Products/Services configured with correct tax templates
- ZATCA API credentials configured in system
- OCI blob storage configured for PDF archiving
- Liquid Glass UI workspace for invoicing role configured
Postconditions
- Invoice cleared by ZATCA (cryptographic stamp)
- PDF with ZATCA QR code attached to invoice
- AR ledger entry created
- Audit trail captured
- Customer notified with stamped invoice
User Flow
Happy Path
┌─────────────────────────────────────────────────────────────────────────────┐
│ INVOICE-TO-CASH WORKFLOW │
├───────────────────────────────────────────────────────────────────────────── ┤
│ │
│ [Sales Rep] │
│ │ │
│ ▼ │
│ 1. Create/Edit Quotation │
│ │ │
│ ▼ │
│ [System] ─── Validate pricing & tax templates ──▶ [Quotation validated] │
│ │ │
│ ▼ │
│ 2. Convert to Sales Order │
│ │ │
│ ▼ │
│ [Accountant] │
│ │ │
│ ▼ │
│ 3. Review SO & Adjust if needed │
│ │ │
│ ▼ │
│ [System] ─── Generate ZATCA XML ──▶ [XML created] │
│ │ │
│ ▼ │
│ 4. Submit for ZATCA Clearance │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ZATCA API CALL │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ POST /v2/invoices/clearance │ │ │
│ │ │ Body: { XML payload } │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ├──────────────────────┬────────────────────────┤ │
│ ▼ ▼ │
│ ✓ CLEARED ✗ REJECTED │
│ │ │ │
│ ▼ ▼ │
│ 5. Attach stamp 6. AI Error Resolution │
│ │ │ │
│ ▼ ▼ │
│ 7. Generate PDF 7. Display: "Buyer's building │
│ │ number is missing" │
│ ▼ │ │
│ 8. Create AR Entry 8. Highlight field in UI │
│ │ │ │
│ ▼ ▼ │
│ 9. Notify Customer 9. User corrects & resubmits │
│ │ │ │
│ ▼ │ │
│ 10. COMPLETE ◄─────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Step-by-Step
| Step | Actor | Action | System Response |
|---|---|---|---|
| 1 | Sales Rep | Creates or edits quotation | Validates pricing, tax templates |
| 2 | Sales Rep | Reviews quotation with customer | — |
| 3 | Sales Rep | Converts to Sales Order | Creates SO with unique ID |
| 4 | Accountant | Reviews SO, adjusts if needed | Shows ZATCA field readiness |
| 5 | System | Generates ZATCA XML payload | Validates required fields |
| 6 | Accountant | Clicks "Submit for Clearance" | — |
| 7 | System | Calls ZATCA API | Returns stamp or error |
| 8a | System (success) | Attaches cryptographic stamp | XML updated with hash |
| 8b | System (error) | Calls AI Error Resolution | Translates JSON to plain text |
| 9a | System (success) | Generates PDF with QR code | PDF stored in OCI blob |
| 9b | Accountant (error) | Reviews AI guidance | Fixes indicated field(s) |
| 10 | System | Creates AR invoice entry | GL entries posted |
| 11 | System | Sends email to customer | Stamped PDF attached |
Error Scenarios
| Scenario | ZATCA Error Code | AI Translation | Resolution |
|---|---|---|---|
| Missing buyer's building number | BR-01 | "Buyer's building number is missing. Add it in Customer master under Address." | User edits customer address |
| Missing VAT registration number | BR-02 | "Buyer's VAT number is not provided. Add VAT# in Customer master." | User adds VAT# |
| Invoice total mismatch | BR-08 | "Invoice total doesn't match sum of line items + VAT. Check line 3." | User corrects amount |
| Duplicate invoice | BR-15 | "This invoice was already submitted. Use amendment flow for corrections." | User checks submission history |
| Invalid date format | BR-04 | "Invoice date should be in Gregorian calendar format." | User corrects date |
| Missing seller details | BR-06 | "Your company details are incomplete. Update in Company master." | User updates settings |
Acceptance Criteria
| # | Criteria | Test Scenario |
|---|---|---|
| 1 | Invoice clears ZATCA in under 2 seconds | Given valid invoice, When submitted, Then clearance received in 2s |
| 2 | AI error message is actionable | Given ZATCA rejection, When AI resolves, Then user knows exact field to fix |
| 3 | PDF contains ZATCA QR code | Given cleared invoice, When PDF generated, Then QR code scannable |
| 4 | AR entry matches invoice amount | Given cleared invoice, When posted, Then GL shows correct amounts |
| 5 | Customer receives stamped PDF | Given cleared invoice, When complete, Then email sent with PDF |
| 6 | Audit trail is immutable | Given any invoice action, When logged, Then cannot be modified |
Compliance Requirements
| Requirement | Implementation |
|---|---|
| ZATCA Phase 2 | All invoices must be cleared before delivery |
| ZATCA XML Schema | TLV-compliant fields per Fatoora specification |
| Cryptographic Stamp | SHA-256 hash + ZATCA signature in XML |
| PDF Requirements | QR code with ZATCA portal URL |
| Data Residency | All documents stored in OCI Riyadh/Jeddah |
| Audit Trail | Timestamped, immutable logs for all actions |
Technical Notes
| Component | Implementation |
|---|---|
| Frontend (Liquid Glass) | Next.js + shadcn/ui, RTL-ready, role-based workspace |
| API Gateway | Middleware for request orchestration, auth, logging |
| ERPNext | Sales Order, Delivery Note, Sales Invoice doctypes |
| Custom App | bayancore_erp for ZATCA XML generation, error handling |
| AI | GPT-4o with ZATCA error corpus for plain-English translations |
| Storage | OCI Object Storage for PDFs, OCI DB for audit logs |
Metrics
| Metric | Target | Measurement |
|---|---|---|
| FWCR: Invoice-to-Cash | >65% | (Cleared without rework) / (Total submitted) |
| Time-to-ZATCA Clearance | under 2 seconds | Average API response time |
| ZATCA Rejection Rate | under 5% | (Rejected) / (Total submitted) |
| AI Error Resolution Rate | >90% | (Resolved after AI help) / (Total errors) |
| Invoice Cycle Time | under 10 minutes | Start of SO to cleared invoice |
Dependencies
| Dependency | Status | Notes |
|---|---|---|
| ZATCA API credentials | Ready | Sandbox configured |
| OCI Object Storage | Ready | Jeddah region |
| ERPNext 15+ | Ready | Frappe 15 |
| Liquid Glass UI components | Planned | Phase 1 deliverable |
| AI Error Resolution service | Planned | Requires ZATCA error corpus |
| Customer master ZATCA fields | Planned | Requires data migration |
Related Documents
| Document | Link |
|---|---|
| OS Blueprint | ../os-blueprint |
| ZATCA Compliance | ../../03-compliance/zatca |
| AI Architecture | ../../04-ai-features/rag-architecture |
| Technical Spec | ../../05-technical-spec/sad |
| Phase 2 Release | ../../08-release/phase-2-forge |
Document Status
Status: ✅ PLANNED Last Updated: May 2026 Next Review: Pre-Phase 2 kickoff