Skip to content

USER_GUIDE.md

Latest commit

 

History

History
237 lines (174 loc) · 6.6 KB

USER_GUIDE.md

File metadata and controls

237 lines (174 loc) · 6.6 KB

Fakturator - User Guide

Welcome to Fakturator! This guide will help you get started with automated invoice generation from Toggl to Fakturoid.

Installation

Windows

  1. Download Fakturator-Setup.exe
  2. Double-click to install
  3. Follow the installation wizard
  4. Launch from Start Menu or Desktop shortcut

macOS

  1. Download Fakturator.dmg
  2. Open the DMG file
  3. Drag Fakturator to Applications folder
  4. Open from Applications

First Time Setup

When you launch Fakturator for the first time, you'll see a Setup Wizard.

Step 1: API Credentials

Toggl API Token

  1. Log in to Toggl Track
  2. Click your profile picture → Profile Settings
  3. Scroll down to "API Token"
  4. Copy the token and paste it into Fakturator

Fakturoid Credentials

  1. Log in to Fakturoid
  2. Go to Settings → API
  3. Copy these values:
    • Account Slug: Your subdomain (e.g., if your URL is yourcompany.fakturoid.cz, use yourcompany)
    • Client ID: Long alphanumeric string
    • Client Secret: Another long alphanumeric string

Step 2: Your Profile

Fill in your business information:

  • Name
  • Business name
  • Email
  • Address
  • Tax ID / VAT ID
  • Bank account
  • Phone

This information will appear on your invoices.

Step 3: Project Settings

The wizard will fetch your Toggl projects. For each project, configure:

  • Hourly Rate: How much you charge per hour
  • VAT Rate: Tax percentage (default 21%)
  • Client Name: Who you're invoicing
  • Client Details: Email, address, tax ID
  • Include in Invoices: Enable/disable automatic invoicing for this project

💡 Tip: Use the "Fetch from Fakturoid" button to import existing client details!

Step 4: Invoice Settings

  • Currency: CZK, EUR, etc.
  • Payment Terms: Days until invoice is due (default 14)
  • Create as Draft: Generate invoices as drafts for review before sending

Daily Usage

Generating Invoices

  1. Select Month: Choose the month to invoice
  2. Review Preview: Check hours and amounts for each project
  3. Generate: Click "Send to Fakturoid"

Automatic Grouping

Projects with the same client name are automatically combined into one invoice!

Example:

  • Project A: Client = "ACME Corp" → 10 hours
  • Project B: Client = "ACME Corp" → 5 hours
  • Result: One invoice for ACME Corp with 15 hours total

Custom Invoice Descriptions

You can customize how time entries appear on invoices:

  1. Go to Settings → Project Settings
  2. Select a project and click Edit
  3. In "Invoice Description" field, enter your template

Available Placeholders:

  • {project_name} - Project name
  • {month} - Month being invoiced
  • {start_date} - First day of month
  • {end_date} - Last day of month
  • {hours} - Total hours worked

Example:

Software development services for {project_name} ({month})

Managing Projects

Adding New Projects

  1. Go to Settings → Project Settings
  2. Click Refresh from Toggl
  3. New projects will appear automatically
  4. Click Edit Selected to configure them

Editing Project Details

  1. Settings → Project Settings
  2. Select a project
  3. Click Edit Selected
  4. Update rates, client info, etc.
  5. Click Save

Importing Client from Fakturoid

Instead of typing client details manually:

  1. Edit a project
  2. Click Fetch from Fakturoid
  3. Select the client from the list
  4. All details are automatically filled!

Viewing Invoice History

The main window shows all previously generated invoices:

  • Date created
  • Project name
  • Total amount
  • Status (Draft/Sent)
  • Invoice ID

Tips & Best Practices

✅ DO:

  • Set up all your projects with correct client names at the start
  • Use exact same client name for projects you want grouped together
  • Review the preview before generating invoices
  • Keep your Toggl time entries accurate and well-tagged
  • Use custom descriptions for professional invoices

❌ DON'T:

  • Generate the same month twice (unless you deleted the first invoice in Fakturoid)
  • Use different client name spellings for the same client
  • Forget to track your time in Toggl!

Common Questions

Q: Can I generate invoices for the same month twice?

A: Yes, but you need to delete the old invoice in Fakturoid first, or use the "Force" option.

Q: Why aren't my time entries showing up?

A: Check that:

  • Time entries exist in Toggl for the selected month
  • The project is configured in Fakturator
  • "Include in Invoices" is enabled for that project

Q: How do I group multiple projects into one invoice?

A: Simple! Just give them the exact same client name in Project Settings.

Example:

Project: "Website Development" → Client: "ACME Corp"
Project: "Mobile App" → Client: "ACME Corp"
= One invoice for "ACME Corp" with both projects

Q: Can I edit the invoice after it's sent to Fakturoid?

A: Yes! Log in to Fakturoid and edit there. Fakturator creates the invoice, Fakturoid manages it after that.

Q: What if I want different hourly rates for the same client?

A: No problem! Each project can have its own rate. The invoice will show separate line items with different rates.

Q: Where are my credentials stored?

A: Encrypted locally on your computer at:

  • Windows: C:\Users\YourName\.fakturator\
  • macOS: /Users/YourName/.fakturator/

Q: Can I use this offline?

A: No, you need internet connection to access Toggl and Fakturoid APIs.

Troubleshooting

"No projects configured for invoicing"

Solution: Go to Settings → Project Settings and enable "Include in Invoices" for your projects.

"Connection failed"

Solution: Check your internet connection and verify your API credentials are correct.

"No time entries found"

Solution: Make sure you've tracked time in Toggl for the selected month and project.

Wrong client showing on invoice

Solution: Edit the project settings and make sure the client name exactly matches the one in Fakturoid.

Application won't start

Solution:

  1. Try restarting your computer
  2. Re-run the installer
  3. Check for antivirus blocking the application

Need Help?

If you encounter issues:

  1. Check this guide first
  2. Try re-running the setup wizard: Settings → Re-run Setup Wizard
  3. Contact your IT department or the person who provided Fakturator
  4. Check the log files at ~/.fakturator/logs/ for detailed error messages

Updates

To update Fakturator:

  1. Download the new installer
  2. Run it (it will update your existing installation)
  3. Your settings and data are preserved

Happy Invoicing! 🎉