Nextcloud Invoice Feeder for WHMCS Печать

What It Does

Automatically uploads paid WHMCS invoices to Nextcloud. WebDAV protocol. Configurable folder structures. Bulk retry for failed uploads. CSV export of upload history.

Features

Automatic Upload:

• Paid invoices upload immediately
• Cancelled invoices upload with CANCELLED_ prefix (if previously paid)
• Refunded invoices upload with CANCELLED_ prefix
• WebDAV protocol

Folder Organization:

Configurable structures:

• Year/Quarter/Invoices (2025/Q1/Invoices/)
• Year/Quarter (2025/Q1/)
• Year/Month (2025/01/)
• Year only (2025/)
• Flat (no subfolders)

Manual Operations:

• Upload specific invoice by ID
• Bulk retry failed uploads (max 50)
• Export logs to CSV
• Real-time connection testing

Logging:

• Activity log with client names
• Upload status tracking
• Error details
• Admin to-do for failures

File Naming:

Format: YYYYMMDD_InvoiceNum_ClientName.pdf

Cancelled: YYYYMMDD_CANCELLED_InvoiceNum_ClientName.pdf

How It Works

Paid invoice flow:

1. Invoice marked paid in WHMCS
2. Hook triggers (InvoicePaid)
3. Module generates PDF
4. Uploads to Nextcloud via WebDAV
5. Files organized by configured structure
6. Success logged

Cancelled invoice flow:

1. Paid invoice cancelled or refunded
2. Hook triggers (InvoiceCancelled/InvoiceRefunded)
3. Module checks if invoice was previously paid
4. If yes: Uploads with CANCELLED_ prefix
5. If no: Skips (never paid, so never uploaded)

Failed upload handling:

1. Upload fails (network, permissions, etc.)
2. Error logged
3. Admin to-do created
4. Invoice marked for retry
5. Admin uses bulk retry later

Installation

1. Purchase from ArkHost Store
2. Upload to `/modules/addons/nextcloud_invoice_feeder/`
3. Activate in Setup → Addon Modules
4. Enter license key
5. Configure WebDAV settings
6. Test connection
7. Done

Configuration

Nextcloud Setup

Generate app password:

1. Log into Nextcloud
2. Settings → Security
3. App passwords section
4. Create new app password
5. Name it "WHMCS"
6. Copy generated password

Why app password?

• More secure than main password
• Can revoke without changing main password
• Specific to WHMCS integration
• Required for WebDAV access

Module Configuration

WHMCS Admin → Addons → Nextcloud Invoice Feeder

License Key:

ArkHost license key.

WebDAV URL:

Full path including username folder.

Format: https://your-nextcloud.com/remote.php/dav/files/username/

Example: https://cloud.example.com/remote.php/dav/files/john/

Important:

• Must include `/remote.php/dav/files/`
• Must include your username
• Must end with `/`
• Must use HTTPS

Username:

Your Nextcloud username (same as in URL).

App Password:

Generated app password from Nextcloud (not main password).

Base Path:

Root folder for invoices in Nextcloud.

Examples:

• `Invoices/` (simple)
• `Company/Finance/Invoices/` (nested)
• Leave empty for root

Folder Structure:

Choose how to organize invoices:

Year/Quarter/Invoices:

Invoices/
└── 2025/
    └── Q1/
        └── Invoices/
            ├── 20250115_1001_Client_Name.pdf
            └── 20250120_1002_Another_Client.pdf

Year/Quarter:

Invoices/
└── 2025/
    └── Q1/
        ├── 20250115_1001_Client_Name.pdf
        └── 20250120_1002_Another_Client.pdf

Year/Month:

Invoices/
└── 2025/
    └── 01/
        ├── 20250115_1001_Client_Name.pdf
        └── 20250120_1002_Another_Client.pdf

Year:

Invoices/
└── 2025/
    ├── 20250115_1001_Client_Name.pdf
    └── 20250120_1002_Another_Client.pdf

Flat:

Invoices/
├── 20250115_1001_Client_Name.pdf
└── 20250120_1002_Another_Client.pdf

Test Connection:

Click "Test Connection" button after configuration.

• Success: Green checkmark
• Failure: Error message with details

Usage

Automatic Upload

No action needed. Invoices upload automatically when paid.

What gets uploaded:

• Invoice marked paid → Uploads immediately
• Invoice cancelled (was paid) → Re-uploads with CANCELLED_ prefix
• Invoice refunded → Re-uploads with CANCELLED_ prefix

What doesn't upload:

• Unpaid invoices
• Draft invoices
• Cancelled invoices (never paid)

Manual Upload

Upload specific invoice:

1. Addons → Nextcloud Invoice Feeder
2. Enter invoice ID
3. Click "Upload Invoice"
4. View result

Use when:

• Testing configuration
• Re-uploading after fixing Nextcloud
• Uploading historical invoices
• Failed automatic upload

Bulk Retry Failed Uploads

Retry all failed:

1. Addons → Nextcloud Invoice Feeder
2. Click "Retry Failed Uploads"
3. Module processes up to 50 failed uploads
4. Results displayed

When to use:

• After Nextcloud downtime
• After fixing configuration
• After fixing folder permissions
• Periodic cleanup

Limit: 50 invoices per retry (prevents timeout)

Export Logs

Download complete history:

1. Click "Export Logs to CSV"
2. File downloads: `nextcloud_invoice_feeder_logs_YYYYMMDD.csv`

CSV contains:

• Invoice ID
• Invoice number
• Client name
• Upload date/time
• Status (Success/Failed)
• Error message (if failed)
• File path in Nextcloud

Use for:

• Accounting reconciliation
• Audit trail
• Troubleshooting
• Backup verification

File Naming

Standard format:

YYYYMMDD_InvoiceNum_ClientName.pdf

Examples:

• `20250115_1001_John_Doe.pdf`
• `20250120_1002_Acme_Corporation.pdf`

Cancelled/refunded format:

YYYYMMDD_CANCELLED_InvoiceNum_ClientName.pdf

Examples:

• `20250115_CANCELLED_1001_John_Doe.pdf`
• `20250120_CANCELLED_1002_Acme_Corporation.pdf`

Client name sanitization:

• Spaces converted to underscores
• Special characters removed
• Length limited
• Filesystem-safe

Nextcloud Folder Structure

Module creates folders automatically:

Example with Year/Quarter/Invoices:

Nextcloud/
└── Company/
    └── Finance/
        └── 2025/
            ├── Q1/
            │   └── Invoices/
            │       ├── 20250115_1001_Client.pdf
            │       └── 20250120_1002_Client.pdf
            ├── Q2/
            │   └── Invoices/
            └── Q3/
                └── Invoices/

Folder creation:

• Module creates folders as needed
• Requires write permissions
• Creates nested structure automatically
• Fails if permissions insufficient

Activity Logging

All actions logged:

• Successful uploads
• Failed uploads
• Manual uploads
• Bulk retries
• Configuration changes

View logs:

WHMCS Admin → System Logs → Module Log

Filter by "nextcloud_invoice_feeder"

Log details:

• Timestamp
• Action
• Invoice ID and number
• Client name
• Success/failure
• Error message
• File path

Admin To-Do Integration

Failed upload creates to-do:

When upload fails:

1. To-do created in WHMCS
2. Title: "Failed Nextcloud Invoice Upload"
3. Description includes:

• Invoice number
• Client name
• Error message
• Suggested action

1. Assigned to admin

View to-dos:

WHMCS Admin → To-Do List

Resolve:

1. Fix issue (permissions, connection, etc.)
2. Use bulk retry or manual upload
3. Mark to-do complete

Troubleshooting

Connection test failed:

Check WebDAV URL format:

Correct: https://cloud.example.com/remote.php/dav/files/username/
Wrong: https://cloud.example.com/username/
Wrong: http://cloud.example.com/remote.php/dav/files/username/ (no HTTPS)

Verify credentials:

• Username correct (case-sensitive)
• App password correct (not main password)
• App password not revoked

Check Nextcloud:

• WebDAV enabled
• HTTPS configured
• Network accessible from WHMCS server

Upload failed:

Check permissions:

• Nextcloud user has write access
• Base path exists
• Folder creation allowed

Check Nextcloud storage:

• Not full
• Quota not exceeded
• No file locks

Check network:

• WHMCS server can reach Nextcloud
• Firewall not blocking
• DNS resolving correctly

Review logs:

• WHMCS activity log
• Nextcloud logs
• Admin to-do details

File not appearing:

Check folder structure:

• Verify configured structure
• Check year/quarter correct
• Look in subdirectories

Check filename:

• Search by invoice number
• Look for CANCELLED_ prefix
• Check client name format

Manual upload test:

• Try uploading specific invoice
• View error message
• Fix issue

Bulk retry not working:

Check limit:

• Maximum 50 invoices per retry
• Run multiple times if needed

Check connection:

• Test connection first
• Fix any connection issues
• Verify credentials

Review results:

• Check which invoices succeeded
• Review error messages for failures
• Fix underlying issues

Use Cases

Accounting integration:

• Accountant uses Nextcloud
• Automatic invoice delivery
• No manual PDF downloads
• Organized by period

Backup and archiving:

• Invoices stored off-site
• Organized structure
• Easy retrieval
• Redundant storage

Team access:

• Share invoices with team
• Nextcloud access control
• No WHMCS admin needed
• Sync to devices

Audit compliance:

• Organized by period
• Complete history
• CSV export for auditors
• Cancelled invoices marked

When You Need This

Required if:

• Using Nextcloud for documents
• Accountant needs automatic invoice delivery
• Want off-site backup
• Team needs invoice access without WHMCS

Not required if:

• Don't use Nextcloud
• Manual invoice download acceptable
• Using different accounting software
• No document management system

Technical Specifications

Requirements:

• WHMCS 8.0+
• PHP 7.4+
• Nextcloud instance with WebDAV
• HTTPS connection
• Valid license from ArkHost

File Structure:

modules/addons/nextcloud_invoice_feeder/
├── nextcloud_invoice_feeder.php    Main module
├── hooks.php                        WHMCS hooks
├── lib/                             WebDAV library
└── lang/                            Language files

Database:

• Tracks upload status
• Stores failed uploads
• Logs activity
• No additional tables (uses WHMCS tables)

Hooks:

• InvoicePaid: Triggers upload
• InvoiceCancelled: Handles cancelled
• InvoiceRefunded: Handles refunds

WebDAV:

• Protocol: WebDAV over HTTPS
• Authentication: Basic (username + app password)
• Methods: PUT, MKCOL, PROPFIND
• Automatic folder creation

Performance:

• Async upload (doesn't block WHMCS)
• Bulk retry limited to 50
• PDF generated on-demand
• Minimal WHMCS overhead

Support

Purchase: ArkHost Store

Before contacting support:

1. Test connection in module
2. Check Nextcloud app password valid
3. Review WHMCS activity log
4. Verify WebDAV URL format

When reporting issues:

• WHMCS version
• PHP version
• Nextcloud version
• Module version
• WebDAV URL format (without credentials)
• Error from activity log
• Connection test result