Kimai ↔ Easybill Sync

Synchronisiert Zeiteinträge aus Kimai automatisch als Positionen in Easybill-Entwurfsrechnungen.

Features

• Rate Limiting: Respektiert das Easybill-Limit von 60 Requests/Stunde (Token-Bucket-Algorithmus)
• Idempotenz: Bereits synchronisierte Einträge werden übersprungen (State-Datei)
• Automatische Dokumentgruppierung: Pro Kunde und Monat wird ein Entwurfsdokument angelegt/gefunden
• Flexibler Betrieb: Einmaliger Lauf, Zeitraum-Sync oder Daemon-Modus
• Kimai-Export-Markierung: Synchronisierte Einträge werden in Kimai als exportiert markiert

Screenshots

Entwurf einer Rechnung in Easybill

Überwicht einer Rechnung mit Gruppierung

Voraussetzungen

• Go 1.21+
• Kimai API-Token (Profil → API-Token)
• Easybill API-Key (Einstellungen → API)

Installation

git clone ...
cd kimai-easybill-sync
make build

Konfiguration

config.yaml.example nach config.yaml kopieren und anpassen:

kimai:
  base_url: "https://deine-kimai-instanz.de"
  api_token: "dein_kimai_token"

easybill:
  api_key: "dein_easybill_api_key"
  rate_limit_per_hour: 60

sync:
  initial_days_back: 30
  state_file: "./sync_state.json"
  timezone: "Europe/Berlin"

customer_mapping:
  - kimai_customer_id: 1
    # kein grouping    → Standard: per_day_activity
    # kein default_unit → globaler Default aus sync.default_unit
    # include_task_descriptions: false  # Nur Header + Aktivitätsbeschreibung, keine Task-Liste

Alternativ können Zugangsdaten auch als Umgebungsvariablen gesetzt werden:

export KIMAI_API_TOKEN="..."
export EASYBILL_API_KEY="..."

Verwendung

# Erstmalige Synchronisation (letzten 30 Tage)
./build/kimai-easybill-sync --mode=initial

# Täglicher Sync (gestern)
./build/kimai-easybill-sync --mode=daily

# Bestimmten Zeitraum synchronisieren
./build/kimai-easybill-sync --mode=range --from=2024-01-01 --to=2024-01-31

# Als Daemon laufen lassen (täglich 02:00 Uhr)
./build/kimai-easybill-sync --daemon

# Ausführliche Ausgabe
./build/kimai-easybill-sync --mode=daily --verbose

Cron-Job (empfohlen)

# Täglich um 02:00 Uhr synchronisieren
0 2 * * * /pfad/zu/kimai-easybill-sync --config=/pfad/zu/config.yaml --mode=daily >> /var/log/kimai-sync.log 2>&1
OR
0 2 * * * /pfad/zu/kimai-easybill-sync --config=/pfad/zu/config.yaml --mode=montly >> /var/log/kimai-sync.log 2>&1

Docker

# Image bauen
docker build -t kimai-easybill-sync .

# Als Daemon laufen lassen
docker run -d \
  -v /pfad/zu/config:/app/data \
  --name kimai-sync \
  kimai-easybill-sync

Workflow in Easybill

1. Sync läuft täglich und erstellt/ergänzt Entwurfsrechnungen pro Kunde und Monat
2. Am Monatsende prüfst du die Entwurfsrechnung in Easybill
3. Du passt sie ggf. an und verschickst sie

Projektmapping finden

• Kimai Projekt-ID: In Kimai unter Projekte → Projekt öffnen → ID in der URL
• Easybill Kunden-ID: In Easybill unter Kunden → Kunde öffnen → ID in der URL