> ## 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.

# API für Dashboard-Analytik

> Abruf umfassender Dashboard-Statistiken und Performance-Metriken

## Überblick

Die API für Dashboard-Analytik liefert aggregierte Statistiken und Performance-Kennzahlen für den Betrieb Ihres Autohauses. Erhalten Sie Echtzeit-Einblicke in Verkauf, Bestand und Kundenmetriken mit flexibler Filterung nach Zeitraum.

## Endpunkte

### Dashboard-Statistiken abrufen

<ParamField path="GET" type="endpoint">
  /analytics/dashboard/stats
</ParamField>

Ruft umfassende Dashboard-Statistiken inklusive KPI-Werte und Trends ab.

**Query-Parameter:**

<ParamField query="period" type="enum">
  Zeitraum für die Berechnung. Optionen:

  * `last7days` - Letzte 7 Tage
  * `last30days` - Letzte 30 Tage (Standard)
  * `last90days` - Letzte 90 Tage
  * `thisWeek` - Aktuelle Woche (Montag-Sonntag)
  * `lastWeek` - Vorherige Woche
  * `thisMonth` - Aktueller Kalendermonat
  * `lastMonth` - Vorheriger Kalendermonat
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "avgDaysToSell": {
      "current": 28.5,
      "previous": 32.4,
      "change": -3.9,
      "changePercentage": -12.0,
      "trend": "down",
      "unit": "days"
    },
    "avgSellingPrice": {
      "current": 185000,
      "previous": 178500,
      "change": 6500,
      "changePercentage": 3.6,
      "trend": "up",
      "unit": "MAD"
    },
    "grossProfitMargin": {
      "current": 18.5,
      "previous": 17.2,
      "change": 1.3,
      "changePercentage": 7.6,
      "trend": "up",
      "unit": "%"
    },
    "avgAgeOfInventory": {
      "current": 45.2,
      "previous": 48.1,
      "change": -2.9,
      "changePercentage": -6.0,
      "trend": "down",
      "unit": "days"
    },
    "inventoryTurnoverRatio": {
      "current": 8.1,
      "previous": 7.5,
      "change": 0.6,
      "changePercentage": 8.0,
      "trend": "up",
      "unit": "times/year"
    },
    "customerSatisfactionScore": {
      "current": 4.6,
      "previous": 4.5,
      "change": 0.1,
      "changePercentage": 2.2,
      "trend": "up",
      "unit": "out of 5"
    },
    "customerRetentionRate": {
      "current": 68.5,
      "previous": 65.2,
      "change": 3.3,
      "changePercentage": 5.1,
      "trend": "up",
      "unit": "%"
    },
    "totalRepairCost": {
      "current": 125400,
      "previous": 118900,
      "change": 6500,
      "changePercentage": 5.5,
      "trend": "up",
      "unit": "MAD"
    }
  },
  "meta": {
    "period": "last30days",
    "startDate": "2023-12-18",
    "endDate": "2024-01-17",
    "comparisonStartDate": "2023-11-18",
    "comparisonEndDate": "2023-12-17",
    "calculatedAt": "2024-01-17T10:30:00Z"
  }
}
```

**Struktur der Statistik-Objekte:**

Jede Kennzahl enthält:

<ResponseField name="current" type="number">
  Wert des aktuellen Zeitraums
</ResponseField>

<ResponseField name="previous" type="number">
  Wert des vorherigen Zeitraums zum Vergleich
</ResponseField>

<ResponseField name="change" type="number">
  Absolute Veränderung zwischen den Zeiträumen
</ResponseField>

<ResponseField name="changePercentage" type="number">
  Prozentuale Veränderung zwischen den Zeiträumen
</ResponseField>

<ResponseField name="trend" type="enum">
  Trendrichtung: `up`, `down`, `stable`
</ResponseField>

<ResponseField name="unit" type="string">
  Maßeinheit (days, MAD, %, usw.)
</ResponseField>

***

### Daten für Bestandsumschlag-Chart abrufen

<ParamField path="GET" type="endpoint">
  /analytics/inventory-turnover
</ParamField>

Ruft Zeitreihendaten zur Visualisierung des Bestandsumschlags ab.

**Query-Parameter:**

<ParamField query="period" type="enum">
  Zeitraum für Chart-Daten (gleiche Optionen wie Dashboard-Statistiken)
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "day": "Monday",
      "date": "2024-01-01",
      "value": 7.8
    },
    {
      "day": "Tuesday",
      "date": "2024-01-02",
      "value": 8.1
    },
    {
      "day": "Wednesday",
      "date": "2024-01-03",
      "value": 8.3
    }
  ],
  "meta": {
    "period": "last7days",
    "dataPoints": 7,
    "average": 8.0,
    "min": 7.5,
    "max": 8.5
  }
}
```

***

## Metriken erklärt

### Durchschnittliche Verkaufstage

**Was wird gemessen:** Die durchschnittliche Anzahl der Tage vom Inserat bis zum Verkauf eines Fahrzeugs.

**Formel:** `Gesamttage im Bestand / Anzahl verkaufter Fahrzeuge`

**Guter Trend:** ⬇️ Niedriger ist besser – zeigt schnellere Verkäufe

**Branchen-Benchmark:** 30–45 Tage

***

### Durchschnittlicher Verkaufspreis

**Was wird gemessen:** Der durchschnittliche Verkaufspreis der im Zeitraum verkauften Fahrzeuge.

**Formel:** `Gesamtumsatz / Anzahl verkaufter Fahrzeuge`

**Guter Trend:** ⬆️ Höher deutet auf bessere Preisstrategie oder Premium-Bestand hin

**Use Case:** Effektivität der Preisstrategie verfolgen

***

### Bruttogewinnmarge

**Was wird gemessen:** Prozentsatz des Umsatzes nach Abzug der Warenkosten.

**Formel:** `((Umsatz - COGS) / Umsatz) × 100`

**Guter Trend:** ⬆️ Höhere Margen bedeuten bessere Profitabilität

**Branchen-Benchmark:** 15–20%

***

### Durchschnittliches Bestandsalter

**Was wird gemessen:** Durchschnittliche Anzahl der Tage, die Fahrzeuge im Bestand sind.

**Formel:** `Summe der (Tage seit Aufnahme) / Gesamtzahl der Fahrzeuge im Bestand`

**Guter Trend:** ⬇️ Niedriger bedeutet frischeren Bestand

**Alarmgrenze:** > 60 Tage (alternder Bestand)

***

### Bestandsumschlagsrate

**Was wird gemessen:** Wie oft der Bestand in einem Zeitraum verkauft und ersetzt wird.

**Formel:** `Warenkosten / Durchschnittlicher Bestandswert`

**Guter Trend:** ⬆️ Höherer Umschlag bedeutet effizienteren Betrieb

**Branchen-Benchmark:** 6–12 pro Jahr

***

### Kundenzufriedenheits-Score

**Was wird gemessen:** Durchschnittliche Kundenbewertung aus Feedback und Reviews.

**Skala:** 1–5 Sterne

**Guter Trend:** ⬆️ Höhere Werte bedeuten bessere Kundenerfahrung

**Zielwert:** 4,5+

***

### Kundenbindungsrate

**Was wird gemessen:** Prozentsatz der Kunden, die wiederholt kaufen.

**Formel:** `(Wiederkehrende Kunden / Gesamtkunden) × 100`

**Guter Trend:** ⬆️ Höhere Bindung senkt Akquisekosten

**Branchen-Benchmark:** 60–70%

***

### Gesamtreparaturkosten

**Was wird gemessen:** Gesamtausgaben für Reparaturen und Aufbereitung.

**Guter Trend:** ⬇️ Niedrigere Kosten verbessern Margen (ohne Qualitätsverlust)

**Use Case:** Budgetplanung und Kostenkontrolle

***

## Zeitraumsvergleiche

Die API vergleicht jede Kennzahl automatisch mit dem entsprechenden vorherigen Zeitraum:

| Aktueller Zeitraum | Vergleichszeitraum  |
| ------------------ | ------------------- |
| last7days          | Vorherige 7 Tage    |
| last30days         | Vorherige 30 Tage   |
| last90days         | Vorherige 90 Tage   |
| thisWeek           | Letzte Woche        |
| lastWeek           | Vorletzte Woche     |
| thisMonth          | Letzter Monat       |
| lastMonth          | Vorvorletzter Monat |

## Caching

Dashboard-Statistiken werden **5 Minuten** gecacht, um die Performance zu optimieren. Anfragen innerhalb dieses Zeitfensters liefern zwischengespeicherte Daten.

Um eine Aktualisierung zu erzwingen, warten Sie auf das Ablaufdatum des Caches oder nutzen Sie Cache-Busting-Techniken.

## Anwendungsfälle

### Beispiel 1: Wöchentlicher Performance-Review

```bash theme={null}
# Get this week's stats
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=thisWeek" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Beispiel 2: Monatlicher Business-Review

```bash theme={null}
# Get last month's complete statistics
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=lastMonth" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Beispiel 3: Quartalsanalyse

```bash theme={null}
# Get last 90 days for quarterly review
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=last90days" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Beispiel 4: Bestandstrends visualisieren

```bash theme={null}
# Get inventory turnover chart data
curl -X GET "https://api.steerai.autos/v1/analytics/inventory-turnover?period=last30days" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Integrationsmuster

### Echtzeit-Dashboard

```javascript theme={null}
// Fetch and display dashboard stats
async function updateDashboard() {
  const response = await fetch(
    'https://api.steerai.autos/v1/analytics/dashboard/stats?period=last30days',
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  // Display metrics
  displayMetric('avg-days-to-sell', data.avgDaysToSell);
  displayMetric('profit-margin', data.grossProfitMargin);
  // ... more metrics
}

// Refresh every 5 minutes (respects cache)
setInterval(updateDashboard, 300000);
```

### Trend-Alarme

```javascript theme={null}
// Monitor for significant changes
function checkAlerts(data) {
  const alerts = [];

  // Alert if days to sell increased by more than 20%
  if (data.avgDaysToSell.changePercentage > 20) {
    alerts.push({
      type: 'warning',
      metric: 'Average Days to Sell',
      message: `Sales velocity decreased by ${data.avgDaysToSell.changePercentage}%`
    });
  }

  // Alert if inventory aging
  if (data.avgAgeOfInventory.current > 60) {
    alerts.push({
      type: 'danger',
      metric: 'Inventory Age',
      message: 'Inventory aging beyond 60 days threshold'
    });
  }

  return alerts;
}
```

## Bewährte Praktiken

<AccordionGroup>
  <Accordion title="Geeignete Zeiträume wählen">
    Kurze Zeiträume (7 Tage) für operative Metriken, längere Zeiträume (90 Tage) für strategische Entscheidungen.
  </Accordion>

  <Accordion title="Trends statt nur Werte beobachten">
    Konzentrieren Sie sich auf `trend` und `changePercentage`, um Verbesserungen oder Rückgänge zu erkennen.
  </Accordion>

  <Accordion title="Automatisierte Alarme einrichten">
    Konfigurieren Sie Alarme, wenn Metriken Schwellen überschreiten (z. B. Verkaufstage > 45).
  </Accordion>

  <Accordion title="Cache-Zeit beachten">
    Der 5-Minuten-Cache verbessert die Performance. Fragen Sie nicht häufiger ab als nötig.
  </Accordion>

  <Accordion title="Zeiträume korrekt vergleichen">
    Vergleichen Sie gleichwertige Zeiträume (z. B. gleicher Wochentag, gleicher Monat).
  </Accordion>
</AccordionGroup>

## Fehlercodes

| Code                      | Status | Beschreibung                              |
| ------------------------- | ------ | ----------------------------------------- |
| `INVALID_PERIOD`          | 400    | Ungültiger Zeitraum angegeben             |
| `INSUFFICIENT_DATA`       | 400    | Nicht genügend Daten für den Zeitraum     |
| `ANALYTICS_SERVICE_ERROR` | 500    | Fehler bei der Berechnung der Statistiken |

## Verwandte Ressourcen

<CardGroup cols={2}>
  <Card title="KPI-Dashboard-API" icon="gauge-high" href="/de/api-reference/analytics/kpi-dashboard">
    Einzelne KPI-Konfigurationen verwalten
  </Card>

  <Card title="Dashboard-KPIs Leitfaden" icon="book" href="/de/guides/dashboard-kpis">
    Lernen Sie, Ihr Dashboard zu optimieren
  </Card>

  <Card title="Datenbasierte Entscheidungen" icon="chart-line" href="/de/guides/data-driven-decisions">
    Nutzen Sie Analytik für die Geschäftsstrategie
  </Card>

  <Card title="Fahrzeuge-API" icon="car" href="/de/api-reference/vehicles/overview">
    Quelldaten für Analysen
  </Card>
</CardGroup>