Skip to main content
GET
/
api
/
dashboard
/
stats
Estadísticas del Dashboard
curl --request GET \
  --url https://api.example.com/api/dashboard/stats
{
  "success": true,
  "data": {
    "ventas_totales": 123,
    "ingresos_netos": 123,
    "ticket_promedio": 123,
    "total_transacciones": 123,
    "cajas_abiertas": 123,
    "diferencias_pendientes": 123,
    "cuentas_cobrar": 123,
    "total_metodos": 123,
    "ventas_cambio": 123,
    "ingresos_cambio": 123,
    "ticket_cambio": 123,
    "transacciones_cambio": 123
  }
}

​
Autenticación

Los endpoints del dashboard requieren autenticación mediante token Bearer. No requieren permisos específicos adicionales.

​
Estadísticas Generales

GET /api/dashboard/stats Retorna los indicadores clave de rendimiento (KPIs) del negocio con comparación del período anterior.

​
Parámetros de Query

​
fecha_inicio
date
Fecha de inicio del período (formato: Y-m-d). Por defecto: hace 7 días
​
fecha_fin
date
Fecha de fin del período (formato: Y-m-d). Por defecto: hoy
​
empresa_id
integer
ID de la empresa a consultar. Por defecto: empresa del usuario autenticado

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
object
KPIs del período con comparaciones

​
Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "ventas_totales": 45820.50,
    "ingresos_netos": 43529.48,
    "ticket_promedio": 285.13,
    "total_transacciones": 162,
    "cajas_abiertas": 2,
    "diferencias_pendientes": 1,
    "cuentas_cobrar": 0,
    "total_metodos": 5,
    "ventas_cambio": 15.3,
    "ingresos_cambio": 15.3,
    "ticket_cambio": -2.8,
    "transacciones_cambio": 18.5
  }
}

​
Ventas por Día

GET /api/dashboard/ventas-por-dia Retorna las ventas diarias del período con comparación del período anterior.

​
Parámetros

Mismos parámetros que /api/dashboard/stats.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "fecha": "2024-03-01",
      "total": 5420.50,
      "total_anterior": 4850.00
    },
    {
      "fecha": "2024-03-02",
      "total": 6180.00,
      "total_anterior": 5920.00
    },
    {
      "fecha": "2024-03-03",
      "total": 4950.00,
      "total_anterior": 6100.00
    }
  ]
}
Uso: Ideal para gráficos de líneas comparativas entre períodos.

​
Métodos de Pago

GET /api/dashboard/metodos-pago Retorna la distribución de ventas por método de pago.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "nombre": "Efectivo",
      "total": 25480.00,
      "cantidad_ventas": 95
    },
    {
      "nombre": "Transferencia BCP",
      "total": 15320.50,
      "cantidad_ventas": 42
    },
    {
      "nombre": "Tarjeta Visa",
      "total": 5020.00,
      "cantidad_ventas": 25
    }
  ]
}
Uso: Gráficos de dona o barras mostrando preferencias de pago.

​
Top Productos

GET /api/dashboard/top-productos Retorna los productos más vendidos por cantidad.

​
Parámetros Adicionales

​
limit
integer
Número de productos a retornar (por defecto: 5)

​
Respuesta

{
  "success": true,
  "data": [
    {
      "nombre": "Arroz Extra Granel x 50kg",
      "cantidad": 245
    },
    {
      "nombre": "Azúcar Rubia x 50kg",
      "cantidad": 198
    },
    {
      "nombre": "Aceite Vegetal x 1L",
      "cantidad": 156
    }
  ]
}

​
Top Categorías

GET /api/dashboard/top-categorias Retorna las categorías de productos más vendidas.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "categoria": "Abarrotes",
      "total_ventas": 85,
      "monto_total": 28450.00,
      "cantidad_total": 420
    },
    {
      "categoria": "Lácteos",
      "total_ventas": 62,
      "monto_total": 12850.50,
      "cantidad_total": 310
    }
  ]
}

​
Top Clientes

GET /api/dashboard/top-clientes Retorna los clientes con mayor volumen de compras.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "nombre": "CORPORACION XYZ S.A.C.",
      "documento": "20612706702",
      "total_compras": 25,
      "monto_total": 45820.50,
      "ticket_promedio": 1832.82
    },
    {
      "nombre": "COMERCIAL ANDES S.A.",
      "documento": "20543210987",
      "total_compras": 18,
      "monto_total": 32100.00,
      "ticket_promedio": 1783.33
    }
  ]
}

​
Ventas por Hora

GET /api/dashboard/ventas-por-hora Retorna la distribución de ventas por hora del día.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "hora": 0,
      "hora_label": "00:00",
      "total_ventas": 0,
      "monto_total": 0
    },
    {
      "hora": 9,
      "hora_label": "09:00",
      "total_ventas": 12,
      "monto_total": 3250.50
    },
    {
      "hora": 10,
      "hora_label": "10:00",
      "total_ventas": 18,
      "monto_total": 5420.00
    }
  ]
}
Uso: Gráfico de barras mostrando horas pico de ventas.

​
Vendedores

GET /api/dashboard/vendedores Retorna el rendimiento de cada vendedor.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "vendedor": "María López",
      "total_ventas": 85,
      "monto_total": 28450.00,
      "ticket_promedio": 334.71
    },
    {
      "vendedor": "Juan Pérez",
      "total_ventas": 77,
      "monto_total": 17370.50,
      "ticket_promedio": 225.46
    }
  ]
}

​
Stock Bajo

GET /api/dashboard/stock-bajo Retorna productos con stock bajo o agotado.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "nombre": "Arroz Extra Granel x 50kg",
      "codigo": "ARR-001",
      "cantidad": 0,
      "stock_minimo": 10,
      "diferencia": -10,
      "urgente": true
    },
    {
      "nombre": "Azúcar Rubia x 50kg",
      "codigo": "AZU-002",
      "cantidad": 5,
      "stock_minimo": 15,
      "diferencia": -10,
      "urgente": false
    }
  ],
  "total": 12
}

​
Cajas Pendientes

GET /api/dashboard/cajas-pendientes Retorna cajas con cierre pendiente de validación.

​
Respuesta

{
  "success": true,
  "data": [
    {
      "id_caja": 5,
      "vendedor": "Carlos Ramírez",
      "apertura": 500.00,
      "cierre": 5420.50,
      "diferencia": -20.00
    }
  ]
}

​
Últimas Transacciones

GET /api/dashboard/ultimas-transacciones Retorna las últimas ventas realizadas.

​
Parámetros

​
limit
integer
Número de transacciones a retornar (por defecto: 10)

​
Respuesta

{
  "success": true,
  "data": [
    {
      "id_venta": 245,
      "serie": "F001",
      "numero": 245,
      "cliente": "CORPORACION XYZ S.A.C.",
      "fecha": "2024-03-05T15:30:00.000000Z",
      "monto": 1850.00,
      "metodo": "Transferencia BCP",
      "estado": "completada"
    }
  ]
}

​
Cálculo de Período Anterior

El sistema calcula automáticamente el período anterior para comparaciones:
  • Período actual: fecha_inicio a fecha_fin
  • Duración: N días entre fecha_inicio y fecha_fin
  • Período anterior: (fecha_inicio - N días) a (fecha_inicio - 1 día)
Ejemplo:
  • Actual: 2024-03-01 a 2024-03-07 (7 días)
  • Anterior: 2024-02-23 a 2024-02-29 (7 días)

​
Filtrado de Ventas Activas

Todos los endpoints filtran automáticamente:
  • Solo ventas con estado activo (excluye anuladas: estado ‘2’ o ‘A’)
  • Por empresa del usuario autenticado (o empresa_id especificado)

​
Notas de Rendimiento

  • Los cálculos de porcentaje de cambio evitan división por cero
  • Las ventas por hora generan un array completo de 0-23 horas (rellena con 0 si no hay datos)
  • Los totales se redondean a 2 decimales
  • Las cantidades se convierten explícitamente a enteros

Build docs developers (and LLMs) love

Get started for freeTalk to us