Company Integrations Modul

Zweck

Das Company Integrations Modul bietet Integrationen mit externen Systemen wie HR-Systeme, Payroll-Software, Buchhaltung, API-Zugriffe, Webhook-Konfiguration und Daten-Synchronisation für nahtlose Workflows.

Verantwortlichkeiten

Was gehört zum Modul

HR-System-Integration: Integration mit HR-Systemen
Payroll-Integration: Integration mit Payroll-Software
Buchhaltungs-Integration: Integration mit Buchhaltungssystemen
API-Zugriffe: Externe API-Zugriffe konfigurieren
Webhook-Konfiguration: Webhooks für externe Systeme
Daten-Synchronisation: Automatische Daten-Synchronisation

Was gehört nicht zum Modul

API-Tokens: Siehe Core API-Tokens
Webhook-Implementierung: Siehe Core Webhooks

Implementierung

Backend- und Frontend-API sind modular aufgebaut; Details siehe interne Entwickler-Dokumentation.

Konfiguration

Entitlement

Das Modul erfordert das Entitlement module.company_integrations. Dieses wird pro Tenant aktiviert/deaktiviert und ist nur für Firmen-Tenants verfügbar.

Entitlement-Key: module.company_integrations

Environment Variables

Keine öffentlich dokumentierten ENV-Variablen. Konfiguration erfolgt über die Admin-Oberfläche.

Defaults

Standard-Status: Inaktiv

Abhängigkeiten

Optionale Abhängigkeiten

Keine.

Core-Abhängigkeiten

api-tokens: Für API-Authentifizierung

API-Endpoints

Authentifizierung

Alle Endpoints erfordern Authentifizierung. Zwei Methoden werden unterstützt:

Firebase ID Token (Standard für Web-App)
API-Token (für externe Nutzung)

Header: Authorization: Bearer <token>

Integrationen auflisten

GET /api/company-integrations/integrations

Lädt alle konfigurierten Integrationen (nur für Firmen-Tenants).

Wird dokumentiert: Detaillierte API-Endpunkt-Dokumentation folgt.

Firestore Collections

Integrations

Pfad: /tenants/{tenantId}/integrations/{integrationId}

{
  type: 'hr' | 'payroll' | 'accounting' | 'custom';
  name: string;
  config: Record<string, unknown>;
  enabled: boolean;
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

Wird dokumentiert: Detaillierte Datenbank-Struktur folgt.

Fehlerfälle

HTTP-Status-Codes

200 OK: Erfolgreich
400 Bad Request: Validierungsfehler
401 Unauthorized: Nicht authentifiziert
403 Forbidden: Keine Berechtigung (nur Firmen-Tenants)
500 Internal Server Error: Server-Fehler

Fehlercodes

Wird dokumentiert: Detaillierte Fehlercodes folgen.

Verwendung

Integration erstellen

Navigiere zu Integrationen im Admin-Bereich
Klicke auf "Neue Integration"
Wähle entweder eine vordefinierte Integration (DATEV, Personio, etc.) oder erstelle eine Custom Integration
Konfiguriere die Basis-Einstellungen:
Name der Integration
Typ (HR, Payroll, Accounting, Custom)
Status (Aktiv/Inaktiv)
Konfiguriere die Authentifizierung:
API-Key, OAuth2, Basic Auth oder Bearer Token
Credentials werden sicher gespeichert
Konfiguriere die API-Endpunkte:
Base URL des externen Systems
Endpunkte für CRUD-Operationen
Konfiguriere die Synchronisation:
Daten-Typen auswählen (Time Entries, Members, Projects, etc.)
Sync-Richtung (Export, Import oder Bidirektional)
Filter-Kriterien
Konfiguriere Feld-Mappings:
Felder zwischen TimeAM und externem System zuordnen
Transformationen definieren (falls nötig)
Teste die Integration
Aktiviere die Integration

CSV-Export konfigurieren

Öffne die Integration-Details
Navigiere zu "CSV-Einstellungen"
Konfiguriere:
Delimiter (Standard: ;)
Encoding (Standard: UTF-8)
Date-Format
Header-Handling
Starte den Export manuell oder konfiguriere einen geplanten Export

Geplanten Export einrichten

Öffne die Integration-Details
Navigiere zu "Geplante Exporte"
Klicke auf "Neuer Export"
Konfiguriere den Zeitplan (z.B. täglich um 2 Uhr)
Setze Filter für die zu exportierenden Daten
Konfiguriere Benachrichtigungen (optional)
Aktiviere den Export

Webhook konfigurieren

Öffne die Integration-Details
Navigiere zu "Webhooks"
Für eingehende Webhooks (Extern → TimeAM):
Kopiere die automatisch generierte Webhook-URL
Generiere und kopiere das Secret
Trage die URL und das Secret im externen System ein
Für ausgehende Webhooks (TimeAM → Extern):
Gib die Webhook-URL des externen Systems ein
Gib das Secret für die Signatur ein
Teste den Webhook

Feld-Mapping konfigurieren

Öffne die Integration-Details
Navigiere zu "Feld-Mapping"
Für jeden Daten-Typ:
Ordne TimeAM-Felder externen Feldern zu
Definiere Transformationen (falls nötig)
Füge Validierungs-Regeln hinzu
Speichere die Mappings

Beispiel-Mapping: - TimeAM: member.email → Extern: employee.email_address - TimeAM: member.firstName → Extern: employee.first_name - TimeAM: member.employeeNumber → Extern: employee.id (mit Transformation)

Best Practices

Integration-Design

Verwende aussagekräftige Namen für Integrationen
Teste Integrationen vor der Aktivierung
Starte mit Export (nur TimeAM → Extern), erweitere schrittweise
Dokumentiere Custom-Konfigurationen

Feld-Mapping

Verwende Mapping-Templates für bekannte Systeme
Validiere Mappings vor dem ersten Sync
Teste Transformationen mit Test-Daten
Dokumentiere Custom-Transformationen

Performance

Verwende Batch-Sync für große Datenmengen
Setze sinnvolle Filter (nur relevante Daten)
Plane Syncs außerhalb der Geschäftszeiten
Überwache die Performance regelmäßig

FAQ

Kann ich mehrere Integrationen gleichzeitig haben?

Ja, du kannst beliebig viele Integrationen konfigurieren. Jede Integration kann für ein anderes externes System oder einen anderen Zweck verwendet werden.

Was passiert bei Konflikten bei bidirektionaler Synchronisation?

Du kannst die Konflikt-Resolution in den Integrationseinstellungen konfigurieren: - TimeAM gewinnt: TimeAM-Daten überschreiben externe Daten - Extern gewinnt: Externe Daten überschreiben TimeAM-Daten - Manuell: Konflikte werden gemeldet und müssen manuell gelöst werden

Kann ich Integrationen pausieren?

Ja, du kannst Integrationen jederzeit deaktivieren. Die Synchronisation wird dann nicht mehr ausgeführt, bis die Integration wieder aktiviert wird.

Wie lange werden Sync-Logs gespeichert?

Sync-Logs werden standardmäßig für 90 Tage gespeichert. Diese Einstellung kann in den erweiterten Einstellungen angepasst werden.

Kann ich Integrationen duplizieren?

Ja, du kannst Integrationen duplizieren, z.B. für Test-Umgebungen oder ähnliche Konfigurationen.

Was passiert bei Fehlern während der Synchronisation?

Bei Fehlern werden diese in den Sync-Logs protokolliert. Wenn Benachrichtigungen konfiguriert sind, erhältst du eine E-Mail. Das System versucht automatisch, fehlgeschlagene Syncs zu wiederholen (wenn konfiguriert).

Welche Daten-Typen können synchronisiert werden?

Time Entries (Zeiterfassungsdaten)
Members (Mitarbeiterdaten)
Projects (Projektdaten)
Shifts (Schichtdaten)
Invoices (Rechnungen)
Payments (Zahlungen)

Welche Authentifizierungs-Methoden werden unterstützt?

API-Key
OAuth2
Basic Auth (Benutzername/Passwort)
Bearer Token

Welche vordefinierten Integrationen sind verfügbar?

DATEV: Für Buchhaltung (Invoices, Payments, Members)
Personio: Für HR (Members, Absences, Time Entries)
Weitere Integrationen werden kontinuierlich hinzugefügt

Troubleshooting

Integration funktioniert nicht

Prüfe die Sync-Logs in den Integration-Details
Stelle sicher, dass die Integration aktiviert ist
Prüfe die Authentifizierung (Credentials korrekt?)
Teste die Verbindung zum externen System
Prüfe die API-Endpunkte (korrekte URLs?)

Synchronisation ist langsam

Prüfe die Batch-Größe in den erweiterten Einstellungen
Reduziere die Anzahl der gleichzeitig synchronisierten Daten-Typen
Setze sinnvolle Filter, um nur relevante Daten zu synchronisieren
Plane Syncs außerhalb der Geschäftszeiten

Feld-Mapping funktioniert nicht

Prüfe, ob alle Required-Felder gemappt sind
Validiere die Feld-Typen (String vs. Number)
Teste Transformationen mit Test-Daten
Prüfe die Sync-Logs auf spezifische Fehlermeldungen

Webhook wird nicht empfangen

Prüfe, ob die Webhook-URL korrekt im externen System eingetragen ist
Stelle sicher, dass das Secret korrekt ist
Teste den Webhook mit der Test-Funktion
Prüfe die Webhook-Logs in den Integration-Details