> ## 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 de analitica del dashboard

> Recupera estadisticas del dashboard y metricas de rendimiento

## 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

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

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

**Query Parameters:**

<ParamField query="period" type="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
</ParamField>

**Response:**

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

**Estructura del objeto estadistica:**

Cada estadistica incluye:

<ResponseField name="current" type="number">
  Valor del periodo actual
</ResponseField>

<ResponseField name="previous" type="number">
  Valor del periodo anterior
</ResponseField>

<ResponseField name="change" type="number">
  Cambio absoluto entre periodos
</ResponseField>

<ResponseField name="changePercentage" type="number">
  Cambio porcentual entre periodos
</ResponseField>

<ResponseField name="trend" type="enum">
  Direccion de tendencia: `up`, `down`, `stable`
</ResponseField>

<ResponseField name="unit" type="string">
  Unidad de medida (days, MAD, %, etc.)
</ResponseField>

***

### Obtener datos del grafico de rotacion de inventario

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

Obtiene serie temporal para visualizacion de rotacion de inventario.

**Query Parameters:**

<ParamField query="period" type="enum">
  Periodo para el grafico (mismas opciones que dashboard stats)
</ParamField>

**Response:**

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

***

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<AccordionGroup>
  <Accordion title="Elige periodos adecuados">
    Usa periodos cortos (7 dias) para metricas operativas, periodos largos (90 dias) para decisiones estrategicas.
  </Accordion>

  <Accordion title="Monitorea tendencias, no solo valores">
    Enfocate en `trend` y `changePercentage` para identificar mejoras o caidas.
  </Accordion>

  <Accordion title="Configura alertas automaticas">
    Configura alertas cuando una metrica supere umbrales (ej., dias para vender > 45).
  </Accordion>

  <Accordion title="Respeta el cache">
    El cache de 5 minutos mejora rendimiento. No consultes mas seguido de lo necesario.
  </Accordion>

  <Accordion title="Compara periodos equivalentes">
    Asegura comparaciones equivalentes (mismo dia de la semana, mismo mes).
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="API de KPI Dashboard" icon="gauge-high" href="/es/api-reference/analytics/kpi-dashboard">
    Gestiona configuraciones de KPIs
  </Card>

  <Card title="Guia de KPIs" icon="book" href="/es/guides/dashboard-kpis">
    Aprende a optimizar tu dashboard
  </Card>

  <Card title="Decisiones basadas en datos" icon="chart-line" href="/es/guides/data-driven-decisions">
    Usa analitica para estrategia
  </Card>

  <Card title="API de vehiculos" icon="car" href="/es/api-reference/vehicles/overview">
    Fuente de datos para analitica
  </Card>
</CardGroup>