> ## 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 du tableau de bord KPI

> Gérer et récupérer les indicateurs de performance clés pour les opérations de concession

## Aperçu

L'API du tableau de bord KPI fournit un suivi et une visualisation complets des métriques pour les opérations de votre concession automobile. Suivez la performance des ventes, les métriques d'inventaire, la satisfaction client et créez des KPI personnalisés adaptés à vos besoins.

## Endpoints

### Récupérer tous les KPI

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

Récupère tous les KPI configurés pour l'utilisateur authentifié, y compris les KPI intégrés et personnalisés.

**Réponse :**

```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"
  }
]
```

***

### Récupérer uniquement les KPI visibles

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

Récupère uniquement les KPI marqués comme visibles pour l'affichage du tableau de bord.

**Réponse :**

Tableau d'objets KPI avec `isVisible: true`.

***

### Récupérer un KPI par ID

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

Récupère les informations détaillées d'un KPI spécifique.

**Paramètres de chemin :**

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

**Réponse :**

```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
  }
}
```

***

### Créer un KPI personnalisé

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

Créez un nouveau KPI personnalisé avec votre propre logique de calcul.

**Corps de la requête :**

```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>
  Clé d'identification unique (minuscules, underscores)
</ParamField>

<ParamField body="title" type="string" required>
  Titre d'affichage du KPI
</ParamField>

<ParamField body="description" type="string">
  Description détaillée de ce que mesure ce KPI
</ParamField>

<ParamField body="formula" type="string">
  Formule ou logique de calcul
</ParamField>

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

<ParamField body="dataType" type="enum" required>
  Type de données : `NUMBER`, `CURRENCY`, `PERCENTAGE`, `DURATION`, `TEXT`
</ParamField>

<ParamField body="icon" type="string">
  Identifiant de l'icône (nom d'icône FontAwesome)
</ParamField>

<ParamField body="color" type="string">
  Code couleur hexadécimal pour la visualisation
</ParamField>

<ParamField body="displayOrder" type="number">
  Ordre d'affichage sur le tableau de bord
</ParamField>

<ParamField body="isVisible" type="boolean">
  Indique si le KPI est visible sur le tableau de bord (par défaut : true)
</ParamField>

<ParamField body="aggregation" type="string">
  Méthode d'agrégation : `sum`, `average`, `count`, `min`, `max`
</ParamField>

<ParamField body="targetModel" type="string">
  Modèle de base de données à agréger
</ParamField>

<ParamField body="targetField" type="string">
  Champ à agréger
</ParamField>

**Réponse :**

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

***

### Mettre à jour un KPI

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

Met à jour la configuration d'un KPI existant. Les KPI intégrés ne peuvent modifier que les paramètres d'affichage, pas la logique de calcul.

**Paramètres de chemin :**

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

**Corps de la requête :**

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

Tous les champs sont facultatifs. Seuls les champs fournis seront mis à jour.

***

### Supprimer un KPI

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

Supprime un KPI personnalisé. Les KPI intégrés ne peuvent pas être supprimés.

**Paramètres de chemin :**

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

**Réponse :**

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

<Warning>
  Seuls les KPI personnalisés peuvent être supprimés. Tenter de supprimer un KPI intégré renverra une erreur 400.
</Warning>

***

### Réordonner les KPI

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

Met à jour l'ordre d'affichage de plusieurs KPI en une seule fois.

**Corps de la requête :**

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

**Réponse :**

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

***

### Basculer la visibilité d'un KPI

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

Bascule la visibilité d'un KPI sur le tableau de bord.

**Paramètres de chemin :**

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

**Réponse :**

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

***

### Réinitialiser aux KPI par défaut

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

Réinitialise tous les KPI à la configuration intégrée par défaut. Cela va :

* Restaurer tous les KPI intégrés aux paramètres par défaut
* Supprimer tous les KPI personnalisés
* Réinitialiser l'ordre d'affichage et la visibilité

**Réponse :**

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

<Warning>
  Cette action est irréversible. Tous les KPI personnalisés et les changements de configuration seront définitivement perdus.
</Warning>

***

### Mettre à jour la configuration des graphiques KPI

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

Configure les paramètres de visualisation du graphique pour un KPI.

**Paramètres de chemin :**

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

**Corps de la requête :**

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

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

<ParamField body="chartEnabled" type="boolean">
  Activer/désactiver l'affichage du graphique
</ParamField>

<ParamField body="chartConfig" type="object">
  Options de configuration spécifiques au graphique
</ParamField>

***

### Récupérer les données du graphique KPI

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

Récupère des données historiques de série temporelle pour la visualisation des graphiques KPI.

**Paramètres de chemin :**

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

**Paramètres de requête :**

<ParamField query="timeRange" type="enum">
  Plage temporelle : `7d`, `30d`, `90d` (par défaut : 30d)
</ParamField>

**Réponse :**

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

***

## KPI intégrés

Steer AI fournit les KPI intégrés suivants prêts à l'emploi :

| Key                           | Title                    | Data Type  | Description                     |
| ----------------------------- | ------------------------ | ---------- | ------------------------------- |
| `avg_days_to_sell`            | Average Days to Sell     | DURATION   | Time from listing to sale       |
| `avg_selling_price`           | Average Selling Price    | CURRENCY   | Mean vehicle sale price         |
| `gross_profit_margin`         | Gross Profit Margin      | PERCENTAGE | Revenue minus COGS percentage   |
| `avg_age_of_inventory`        | Average Age of Inventory | DURATION   | Days vehicles stay in inventory |
| `inventory_turnover_ratio`    | Inventory Turnover Ratio | NUMBER     | How quickly inventory sells     |
| `customer_satisfaction_score` | Customer Satisfaction    | PERCENTAGE | Customer satisfaction rating    |
| `customer_retention_rate`     | Customer Retention Rate  | PERCENTAGE | Repeat customer percentage      |
| `total_repair_cost`           | Total Repair Cost        | CURRENCY   | Sum of all repair expenses      |

## Types de données

### NUMBER

Valeurs numériques brutes (ex. 1234, 567.89)

### CURRENCY

Valeurs monétaires formatées avec des symboles de devise (ex. \$1,234.56, MAD 5,000.00)

### PERCENTAGE

Valeurs affichées en pourcentage (ex. 18,5 %, 92,3 %)

### DURATION

Durées en jours ou heures (ex. 28 jours, 3,5 heures)

### TEXT

Valeurs texte pour les KPI non numériques

## Types de graphiques

### DONUT

Graphique circulaire montrant la distribution proportionnelle

### BAR

Graphique en barres verticales ou horizontales pour les comparaisons

### LINE

Graphique en lignes montrant les tendances dans le temps

### AREA

Graphique en aire montrant les tendances cumulées

### RADIAL

Graphique radial/jauge pour les métriques à valeur unique

### NONE

Aucune visualisation graphique

## Cas d'usage

### Exemple 1 : Suivre la performance des ventes

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

### Exemple 2 : Créer un KPI personnalisé de taux de conversion

```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"
  }'
```

### Exemple 3 : Obtenir les données historiques du graphique

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

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Commencer par les KPI intégrés">
    Utilisez les KPI intégrés avant de créer des KPI personnalisés. Ils sont optimisés et éprouvés.
  </Accordion>

  <Accordion title="Limiter les KPI du tableau de bord à 6-8">
    Trop de KPI créent du bruit. Concentrez-vous sur vos métriques les plus critiques.
  </Accordion>

  <Accordion title="Utiliser des périodes cohérentes">
    Comparez les KPI en utilisant les mêmes périodes pour des insights pertinents.
  </Accordion>

  <Accordion title="Documenter les formules de KPI personnalisés">
    Documentez clairement le calcul des KPI personnalisés pour une compréhension d'équipe.
  </Accordion>

  <Accordion title="Revoir et ajuster régulièrement">
    Les KPI doivent évoluer avec votre activité. Passez en revue trimestriellement et ajustez si besoin.
  </Accordion>
</AccordionGroup>

## Codes d'erreur

| Code                          | Status | Description                                |
| ----------------------------- | ------ | ------------------------------------------ |
| `KPI_NOT_FOUND`               | 404    | KPI ID does not exist                      |
| `CANNOT_DELETE_BUILTIN`       | 400    | Cannot delete built-in KPIs                |
| `CANNOT_MODIFY_BUILTIN_LOGIC` | 400    | Cannot change calculation of built-in KPIs |
| `DUPLICATE_KPI_KEY`           | 400    | KPI key already exists                     |
| `INVALID_CHART_TYPE`          | 400    | Chart type not supported                   |

<Card title="Guide des KPI du tableau de bord" icon="gauge-high" href="/fr/guides/dashboard-kpis">
  En savoir plus sur l'optimisation de votre tableau de bord KPI
</Card>