KPIs y reportes administrativos¶

Documento operativo — 2026-06-07

Define los indicadores clave de desempeño (KPIs) que IslaBox monitorea para evaluar la salud del negocio, y los reportes administrativos que se generan automáticamente o bajo demanda.

Audiencia: administradores, equipo directivo, operaciones.

1. Definiciones generales¶

KPI: indicador cuantificable que mide un aspecto clave del negocio.
Reportes automáticos: se generan periódicamente (diario, semanal, mensual) y se envían a destinatarios definidos.
Reportes bajo demanda: el administrador los solicita desde el backoffice.

2. KPIs principales (los 12 que importan)¶

2.1 Adquisición¶

KPI	Fórmula	Frecuencia	Objetivo MVP	Fuente
Registros nuevos	COUNT(users WHERE created_at = hoy)	Diaria	≥ 5/día	`users`
Tasa de verificación	(verificados / registrados) × 100	Diaria	≥ 80%	`users.email_verified`
Tasa de KYC	(kyc_aprobado / usuarios_activos) × 100	Mensual	≥ 50%	`kyc_records`
CAC (costo adquisición)	Gasto_marketing / nuevos_registros	Mensual	< $15	externo + `users`

2.2 Activación¶

KPI	Fórmula	Frecuencia	Objetivo
Usuarios activos semanales (WAU)	COUNT(DISTINCT user_id WHERE last_login > 7d)	Semanal	≥ 70% del MAU
Usuarios activos mensuales (MAU)	COUNT(DISTINCT user_id WHERE last_login > 30d)	Mensual	≥ 100 en MVP
Tasa de primer reporte	(usuarios_con_reporte / usuarios_registrados) × 100	Mensual	≥ 60%
Tiempo a primer envío	AVG(consolidation.created_at - user.created_at)	Mensual	≤ 30 días

2.3 Operación¶

KPI	Fórmula	Frecuencia	Objetivo
Paquetes recibidos/día	COUNT(physical_packages WHERE received_at = hoy)	Diaria	≥ 10/día
Tiempo promedio en almacén	AVG(despacho - recepción)	Semanal	≤ 21 días
Tasa de conciliación	(conciliados / recibidos) × 100	Diaria	≥ 95%
Paquetes abandonados	COUNT(status = descartado_o_cerrado)	Mensual	< 2%

2.4 Financiero¶

KPI	Fórmula	Frecuencia	Objetivo
Ingresos/mes	SUM(payments.amount WHERE status=completado)	Mensual	≥ $10k
Ingreso promedio por envío (ARPU)	Ingresos_mes / envíos_mes	Mensual	≥ $50
Tasa de morosidad de almacenaje	(deuda_acumulada / facturado_mes) × 100	Mensual	< 5%
LTV (valor de vida)	AVG(ingresos_acumulados por usuario con > 6 meses)	Trimestral	> $200

2.5 Calidad¶

KPI	Fórmula	Frecuencia	Objetivo
NPS (encuesta)	% promotores - % detractores	Trimestral	≥ 40
Tasa de incidencias	(incidents / envíos) × 100	Mensual	< 8%
Tiempo de resolución de incidencias	AVG(resolved_at - created_at)	Mensual	≤ 5 días
Tasa de rechazo KYC	(kyc_rechazado / kyc_enviado) × 100	Mensual	< 15%

3. Reportes automáticos¶

3.1 Reporte diario de operaciones¶

Generado: todos los días a las 08:00 (hora Miami) Destinatarios: equipo de operaciones, supervisores de almacén Contenido:

RESUMEN DIARIO — ISLABOX — [fecha]

📦 Paquetes recibidos: 14
   - Identificados: 12 (85.7%)
   - Pendiente conciliación: 2 (14.3%)

📊 Consolidaciones nuevas: 3
💰 Pagos confirmados: 5 ($342.50 total)
📤 Envíos despachados: 2
   - En tránsito: 8
   - En aduana: 3
   - En reparto: 1

⚠️ Incidencias abiertas: 4
   - Críticas: 0
   - En revisión: 2
   - Esperando usuario: 2
   - Esperando agencia: 0

👤 Nuevos registros: 7
✅ KYC aprobados hoy: 2

3.2 Reporte semanal ejecutivo¶

Generado: lunes 09:00 Destinatarios: CEO, CFO, COO Contenido:

Resumen de KPIs vs objetivos
Gráficos de tendencia (7 días, 30 días)
Top 5 incidencias activas
Top 5 KYC pendientes
Ingresos de la semana vs semana anterior
Previsión de almacenaje (próximos 7 días)

3.3 Reporte mensual de negocio¶

Generado: día 1 del mes siguiente, 10:00 Destinatarios: CEO, CFO, inversionistas Contenido:

KPIs completos vs objetivos
Cohortes de retención (mes 1, 3, 6, 12)
CAC vs LTV
Embudo de conversión (registro → prealerta → consolidación → pago → despacho)
Análisis de cohortes por país de origen
Top 10 usuarios por volumen
Análisis de cohortes por vía de envío (aérea/marítima)
Análisis de morosidad

3.4 Reporte trimestral de calidad¶

Generado: día 1 del trimestre Destinatarios: equipo de producto, equipo de soporte Contenido:

NPS (con comentarios)
Tasa de incidencias por tipo
Tiempo promedio de resolución
Causas raíz de incidencias
Quejas recurrentes
Áreas de mejora priorizadas

4. Reportes bajo demanda (backoffice)¶

El administrador puede solicitar desde /backoffice/reportes:

4.1 Paquetes por período¶

Parámetros: fecha_inicio, fecha_fin, status, marketplace
Output: tabla + CSV
Endpoint: GET /api/v1/admin/reports/packages?from=...&to=...&status=...

4.2 Ingresos por período¶

Parámetros: fecha_inicio, fecha_fin, agrupado_por (día/semana/mes)
Output: serie temporal + CSV
Endpoint: GET /api/v1/admin/reports/revenue?from=...&to=...&group_by=day

4.3 Incidencias por estado y tipo¶

Parámetros: fecha_inicio, fecha_fin, status, type
Endpoint: GET /api/v1/admin/reports/incidents?...

4.4 Paquetes próximos a abandonar¶

Parámetros: días_restantes (default 7)
Output: lista de paquetes con días restantes
Endpoint: GET /api/v1/admin/reports/abandonment-risk?days=7

4.5 Usuarios activos por cohorte¶

Parámetros: cohorte (mes de registro), métrica (WAU/MAU/envíos)
Endpoint: GET /api/v1/admin/reports/cohorts?cohort=2026-06&metric=monthly_active

4.6 Eficiencia del almacén¶

Parámetros: fecha_inicio, fecha_fin
Output: paquetes/operador, tiempo_promedio_recepción, % conciliación
Endpoint: GET /api/v1/admin/reports/warehouse-efficiency?...

4.7 Cargos por almacenaje pendientes¶

Output: total acumulado, top 10 usuarios con deuda, proyección
Endpoint: GET /api/v1/admin/reports/storage-charges

4.8 Auditoría de cambios de estado¶

Parámetros: fecha_inicio, fecha_fin, entity_type
Output: lista de cambios con usuario que los hizo
Endpoint: GET /api/v1/admin/reports/audit-changes?...

5. Dashboards en tiempo real (backoffice)¶

5.1 Dashboard principal¶

KPIs del día (paquetes recibidos, ingresos, incidencias abiertas)
Gráfico de envíos por estado (pie chart)
Gráfico de ingresos últimos 30 días (línea)
Cola de KYC pendientes (top 5)
Cola de incidencias activas (top 5)
Paquetes próximos a abandonar (top 10)

5.2 Dashboard de almacén¶

Paquetes por zona (A, B, C, D, E, F)
Operadores activos en este momento
Tiempo promedio de recepción hoy
Cola de conciliación
Paquetes sin prealerta

5.3 Dashboard de calidad¶

NPS último mes
Tasa de incidencias vs mes anterior
Tiempo promedio de resolución
Top 5 motivos de incidencia
Distribución de ratings de la app

6. Exportación¶

Todos los reportes se pueden exportar en:

CSV: para análisis en Excel/Google Sheets
JSON: para integración con herramientas externas
PDF: para reportes ejecutivos
Excel (.xlsx): para análisis avanzado con tablas dinámicas

Límite: 100,000 filas por exportación (más se hace vía API + paginación).

7. Alertas automáticas¶

El sistema envía alertas cuando:

Condición	Destinatario	Canal
Cualquier KPI se desvía > 20% del objetivo	Admin de turno	Email + Slack
> 10 incidencias críticas abiertas	COO	SMS + Slack
Caída de pagos confirmados por > 1h	Tech lead	PagerDuty
Cola de KYC > 50 pendientes	Equipo de revisión	Email
Almacenaje acumulado > $5k sin pagar	Admin	Email
NPS < 30 en último mes	CEO	Email

8. Almacenamiento de datos para reportes¶

Datos raw: PostgreSQL (consulta directa)
Datos agregados diarios: tabla daily_metrics (cron diario 02:00)
Datos agregados mensuales: tabla monthly_metrics (cron mensual día 1)
Datos de auditoría: audit_logs (inmutable, 3 años)
Snapshots para BI: data warehouse en S3 + Athena (Fase 2)

9. Implementación técnica¶

9.1 Generación de reportes¶

Síncronos (consulta en vivo): para reportes pequeños (< 1s de query)
Asíncronos (job en background): para reportes pesados o CSV grandes
Cacheados (Redis 5 min): para dashboards en tiempo real

9.2 Stack¶

Backend: Python + pandas para agregaciones
Visualización backoffice: Recharts (React)
Email: SendGrid con plantillas
Slack: webhook
PDF: WeasyPrint
Excel: openpyxl

Ver api-contract.md §admin para el detalle de los endpoints /api/v1/admin/reports/*.

10. Privacidad en reportes¶

Los reportes nunca incluyen datos personales sensibles (número de documento, KYC).
Los datos personales se enmascaran en logs y reportes.
Solo el admin y sysadmin pueden acceder a los endpoints de reporte.
Cada acceso a un reporte queda en audit_logs.