Money Manager

El Copiloto IA es un asistente conversacional avanzado integrado a tu cuenta de Money Manager que te permite administrar tus finanzas mediante lenguaje natural, directamente desde WhatsApp o la interfaz web.

💬 ¿Cómo funciona el Copiloto?

El Copiloto está conectado a la API de Money Manager de forma interna y segura. Gracias a su procesamiento de lenguaje natural, no necesitas rellenar formularios en la app: puedes simplemente hablarle como si fuera tu contador personal.

¿Qué puede hacer el Copiloto por ti?

Registrar ingresos y gastos al vuelo: Le describes qué compraste y él se encarga de deducir el monto, la categoría y la cartera adecuada.
Consultar saldos y presupuestos: Puedes preguntarle cuánto dinero te queda en una cuenta o cuánto has gastado de tu presupuesto del mes.
Hacer consultas complejas: Puedes pedirle análisis o resúmenes financieros (ej. "¿En qué gasté más esta semana?").

📲 Ejemplos de Conversación (Flujo Conversacional)

Aquí tienes ejemplos reales de cómo interactuar con el chatbot de WhatsApp:

1. Registrar un gasto ordinario

Tú: Gasté $250 pesos en tacos con mi tarjeta BBVA

Copiloto IA: 📝 Entendido. Registré un Gasto por $250.00 MXN en la categoría Comida utilizando tu cartera BBVA. Tu saldo restante estimado en esa cuenta es de $14,250.00 MXN.

2. Registrar un gasto con descripción detallada

Tú: Pagué la luz de la oficina $1,200 en efectivo y ponle de nota que vencía hoy

Copiloto IA: 📝 Gasto registrado por $1,200.00 MXN en Servicios desde tu cartera Efectivo. Nota: "vencía hoy".

3. Consultar balances de carteras

Tú: ¿Cuánto tengo en mis cuentas?

Copiloto IA: 💳 Aquí tienes el balance actual de tus carteras activas:

BBVA (Débito): $14,250.00 MXN

Santander (Crédito): -$8,500.00 MXN

Efectivo: $2,300.00 MXN

Patrimonio Neto Consolidado: $8,050.00 MXN.

4. Consultar el estado de un presupuesto

Tú: ¿Cuánto me queda para gastar en comida?

Copiloto IA: 🏷️ Tienes un presupuesto de $5,000.00 MXN al mes para Comida. Has gastado $3,250.00 MXN (65% del límite). Te quedan $1,750.00 MXN disponibles para el resto del mes.

🔗 Integración con Wallavi Conversational Engine

El Copiloto IA de Money Manager opera mediante la potente infraestructura de Wallavi, la plataforma de mensajería empresarial líder dentro de nuestro mismo grupo corporativo.

Esta integración nativa con Wallavi nos permite garantizar:

Alta Disponibilidad y Velocidad: Conexión ultra-rápida a la API oficial de WhatsApp Business Cloud de Meta.
Seguridad Nivel Bancario: Cifrado corporativo y cumplimiento normativo estricto en la transferencia de tus datos financieros.
Procesamiento Inteligente: Procesamiento de Lenguaje Natural avanzado que traduce mensajes hablados o escritos en transacciones estructuradas en milisegundos.

📲 Por WhatsApp

Estas cinco operaciones son las que usa el agente cuando escribes por WhatsApp. Ninguna recibe el id de una transacción: actúan sobre lo último que registraste por WhatsApp.

Tú dices	Operación	Qué hace
«Deshacer»	`undoLastTransaction` · `POST /api/whatsapp/last-transaction/undo`	Borra lo último que registraste y devuelve el saldo de la cartera.
«No, eran 150»	`updateLastTransaction` · `PATCH /api/whatsapp/last-transaction`	Cambia monto, moneda, concepto, categoría, cartera o fecha de lo último.
«¿Cuánto tengo en BBVA?» / «Saldos»	`listWallets` · `GET /api/wallets`	Lista carteras con sus saldos y permite dar el saldo por cuenta y el total.
«¿Cuánto me queda para comida?»	`listBudgets` · `GET /api/budgets`	Lista presupuestos con lo consumido y restante del mes.
«¿Cómo van mis metas?»	`listGoals` · `GET /api/goals`	Lista metas de ahorro con monto ahorrado, objetivo y porcentaje.
«Aparta 500 para el viaje»	`depositToGoal` · `POST /api/goals/{id}/deposit`	Deposita fondos en una meta de ahorro desde tu cartera.
«Retira 200 de mi meta»	`withdrawFromGoal` · `POST /api/goals/{id}/withdraw`	Retira fondos de una meta de ahorro hacia tu cartera.
«¿Cuánto debo?» / «Deudas»	`listDebts` · `GET /api/debts`	Lista deudas con saldo pendiente y total de cada una.
«Abona 1000 a la tarjeta»	`createDebtPayment` · `POST /api/debts/{id}/payments`	Registra un abono a una deuda y descuenta su saldo.
«¿Qué pagos tengo esta semana?»	`listRecurrent` · `GET /api/recurrent`	Lista próximos pagos recurrentes con monto y fecha.
«Ya pagué la luz»	`payRecurrent` · `POST /api/recurrent/{id}/pay`	Marca un recurrente como pagado, registra el gasto y avanza la fecha.
«Crea la categoría Mascotas»	`createCategory` · `POST /api/categories`	Crea una categoría de gasto o ingreso en el espacio de trabajo.
«Crea la etiqueta Vacaciones»	`createTag` · `POST /api/tags`	Crea una etiqueta para clasificar movimientos.
«¿Qué etiquetas tengo?»	`listTags` · `GET /api/tags`	Lista las etiquetas activas del espacio de trabajo.
«¿Cómo voy este mes?»	`getMonthlySummary` · `GET /api/reports/monthly-summary`	Resumen del mes con ingresos, gastos, top 3 categorías y comparación contra el mes pasado.
«Corrige el gasto de tacos del martes»	`updateTransaction` · `PATCH /api/transactions/{id}`	Corrige cualquier movimiento específico encontrado tras confirmación.
«Borra el ingreso de 5000 de la semana pasada»	`deleteTransaction` · `DELETE /api/transactions/{id}`	Borra cualquier movimiento específico encontrado tras confirmación.
«¿En qué equipos estoy?»	`listMyWorkspaces` · `GET /api/whatsapp/workspaces`	Tu espacio personal y los equipos donde eres miembro.
«Pásate a Grupo Pérez»	`setWhatsappWorkspace` · `PUT /api/whatsapp/workspace`	Cambia el workspace que usas por WhatsApp.
«¿Cuánto gasté esta semana en comida?»	`getSpendingSummary` · `GET /api/reports/spending-summary`	Total por moneda de un periodo, con la semana de lunes a hoy en la Ciudad de México.

Reglas de deshacer y corregir. Solo se puede cambiar lo que tú registraste por WhatsApp o que tienes permisos para modificar en el workspace activo. Para el último movimiento reciente rige undoLastTransaction y updateLastTransaction (hace 24 horas o menos). Para cualquier otro movimiento, el agente busca con listTransactions y, si hay varios coincidentes, muestra las opciones y pregunta cuál antes de modificar nada; luego aplica updateTransaction o deleteTransaction. Todo lo que corrige o borra pide confirmación previa antes de ejecutarse. Las escrituras piden Idempotency-Key.

Categorías, etiquetas y resumen mensual. createCategory y createTag permiten dar de alta nuevas categorías y etiquetas al vuelo sin pedir confirmación, para usarlas de inmediato en registros posteriores. listTags y listCategories consultan los catálogos activos. getMonthlySummary devuelve los ingresos totales, los gastos totales, las tres categorías con mayor egreso del mes y la comparación exacta contra el mes anterior. Las tres categorías son las mismas que «Gastos por categoría» del tablero: no cuentan los gastos sin categoría, convierten cada moneda a la del workspace con el tipo de cambio de hoy y traen currency = la moneda del workspace. percentageChange va con dos decimales, redondeado (66.666…% es 66.67). listTags y createTag no piden el módulo «Etiquetas»: sirven en cualquier cuenta, como el selector de etiquetas de los formularios; editar o borrar etiquetas sí lo pide. En una empresa, crear etiquetas pide tags:write, que los roles «Colaborador» y «Lector» no traen por omisión: un lector o un colaborador recibe 403, igual que en la página.

Deudas y pagos recurrentes. listDebts permite consultar el estado actual de las deudas y saldos pendientes. Para abonar a una deuda, createDebtPayment descuenta el monto aportado del saldo de la deuda, deduce el balance de la cartera especificada (si no se envía, la cartera marcada por omisión o, si ninguna lo está, la más antigua; sin ninguna cartera el abono falla con WALLET_NOT_FOUND y la deuda no cambia) y registra el movimiento de gasto. Para pagos recurrentes (renta, suscripciones, servicios), listRecurrent muestra los próximos pagos programados con su periodicidad y fecha; payRecurrent valida que el recurrente esté activo, pertenezca a ingreso/gasto y no haya sido pagado ya en el ciclo actual (si lastPayment cae en o después del vencimiento anterior, como cuando el cron ya lo registró, responde 409; el pago adelantado del ciclo que viene sí se permite), registrando el movimiento, descontando el saldo y avanzando automáticamente la fecha de nextPayment. Ambas operaciones se ejecutan sin confirmación previa y reportan el resultado exacto.

Presupuestos y metas de ahorro. listBudgets devuelve los límites presupuestarios con el monto gastado (spent) y el disponible (remaining). Si al registrar un gasto con createTransactionByName se rebasa el presupuesto de esa categoría, la respuesta incluye budgetWarning dentro de resolved y el agente lo avisa de inmediato en su mensaje. Para metas de ahorro, listGoals muestra el progreso de cada una; depositToGoal y withdrawFromGoal permiten ingresar o retirar dinero de una meta sin pedir confirmación, descontando o acreditando el saldo en la cartera correspondiente.

Categorías y carteras por nombre. updateLastTransaction busca el nombre exacto (sin acentos ni mayúsculas). Si no existe responde 404 CATEGORY_NOT_FOUND o WALLET_NOT_FOUND con details.suggestions (hasta 5 nombres) y no cambia nada. currency solo se manda junto con amount.

Cambiar de workspace. setWhatsappWorkspace busca primero el nombre igual y luego el único que lo contenga. Sin coincidencias responde 404 WORKSPACE_NOT_FOUND con los nombres disponibles; con varias, 409 CONFLICT con las candidatas.

Cuánto gastaste y saldos. listWallets devuelve las carteras activas con su saldo y moneda. period en getSpendingSummary puede ser today, yesterday, this_week (por omisión), last_week, this_month, last_month, last_7_days o last_30_days; o manda from y to juntos (366 días como máximo). category es opcional y type es expense (por omisión) o income. El total viene agrupado por la moneda de la cartera, como texto con dos decimales, y no cuenta movimientos borrados.

Al registrar con createTransactionByName, la respuesta trae resolved (workspaceName, walletName, categoryName, budgetWarning) para que el agente diga dónde quedó y si se rebasó un presupuesto, y sin date usa el día de la Ciudad de México. Si mandas walletName o categoryName y no existe (tampoco sin acentos ni mayúsculas), responde 404 WALLET_NOT_FOUND o CATEGORY_NOT_FOUND con details.suggestions y no guarda nada: nunca cae a otra cartera o categoría. Sin esos nombres, usa la primera activa.

topCategories nunca compara monedas distintas: primero van las de la moneda del workspace, luego las demás por orden alfabético, y dentro de cada moneda de mayor a menor.

🤖 El agente de WhatsApp

Es un agente de Wallavi aparte del copiloto web: solo texto, en español, sin pantallas. Su blueprint vive en .wallavi/whatsapp/money-manager-whatsapp.json (fuera de .wallavi/blueprints/, así torre setup nunca lo toca) y el id de cada ambiente, en .wallavi/whatsapp/agents.json (dev y prd).

Cómo se aplica. Desde la raíz del repo:

MONEY_MANAGER_URL=https://money-manager.web.localhost:3009 node scripts/wallavi-whatsapp.mjs            # aplica al agente de TORRE_ENV (dev por omisión)
MONEY_MANAGER_URL=… node scripts/wallavi-whatsapp.mjs --create                                          # crea uno nuevo e imprime su id

bash

Los dos aceptan --dry-run. Con --create no escribe ningún archivo: el id se pone a mano en agents.json. Si el ambiente no tiene id, el script falla y dice cómo crearlo. MONEY_MANAGER_URL se lee en la terminal que aplica y Wallavi guarda la URL ya resuelta; su origen es el aud del JWT, así que debe ser igual al de NEXT_PUBLIC_APP_URL de Money Manager en ese ambiente.

Su acción. Una sola, «Money Manager API (WhatsApp)», con authType: "channel_identity" (Wallavi firma X-Wallavi-Identity; ver Autenticación) y sus operaciones de WhatsApp: linkWhatsapp, listWallets, listCategories, createCategory, listTags, createTag, listTransactions, createTransactionByName, undoLastTransaction, updateLastTransaction, getSpendingSummary, getMonthlySummary, listMyWorkspaces, setWhatsappWorkspace, updateTransaction, deleteTransaction, listBudgets, listGoals, depositToGoal, withdrawFromGoal, listDebts, createDebtPayment, listRecurrent y payRecurrent.

Qué pide confirmación. Registrar un gasto o ingreso (createTransactionByName), crear categorías (createCategory) o etiquetas (createTag), vincular (linkWhatsapp), cambiar de workspace (setWhatsappWorkspace), y depositar o retirar en metas (depositToGoal / withdrawFromGoal) se hacen sin preguntar; el registro siempre termina con «Si no es así, escribe "deshacer"». Deshacer (undoLastTransaction), corregir (updateLastTransaction / updateTransaction) y borrar (deleteTransaction) sí preguntan antes. Las consultas nunca preguntan.

Atención por asesor (Support). Si la persona pide hablar con un asesor o soporte, o tras dos intentos fallidos, el agente escala a Support (escalateToHuman), donde un asesor atiende la conversación desde la bandeja de entrada compartida por este mismo chat de WhatsApp.

Suite de pruebas de punta a punta. La suite apps/web/src/e2e-whatsapp/ valida todo el flujo por WhatsApp (vincular, registrar, consultar saldos, gastos, presupuestos y metas, depositar en metas, aviso de rebase de presupuesto, corregir y borrar cualquier movimiento, disambiguación, permisos de lector, cambio de workspace, cambio de SIM y escalación a soporte). Se ejecuta contra desarrollo con:

torre prueba -- bash -c 'export ALLOW_WHATSAPP_E2E=true WALLAVI_URL=http://localhost:14000 WALLAVI_META_APP_SECRET="$(doppler secrets get META_APP_SECRET -p wallavi -c dev --plain)" && doppler run -p money-manager -c dev -- pnpm --filter @money-manager/web test:whatsapp-e2e'