Dashboard de Analytics

Esta guía explica cómo obtener datos de Ozzie para un dashboard de BI o analytics. Puedes agregar datos de transacciones, rastrear adherencia al plan, medir tasas de cumplimiento de metas y construir visualizaciones de reportes.

---

Qué datos están disponibles

Tipo de dato	Endpoint	Campos principales
Transacciones	GET /users/{id}/transactions	monto, categoría, establecimiento, fecha, fuente
Asignaciones del plan	POST /users/{id}/plan	% de necesidades/deseos/ahorro/deuda
Progreso de la meta	GET /users/{id}/goals	target_amount, starting_amount, next_move_date
Completación de money move	GET /users/{id}/money-moves	estado por ciclo, tasas de completación de tareas
Intake financiero	GET /users/{id}/financial-intake	ingresos, gastos, snapshot de deuda

---

Métricas clave que puedes calcular

Métrica	Cómo calcular
Gasto mensual por categoría	Suma amount_cents agrupado por category para transacciones del mes actual
Tasa de ahorro	(monthly_net_income - total_expenses) / monthly_net_income * 100 del intake
% de progreso de la meta	(current_amount - starting_amount) / (target_amount - starting_amount) * 100
Tasa de completación de money move	ciclos completados / total de ciclos * 100 por usuario o en todos los usuarios
Ahorro promedio por ciclo	Suma de amount_cents para tareas do marcadas como done, dividido por el conteo de ciclos
Adherencia al plan	Comparar categorías de gasto reales de transacciones vs. objetivos de allocations del plan

---

Estrategia de paginación para exportación masiva

Ozzie usa paginación basada en cursor en todos los endpoints de lista. Para una exportación completa de datos, itera hasta que has_more sea false:

export async function fetchAllPages(path, params = {}) {
  const allItems = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const queryParams = new URLSearchParams({ limit: '50', ...params });
    if (cursor) queryParams.set('cursor', cursor);

    const { data, pagination } = await ozzieRequest('GET', `${path}?${queryParams}`);
    allItems.push(...data);
    hasMore = pagination.has_more;
    cursor = pagination.next_cursor;
  }

  return allItems;
}

---

Gasto mensual por categoría

async function getMonthlySpendingByCategory(ozzieUserId, year, month) {
  const startDate = `${year}-${String(month).padStart(2, '0')}-01`;
  const endDate = new Date(year, month, 0).toISOString().split('T')[0];

  const transactions = await fetchAllPages(`/users/${ozzieUserId}/transactions`, {
    start_date: startDate,
    end_date: endDate,
  });

  const byCategory = transactions.reduce((acc, tx) => {
    const category = tx.category ?? 'Sin categoría';
    acc[category] = (acc[category] ?? 0) + tx.amount_cents;
    return acc;
  }, {});

  return Object.entries(byCategory)
    .map(([category, cents]) => ({ category, amount: cents / 100 }))
    .sort((a, b) => b.amount - a.amount);
}

---

Exportación masiva para todos los usuarios

async function exportAll() {
  const users = await db.users.findAll({ where: { ozzie_user_id: { not: null } } });
  const results = [];
  const errors = [];

  for (const user of users) {
    try {
      const data = await exportUserFinancialData(user.ozzie_user_id);
      results.push({ internal_user_id: user.id, ...data });
    } catch (err) {
      errors.push({ user_id: user.id, error: err.message });
    }
    await new Promise(r => setTimeout(r, 100));
  }

  writeFileSync(`exports/ozzie-${Date.now()}.json`, JSON.stringify(results, null, 2));
}

info

Para bases de usuarios muy grandes (10k+ usuarios), ejecuta exportaciones en lotes paralelos de 10–20 usuarios, respetando tu límite de tasa. Verifica los headers de respuesta X-RateLimit-Remaining para evitar alcanzar el límite.

---

Gráficos sugeridos

Desglose de gasto — gráfico de pastel o donut

Usa datos de getMonthlySpendingByCategory(). Codifica por colores por categoría. Superpone un anillo punteado mostrando los objetivos de allocations del plan para mostrar presupuesto vs. real.

Tendencia de tasa de ahorro — gráfico de líneas

Usa datos de getSavingsRateTrend() a lo largo de 6–12 meses. Agrega una línea discontinua horizontal en la target_savings_rate del plan.

Progreso de la meta — barra de progreso horizontal

Usa datos de getGoalProgress(). Muestra porcentaje, monto restante y fecha proyectada del plan.key_metrics.projected_goal_date.

Tasa de completación de money move — gauge o barra

Usa datos de getMoneyMoveCompletionRate(). Para un dashboard orientado al usuario, muestra un contador de racha (ciclos consecutivos completados) para fomentar la consistencia.