Fakturator - Invoice Generator

Automated invoice generation from Toggl time tracking to Fakturoid invoices.

Overview

Fakturator is a desktop application that simplifies invoice generation for freelancers and small business owners. It automatically fetches time entries from Toggl Track and creates invoices in Fakturoid with a single click.

Key Features

• Single-Click Invoice Generation: Generate invoices for any month with one button
• Automatic Grouping: Projects with the same client are automatically combined into one invoice
• Custom Invoice Descriptions: Use templates with placeholders for professional invoice text
• API Integrations: Seamlessly connects with Toggl Track and Fakturoid APIs
• Local Data Storage: All configuration and history stored securely on your computer
• Setup Wizard: Easy first-time configuration with guided setup
• Project Configuration: Customize hourly rates, VAT, and client info per project
• Time Rounding: Configurable time rounding (e.g., to 15-minute increments)
• Tag Filtering: Exclude specific tags from billing
• Invoice History: Track all generated invoices with status and PDF links
• Client Import: Fetch client details directly from Fakturoid
• Privacy-First: No data sharing - everything stays on your local machine
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

For End Users (Windows/macOS)

Download the installer for your platform:

Windows

1. Download Fakturator-Setup.exe from Releases
2. Run the installer
3. Launch Fakturator from Start Menu
4. Complete the setup wizard

macOS

1. Download Fakturator.dmg from Releases
2. Open the DMG and drag Fakturator to Applications
3. Launch from Applications
4. Complete the setup wizard

📖 See User Guide for detailed instructions

For Developers

Prerequisites

• Python 3.9 or higher
• Toggl Track account with API access
• Fakturoid account with API access

Setup Steps

1. Clone the repository

git clone https://github.com/yourusername/Fakturator.git
cd Fakturator

2. Create and activate virtual environment

python -m venv venv

# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the application

python main.py

5. Complete the setup wizard

On first launch, you'll be guided through:

• Entering your Toggl API credentials
• Entering your Fakturoid API credentials
• Setting up your business profile
• Selecting Toggl projects to track
• Configuring invoice defaults

Usage

Getting API Credentials

Toggl Track

1. Log in to your Toggl Track account
2. Go to Profile Settings
3. Scroll down to find your API Token
4. Copy your Workspace ID from the workspace settings

Fakturoid

1. Log in to your Fakturoid account
2. Go to Settings → API
3. Generate an API key
4. Note your account slug (subdomain)

Generating Invoices

1. Launch the application

   python main.py

2. Select the month you want to generate invoices for (defaults to previous month)

3. Choose invoice mode:

   • Draft: Creates invoices as drafts for review before sending
   • Final: Creates and sends invoices directly

4. Click "Generate Invoices"

5. Review the results in the log panel and invoice history table

Project Configuration

Access project settings via Settings → Project Settings to:

• Set hourly rates per project
• Configure VAT rates
• Add client information (name, email, address, tax ID)
• Enable/disable projects for automatic invoicing
• Configure time rounding rules
• Exclude specific tags from billing

Invoice History

The main window displays a history of all generated invoices including:

• Date generated
• Invoice month
• Project name
• Total hours
• Total amount
• Status (draft/sent)
• PDF download link

Configuration

Data Storage

All data is stored locally in:

• Database: ~/.fakturator/fakturator.db (SQLite)
• Encryption Key: ~/.fakturator/.key (for API credentials)
• Logs: ~/.fakturator/logs/fakturator.log

Settings

Configure default settings via Settings → Run Setup Wizard or by editing:

• Currency (CZK, EUR, USD)
• Payment terms (default: 14 days)
• Default invoice notes
• Draft mode preference

Building Executable

To create standalone installers for distribution to non-technical users:

Windows Installer

# On Windows machine
build_windows.bat

Creates: installer\Fakturator-Setup-1.0.0.exe

macOS Application

# On macOS
./build_macos.sh

Creates: dist/Fakturator.app

📖 See Build Guide for detailed build instructions

Distribution

Once built, you can distribute the installers to colleagues who don't need Python installed:

• Windows: Share Fakturator-Setup-1.0.0.exe - double-click to install
• macOS: Share Fakturator.dmg - drag to Applications to install

Each user will configure their own API credentials on first run through the setup wizard.

Troubleshooting

API Connection Issues

• Toggl: Verify your API token and workspace ID are correct
• Fakturoid: Ensure your API key, account slug, and email are correct
• Check your internet connection

No Projects Showing

1. Go to Settings → Project Settings
2. Click "Refresh from Toggl"
3. Configure hourly rates and client information for each project

Invoice Generation Fails

• Check the log panel for error messages
• Verify project configurations have client information
• Ensure time entries exist for the selected month
• Check API credentials are valid

Logs

View detailed logs at: ~/.fakturator/logs/fakturator.log

Development

Project Structure

Fakturator/
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── src/
│   ├── __init__.py
│   ├── invoice_generator.py   # Core invoice generation logic
│   ├── api/
│   │   ├── toggl_client.py     # Toggl API client
│   │   └── fakturoit_client.py # Fakturoid API client
│   ├── database/
│   │   └── manager.py          # SQLite database manager
│   ├── models/
│   │   ├── config.py           # Configuration models
│   │   ├── invoice.py          # Invoice data models
│   │   └── toggl.py            # Toggl data models
│   ├── ui/
│   │   ├── main_window.py      # Main application window
│   │   ├── setup_wizard.py     # First-time setup wizard
│   │   └── project_settings.py # Project configuration dialog
│   └── utils/
│       ├── logger.py           # Logging utilities
│       └── transformers.py     # Data transformation utilities
└── tests/                      # Unit tests

Running Tests

pytest tests/

Code Quality

# Format code
black src/

# Lint code
flake8 src/

Data Privacy

Fakturator is designed with privacy in mind:

• All data stored locally on your computer
• API credentials encrypted with local key
• No telemetry or data sharing
• No internet access except to Toggl and Fakturoid APIs

License

[Your chosen license]

Support

For issues, feature requests, or questions:

• Create an issue on GitHub
• Contact: [your-email@example.com]

Acknowledgments

• Built with PyQt6
• Integrates with Toggl Track
• Integrates with Fakturoid

---

Version: 1.0.0 Author: Filip Last Updated: 2025-10