Invoice Creation

Overview

📤 Direction: Zudello → Zavanti
⚡ Sync Type: Real-time
🌐 API Endpoint: zav_webexpenseses
💼 Purpose: Web expense creation with comprehensive transaction linking and automatic purchase order closure

Invoice data flows from Zudello to Zavanti as web expenses, with automatic purchase order closure functionality and comprehensive transaction linking.

Invoice Creation Features

✅ Automatic Linking - Links invoices to originating work orders automatically
✅ PO Closure Automation - Optionally closes purchase orders based on configuration
✅ Web Integration - Provides web URL links for easy navigation
✅ GST Calculation - Automatically calculates GST-exclusive amounts

API Configuration

Endpoint: /api/data/v9.2/zav_webexpenseses
Method: POST
Authentication: Zavanti universal authentication

Field Mappings

Zavanti Field	Zudello Field	Data Type	Notes
zav_invoicedate	date_issued	Date	Invoice date
statuscode	custom.closePO evaluation	Integer	1 if closePO is false, 3 if true
zav_invoiceno	document_number	String	Invoice number
zav_poworkorderno	Purchase order mapping	String	From related transaction
zav_name	document_number	String	Same as invoice number
zav_WorkTask@odata.bind	Purchase order external_id	String	OData binding to maintenance task
zav_invoicevalue	total	Decimal	Total invoice amount
zav_invoiceamountexclgst	Calculated	Decimal	Total minus tax
zav_link	webURL	String	Link back to Zudello

Purchase Order Resolution

The integration resolves related purchase orders through transaction allocations:

Resolution Process

1. Allocation Analysis

Examines line item allocations to find related transactions:

• Source: Transaction allocation data from invoice lines
• Target: Identifies non-invoice transactions in allocations
• Filtering: Excludes current invoice from analysis

2. Related Transaction Identification

Finds the purchase order transaction:

• Method: Looks for transaction that isn't the current invoice
• Validation: Ensures transaction exists and has valid external_id
• Data Extraction: Extracts PO number, external_id, UUID, module, and submodule

3. PO Data Extraction

Extracts essential purchase order information:

• PO Number: Document number from related transaction
• External ID: Zavanti maintenance task identifier
• UUID: Zudello transaction identifier
• Module/Submodule: Transaction classification

Status Code Logic

Determines web expense status based on purchase order closure configuration:

Status Determination

Zudello Configuration	Zavanti Status Code	Result
custom.closePO = false	1	Purchase order remains open
custom.closePO = true	3	Purchase order should be closed

Status Impact

• Status 1: Allows continued activity on purchase order
• Status 3: Triggers purchase order closure workflow in Zavanti

OData Binding Construction

Creates proper OData reference for linking to maintenance tasks:

Binding Format

/zav_maintenancetasks({external_id})

Construction Process

1. External ID: Uses external_id from related purchase order
2. Validation: Ensures external_id is valid GUID format
3. Binding: Creates OData navigation property reference
4. Integration: Links web expense to originating work order

Purchase Order Closure

When closePO configuration is true, automatically updates the related purchase order:

Closure Process

1. Condition Check

Verifies if purchase order should be closed:

• Configuration: Checks custom.closePO field value
• Validation: Ensures PO resolution was successful
• Permission: Confirms user has PO update permissions

2. PO Update Fields

Zudello Field	Value	Notes
status	"COMPLETE"	Marks PO as complete
external_id	From PO resolution	Maintains external reference

3. Update Execution

• Method: Updates Zudello purchase order transaction
• Timing: Performed after successful web expense creation
• Validation: Confirms successful status update

GST Calculation

Automatically calculates GST-exclusive amounts for Zavanti integration:

Calculation Method

zav_invoiceamountexclgst = total - tax

Benefits

• Tax Compliance: Separates GST from base amount
• Reporting: Enables accurate tax reporting in Zavanti
• Integration: Matches Zavanti's tax structure requirements

Web URL Integration

Provides navigation links back to Zudello for seamless user experience:

URL Construction

• Source: Uses webURL field from Zudello transaction
• Purpose: Enables quick navigation back to invoice details
• Integration: Maintains workflow continuity between systems

Error Handling

PO Resolution Errors

• Missing Allocations: Handles cases where no allocations exist
• PO Resolution Failures: Logs warnings for unresolved purchase orders
• Invalid External IDs: Manages cases with malformed external identifiers
• Missing Transactions: Handles allocations to non-existent transactions

Web Expense Creation Errors

• API Failures: Uses Zudello's failIf method for error handling
• Validation Errors: Handles Zavanti field validation failures
• Authentication Issues: Manages authentication and permission errors
• Network Problems: Handles connectivity issues gracefully

PO Closure Errors

• Update Failures: Handles cases where PO status update fails
• Permission Issues: Manages insufficient permission scenarios
• Transaction Conflicts: Handles concurrent update conflicts
• Status Validation: Ensures status update is valid

Transaction Completion

Upon successful web expense creation:

Success Process

1. External ID Assignment

Sets invoice external_id to document_number for future reference

2. Status Update

Marks Zudello transaction as complete to finalize processing

3. Success Logging

Comprehensive success logging with:

• Web Expense ID: Zavanti web expense identifier
• PO Closure Status: Whether PO was closed (if applicable)
• Transaction Details: Complete transaction information

Use Cases

Invoice Processing

• Automated Creation: Automatic invoice creation in Zavanti
• Work Order Linking: Links invoices to originating maintenance tasks
• PO Closure: Optional automatic closure of related purchase orders
• Tax Integration: Proper GST handling for compliance

Workflow Management

• End-to-End Processing: Completes work order to invoice workflow
• Status Management: Maintains status consistency across systems
• Audit Trail: Creates comprehensive audit trail for compliance
• Web Integration: Seamless navigation between systems

Financial Management

• GL Integration: Proper integration with Zavanti financial structure
• Tax Compliance: Accurate GST calculation and reporting
• Cost Tracking: Links costs back to originating work orders
• Budget Management: Enables budget tracking by work order

Integration Benefits

Workflow Automation

• Automated Processing: Eliminates manual invoice creation in Zavanti
• PO Closure: Optional automated purchase order closure
• Link Management: Automatic linking to originating work orders
• Status Synchronization: Maintains consistent status across systems

Data Integrity

• Transaction Linking: Reliable linking between invoices and work orders
• Bidirectional Updates: Updates both Zavanti and Zudello records
• Audit Trail: Complete audit trail from work order to invoice
• Error Recovery: Comprehensive error handling and recovery

Configuration Requirements

Invoice Creation Setup

For successful invoice creation:

• Configure Zavanti universal authentication
• Ensure transaction allocations properly link invoices to purchase orders
• Set up closePO configuration for purchase order closure behavior
• Verify webURL field is populated for navigation links
• Configure GST calculation parameters
• Set up appropriate error handling for failed invoice creation

Troubleshooting

Issue	Cause	Solution
Invoice creation fails	Missing required fields	Ensure all required invoice fields are populated
PO linking errors	Allocation data missing	Verify transaction allocations exist and are valid
OData binding failures	Invalid external_id format	Check external_id is valid GUID format
GST calculation errors	Missing tax amounts	Verify tax calculations are correct in Zudello
PO closure failures	Insufficient permissions	Check user permissions for PO updates
Web expense not created	API authentication issues	Verify Zavanti authentication credentials
Status code issues	closePO configuration problems	Check custom.closePO field configuration

Related Documentation

• Work Order - Work order creation and master data mapping
• Work Order Approval - Approval processing workflow
• Overview - Integration architecture overview