Dashboard

API de Dashboard

Un solo endpoint que devuelve todos los datos analíticos para la vista del dashboard, incluyendo KPIs con comparación de tendencia, datos para gráficas y desgloses de actividad.

Obtener Datos del Dashboard

GET /api/dashboard

Permiso: dashboard:view

Devuelve analíticas completas del tenant actual dentro de un período de tiempo determinado. Incluye comparación con el período equivalente anterior para el cálculo de tendencias.

Query Parameters:

Parameter	Type	Required	Description
period	string	No	`day`, `week` o `month` (por defecto: `month`)
from	string	No	Fecha de inicio personalizada (ISO 8601). Sobrescribe `period`.
to	string	No	Fecha de fin personalizada (ISO 8601). Por defecto es el momento actual.

Response 200 OK:

{
  "data": {
    "kpis": {
      "generated": { "value": 25, "trend": 12 },
      "won": { "value": 8, "rate": 32, "trend": -5 },
      "lost": { "value": 3, "rate": 12, "trend": 0 },
      "clients": { "value": 145, "newInPeriod": 7, "trend": 40 }
    },
    "amounts": {
      "quoted": 485000,
      "won": 195000,
      "prevQuoted": 420000
    },
    "chartData": [
      { "date": "2026-03-01", "generated": 3, "won": 1, "amount": 45000 },
      { "date": "2026-03-02", "generated": 1, "won": 0, "amount": 12000 }
    ],
    "statusDistribution": [
      { "name": "Generadas", "value": 10, "color": "#6366f1" },
      { "name": "Enviadas", "value": 8, "color": "#3b82f6" },
      { "name": "Ganadas", "value": 5, "color": "#10b981" },
      { "name": "Perdidas", "value": 2, "color": "#ef4444" }
    ],
    "recentQuotes": [
      {
        "id": "clxyz...",
        "quoteNumber": 42,
        "status": "SENT",
        "total": 17900,
        "createdAt": "2026-03-31T10:00:00.000Z",
        "clientName": "María López",
        "companyName": "Distribuidora del Norte S.A."
      }
    ],
    "topClients": [
      { "name": "María López", "company": "Distribuidora del Norte S.A.", "count": 5, "total": 89500 }
    ],
    "collaboratorActivity": [
      {
        "userId": "clxyz...",
        "name": "Carlos Méndez",
        "generated": 12,
        "won": 4,
        "lost": 1,
        "amount": 245000
      }
    ],
    "period": {
      "from": "2026-03-01T00:00:00.000Z",
      "to": "2026-03-31T18:30:00.000Z",
      "label": "month"
    }
  }
}

Campos de la respuesta:

Campo	Descripción
`kpis.generated`	Total de cotizaciones creadas en el período con tendencia % respecto al período anterior
`kpis.won`	Cotizaciones ganadas con tasa de conversión y tendencia
`kpis.lost`	Cotizaciones perdidas con tasa de pérdida y tendencia
`kpis.clients`	Total de clientes (histórico), nuevos en el período y tendencia de nuevos
`amounts`	Monto total cotizado, monto ganado y monto cotizado del período anterior
`chartData`	Desglose diario de cotizaciones para gráficas de series de tiempo
`statusDistribution`	Conteo por estado con colores para gráficas de dona/pastel (excluye estados con conteo cero)
`recentQuotes`	Últimas 7 cotizaciones del período
`topClients`	Top 5 clientes por monto cotizado en el período
`collaboratorActivity`	Desglose por usuario (solo propietario/administrador; array vacío para colaboradores)

Errores:

Status	Error	Cuándo
401	"No autorizado"	Sesión ausente o inválida
403	"Sin permisos"	El rol no tiene `dashboard:view`

Ejemplo con cURL:

curl -X GET "https://cotizera.com/api/dashboard?period=month" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

AnteriorPipeline SiguienteCollaborators