FinSight AI — Autonomous Financial Reporting API

Concepto

FinSight AI es un SaaS B2B que elimina el trabajo manual de generación e interpretación de informes financieros para PYMES y startups. Conecta con QuickBooks Online vía OAuth2, genera estados financieros estándar con un solo endpoint, y los enriquece con un resumen ejecutivo en lenguaje natural producido por un LLM (GPT-4 o compatible). El resultado: el fundador recibe insights accionables en segundos, no horas.

---

Arquitectura

┌──────────────────────────────────────────────────────────────────────┐
│                           REST API (HTTPS)                           │
│   /auth/**  (public)  │  /api/connections/**  │  /api/reports/**     │
└─────────────┬──────────────────────┬──────────────────────┬──────────┘
              │                      │                      │
       AuthController      ConnectionController      ReportController
              │                      │                      │
       UserService            OAuthService         ReportingService
              │                      │                 /         \
       UserRepository    ApiConnectionRepository   QuickBooks   AiAnalysis
              │                      │              Client       Service
         PostgreSQL              PostgreSQL (H2)       │              │
                                                 [Feign:QB]    [Feign:OpenAI]
                                                 QuickBooks    GPT-4 / mock
                                                   Online

Capas:

Capa	Paquete	Responsabilidad
Controladores	controller/	HTTP in/out, validación, respuestas
Servicios	service/	Lógica de negocio, orquestación
Clientes	client/	Feign: QuickBooks + OpenAI
Modelos	model/	Entidades JPA
Repositorios	repository/	Spring Data JPA CRUD
Seguridad	security/	JWT filter, UserDetails
Configuración	config/	Security, Feign, Jackson, AppProperties

---

Endpoints

Autenticación (público)

Método	Ruta	Body	Descripción
%%INLINE7%%	%%INLINE8%%	RegisterRequest	Crea cuenta, devuelve JWT
%%INLINE10%%	%%INLINE11%%	AuthRequest	Autentica, devuelve JWT

Conexión QuickBooks (requiere JWT)

Método	Ruta	Descripción
%%INLINE13%%	%%INLINE14%%	Genera URL de autorización OAuth2
%%INLINE15%%	%%INLINE16%%	Intercambia código por tokens
%%INLINE17%%	%%INLINE18%%	Estado actual de la conexión
%%INLINE19%%	%%INLINE20%%	Revoca la conexión

Informes Financieros (requiere JWT)

Método	Ruta	Params	Descripción
%%INLINE21%%	%%INLINE22%%	?type=pnl&period=2025-Q4	Genera un informe nuevo + análisis IA
%%INLINE24%%	%%INLINE25%%	?type=balance (opcional)	Lista todos los informes históricos
%%INLINE27%%	%%INLINE28%%	—	Obtiene un informe específico

Tipos de informe: %%INLINE29%% (P&L / Estado de Resultados), %%INLINE30%% (Balance General), cashflow (Flujo de Caja)

Ejemplos de payload

// POST /auth/register
{
  "email": "founder@acme.com",
  "password": "secure123!",
  "fullName": "Jane Smith"
}

// POST /auth/login → respuesta
{
  "token": "eyJhbGci...",
  "email": "founder@acme.com",
  "fullName": "Jane Smith",
  "role": "USER"
}

// POST /api/reports/generate?type=pnl&period=2025-Q4 → respuesta
{
  "id": 1,
  "type": "PNL",
  "period": "2025-Q4",
  "rawData": "{ ... JSON de QuickBooks ... }",
  "aiSummary": "Revenue increased 12% QoQ...",
  "generatedAt": "2026-04-21T10:30:00"
}

---

Flujo OAuth2 con QuickBooks

1. Frontend → POST /api/connections/quickbooks/initiate
   ← { authorizationUrl, state }

2. Frontend redirige al usuario a authorizationUrl (QuickBooks consent)

3. QuickBooks redirige al frontend con ?code=...&state=...&realmId=...

4. Frontend → POST /api/connections/quickbooks/callback
   { "code": "...", "state": "...", "realmId": "..." }
   ← { "provider": "quickbooks", "connected": true, "realmId": "..." }

5. FinSight intercambia code → access_token + refresh_token (jjwt almacenado)

Modo demo: si app.quickbooks.client-id está vacío, el servidor usa tokens mock y datos financieros simulados — la app arranca sin credenciales reales.

---

Análisis por IA

%%INLINE33%% construye un prompt estructurado con los datos contables y llama a %%INLINE34%% (OpenAI-compatible). La llamada se ejecuta en un virtual thread (Java 25) para no bloquear threads del servidor durante la espera de red.

Si app.ai.api-key está vacío, devuelve un resumen demo pre-escrito. El mismo mecanismo aplica para QuickBooks.

---

Tecnologías clave

Componente	Tecnología
Framework	Spring Boot 4.0.4 + Spring Framework 7
Seguridad	Spring Security 7 + JWT (jjwt 0.12.6)
ORM	Spring Data JPA + Hibernate 7
DB dev	H2 in-memory (auto-configurado)
DB prod	PostgreSQL 16+
Clientes HTTP	Spring Cloud OpenFeign 4.2.1
Concurrencia	Virtual Threads — Java 25
Serialización	Jackson 3.x (tools.jackson.*)
Validación	Jakarta Validation 3

---

Análisis de Negocio

Mercado objetivo: ~33 M PYMES en LATAM/España que usan QuickBooks, Xero o Sage. Solo en México: +4 M PYMEs.

Propuesta de valor: ahorro estimado de 8-15 h/mes por empresa en tareas de reporting financiero.

Monetización SaaS:

• Free tier: 3 informes/mes
• Starter ($29/mes): 20 informes, 1 conexión contable
• Pro ($99/mes): ilimitado, múltiples conexiones (Xero, Sage), exportación PDF, alertas

Barrera defensible: red de datos financieros anonimizados para benchmarking sectorial (feature v2).

---

Cómo ejecutar

Prerrequisitos

• Java 25
• Maven 3.9+

Inicio rápido (modo demo — sin credenciales externas)

cd solutions/2026-04-21-finsight-ai-api
mvn spring-boot:run

La app arranca en http://localhost:8080 con H2 in-memory. Todos los endpoints funcionan con datos simulados.

Con credenciales reales

Agrega en application.yml:

app:
  jwt:
    secret: "tu-secreto-de-al-menos-32-caracteres-en-produccion"
    expiration: 86400000

  ai:
    api-key: "sk-..."
    model: "gpt-4"
    base-url: "https://api.openai.com"

  quickbooks:
    client-id: "tu-qb-client-id"
    client-secret: "tu-qb-client-secret"
    redirect-uri: "https://tu-dominio.com/api/connections/quickbooks/callback"

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/finsight
    username: postgres
    password: secreto
  jpa:
    hibernate:
      ddl-auto: update

Compilación

mvn clean compile       # verifica compilación
mvn clean package       # genera JAR ejecutable
java -jar target/finsight-ai-api-0.0.1-SNAPSHOT.jar

Prueba rápida con curl

# Registro
curl -s -X POST http://localhost:8080/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"test@acme.com","password":"password123","fullName":"Test User"}'

# Login (guarda el token)
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"test@acme.com","password":"password123"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# Simular conexión QuickBooks (modo demo)
curl -s -X POST http://localhost:8080/api/connections/quickbooks/callback \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"code":"demo-code","state":"demo-state","realmId":"123456789"}'

# Generar informe P&L con análisis IA
curl -s -X POST "http://localhost:8080/api/reports/generate?type=pnl&period=2025-Q4" \
  -H "Authorization: Bearer $TOKEN"

---

Referencias

• QuickBooks Online API Docs
• QuickBooks OAuth2 Guide
• OpenAI Chat Completions API
• Spring Cloud OpenFeign 4.2.x
• jjwt 0.12.x Reference
• GroovyWeb SaaS Ideas 2026

---

FinOps Analysis para FinSight AI

1. Estimación de Uso de LLM y Costos

Para el MVP de FinSight AI, se espera que cada cliente genere al menos 3 informes financieros (P&L, Balance, Flujo de Caja) mensualmente, cada uno con su análisis de IA. Asumiendo un prompt detallado con datos financieros (aproximadamente 3000 tokens de entrada) y un resumen ejecutivo de la IA (aproximadamente 1000 tokens de salida) por informe:

• Tokens por informe: ~4000 tokens (3000 entrada + 1000 salida)
• Informes por cliente/mes: 3
• Clientes iniciales (MVP): 20

Total de tokens mensuales esperados: 4000 tokens/informe 3 informes/cliente * 20 clientes = 240,000 tokens/mes.

Para el cálculo, se redondeará a ~500K tokens/mes para incluir desarrollo, pruebas, retries y un pequeño margen de crecimiento.

Utilizando OpenAI GPT-4o-mini (precios al momento de la estimación: $0.15/1M tokens de entrada, $0.60/1M tokens de salida):

Costo de entrada (400K tokens): (400,000 / 1,000,000) $0.15 = $0.06 Costo de salida (100K tokens): (100,000 / 1,000,000) $0.60 = $0.06

• Costo LLM mensual estimado: ~$0.12

Aunque el costo directo de %%INLINE39%% es muy bajo, se asigna un presupuesto de $15/mes para APIs externas (principalmente OpenAI) para cubrir posibles usos de modelos más caros como %%INLINE40%% en el futuro, un mayor volumen de tokens o errores/reintentos durante el desarrollo.

2. Desglose de Costos Operativos Mensuales

Categoría	Estimación Mensual	Detalles
LLM API	$15	Presupuesto para OpenAI (mayormente %%INLINE41%% con margen para %%INLINE42%% limitado)
Cloud Hosting (EC2)	$25	Instancia AWS EC2 t3.small (o similar en GCP/Azure) para Spring Boot, incluyendo red.
Base de Datos (RDS)	$10	Instancia AWS RDS db.t3.micro PostgreSQL (o similar), incluyendo almacenamiento y I/O.
Otros Cloud	$0-5	S3 para almacenamiento de informes, DNS (Route 53), transferencia de datos mínima.
Total Estimado	$50/mes

3. Costos de Infraestructura Cloud

Se estima un costo base de infraestructura de $35/mes utilizando servicios de AWS (o equivalentes en GCP/Azure) para un MVP:

• EC2 t3.small: Aproximadamente $15/mes para la ejecución de la aplicación Spring Boot.
• RDS db.t3.micro (PostgreSQL): Aproximadamente $15/mes para la base de datos transaccional.
• Otros servicios: ~$5/mes para S3 (almacenamiento de informes), Route 53 (DNS) y transferencia de datos.

4. Costos de APIs Externas

El costo principal de APIs externas proviene del uso de modelos de lenguaje. Se presupuesta $15/mes para OpenAI, asumiendo un uso predominante de gpt-4o-mini con un buffer para experimentos o picos de uso. La API de QuickBooks no tiene costos directos por uso.

5. Ingresos Mensuales Estimados

Considerando un modelo de monetización SaaS con un precio de $25/mes por cliente y un objetivo inicial de 20 clientes para el MVP:

Ingresos mensuales estimados: 20 clientes $25/cliente = $500/mes.

6. Margen de Beneficio

• Ingresos mensuales: $500
• Costos mensuales totales: $50
• Beneficio mensual: $500 - $50 = $450

Margen de beneficio: (($500 - $50) / $500) 100 = 90%

El margen de beneficio inicial es excepcionalmente alto, lo que indica un modelo de negocio muy viable desde una perspectiva de costos operativos si se mantiene la eficiencia.

7. Optimizaciones Concretas para Reducir Costos

1. Caché de Respuestas LLM: Implementar una capa de caché robusta para los análisis de IA. Si un informe para un período específico ya ha sido generado y los datos subyacentes no han cambiado, la respuesta del LLM debe servirse desde el caché, eliminando la necesidad de una nueva llamada a la API y el costo asociado.
2. Selección de Modelo LLM Estratégica: Comenzar y priorizar el uso de modelos LLM de menor costo como %%INLINE44%% para la mayoría de las tareas de análisis. Reservar modelos más potentes (y caros) como %%INLINE45%% solo para análisis que requieran una complejidad o precisión superior, y solo si se justifica el costo adicional.
3. Prompt Engineering Eficiente: Invertir tiempo en la optimización de los prompts para que sean lo más concisos y efectivos posible, minimizando la cantidad de tokens de entrada y salida necesarios para obtener el resultado deseado.
4. Arquitectura Serverless para Carga de Trabajo Variable: Si la generación de informes es una tarea que se ejecuta de forma esporádica o en picos, migrar la lógica de procesamiento y análisis de IA a funciones serverless (ej. AWS Lambda, Google Cloud Functions). Esto permitiría pagar solo por el tiempo de cómputo real utilizado, en lugar de mantener una instancia EC2 activa 24/7.
5. Almacenamiento de Objetos para Informes: Almacenar los informes generados (ej. en formato PDF) en servicios de almacenamiento de objetos de bajo costo como AWS S3, en lugar de incrustarlos directamente en la base de datos. Esto reduce los costos de almacenamiento de la base de datos y mejora la escalabilidad.
6. Monitoreo y Alertas de Costos: Implementar herramientas de FinOps (ej. AWS Cost Explorer, GCP Billing Reports) para monitorear el gasto en la nube en tiempo real, configurar alertas para umbrales de costos y revisar periódicamente los informes de uso para identificar anomalías y oportunidades de optimización.