API du tableau de bord KPI - Steer Autos Documentation

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

GET

endpoint

/kpis

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

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

GET

endpoint

/kpis/visible

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

GET

endpoint

/kpis/

Récupère les informations détaillées d’un KPI spécifique. Paramètres de chemin :

string

requis

UUID du KPI

Réponse :

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

POST

endpoint

/kpis

Créez un nouveau KPI personnalisé avec votre propre logique de calcul. Corps de la requête :

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

requis

Clé d’identification unique (minuscules, underscores)

title

string

requis

Titre d’affichage du KPI

description

string

Description détaillée de ce que mesure ce KPI

formula

string

Formule ou logique de calcul

kpiType

enum

requis

Type : BUILTIN, CUSTOM

dataType

enum

requis

Type de données : NUMBER, CURRENCY, PERCENTAGE, DURATION, TEXT

icon

string

Identifiant de l’icône (nom d’icône FontAwesome)

color

string

Code couleur hexadécimal pour la visualisation

displayOrder

number

Ordre d’affichage sur le tableau de bord

isVisible

boolean

Indique si le KPI est visible sur le tableau de bord (par défaut : true)

aggregation

string

Méthode d’agrégation : sum, average, count, min, max

targetModel

string

Modèle de base de données à agréger

targetField

string

Champ à agréger

Réponse :

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

Mettre à jour un KPI

PATCH

endpoint

/kpis/

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 :

string

requis

UUID du KPI

Corps de la requête :

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

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

Supprimer un KPI

DELETE

endpoint

/kpis/

Supprime un KPI personnalisé. Les KPI intégrés ne peuvent pas être supprimés. Paramètres de chemin :

string

requis

UUID du KPI

Réponse :

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

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

Réordonner les KPI

PUT

endpoint

/kpis/reorder

Met à jour l’ordre d’affichage de plusieurs KPI en une seule fois. Corps de la requête :

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

Réponse :

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

Basculer la visibilité d’un KPI

PATCH

endpoint

/kpis//toggle

Bascule la visibilité d’un KPI sur le tableau de bord. Paramètres de chemin :

string

requis

UUID du KPI

Réponse :

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

Réinitialiser aux KPI par défaut

POST

endpoint

/kpis/reset

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 :

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

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

Mettre à jour la configuration des graphiques KPI

PATCH

endpoint

/kpis//chart

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

string

requis

UUID du KPI

Corps de la requête :

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

chartType

enum

Type de graphique : NONE, DONUT, BAR, LINE, AREA, RADIAL

chartEnabled

boolean

Activer/désactiver l’affichage du graphique

chartConfig

object

Options de configuration spécifiques au graphique

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

GET

endpoint

/kpis//chart-data

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

string

requis

UUID du KPI

Paramètres de requête :

timeRange

enum

Plage temporelle : 7d, 30d, 90d (par défaut : 30d)

Réponse :

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

# 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

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

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

Bonnes pratiques

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.

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.

Utiliser des périodes cohérentes

Comparez les KPI en utilisant les mêmes périodes pour des insights pertinents.

Documenter les formules de KPI personnalisés

Documentez clairement le calcul des KPI personnalisés pour une compréhension d’équipe.

Revoir et ajuster régulièrement

Les KPI doivent évoluer avec votre activité. Passez en revue trimestriellement et ajustez si besoin.

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

Guide des KPI du tableau de bord

En savoir plus sur l’optimisation de votre tableau de bord KPI

Documentation API

​Aperçu

​Endpoints

​Récupérer tous les KPI

​Récupérer uniquement les KPI visibles

​Récupérer un KPI par ID

​Créer un KPI personnalisé

​Mettre à jour un KPI

​Supprimer un KPI

​Réordonner les KPI

​Basculer la visibilité d’un KPI

​Réinitialiser aux KPI par défaut

​Mettre à jour la configuration des graphiques KPI

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

​KPI intégrés

​Types de données

​NUMBER

​CURRENCY

​PERCENTAGE

​DURATION

​TEXT

​Types de graphiques

​DONUT

​BAR

​LINE

​AREA

​RADIAL

​NONE

​Cas d’usage

​Exemple 1 : Suivre la performance des ventes

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

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

​Bonnes pratiques

​Codes d’erreur

Guide des KPI du tableau de bord

Aperçu

Endpoints

Récupérer tous les KPI

Récupérer uniquement les KPI visibles

Récupérer un KPI par ID

Créer un KPI personnalisé

Mettre à jour un KPI

Supprimer un KPI

Réordonner les KPI

Basculer la visibilité d’un KPI

Réinitialiser aux KPI par défaut

Mettre à jour la configuration des graphiques KPI

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

KPI intégrés

Types de données

NUMBER

CURRENCY

PERCENTAGE

DURATION

TEXT

Types de graphiques

DONUT

BAR

LINE

AREA

RADIAL

NONE

Cas d’usage

Exemple 1 : Suivre la performance des ventes

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

Exemple 3 : Obtenir les données historiques du graphique

Bonnes pratiques

Codes d’erreur