> ## 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 d'analytique du tableau de bord

> Récupérer des statistiques complètes du tableau de bord et des métriques de performance

## Aperçu

L'API d'analytique du tableau de bord fournit des statistiques agrégées et des métriques de performance pour les opérations de votre concession. Obtenez des insights en temps réel sur les ventes, l'inventaire et les métriques client grâce à un filtrage flexible par période.

## Endpoints

### Récupérer les statistiques du tableau de bord

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

Récupère des statistiques complètes du tableau de bord, y compris les valeurs de KPI et les tendances.

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

<ParamField query="period" type="enum">
  Période de calcul des statistiques. Options :

  * `last7days` - 7 derniers jours
  * `last30days` - 30 derniers jours (par défaut)
  * `last90days` - 90 derniers jours
  * `thisWeek` - Semaine en cours (lundi-dimanche)
  * `lastWeek` - Semaine précédente
  * `thisMonth` - Mois civil en cours
  * `lastMonth` - Mois précédent
</ParamField>

**Réponse :**

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

**Structure de l'objet Stat :**

Chaque statistique inclut :

<ResponseField name="current" type="number">
  Valeur de la période en cours
</ResponseField>

<ResponseField name="previous" type="number">
  Valeur de la période précédente pour comparaison
</ResponseField>

<ResponseField name="change" type="number">
  Variation absolue entre les périodes
</ResponseField>

<ResponseField name="changePercentage" type="number">
  Pourcentage d'évolution entre les périodes
</ResponseField>

<ResponseField name="trend" type="enum">
  Direction de la tendance : `up`, `down`, `stable`
</ResponseField>

<ResponseField name="unit" type="string">
  Unité de mesure (days, MAD, %, etc.)
</ResponseField>

***

### Récupérer les données du graphique de rotation des stocks

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

Récupère les données de série temporelle pour la visualisation du turnover d'inventaire.

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

<ParamField query="period" type="enum">
  Période pour les données du graphique (mêmes options que les stats du tableau de bord)
</ParamField>

**Réponse :**

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

***

## Explication des métriques

### Nombre moyen de jours avant vente

**Ce que cela mesure :** Le nombre moyen de jours entre la mise en vente d'un véhicule et sa vente.

**Formule :** `Total Days in Inventory / Number of Vehicles Sold`

### Prix de vente moyen

**Ce que cela mesure :** Le prix moyen auquel les véhicules sont vendus.

**Formule :** `Total Sales Revenue / Number of Vehicles Sold`

### Marge brute moyenne

**Ce que cela mesure :** La marge moyenne après coûts de réparation et d'acquisition.

**Formule :** `(Total Revenue - Total Costs) / Total Revenue * 100`

### Âge moyen de l'inventaire

**Ce que cela mesure :** Durée moyenne pendant laquelle les véhicules restent en stock.

**Formule :** `Sum of Days in Inventory / Number of Vehicles`

### Taux de rotation des stocks

**Ce que cela mesure :** Nombre de fois que l'inventaire est renouvelé sur une période donnée.

**Formule :** `Number of Vehicles Sold / Average Inventory`

### Score de satisfaction client

**Ce que cela mesure :** Note moyenne de satisfaction des clients après achat.

**Formule :** `Sum of Ratings / Number of Ratings`

### Taux de rétention client

**Ce que cela mesure :** Pourcentage de clients qui reviennent pour un nouvel achat.

**Formule :** `Returning Customers / Total Customers * 100`

### Coût total de réparation

**Ce que cela mesure :** Coût total des réparations et reconditionnements sur la période.

**Formule :** `Sum of Repair Costs`