> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# KPI-Dashboard-API

> Leistungskennzahlen für den Autohausbetrieb verwalten und abrufen

## Überblick

Die KPI-Dashboard-API bietet umfassendes Tracking und Visualisierung von Kennzahlen für Ihren Autohausbetrieb. Überwachen Sie Vertriebsleistung, Bestandsmetriken und Kundenzufriedenheit und erstellen Sie individuelle KPIs für Ihre Geschäftsziele.

## Endpunkte

### Alle KPIs abrufen

<ParamField path="GET" type="endpoint">
  /kpis
</ParamField>

Ruft alle für den authentifizierten Nutzer konfigurierten KPIs ab, einschließlich integrierter und benutzerdefinierter KPIs.

**Antwort:**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "avg_days_to_sell",
    "title": "Average Days to Sell",
    "description": "Average number of days from listing to sale",
    "kpiType": "BUILTIN",
    "dataType": "DURATION",
    "value": 28.5,
    "trend": "down",
    "trendPercentage": -12.3,
    "icon": "calendar-days",
    "color": "#282F75",
    "displayOrder": 1,
    "isVisible": true,
    "chartType": "LINE",
    "chartEnabled": true,
    "chartConfig": {
      "timeRange": "30d",
      "showAverage": true
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]
```

***

### Nur sichtbare KPIs abrufen

<ParamField path="GET" type="endpoint">
  /kpis/visible
</ParamField>

Ruft nur KPIs ab, die für die Dashboard-Anzeige sichtbar sind.

**Antwort:**

Array von KPI-Objekten mit `isVisible: true`.

***

### KPI nach ID abrufen

<ParamField path="GET" type="endpoint">
  /kpis/{id}
</ParamField>

Ruft detaillierte Informationen zu einem bestimmten KPI ab.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Antwort:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "gross_profit_margin",
  "title": "Gross Profit Margin",
  "description": "Percentage of revenue remaining after cost of goods sold",
  "formula": "(Revenue - COGS) / Revenue * 100",
  "kpiType": "BUILTIN",
  "dataType": "PERCENTAGE",
  "value": 18.5,
  "trend": "up",
  "trendPercentage": 5.2,
  "icon": "chart-line",
  "color": "#4360B1",
  "displayOrder": 3,
  "isVisible": true,
  "chartType": "AREA",
  "chartEnabled": true,
  "chartConfig": {
    "timeRange": "90d",
    "showAverage": true,
    "showTrendline": true
  }
}
```

***

### Benutzerdefinierten KPI erstellen

<ParamField path="POST" type="endpoint">
  /kpis
</ParamField>

Erstellt einen neuen benutzerdefinierten KPI mit eigener Berechnungslogik.

**Anfrage-Body:**

```json theme={null}
{
  "key": "customer_referral_rate",
  "title": "Customer Referral Rate",
  "description": "Percentage of customers who refer others",
  "formula": "Referrals / Total Customers * 100",
  "kpiType": "CUSTOM",
  "dataType": "PERCENTAGE",
  "icon": "users",
  "color": "#28a745",
  "displayOrder": 10,
  "isVisible": true,
  "aggregation": "average",
  "targetModel": "Customer",
  "targetField": "referralCount"
}
```

<ParamField body="key" type="string" required>
  Eindeutiger Schlüssel (kleinbuchstaben, underscores)
</ParamField>

<ParamField body="title" type="string" required>
  Anzeige-Titel des KPI
</ParamField>

<ParamField body="description" type="string">
  Detaillierte Beschreibung der Kennzahl
</ParamField>

<ParamField body="formula" type="string">
  Formel oder Berechnungslogik
</ParamField>

<ParamField body="kpiType" type="enum" required>
  Typ: `BUILTIN`, `CUSTOM`
</ParamField>

<ParamField body="dataType" type="enum" required>
  Datentyp: `NUMBER`, `CURRENCY`, `PERCENTAGE`, `DURATION`, `TEXT`
</ParamField>

<ParamField body="icon" type="string">
  Icon-Kennung (FontAwesome-Name)
</ParamField>

<ParamField body="color" type="string">
  Hex-Farbcode für die Visualisierung
</ParamField>

<ParamField body="displayOrder" type="number">
  Reihenfolge für die Dashboard-Anzeige
</ParamField>

<ParamField body="isVisible" type="boolean">
  Ob der KPI im Dashboard sichtbar ist (Standard: true)
</ParamField>

<ParamField body="aggregation" type="string">
  Aggregationsmethode: `sum`, `average`, `count`, `min`, `max`
</ParamField>

<ParamField body="targetModel" type="string">
  Datenbankmodell für die Aggregation
</ParamField>

<ParamField body="targetField" type="string">
  Feld zur Aggregation
</ParamField>

**Antwort:**

```json theme={null}
{
  "id": "new_kpi_uuid",
  "key": "customer_referral_rate",
  "title": "Customer Referral Rate",
  "kpiType": "CUSTOM",
  "createdAt": "2024-01-17T09:15:00Z"
}
```

***

### KPI aktualisieren

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}
</ParamField>

Aktualisiert die Konfiguration eines KPIs. Integrierte KPIs können nur Anzeigeeinstellungen ändern, nicht die Berechnungslogik.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Anfrage-Body:**

```json theme={null}
{
  "title": "Updated Title",
  "isVisible": false,
  "displayOrder": 5,
  "color": "#ff6b6b"
}
```

Alle Felder sind optional. Nur übermittelte Felder werden aktualisiert.

***

### KPI löschen

<ParamField path="DELETE" type="endpoint">
  /kpis/{id}
</ParamField>

Löscht einen benutzerdefinierten KPI. Integrierte KPIs können nicht gelöscht werden.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Antwort:**

```json theme={null}
{
  "success": true,
    "message": "Custom KPI deleted successfully"
}
```

<Warning>
  Nur benutzerdefinierte KPIs können gelöscht werden. Der Versuch, einen integrierten KPI zu löschen, führt zu einem 400-Fehler.
</Warning>

***

### KPIs neu sortieren

<ParamField path="PUT" type="endpoint">
  /kpis/reorder
</ParamField>

Aktualisiert die Anzeigereihenfolge für mehrere KPIs gleichzeitig.

**Anfrage-Body:**

```json theme={null}
{
  "orders": [
    { "id": "kpi_uuid_1", "displayOrder": 1 },
    { "id": "kpi_uuid_2", "displayOrder": 2 },
    { "id": "kpi_uuid_3", "displayOrder": 3 }
  ]
}
```

**Antwort:**

```json theme={null}
{
  "success": true,
  "message": "KPIs reordered successfully"
}
```

***

### KPI-Sichtbarkeit umschalten

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}/toggle
</ParamField>

Schaltet die Sichtbarkeit eines KPIs im Dashboard um.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Antwort:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isVisible": false,
    "message": "KPI visibility toggled"
}
```

***

### Auf Standard-KPIs zurücksetzen

<ParamField path="POST" type="endpoint">
  /kpis/reset
</ParamField>

Setzt alle KPIs auf die Standardkonfiguration zurück. Dabei wird:

* Alle integrierten KPIs auf Standardwerte zurückgesetzt
* Alle benutzerdefinierten KPIs entfernt
* Anzeige-Reihenfolge und Sichtbarkeit zurückgesetzt

**Antwort:**

```json theme={null}
{
  "success": true,
  "message": "KPIs reset to defaults successfully",
  "kpisCount": 8
}
```

<Warning>
  Diese Aktion kann nicht rückgängig gemacht werden. Alle benutzerdefinierten KPIs und Konfigurationsänderungen gehen dauerhaft verloren.
</Warning>

***

### KPI-Chart-Konfiguration aktualisieren

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}/chart
</ParamField>

Konfiguriert die Diagramm-Darstellung für einen KPI.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Anfrage-Body:**

```json theme={null}
{
  "chartType": "BAR",
  "chartEnabled": true,
  "chartConfig": {
    "timeRange": "30d",
    "showAverage": true,
    "showTrendline": false,
    "colors": ["#282F75", "#4360B1"]
  }
}
```

<ParamField body="chartType" type="enum">
  Diagrammtyp: `NONE`, `DONUT`, `BAR`, `LINE`, `AREA`, `RADIAL`
</ParamField>

<ParamField body="chartEnabled" type="boolean">
  Diagramm anzeigen oder ausblenden
</ParamField>

<ParamField body="chartConfig" type="object">
  Diagramm-spezifische Konfiguration
</ParamField>

***

### KPI-Chartdaten abrufen

<ParamField path="GET" type="endpoint">
  /kpis/{id}/chart-data
</ParamField>

Ruft historische Zeitreihendaten für die KPI-Chart-Visualisierung ab.

**Path-Parameter:**

<ParamField path="id" type="string" required>
  KPI-UUID
</ParamField>

**Query-Parameter:**

<ParamField query="timeRange" type="enum">
  Zeitraum: `7d`, `30d`, `90d` (Standard: 30d)
</ParamField>

**Antwort:**

```json theme={null}
{
  "kpiId": "550e8400-e29b-41d4-a716-446655440000",
  "timeRange": "30d",
  "dataPoints": [
    {
      "date": "2024-01-01",
      "value": 25.5,
      "label": "Jan 1"
    },
    {
      "date": "2024-01-02",
      "value": 27.2,
      "label": "Jan 2"
    }
  ],
  "statistics": {
    "min": 22.1,
    "max": 32.8,
    "average": 27.3,
    "trend": "up"
  }
}
```

***

## Integrierte KPIs

Steer AI stellt standardmäßig folgende KPIs bereit:

| Key                           | Titel                            | Datentyp   | Beschreibung                         |
| ----------------------------- | -------------------------------- | ---------- | ------------------------------------ |
| `avg_days_to_sell`            | Durchschnittliche Verkaufstage   | DURATION   | Zeit vom Inserat bis zum Verkauf     |
| `avg_selling_price`           | Durchschnittlicher Verkaufspreis | CURRENCY   | Durchschnittlicher Verkaufspreis     |
| `gross_profit_margin`         | Bruttogewinnmarge                | PERCENTAGE | Umsatz minus COGS in Prozent         |
| `avg_age_of_inventory`        | Durchschnittliches Bestandsalter | DURATION   | Tage im Bestand                      |
| `inventory_turnover_ratio`    | Bestandsumschlagsrate            | NUMBER     | Umschlaggeschwindigkeit des Bestands |
| `customer_satisfaction_score` | Kundenzufriedenheit              | PERCENTAGE | Kundenzufriedenheitsbewertung        |
| `customer_retention_rate`     | Kundenbindungsrate               | PERCENTAGE | Anteil wiederkehrender Kunden        |
| `total_repair_cost`           | Gesamte Reparaturkosten          | CURRENCY   | Summe aller Reparaturkosten          |

## Datentypen

### NUMBER

Rohwerte (z. B. 1234, 567.89)

### CURRENCY

Geldwerte mit Währungssymbol (z. B. \$1,234.56, MAD 5,000.00)

### PERCENTAGE

Werte als Prozentangaben (z. B. 18,5%, 92,3%)

### DURATION

Zeitangaben in Tagen oder Stunden (z. B. 28 Tage, 3,5 Stunden)

### TEXT

Textwerte für nicht-numerische KPIs

## Diagrammtypen

### DONUT

Kreisdiagramm für proportionale Verteilungen

### BAR

Vertikale oder horizontale Balkendiagramme zum Vergleich

### LINE

Liniendiagramm zur Darstellung von Trends über die Zeit

### AREA

Flächendiagramm für kumulative Trends

### RADIAL

Radial-/Tacho-Diagramm für Einzelwerte

### NONE

Keine Diagrammvisualisierung

## Anwendungsfälle

### Beispiel 1: Vertriebsleistung verfolgen

```bash theme={null}
# Get visible KPIs for dashboard
curl -X GET "https://api.steerai.autos/v1/kpis/visible" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Beispiel 2: Benutzerdefinierten Lead-Conversion-KPI erstellen

```bash theme={null}
curl -X POST "https://api.steerai.autos/v1/kpis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "lead_conversion_rate",
    "title": "Lead Conversion Rate",
    "description": "Percentage of leads that convert to sales",
    "kpiType": "CUSTOM",
    "dataType": "PERCENTAGE",
    "icon": "chart-line",
    "color": "#28a745"
  }'
```

### Beispiel 3: Historische Chart-Daten abrufen

```bash theme={null}
curl -X GET "https://api.steerai.autos/v1/kpis/{kpi_id}/chart-data?timeRange=90d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Bewährte Praktiken

<AccordionGroup>
  <Accordion title="Mit integrierten KPIs starten">
    Nutzen Sie die integrierten KPIs, bevor Sie eigene erstellen. Sie sind optimiert und praxiserprobt.
  </Accordion>

  <Accordion title="Dashboard auf 6-8 KPIs begrenzen">
    Zu viele KPIs sorgen für Unübersichtlichkeit. Fokussieren Sie sich auf die wichtigsten Metriken.
  </Accordion>

  <Accordion title="Konsistente Zeiträume nutzen">
    Vergleichen Sie KPIs mit identischen Zeiträumen für aussagekräftige Einblicke.
  </Accordion>

  <Accordion title="Formeln für benutzerdefinierte KPIs dokumentieren">
    Dokumentieren Sie klar, wie eigene KPIs berechnet werden, damit das Team sie versteht.
  </Accordion>

  <Accordion title="Regelmäßig prüfen und anpassen">
    KPIs sollten sich mit Ihrem Geschäft weiterentwickeln. Quartalsweise prüfen und anpassen.
  </Accordion>
</AccordionGroup>

## Fehlercodes

| Code                          | Status | Beschreibung                                       |
| ----------------------------- | ------ | -------------------------------------------------- |
| `KPI_NOT_FOUND`               | 404    | KPI-ID existiert nicht                             |
| `CANNOT_DELETE_BUILTIN`       | 400    | Integrierte KPIs können nicht gelöscht werden      |
| `CANNOT_MODIFY_BUILTIN_LOGIC` | 400    | Logik integrierter KPIs kann nicht geändert werden |
| `DUPLICATE_KPI_KEY`           | 400    | KPI-Schlüssel existiert bereits                    |
| `INVALID_CHART_TYPE`          | 400    | Diagrammtyp nicht unterstützt                      |

<Card title="Dashboard-KPIs Leitfaden" icon="gauge-high" href="/de/guides/dashboard-kpis">
  Mehr zur Optimierung Ihres KPI-Dashboards
</Card>