KPI-Dashboard-API - Steer Autos Documentation

Ü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

GET

endpoint

/kpis

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

[
  {
    "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

GET

endpoint

/kpis/visible

Ruft nur KPIs ab, die für die Dashboard-Anzeige sichtbar sind. Antwort: Array von KPI-Objekten mit isVisible: true.

KPI nach ID abrufen

GET

endpoint

/kpis/

Ruft detaillierte Informationen zu einem bestimmten KPI ab. Path-Parameter:

string

erforderlich

KPI-UUID

Antwort:

{
  "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

POST

endpoint

/kpis

Erstellt einen neuen benutzerdefinierten KPI mit eigener Berechnungslogik. Anfrage-Body:

{
  "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"
}

key

string

erforderlich

Eindeutiger Schlüssel (kleinbuchstaben, underscores)

title

string

erforderlich

Anzeige-Titel des KPI

description

string

Detaillierte Beschreibung der Kennzahl

formula

string

Formel oder Berechnungslogik

kpiType

enum

erforderlich

Typ: BUILTIN, CUSTOM

dataType

enum

erforderlich

Datentyp: NUMBER, CURRENCY, PERCENTAGE, DURATION, TEXT

icon

string

Icon-Kennung (FontAwesome-Name)

color

string

Hex-Farbcode für die Visualisierung

displayOrder

number

Reihenfolge für die Dashboard-Anzeige

isVisible

boolean

Ob der KPI im Dashboard sichtbar ist (Standard: true)

aggregation

string

Aggregationsmethode: sum, average, count, min, max

targetModel

string

Datenbankmodell für die Aggregation

targetField

string

Feld zur Aggregation

Antwort:

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

KPI aktualisieren

PATCH

endpoint

/kpis/

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

string

erforderlich

KPI-UUID

Anfrage-Body:

{
  "title": "Updated Title",
  "isVisible": false,
  "displayOrder": 5,
  "color": "#ff6b6b"
}

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

KPI löschen

DELETE

endpoint

/kpis/

Löscht einen benutzerdefinierten KPI. Integrierte KPIs können nicht gelöscht werden. Path-Parameter:

string

erforderlich

KPI-UUID

Antwort:

{
  "success": true,
    "message": "Custom KPI deleted successfully"
}

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

KPIs neu sortieren

PUT

endpoint

/kpis/reorder

Aktualisiert die Anzeigereihenfolge für mehrere KPIs gleichzeitig. Anfrage-Body:

{
  "orders": [
    { "id": "kpi_uuid_1", "displayOrder": 1 },
    { "id": "kpi_uuid_2", "displayOrder": 2 },
    { "id": "kpi_uuid_3", "displayOrder": 3 }
  ]
}

Antwort:

{
  "success": true,
  "message": "KPIs reordered successfully"
}

KPI-Sichtbarkeit umschalten

PATCH

endpoint

/kpis//toggle

Schaltet die Sichtbarkeit eines KPIs im Dashboard um. Path-Parameter:

string

erforderlich

KPI-UUID

Antwort:

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

Auf Standard-KPIs zurücksetzen

POST

endpoint

/kpis/reset

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:

{
  "success": true,
  "message": "KPIs reset to defaults successfully",
  "kpisCount": 8
}

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

KPI-Chart-Konfiguration aktualisieren

PATCH

endpoint

/kpis//chart

Konfiguriert die Diagramm-Darstellung für einen KPI. Path-Parameter:

string

erforderlich

KPI-UUID

Anfrage-Body:

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

chartType

enum

Diagrammtyp: NONE, DONUT, BAR, LINE, AREA, RADIAL

chartEnabled

boolean

Diagramm anzeigen oder ausblenden

chartConfig

object

Diagramm-spezifische Konfiguration

KPI-Chartdaten abrufen

GET

endpoint

/kpis//chart-data

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

string

erforderlich

KPI-UUID

Query-Parameter:

timeRange

enum

Zeitraum: 7d, 30d, 90d (Standard: 30d)

Antwort:

{
  "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

# 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

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

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

Bewährte Praktiken

Mit integrierten KPIs starten

Nutzen Sie die integrierten KPIs, bevor Sie eigene erstellen. Sie sind optimiert und praxiserprobt.

Dashboard auf 6-8 KPIs begrenzen

Zu viele KPIs sorgen für Unübersichtlichkeit. Fokussieren Sie sich auf die wichtigsten Metriken.

Konsistente Zeiträume nutzen

Vergleichen Sie KPIs mit identischen Zeiträumen für aussagekräftige Einblicke.

Formeln für benutzerdefinierte KPIs dokumentieren

Dokumentieren Sie klar, wie eigene KPIs berechnet werden, damit das Team sie versteht.

Regelmäßig prüfen und anpassen

KPIs sollten sich mit Ihrem Geschäft weiterentwickeln. Quartalsweise prüfen und anpassen.

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

Dashboard-KPIs Leitfaden

Mehr zur Optimierung Ihres KPI-Dashboards

API-Dokumentation

​Überblick

​Endpunkte

​Alle KPIs abrufen

​Nur sichtbare KPIs abrufen

​KPI nach ID abrufen

​Benutzerdefinierten KPI erstellen

​KPI aktualisieren

​KPI löschen

​KPIs neu sortieren

​KPI-Sichtbarkeit umschalten

​Auf Standard-KPIs zurücksetzen

​KPI-Chart-Konfiguration aktualisieren

​KPI-Chartdaten abrufen

​Integrierte KPIs

​Datentypen

​NUMBER

​CURRENCY

​PERCENTAGE

​DURATION

​TEXT

​Diagrammtypen

​DONUT

​BAR

​LINE

​AREA

​RADIAL

​NONE

​Anwendungsfälle

​Beispiel 1: Vertriebsleistung verfolgen

​Beispiel 2: Benutzerdefinierten Lead-Conversion-KPI erstellen

​Beispiel 3: Historische Chart-Daten abrufen

​Bewährte Praktiken

​Fehlercodes

Dashboard-KPIs Leitfaden

Überblick

Endpunkte

Alle KPIs abrufen

Nur sichtbare KPIs abrufen

KPI nach ID abrufen

Benutzerdefinierten KPI erstellen

KPI aktualisieren

KPI löschen

KPIs neu sortieren

KPI-Sichtbarkeit umschalten

Auf Standard-KPIs zurücksetzen

KPI-Chart-Konfiguration aktualisieren

KPI-Chartdaten abrufen

Integrierte KPIs

Datentypen

NUMBER

CURRENCY

PERCENTAGE

DURATION

TEXT

Diagrammtypen

DONUT

BAR

LINE

AREA

RADIAL

NONE

Anwendungsfälle

Beispiel 1: Vertriebsleistung verfolgen

Beispiel 2: Benutzerdefinierten Lead-Conversion-KPI erstellen

Beispiel 3: Historische Chart-Daten abrufen

Bewährte Praktiken

Fehlercodes