API de analitica del dashboard - Steer Autos Documentation

Resumen

La API de analitica del dashboard ofrece estadisticas agregadas y metricas de rendimiento para operaciones del concesionario. Obtén insights en tiempo real de ventas, inventario y clientes con filtros por periodo.

Endpoints

Obtener estadisticas del dashboard

GET

endpoint

/analytics/dashboard/stats

Obtiene estadisticas completas del dashboard incluyendo valores y tendencias de KPIs. Query Parameters:

period

enum

Periodo para el calculo. Opciones:

last7days - Ultimos 7 dias
last30days - Ultimos 30 dias (default)
last90days - Ultimos 90 dias
thisWeek - Semana actual (lunes-domingo)
lastWeek - Semana previa
thisMonth - Mes calendario actual
lastMonth - Mes calendario previo

Response:

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

Estructura del objeto estadistica: Cada estadistica incluye:

current

number

Valor del periodo actual

number

Valor del periodo anterior

change

number

Cambio absoluto entre periodos

changePercentage

number

Cambio porcentual entre periodos

trend

enum

Direccion de tendencia: up, down, stable

unit

string

Unidad de medida (days, MAD, %, etc.)

Obtener datos del grafico de rotacion de inventario

GET

endpoint

/analytics/inventory-turnover

Obtiene serie temporal para visualizacion de rotacion de inventario. Query Parameters:

period

enum

Periodo para el grafico (mismas opciones que dashboard stats)

Response:

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

Metricas explicadas

Promedio de dias para venta

Que mide: Promedio de dias desde que un vehiculo se lista hasta que se vende. Formula: Total Days in Inventory / Number of Vehicles Sold Tendencia buena: ⬇️ Menor es mejor - indica ventas mas rapidas Benchmark del sector: 30-45 dias

Precio promedio de venta

Que mide: Promedio del precio de venta en el periodo. Formula: Total Revenue / Number of Vehicles Sold Tendencia buena: ⬆️ Mayor indica mejor pricing o inventario premium Caso de uso: Medir efectividad de estrategia de precios

Margen bruto de ganancia

Que mide: Porcentaje de ingresos despues de costos de bienes vendidos. Formula: ((Revenue - COGS) / Revenue) × 100 Tendencia buena: ⬆️ Margenes mas altos indican mayor rentabilidad Benchmark del sector: 15-20%

Antiguedad promedio de inventario

Que mide: Promedio de dias de permanencia en inventario. Formula: Sum of (Days Since Added) / Total Vehicles in Inventory Tendencia buena: ⬇️ Menor indica inventario mas fresco Umbral de alerta: > 60 dias (inventario envejecido)

Ratio de rotacion de inventario

Que mide: Cuantas veces se vende y repone inventario en un periodo. Formula: Cost of Goods Sold / Average Inventory Value Tendencia buena: ⬆️ Mayor rotacion indica operaciones mas eficientes Benchmark del sector: 6-12 veces por ano

Puntaje de satisfaccion del cliente

Que mide: Promedio de calificaciones de clientes. Escala: 1-5 estrellas Tendencia buena: ⬆️ Puntuaciones altas indican mejor experiencia Objetivo: 4.5+

Tasa de retencion de clientes

Que mide: Porcentaje de clientes que regresan. Formula: (Repeat Customers / Total Customers) × 100 Tendencia buena: ⬆️ Mayor retencion reduce costos de adquisicion Benchmark del sector: 60-70%

Costo total de reparacion

Que mide: Monto total gastado en reparaciones y reacondicionamiento. Tendencia buena: ⬇️ Costos menores mejoran margenes (sin afectar calidad) Caso de uso: Planeacion de presupuesto y control de costos

Comparaciones por periodo

La API compara automaticamente cada metrica contra el periodo anterior equivalente:

Periodo actual	Periodo de comparacion
last7days	7 dias previos
last30days	30 dias previos
last90days	90 dias previos
thisWeek	Semana pasada
lastWeek	Semana antepasada
thisMonth	Mes pasado
lastMonth	Mes anterior

Cache

Las estadisticas del dashboard se cachean por 5 minutos para optimizar rendimiento. Solicitudes dentro de esa ventana devuelven datos cacheados. Para forzar refresh, espera a que expire el cache o usa tecnicas de cache-busting.

Casos de uso

Ejemplo 1: Revision semanal de rendimiento

# Get this week's stats
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=thisWeek" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo 2: Revision mensual del negocio

# Get last month's complete statistics
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=lastMonth" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo 3: Analisis trimestral

# Get last 90 days for quarterly review
curl -X GET "https://api.steerai.autos/v1/analytics/dashboard/stats?period=last90days" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo 4: Visualizar tendencias de inventario

# Get inventory turnover chart data
curl -X GET "https://api.steerai.autos/v1/analytics/inventory-turnover?period=last30days" \
  -H "Authorization: Bearer YOUR_API_KEY"

Patrones de integracion

Dashboard en tiempo real

// Fetch and display dashboard stats
async function updateDashboard() {
  const response = await fetch(
    'https://api.steerai.autos/v1/analytics/dashboard/stats?period=last30days',
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  // Display metrics
  displayMetric('avg-days-to-sell', data.avgDaysToSell);
  displayMetric('profit-margin', data.grossProfitMargin);
  // ... more metrics
}

// Refresh every 5 minutes (respects cache)
setInterval(updateDashboard, 300000);

Alertas de tendencia

// Monitor for significant changes
function checkAlerts(data) {
  const alerts = [];

  // Alert if days to sell increased by more than 20%
  if (data.avgDaysToSell.changePercentage > 20) {
    alerts.push({
      type: 'warning',
      metric: 'Average Days to Sell',
      message: `Sales velocity decreased by ${data.avgDaysToSell.changePercentage}%`
    });
  }

  // Alert if inventory aging
  if (data.avgAgeOfInventory.current > 60) {
    alerts.push({
      type: 'danger',
      metric: 'Inventory Age',
      message: 'Inventory aging beyond 60 days threshold'
    });
  }

  return alerts;
}

Mejores practicas

Elige periodos adecuados

Usa periodos cortos (7 dias) para metricas operativas, periodos largos (90 dias) para decisiones estrategicas.

Monitorea tendencias, no solo valores

Enfocate en trend y changePercentage para identificar mejoras o caidas.

Configura alertas automaticas

Configura alertas cuando una metrica supere umbrales (ej., dias para vender > 45).

Respeta el cache

El cache de 5 minutos mejora rendimiento. No consultes mas seguido de lo necesario.

Compara periodos equivalentes

Asegura comparaciones equivalentes (mismo dia de la semana, mismo mes).

Codigos de error

Code	Status	Description
`INVALID_PERIOD`	400	Periodo de tiempo invalido
`INSUFFICIENT_DATA`	400	No hay datos suficientes
`ANALYTICS_SERVICE_ERROR`	500	Error al calcular estadisticas

Recursos relacionados

API de KPI Dashboard

Gestiona configuraciones de KPIs

Guia de KPIs

Aprende a optimizar tu dashboard

Decisiones basadas en datos

Usa analitica para estrategia

API de vehiculos

Fuente de datos para analitica

Documentacion de la API

​Resumen

​Endpoints

​Obtener estadisticas del dashboard

​Obtener datos del grafico de rotacion de inventario

​Metricas explicadas

​Promedio de dias para venta

​Precio promedio de venta

​Margen bruto de ganancia

​Antiguedad promedio de inventario

​Ratio de rotacion de inventario

​Puntaje de satisfaccion del cliente

​Tasa de retencion de clientes

​Costo total de reparacion

​Comparaciones por periodo

​Cache

​Casos de uso

​Ejemplo 1: Revision semanal de rendimiento

​Ejemplo 2: Revision mensual del negocio

​Ejemplo 3: Analisis trimestral

​Ejemplo 4: Visualizar tendencias de inventario

​Patrones de integracion

​Dashboard en tiempo real

​Alertas de tendencia

​Mejores practicas

​Codigos de error

​Recursos relacionados

API de KPI Dashboard

Guia de KPIs

Decisiones basadas en datos

API de vehiculos

Resumen

Endpoints

Obtener estadisticas del dashboard

Obtener datos del grafico de rotacion de inventario

Metricas explicadas

Promedio de dias para venta

Precio promedio de venta

Margen bruto de ganancia

Antiguedad promedio de inventario

Ratio de rotacion de inventario

Puntaje de satisfaccion del cliente

Tasa de retencion de clientes

Costo total de reparacion

Comparaciones por periodo

Cache

Casos de uso

Ejemplo 1: Revision semanal de rendimiento

Ejemplo 2: Revision mensual del negocio

Ejemplo 3: Analisis trimestral

Ejemplo 4: Visualizar tendencias de inventario

Patrones de integracion

Dashboard en tiempo real

Alertas de tendencia

Mejores practicas

Codigos de error

Recursos relacionados