fleetbase/ledger-api

Accounting & Invoicing Extension for Fleetbase

0.0.4 2026-06-05 04:31 UTC

Requires

• php: ^8.0
• fleetbase/core-api: *
• fleetbase/fleetops-api: *
• guzzlehttp/guzzle: ^7.0
• php-http/guzzle7-adapter: ^1.0
• psr/http-factory-implementation: *
• stripe/stripe-php: ^17.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.34.1
• nunomaduro/collision: ^5.11.0|^6.4.0
• pestphp/pest: ^1.22.6
• phpstan/phpstan: ^1.10.38
• symfony/var-dumper: ^5.4.29

AGPL-3.0-or-later

• Fleetbase Pte Ltd.
• Ronald A. Richardson

• Accounting
• invoicing
• payroll
• fleetbase
• fleetbase-extension
• settlements
• finance management api
• accounting system

README

Fleetbase Ledger

Accounting, invoicing, wallets, payments, and financial reporting for Fleetbase.

Overview

Ledger is the finance and billing extension for Fleetbase. It adds a complete financial management layer to the Fleetbase console, including double-entry bookkeeping, customer invoicing, invoice templates, digital wallets, payment gateway processing, immutable transaction history, and standard financial reports.

Ledger ships as both a Laravel package and an Ember engine. The backend package provides the accounting models, services, routes, gateway drivers, events, observers, migrations, and console commands. The frontend engine provides the Ledger console experience for billing, payments, accounting, reports, and settings.

Ledger is included with standard Fleetbase installations. See the Fleetbase Ledger documentation for the product guide, concepts, and setup walkthroughs.

Contents

• Features
• Architecture
• Requirements
• Installation
• Development
• API and Extension Points
• Documentation
• Contributing
• Security
• License

Features

Accounting

• Chart of accounts for asset, liability, equity, revenue, and expense accounts.
• Double-entry journal entries with debit and credit accounts.
• Cached account balances with recalculation support.
• General ledger views per account and across the company.
• System-created and manual journal entries for operational accounting workflows.

Billing and Invoicing

• Customer invoices with line items, tax, subtotal, total, balance, due date, notes, and terms.
• Invoice lifecycle support for draft, sent, viewed, paid, overdue, cancelled, refunded, and void states.
• Invoice templates with company branding and registered template context variables.
• Invoice previews, rendered PDFs, invoice emails, and public customer invoice pages.
• Manual payment recording and invoice transaction history.
• Fleet-Ops purchase-rate integration for automatically generating draft invoices from orders.

Wallets and Transactions

• Digital wallets for companies, users, customers, drivers, and other Fleetbase subjects.
• Wallet operations for top-ups, credits, transfers, payouts, freezes, unfreezes, and recalculation.
• Atomic balance changes through WalletService.
• Immutable transaction records for wallet activity, payment activity, and operational money movement.
• Direction-aware transaction history for credits, debits, deposits, payouts, transfers, refunds, and reversals.

Payment Gateways

• Built-in gateway drivers for Stripe, QPay, and Cash/manual payments.
• Gateway configuration with encrypted credentials at rest.
• Sandbox and live environments.
• Purchases, refunds, setup intents, tokenization where supported, and gateway transaction history.
• Public gateway webhook endpoint with driver-level signature verification.
• Idempotent gateway processing through GatewayTransaction records.

Reports and Dashboard

• Financial dashboard with KPIs, revenue trends, cash flow summaries, invoice status, AR aging, wallet balances, and activity.
• Standard financial reports for balance sheet, income statement, cash flow statement, trial balance, AR aging, wallet summary, and general ledger.
• Report services built around double-entry accounting data and Fleetbase transaction records.

Fleetbase Integrations

• Fleet-Ops integration for purchase-rate invoice creation and order accounting.
• Storefront integration for direct storefront sale journal entries.
• Company and user observers that provision default accounts and wallets automatically.
• Invoice, payment, and accounting settings inside the Fleetbase console.

Architecture

Ledger is split into two distributable packages:

Package	Runtime	Description
fleetbase/ledger-api	Laravel / PHP	Backend models, routes, services, migrations, gateway drivers, observers, events, resources, reports, and console commands.
@fleetbase/ledger-engine	Ember	Fleetbase console engine for the Ledger dashboard, billing, payments, accounting, reports, and settings screens.

Backend routes are mounted under the configured Ledger API prefix, which defaults to ledger.

Route group	Authentication	Purpose
POST /ledger/webhooks/{driver}	Public, driver verified	Payment gateway webhook callbacks.
/ledger/public/invoices/{public_id}	Public	Customer invoice view, gateway list, and payment flow.
/ledger/v1/wallet/*	API key	Customer and driver wallet API endpoints.
/ledger/int/v1/*	Fleetbase session	Console APIs for accounts, invoices, journals, wallets, transactions, gateways, settings, and reports.

The Ember engine mounts at the Fleetbase extension route ledger and exposes console sections for billing, payments, accounting, reports, and settings.

Requirements

• PHP ^8.0
• Composer
• Fleetbase Core API
• Fleetbase FleetOps API
• Node.js >=18
• pnpm
• Ember CLI compatible with the workspace

Installation

Ledger comes pre-installed with Fleetbase. In a standard Fleetbase instance, open the console sidebar and navigate to Ledger to begin. Default accounts and wallets are provisioned automatically for new companies and users.

For package-level installation:

composer require fleetbase/ledger-api

pnpm install @fleetbase/ledger-engine

If you are adding Ledger to an existing Fleetbase installation, run migrations through your normal Fleetbase deployment flow, then provision defaults for existing records:

php artisan ledger:provision

Development

Fleetbase workspace linking

When working on Ledger inside a full Fleetbase checkout, use Fleetbase's package linker from the repository root instead of hand-editing console/package.json, api/composer.json, or console/pnpm-workspace.yaml.

Install the linker once from the Fleetbase repository root:

npm link

Enable Ledger as a local development package:

flb-package-linker enable ledger
flb-package-linker install ledger

Use --install to let the linker run the required package-manager commands immediately:

flb-package-linker enable ledger --install

Check link state with:

flb-package-linker status
flb-package-linker doctor

See the Fleetbase development setup guide for Docker mounts, local Ember dev server setup, package-linker details, and unlink/reset commands. Fleetbase runs Laravel Octane, so reload the API worker after PHP changes:

docker compose exec application php artisan octane:reload

Package-level development

Install dependencies:

composer install
pnpm install

Run the Ember engine locally:

pnpm start

Frontend checks:

pnpm lint
pnpm test
pnpm build

Backend checks:

composer test:lint
composer test:types
composer test:unit
composer test

Ledger Artisan commands:

php artisan ledger:provision
php artisan ledger:backfill-direction
php artisan ledger:update-overdue-invoices

ledger:provision is idempotent and can target all companies, one company, accounts only, or wallets only. ledger:backfill-direction fills missing transaction directions on older transaction rows. ledger:update-overdue-invoices marks sent or viewed invoices as overdue when their due date has passed.

API and Extension Points

Ledger exposes backend services for accounting, wallets, invoices, and payments:

• LedgerService creates double-entry journal entries and powers financial reports.
• WalletService manages wallet provisioning and balance-changing operations.
• InvoiceService creates and manages invoices, including order-based invoice creation.
• PaymentService coordinates gateway charges, refunds, setup intents, events, and gateway transaction persistence.
• PaymentGatewayManager resolves and initializes configured payment gateway drivers.

Custom payment gateways can extend AbstractGatewayDriver and implement the GatewayDriverInterface contract. Gateway drivers provide a code, name, capability list, configuration schema, purchase/refund behavior, and optional webhook or tokenization support.

Ledger also registers invoice template context variables with Fleetbase's template rendering system so invoice templates can reference invoice, transaction, account, and wallet data during rendering.

Documentation

• Ledger documentation
• Core concepts
• Payment gateways
• Adding a payment gateway driver
• Fleetbase development setup

Contributing

Contributions are welcome. Please read the contributing guide before opening a pull request.

For local changes, keep frontend and backend checks focused on the area you touched and include relevant test output in your pull request.

Security

Please do not report security issues in public GitHub issues. Contact Fleetbase at [e-mail] with details so the team can coordinate a responsible fix.

License

Fleetbase Ledger is open-source software licensed under the AGPL-3.0-or-later.