1. Overview

Simplify accounting for your transport business. Transport Accounting is a Joomla 6 package for taxi, cargo and passenger-transfer invoicing. It calculates Google Maps driving routes, estimates kilometres by country, allocates the selling price and VAT, stores customers and documents, applies country-specific tax rules, generates invoice descriptions and Unicode PDFs, and exports accounting data in XML for supported accounting software.

2. Requirements

3. Installation and upgrade

New installation

1. Back up the Joomla files and database.
2. In Joomla Administrator open System → Install → Extensions.
3. Upload pkg_transport_accounting_v2.0.0.zip. Use the combined package ZIP, not an enclosed individual extension ZIP.
4. Open Components → Transport Accounting → Options and configure the shared settings.
5. Open Content → Site Modules, create or open Transport Accounting, assign a position and restricted access level, then publish it on the intended menu item.
6. If subscribed to updates, enable and configure the installer update-key plugin.
7. Test a domestic and a cross-border route, a PDF, a pro forma conversion, and a Minimax import in a non-production accounting environment.

Migration from the former extension

Future Transport Accounting releases can be installed through Joomla Update or over the existing Transport Accounting package. Do not update the module, component, or plugin separately: their versions are released as one compatibility set.

Post-upgrade checks

• Clear Joomla and browser caches if the embedded calculator appears stale.
• Confirm the module and global configuration sources still point to the intended values.
• Open an older saved invoice and verify route, stop, country, adjustment and customer restoration.
• Verify the package version under System → Manage → Extensions.

4. Quick start

5. Configuration reference

Global settings live at Components → Transport Accounting → Options. Each module independently chooses Global or Module values for Google Maps, company/PDF, Minimax and countries. This permits shared accounting settings while allowing language-specific modules to override PDF text or other selected groups.

6. Calculator workflow

Route input

1. Enter pickup and drop-off using Google Places suggestions.
2. Add up to 25 additional places and arrange them in travel order.
3. Select Return trip to pickup when appropriate.
4. Enter either the transport gross price or net price. The paired value is recalculated.
5. Add costs such as parking if needed. Cost rows accept a gross amount and a VAT preset (22% S, 9.5% Z or 0% N). By default they are added on top of the entered gross price. Select Included in entered gross price when the costs are already part of that price.
6. Choose a country-split method and sampling accuracy, then select Calculate route and VAT split.

Country split methods

How amounts are allocated

The route portion of the selling price is allocated among country rows in proportion to kilometres. Each row’s configured VAT rate determines its net base and VAT. Additional-cost rows are calculated by their own VAT preset. The results show total kilometres, base/foreign kilometres, net price, taxable bases, VAT by country, additional costs, total VAT and final invoice amount.

After calculation you may edit a country’s kilometres, VAT rate, revenue account and PDF note, then select Recalculate country VAT split. The calculator adjusts the remaining country distance to match the route total.

7. Customers, drafts and documents

Customers

Customer records store the name, optional unique customer code, address, postcode, city, two-letter country code, VAT ID and reusable message/configuration details. The name is required. The code can be empty for local storage, but Minimax export requires a current valid code.

• The customer code is unique when non-empty and can be generated from the VAT ID or edited.
• For Minimax, use no more than 10 characters from A–Z, a–z, digits, #, period, underscore and hyphen.
• Use Customers to search and paginate saved customers (25/50/100 per page).
• Deleting a customer does not delete historical documents. Document payloads preserve their issued customer snapshot.

Draft invoice lines

Add to draft Invoice saves the current calculated service as a draft line for a customer/project. Draft lines can combine several transfers into a later invoice. Review service dates, labels and totals before final generation.

Invoice

1. Calculate and review the route and amounts.
2. Select or save the customer; set the issue, service, and due dates.
3. Generate the next number or supply an allowed unique number.
4. Review/edit English and Slovenian invoice text.
5. Select Generate Invoice PDF / Save. Saving and PDF generation are one workflow.

Generated invoice numbers follow TA-YY-NNNN. Allocation retries protect automatic numbering from simultaneous unique-number conflicts.

Pro forma invoice

Use Generate Pro forma invoice / Save to create a document numbered PR-TA-YY-NNNN. A pro forma is stored as open, omits the signature/stamp and cannot be exported to Minimax. Use Create Invoice to convert it once into a separately numbered invoice. The source and converted document remain linked.

Load and update

The invoice browser filters by number, document type and date. Loading a saved document restores the route, stops, return-trip flag, country rows, kilometres, VAT, Minimax accounts, PDF notes, additional costs, dates, customer and text. It can generate PDF/XML without recalculating. For a correction, load an invoice, change and recalculate it, then use Update Invoice; the original invoice number, creation time, conversion links and payments are preserved. Historical records without an explicit issue date fall back to their original creation date, and records created before the additional-cost mode was introduced retain the former included-in-gross calculation.

8. Payment tracking

Payments are recorded in the administrator component against issued invoices only. Supported methods are bank transfer, cash, card and other.

1. Open Components → Transport Accounting.
2. Find an invoice with a remaining amount and select Add payment.
3. Enter a valid date, positive amount, method, optional reference and note.
4. Save. The transaction locks the invoice while validating the remaining amount and rejects overpayment.

A Unicode payment-confirmation PDF includes supplier/customer information, invoice reference, payment history, paid and remaining totals, footer, signature and a prominent PAID/PLAČANO label when settled. It does not consume an invoice number.

9. Minimax XML export

Only an invoice can be exported. The exporter writes customer master data before journal entries, uses passenger-transport VAT accounting type PP, includes the invoice reference on the receivable line, and separates revenue from VAT liabilities.

Pre-export checklist

• ✓The current saved customer has a Minimax-compatible code of 1–10 supported characters. The current customer record overrides stale values in an older invoice payload.
• ✓Customer name/address fields fit Minimax limits and the country is a two-letter code.
• ✓The receivable account and base-country VAT account are configured.
• ✓Every used country has a VAT rate, revenue account and—when VAT applies—VAT-liability account.
• ✓Additional costs use supported S (22%), Z (9.5%) or N (0%) treatment.
• ✓Debit and credit totals balance and the selected base-country/VAT treatment matches the accountant’s instructions.

Foreign net bases remain outside Slovenian VAT when Slovenia is the base country; foreign VAT posts to the configured foreign liability account. The exporter blocks missing rates/accounts, unsupported customer codes and incompatible VAT mixtures instead of producing a knowingly incomplete file.

10. Administrator document management

The component list is server-side paginated and supports search, document-type/status filters, sortable columns and page sizes of 25, 50 or 100. It displays number, status, customer, total, payment status, date and actions.

Deletion rules

• Deletion is administrator-only, POST-only, CSRF protected and requires core.delete.
• A converted pro forma cannot be deleted alone while its linked invoice remains. Select both when deletion is genuinely required.
• Deleting only a converted invoice reopens its source pro forma and clears the conversion link.
• Deleting an invoice also deletes its payment records in the same management transaction.
• Deletion is permanent; take a backup and follow legal document-retention obligations.

Payment recording requires core.edit. Component access requires core.manage. Configuration and permission changes should be reserved for users with core.admin.

11. Subscriber updates

1. Install the combined package so the installer plugin is present.
2. Open System → Manage → Plugins.
3. Find Installer – Transport Accounting update key and enable it.
4. Open Components → Transport Accounting → Options, enter the shared subscriber update key, and save.
5. Use Joomla Update normally. The plugin adds the key only to an approved Transport Accounting package download URL.

The update feed advertises the combined package and SHA-256 checksum. The server endpoint accepts only approved package filename patterns, compares SHA-256 key hashes with constant-time matching, confines files to the downloads directory and returns ZIP downloads with nosniff.

12. Security, privacy and backup

• Use HTTPS for Joomla and Google Maps referrer restrictions.
• Grant administrator ACL rights by least privilege and review them periodically.
• Do not commit Google API keys, subscriber keys or download-keys.local.php.
• Patch Joomla, PHP, the database and this package promptly; test updates on staging.
• Back up the entire Joomla database and files before upgrades, bulk deletion or uninstall.
• Test restore procedures. The four #__transport_accounting_* tables are the core business data but a full Joomla backup is safer because configuration and extension state live elsewhere.
• Keep PDFs/XML files in controlled storage; browser downloads are outside Joomla’s access control after generation.

13. Troubleshooting

14. Technical reference

Package layout

Runtime architecture

The module template embeds media/calculator.html in an iframe, injects translated strings and selected configuration, and supplies a Joomla com_ajax URL plus session token. Google Maps performs route/place work in the browser. PDF and Minimax XML generation also occur in the browser. Customer/document persistence uses JSON POST requests to the module helper.

Frontend AJAX operations

saveCustomer, saveInvoice, updateInvoice, nextInvoiceNumber, addDraftLine, listDraftLines, deleteDraftLine, clearDraftLines, loadCustomer, listCustomers and listInvoices. Public/module invoice deletion is intentionally disabled; use the administrator component.

Database tables

Tables use InnoDB, utf8mb4 and utf8mb4_unicode_ci. Joomla’s configured database prefix replaces #__. Version 2.0.0 does not automatically copy records from the former table names; migrate required historical data manually after comparing the live table columns.

Bundled third-party/data assets

• Bootstrap 5 frontend assets.
• jsPDF for client-side PDFs.
• Noto Sans Regular/Bold for Unicode PDF text.
• Country polygon/GeoJSON boundary data for supported fast splitting.
• Google Maps JavaScript services are loaded externally with the configured key.

15. Developer release process

Before building, update package, module, component and plugin versions as appropriate, update enclosed filenames in the package manifest, and add a concise entry to VERSION_SUMMARY.md.

scripts/build-release.sh

The script validates semantic manifest versions and package references; creates module, component and plugin ZIPs; assembles the package ZIP; updates the feed download URL and SHA-256; ensures the advertised package ZIP is trackable; and verifies every archive with unzip -t.

Release verification checklist

• Install the combined ZIP into a clean Joomla 6 test site and test a future Transport Accounting upgrade separately.
• Verify manual migration from the former identifiers and preserve a copy of the original data.
• Run domestic/cross-border route, PDF, pro forma conversion, invoice update, payment and Minimax test cases.
• Confirm the update XML version, filename and SHA-256 match the generated package ZIP.
• Commit the advertised package ZIP with its update-feed change so deployment never advertises a missing file.
• Never commit local download-key configuration or real Google/subscriber keys.

16. Current release notes

For the complete historical changelog, see VERSION_SUMMARY.md in the source repository.