API de KPI Dashboard - Steer Autos Documentation

Resumen

La API de KPI Dashboard ofrece metricas y visualizaciones para operaciones automotrices. Monitorea ventas, inventario, satisfaccion del cliente y crea KPIs personalizados para tu negocio.

Endpoints

Obtener todos los KPIs

GET

endpoint

/kpis

Obtiene todos los KPIs configurados para el usuario autenticado, incluyendo KPIs integrados y personalizados. Response:

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

Obtener solo KPIs visibles

GET

endpoint

/kpis/visible

Obtiene solo los KPIs marcados como visibles para el dashboard. Response: Arreglo de KPIs con isVisible: true.

Obtener KPI por ID

GET

endpoint

/kpis/

Obtiene informacion detallada de un KPI especifico. Path Parameters:

string

requerido

KPI UUID

Response:

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

Crear KPI personalizado

POST

endpoint

/kpis

Crea un KPI personalizado con tu propia logica de calculo. Request 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

requerido

Identificador unico (minusculas, underscores)

title

string

requerido

Titulo visible del KPI

description

string

Descripcion de lo que mide el KPI

formula

string

Formula o logica de calculo

kpiType

enum

requerido

Tipo: BUILTIN, CUSTOM

dataType

enum

requerido

Tipo de dato: NUMBER, CURRENCY, PERCENTAGE, DURATION, TEXT

icon

string

Identificador de icono (FontAwesome)

color

string

Color hex para visualizacion

displayOrder

number

Orden en el dashboard

isVisible

boolean

KPI visible en dashboard (default: true)

aggregation

string

Metodo de agregacion: sum, average, count, min, max

targetModel

string

Modelo de base de datos a agregar

targetField

string

Campo a agregar

Response:

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

Actualizar KPI

PATCH

endpoint

/kpis/

Actualiza la configuracion de un KPI existente. Los KPIs integrados solo pueden cambiar ajustes de visualizacion, no la logica. Path Parameters:

string

requerido

KPI UUID

Request Body:

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

Todos los campos son opcionales. Solo se actualizan los proporcionados.

Eliminar KPI

DELETE

endpoint

/kpis/

Elimina un KPI personalizado. Los KPIs integrados no se pueden eliminar. Path Parameters:

string

requerido

KPI UUID

Response:

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

Solo los KPIs personalizados pueden eliminarse. Intentar eliminar un KPI integrado devuelve 400.

Reordenar KPIs

PUT

endpoint

/kpis/reorder

Actualiza el orden de visualizacion de multiples KPIs a la vez. Request Body:

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

Response:

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

Alternar visibilidad de KPI

PATCH

endpoint

/kpis//toggle

Activa/desactiva la visibilidad del KPI en el dashboard. Path Parameters:

string

requerido

KPI UUID

Response:

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

Restablecer KPIs por defecto

POST

endpoint

/kpis/reset

Restablece todos los KPIs a la configuracion por defecto. Esto:

Restaura KPIs integrados a defaults
Elimina KPIs personalizados
Restablece orden y visibilidad

Response:

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

Esta accion no se puede deshacer. Todos los KPIs personalizados se perderan.

Actualizar configuracion de grafico KPI

PATCH

endpoint

/kpis//chart

Configura la visualizacion de grafico para un KPI. Path Parameters:

string

requerido

KPI UUID

Request Body:

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

chartType

enum

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

chartEnabled

boolean

Activar/desactivar grafico

chartConfig

object

Opciones de configuracion del grafico

Obtener datos de grafico KPI

GET

endpoint

/kpis//chart-data

Obtiene datos historicos para visualizar el grafico del KPI. Path Parameters:

string

requerido

KPI UUID

Query Parameters:

timeRange

enum

Rango: 7d, 30d, 90d (default: 30d)

Response:

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

KPIs integrados

Steer AI incluye los siguientes KPIs por defecto:

Key	Title	Data Type	Description
`avg_days_to_sell`	Average Days to Sell	DURATION	Tiempo de listado a venta
`avg_selling_price`	Average Selling Price	CURRENCY	Precio promedio de venta
`gross_profit_margin`	Gross Profit Margin	PERCENTAGE	Porcentaje de ingresos menos COGS
`avg_age_of_inventory`	Average Age of Inventory	DURATION	Dias en inventario
`inventory_turnover_ratio`	Inventory Turnover Ratio	NUMBER	Velocidad de rotacion
`customer_satisfaction_score`	Customer Satisfaction	PERCENTAGE	Satisfaccion del cliente
`customer_retention_rate`	Customer Retention Rate	PERCENTAGE	Porcentaje de clientes recurrentes
`total_repair_cost`	Total Repair Cost	CURRENCY	Suma de costos de reparacion

Tipos de datos

NUMBER

Valores numericos (ej., 1234, 567.89)

CURRENCY

Valores monetarios con simbolos (ej., $1,234.56, MAD 5,000.00)

PERCENTAGE

Valores en porcentaje (ej., 18.5%, 92.3%)

DURATION

Periodos de tiempo en dias u horas (ej., 28 dias, 3.5 horas)

TEXT

Valores de texto para KPIs no numericos

Tipos de graficos

DONUT

Grafico circular con distribucion proporcional

BAR

Barras verticales u horizontales para comparaciones

LINE

Grafico de lineas para tendencias en el tiempo

AREA

Grafico de area para tendencias acumuladas

RADIAL

Grafico radial para metricas de un solo valor

NONE

Sin visualizacion de grafico

Casos de uso

Ejemplo 1: Seguimiento de ventas

# Get visible KPIs for dashboard
curl -X GET "https://api.steerai.autos/v1/kpis/visible" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo 2: Crear KPI 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"
  }'

Ejemplo 3: Obtener datos historicos

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

Mejores practicas

Empieza con KPIs integrados

Usa los KPIs integrados antes de crear personalizados. Estan optimizados.

Limita KPIs del dashboard a 6-8

Demasiados KPIs generan ruido. Enfocate en metricas criticas.

Usa rangos de tiempo consistentes

Compara KPIs con los mismos periodos para insights validos.

Documenta formulas de KPIs personalizados

Documenta como se calculan para que el equipo lo entienda.

Revisa y ajusta regularmente

Los KPIs deben evolucionar con el negocio. Revisa trimestralmente.

Codigos de error

Code	Status	Description
`KPI_NOT_FOUND`	404	El ID del KPI no existe
`CANNOT_DELETE_BUILTIN`	400	No se puede eliminar KPI integrado
`CANNOT_MODIFY_BUILTIN_LOGIC`	400	No se puede cambiar la logica
`DUPLICATE_KPI_KEY`	400	La key de KPI ya existe
`INVALID_CHART_TYPE`	400	Tipo de grafico no soportado

Guia de KPIs

Aprende mas sobre optimizacion del KPI dashboard

Documentacion de la API

​Resumen

​Endpoints

​Obtener todos los KPIs

​Obtener solo KPIs visibles

​Obtener KPI por ID

​Crear KPI personalizado

​Actualizar KPI

​Eliminar KPI

​Reordenar KPIs

​Alternar visibilidad de KPI

​Restablecer KPIs por defecto

​Actualizar configuracion de grafico KPI

​Obtener datos de grafico KPI

​KPIs integrados

​Tipos de datos

​NUMBER

​CURRENCY

​PERCENTAGE

​DURATION

​TEXT

​Tipos de graficos

​DONUT

​BAR

​LINE

​AREA

​RADIAL

​NONE

​Casos de uso

​Ejemplo 1: Seguimiento de ventas

​Ejemplo 2: Crear KPI de conversion

​Ejemplo 3: Obtener datos historicos

​Mejores practicas

​Codigos de error

Guia de KPIs

Resumen

Endpoints

Obtener todos los KPIs

Obtener solo KPIs visibles

Obtener KPI por ID

Crear KPI personalizado

Actualizar KPI

Eliminar KPI

Reordenar KPIs

Alternar visibilidad de KPI

Restablecer KPIs por defecto

Actualizar configuracion de grafico KPI

Obtener datos de grafico KPI

KPIs integrados

Tipos de datos

NUMBER

CURRENCY

PERCENTAGE

DURATION

TEXT

Tipos de graficos

DONUT

BAR

LINE

AREA

RADIAL

NONE

Casos de uso

Ejemplo 1: Seguimiento de ventas

Ejemplo 2: Crear KPI de conversion

Ejemplo 3: Obtener datos historicos

Mejores practicas

Codigos de error