Zum Inhalt

Company Branding Modul

Zweck

Das Company Branding Modul bietet vollständige Branding-Anpassung für Firmen mit eigenen Farben, Logo-Upload, Custom CSS, Announcement Bar, individuellen Begrüßungstexten und Firmen-spezifischem Erscheinungsbild.

Verantwortlichkeiten

Was gehört zum Modul

  • Farben anpassen: Eigene Farben für die Anwendung
  • Logo-Upload: Firmen-Logo hochladen und anzeigen
  • Custom CSS: Eigene CSS-Styles hinzufügen
  • Announcement Bar: Ankündigungsleiste konfigurieren
  • Begrüßungstexte: Individuelle Begrüßungstexte
  • Firmen-Erscheinungsbild: Vollständige Anpassung des UI

Was gehört nicht zum Modul

  • Tenant-Verwaltung: Siehe Core Tenancy
  • Benutzer-Verwaltung: Siehe members Modul

Implementierung

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

Konfiguration

Entitlement

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

Entitlement-Key: module.company_branding

Environment Variables

Keine modulspezifischen ENV-Variablen erforderlich.

Defaults

  • Standard-Farben: TimeAM Standard-Farben
  • Logo: TimeAM Standard-Logo

Abhängigkeiten

Optionale Abhängigkeiten

Keine.

Core-Abhängigkeiten

Keine.

API-Endpoints

Authentifizierung

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

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

Header: Authorization: Bearer <token>

Branding-Konfiguration abrufen

GET /api/company-branding/config

Lädt die Branding-Konfiguration für den aktuellen Tenant. Öffentlich (auch für Employee), damit alle User das Branding sehen können.

Response: 

{
  "config": {
    "primaryColor": "#1976d2",
    "secondaryColor": "#dc004e",
    "logoUrl": "https://...",
    "customCss": "...",
    "welcomeText": "Willkommen bei TimeAM"
  }
}

Branding-Konfiguration aktualisieren

PUT /api/company-branding/config

Aktualisiert die Branding-Konfiguration (nur Admin/Manager).

Request Body: 

{
  "primaryColor": "#1976d2",
  "secondaryColor": "#dc004e",
  "logoUrl": "https://...",
  "customCss": "...",
  "welcomeText": "Willkommen bei TimeAM"
}

Response: 

{
  "message": "Branding-Konfiguration aktualisiert",
  "config": {
    "primaryColor": "#1976d2",
    "secondaryColor": "#dc004e",
    "logoUrl": "https://...",
    "customCss": "...",
    "welcomeText": "Willkommen bei TimeAM"
  }
}

Fehler: - 400 VALIDATION_ERROR: Ungültige Eingabedaten - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Branding aktualisieren

Branding-Konfiguration zurücksetzen

DELETE /api/company-branding/config

Setzt die Branding-Konfiguration auf Standard-Werte zurück (nur Admin/Manager).

Response: 

{
  "message": "Branding-Konfiguration zurückgesetzt",
  "config": {
    "primaryColor": null,
    "secondaryColor": null,
    "logoUrl": null,
    "customCss": null
  }
}

Ankündigungen

Aktive Ankündigung abrufen

GET /api/company-branding/announcement

Lädt die aktive Ankündigung für den aktuellen Tenant. Öffentlich (auch für Employee), berücksichtigt User-spezifische Dismissals.

Response: 

{
  "announcement": {
    "id": "announcement123",
    "title": "Wichtige Ankündigung",
    "message": "Bitte beachten Sie...",
    "type": "info",
    "dismissible": true,
    "startsAt": "2024-01-15T00:00:00Z",
    "endsAt": "2024-01-31T23:59:59Z"
  }
}

Ankündigung erstellen

POST /api/company-branding/announcement

Erstellt eine neue Ankündigung (nur Admin/Manager).

Request Body: 

{
  "title": "Wichtige Ankündigung",
  "message": "Bitte beachten Sie...",
  "type": "info",
  "dismissible": true,
  "startsAt": "2024-01-15T00:00:00Z",
  "endsAt": "2024-01-31T23:59:59Z"
}

Response: 

{
  "message": "Ankündigung erstellt",
  "announcement": {
    "id": "announcement123",
    "title": "Wichtige Ankündigung",
    "message": "Bitte beachten Sie...",
    "type": "info",
    "dismissible": true
  }
}

Fehler: - 400 VALIDATION_ERROR: Titel, Nachricht oder Datum erforderlich oder ungültig - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Ankündigungen erstellen

Ankündigung aktualisieren

PUT /api/company-branding/announcement/:id

Aktualisiert eine Ankündigung (nur Admin/Manager).

Request Body: 

{
  "title": "Aktualisierte Ankündigung",
  "message": "Aktualisierte Nachricht",
  "type": "warning",
  "dismissible": false
}

Response: 

{
  "message": "Ankündigung aktualisiert",
  "announcement": {
    "id": "announcement123",
    "title": "Aktualisierte Ankündigung",
    "message": "Aktualisierte Nachricht"
  }
}

Fehler: - 404 NOT_FOUND: Ankündigung nicht gefunden - 400 VALIDATION_ERROR: Ungültige Eingabedaten - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Ankündigungen aktualisieren

Ankündigung löschen

DELETE /api/company-branding/announcement/:id

Löscht eine Ankündigung (nur Admin/Manager).

Response: 

{
  "success": true,
  "message": "Ankündigung gelöscht"
}

Fehler: - 404 NOT_FOUND: Ankündigung nicht gefunden - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Ankündigungen löschen

Ankündigung ausblenden

POST /api/company-branding/announcement/:id/dismiss

Markiert eine Ankündigung als ausgeblendet für den aktuellen User. Öffentlich (auch für Employee).

Response: 

{
  "success": true,
  "message": "Ankündigung ausgeblendet"
}

Fehler: - 404 NOT_FOUND: Ankündigung nicht gefunden - 400 NOT_DISMISSIBLE: Diese Ankündigung kann nicht ausgeblendet werden

Custom Fields

Custom Fields abrufen

GET /api/company-branding/custom-fields

Lädt alle Custom-Felder-Definitionen für den aktuellen Tenant (nur Admin/Manager).

Response: 

{
  "fields": [
    {
      "id": "field123",
      "key": "employee_number",
      "label": "Mitarbeiternummer",
      "type": "text",
      "required": false,
      "order": 1
    }
  ]
}

Custom Field erstellen

POST /api/company-branding/custom-fields

Erstellt eine neue Custom-Feld-Definition (nur Admin/Manager).

Request Body: 

{
  "key": "employee_number",
  "label": "Mitarbeiternummer",
  "type": "text",
  "required": false,
  "order": 1
}

Response: 

{
  "message": "Custom-Feld erstellt",
  "field": {
    "id": "field123",
    "key": "employee_number",
    "label": "Mitarbeiternummer",
    "type": "text",
    "required": false,
    "order": 1
  }
}

Fehler: - 400 VALIDATION_ERROR: Key, Label oder Type erforderlich oder bereits existiert - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Custom Fields erstellen

Custom Field aktualisieren

PUT /api/company-branding/custom-fields/:id

Aktualisiert eine Custom-Feld-Definition (nur Admin/Manager).

Request Body: 

{
  "label": "Aktualisierte Mitarbeiternummer",
  "required": true,
  "order": 2
}

Response: 

{
  "message": "Custom-Feld aktualisiert",
  "field": {
    "id": "field123",
    "label": "Aktualisierte Mitarbeiternummer",
    "required": true,
    "order": 2
  }
}

Fehler: - 404 NOT_FOUND: Custom Field nicht gefunden - 400 VALIDATION_ERROR: Ungültige Eingabedaten - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Custom Fields aktualisieren

Custom Field löschen

DELETE /api/company-branding/custom-fields/:id

Löscht eine Custom-Feld-Definition (nur Admin/Manager).

Response: 

{
  "success": true,
  "message": "Custom-Feld gelöscht"
}

Fehler: - 404 NOT_FOUND: Custom Field nicht gefunden - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Custom Fields löschen

Custom Fields sortieren

PUT /api/company-branding/custom-fields/reorder

Sortiert Custom Fields neu (nur Admin/Manager).

Request Body: 

{
  "fieldIds": ["field123", "field456", "field789"]
}

Response: 

{
  "message": "Custom-Felder sortiert",
  "fields": [
    {
      "id": "field123",
      "order": 1
    },
    {
      "id": "field456",
      "order": 2
    },
    {
      "id": "field789",
      "order": 3
    }
  ]
}

Fehler: - 400 VALIDATION_ERROR: fieldIds ist erforderlich - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Custom Fields sortieren

Firestore Collections

Branding Settings

Pfad: /tenants/{tenantId}/branding

{
  primaryColor?: string;
  secondaryColor?: string;
  logoUrl?: string;
  customCss?: string;
  announcementBar?: {
    enabled: boolean;
    text?: string;
  };
  welcomeText?: string;
  updatedAt: Timestamp;
  updatedBy: string; // UID
}

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, nur Admin)
  • 500 Internal Server Error: Server-Fehler

Fehlercodes

Die folgenden Fehlercodes werden von den API-Endpunkten zurückgegeben:

  • NOT_FOUND: Ressource nicht gefunden
  • VALIDATION_ERROR: Validierungsfehler bei Eingabedaten
  • ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können diese Operation ausführen
  • NOT_DISMISSIBLE: Ankündigung kann nicht ausgeblendet werden

FAQ / Troubleshooting

Wird dokumentiert: Häufige Fragen und Lösungen folgen.