Business Ledger Module

INTRODUCTION

The Business Ledger module provides comprehensive invoicing, client management, and tax compliance tools for entrepreneurs and small businesses. It is particularly tailored for Serbian tax system requirements but can be used internationally.

The primary use cases for this module are:

• Managing client information with tax IDs and registration numbers
• Creating and tracking invoices with multi-currency support
• Automated exchange rate conversion (Serbian National Bank integration)
• KPO Book (KPO knjiga) for tax inspection compliance
• Monitoring Serbian tax obligations (Test Samostalnosti, Pausal limit, VAT threshold)
• Sending invoices to clients via email
• Generating printable invoices and tax reports

FEATURES

Client Management

• Complete client information storage (name, contact details, address)
• Tax ID (PIB) and Company ID (MB) tracking
• Separate invoicing email address with fallback to main email
• Bank account information
• Support for both individual and business clients
• Country selection with phone prefix integration
• Full CRUD operations with permissions

Invoice Management

• Create, edit, and track invoices
• Multi-currency support (RSD, EUR, USD)
• Automatic exchange rate conversion via Serbian National Bank (NBS) API
• Line items with automatic calculations
• Service period tracking (from-to dates)
• Multiple invoice statuses (draft, sent, paid, overdue, cancelled)
• Payment tracking (payment date, payment method)
• VAT support
• Beautiful, printable invoice layout

Email Notifications

• Send invoices to clients directly from the system
• Automatic status update to "sent" after successful email delivery
• Uses client's invoicing email or falls back to main email
• Customizable email templates

KPO Book (Tax Inspection Book)

• KPO knjiga (Book of Issued Invoices) for Serbian tax compliance
• Year-based filtering
• Shows all invoices issued in calendar year regardless of payment status
• 5-column format: No., Date/Invoice#, Products, Services, Total
• Printable layout for tax inspection
• Automatic RSD conversion for all currencies

Serbian Tax Compliance

• Test Samostalnosti (Independence Test): Tracks if more than 70% of annual income comes from a single client
• Pausal Taxing Limit: Monitors if annual income stays below 6,000,000 RSD for pausal tax system
• VAT Threshold: Tracks when annual income exceeds 8,000,000 RSD, requiring VAT registration
• Dashboard displays compliance status in real-time

Dashboard & Reporting

• Comprehensive dashboard with financial overview
• Stats cards: Total Paid, Total Pending, Total Overdue, Total Expected
• Currency breakdown for multi-currency invoices (RSD total + breakdown)
• Date range filtering (current month, quarter, year, all time, custom range)
• Compliance section showing tax obligations
• Beautiful, modern UI with gradient styling

User Interface

• Sticky navigation bar for easy access across all pages
• Modern, responsive design with professional styling
• Mobile-friendly layouts
• Print support for invoices and KPO book
• Consistent theming across all pages

REQUIREMENTS

This module requires the following:

• Drupal 11.x
• PHP 8.1 or higher
• Internet connection for exchange rate API (optional, uses 1.0 rate if unavailable)

INSTALLATION

1. Install as you would normally install a contributed Drupal module. See: https://www.drupal.org/node/895232 for further information.

2. Enable the module at Admin > Extend

3. Run database updates:

   drush updb -y
   drush cr

4. Navigate to /admin/business-ledger to access the dashboard

CONFIGURATION

Permissions

Navigate to Admin > People > Permissions to configure the following:

Client Permissions:

• Administer clients: Full administrative access to client settings
• Add clients: Permission to create new clients
• Edit clients: Permission to modify existing clients
• Delete clients: Permission to remove clients
• View published clients: Permission to view active clients

Invoice Permissions:

• Administer invoices: Full administrative access to invoice settings
• Add invoices: Permission to create new invoices
• Edit invoices: Permission to modify existing invoices (also allows sending emails)
• Delete invoices: Permission to remove invoices
• View published invoices: Permission to view active invoices

General Permissions:

• Access Business Ledger: Permission to access dashboard and KPO book

Exchange Rate Configuration

The module automatically fetches exchange rates from the Serbian National Bank (NBS) via the Kurs API:

• API Endpoint: https://kurs.resenje.org/api/v1/currencies/{currency}/day-average?date={date}
• Rates are cached for 24 hours per date
• Uses middle rate (Srednji kurs) for conversions
• Falls back to 1.0 rate if API is unavailable

No configuration is required - the module handles this automatically.

USAGE

Managing Clients

1. Navigate to /admin/business-ledger and click "Clients" tab or "New Client" button
2. Click "Add Client" to create a new client
3. Fill in the required information:
   • Name (required)
   • Email and Invoicing Email
   • Phone (country prefix auto-added based on country)
   • Address, City, Postal Code, Country
   • Tax ID (PIB) and Company ID (MB)
   • Bank account
   • Internal notes

Creating Invoices

1. Navigate to /admin/business-ledger and click "Invoices" tab or "New Invoice" button
2. Fill in invoice details:
   • Client selection (required)
   • Invoice number, date, due date
   • Currency (RSD, EUR, USD)
   • Service period (from-to dates)
   • Payment information
   • Notes/terms
3. Add line items with description, quantity, and unit price
4. Invoice total is calculated automatically
5. For non-RSD currencies, exchange rate is fetched and RSD equivalent is calculated automatically

Sending Invoices to Clients

1. Open an invoice detail page
2. Click "Send to Client" button
3. Invoice is sent to client's invoicing email (or main email if not set)
4. Invoice status automatically updates to "sent"
5. Client receives email with invoice details and link

Viewing KPO Book

1. Navigate to /admin/business-ledger and click "KPO Book" tab
2. Select year from dropdown
3. View all invoices issued in that calendar year
4. Click "Print" for printer-friendly format
5. Use for tax inspection purposes

Using the Dashboard

1. Navigate to /admin/business-ledger
2. View financial overview with:
   • Total Paid (completed invoices)
   • Total Pending (unpaid invoices not yet overdue)
   • Total Overdue (past due date invoices)
   • Total Expected (all unpaid invoices)
3. Select date range: Current Month, Quarter, Year, All Time, or Custom
4. Review compliance section for Serbian tax obligations:
   • Test Samostalnosti (Independence Test)
   • Pausal Taxing Limit
   • VAT Threshold
5. All amounts show RSD total with currency breakdown

Printing Invoices

1. Open an invoice detail page
2. Click "Print" button or use browser's print function (Ctrl+P)
3. Professional print layout is automatically applied
4. Navigation and action buttons are hidden when printing

TECHNICAL DETAILS

Database Schema

Client Entity (bl_client):

• id, uuid, name, email, invoicing_email
• address, city, postal_code, country, phone
• tax_id, registration_number, bank_account
• notes, status, created, changed, user_id

Invoice Entity (bl_invoice):

• id, uuid, invoice_number
• client_id (reference)
• invoice_date, due_date, payment_date
• period_start, period_end
• status, currency, payment_method, place_of_issue
• exchange_rate, rsd_equivalent
• apply_vat, notes
• created, changed, user_id

Line Item Entity (bl_line_item):

• id, uuid, invoice_id (reference)
• description, quantity, unit_price
• created, changed, user_id

API Integration

The module integrates with the Kurs API (Serbian National Bank exchange rates):

• Real-time exchange rate fetching
• 24-hour caching per date
• Automatic fallback if API unavailable
• Supports EUR, USD, and other major currencies

Update Hooks

The module includes several database update hooks:

• 9001: Install Invoice and LineItem schemas
• 9003: Add exchange rate fields
• 9004: Populate RSD equivalents
• 9005: Update with new API
• 9006: Add service period fields
• 9007: Add invoicing email field

Always run drush updb -y after updating the module.

TROUBLESHOOTING

Exchange rates not updating

• Exchange rates are cached for 24 hours
• Clear cache: drush cr
• Check internet connection
• Verify API is accessible: https://kurs.resenje.org

Invoices showing 0 in dashboard

• Check that invoice_date is set correctly
• Verify date range filter in dashboard
• Ensure invoices have RSD equivalent calculated

Email not sending

• Check that client has email or invoicing_email set
• Verify Drupal mail system is configured
• Check permissions (user needs 'edit invoices' permission)
• Review site email configuration at /admin/config/system/site-information

Dashboard stats incorrect

• Clear cache: drush cr
• Verify invoice statuses are set correctly
• Check that RSD equivalents are calculated (re-save invoices if needed)

DEVELOPMENT

For developers working on this module:

1. Read /web/modules/custom/business_ledger/Claude.md for detailed technical documentation
2. Date fields are stored as VARCHAR in Y-m-d format, not timestamps
3. Dashboard stats return both rsd_total and breakdown arrays
4. Always run drush cr after making changes to routes, libraries, or themes
5. Use update hooks for schema changes

ROADMAP

Future planned features:

• PDF invoice generation with custom templates
• Bulk invoice operations
• Advanced reporting and analytics
• Client portal for viewing invoices
• Payment gateway integration
• Recurring invoices
• Invoice templates with custom branding
• Export to accounting software
• E-invoice integration (SEF system for Serbia)

SUPPORT

For bug reports and feature requests:

• GitHub: https://github.com/418-HTTP (if public repository exists)
• Email: Contact module maintainer

MAINTAINERS

Current maintainers:

• Slobodan Prodanović (HTTP 418) - https://www.drupal.org/u/slobaprodanovic

This project is sponsored by:

• HTTP 418 - https://www.slobaprodanovic.in.rs

LICENSE

This module is licensed under the GNU General Public License v2.0 or later.