LedgerLens API — Explainer

Concepto

LedgerLens es un microservicio SaaS B2B que automatiza el análisis de estados financieros para Pymes. Los dueños de negocio y contadores suben un PDF (Estado de Resultados, Balance General o Flujo de Caja) y en segundos reciben:

• KPIs financieros clave calculados automáticamente (margen bruto, EBITDA, ratio de endeudamiento…)
• Un resumen ejecutivo en lenguaje natural generado por IA
• Un dashboard visual con la evolución histórica de sus métricas

---

Arquitectura

┌──────────────────────────────────────────────────────────────────────┐
│                        LedgerLens API (SB 4.0.4 / Java 25)           │
│                                                                       │
│  ┌─────────────┐   ┌──────────────────┐   ┌──────────────────────┐  │
│  │AuthController│   │DocumentController│   │AnalysisController    │  │
│  │  /api/auth   │   │ /api/documents   │   │ /api/analysis/{id}   │  │
│  └──────┬───────┘   └────────┬─────────┘   └──────────┬───────────┘  │
│         │                    │                         │              │
│  ┌──────▼───────┐   ┌────────▼─────────┐   ┌──────────▼───────────┐  │
│  │  AuthService │   │  DocumentService  │   │   AnalysisService    │  │
│  │  JWT + BCrypt│   │  PDF validation   │   │   @Async VThread      │  │
│  └──────┬───────┘   └────────┬─────────┘   └──────────┬───────────┘  │
│         │                    │                         │              │
│  ┌──────▼───────────────────▼─────────────────────────▼───────────┐  │
│  │                  Spring Data JPA  (H2 dev / PostgreSQL prod)    │  │
│  │         UserRepository · DocumentRepository · AnalysisRepository│  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                       │
│  ┌────────────────────────┐   ┌──────────────────────────────────┐   │
│  │  StorageService        │   │  LlmClient (OpenFeign)           │   │
│  │  local FS / S3 prod    │   │  OpenAI-compatible endpoint      │   │
│  └────────────────────────┘   └──────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

Stack técnico

Capa	Tecnología
Runtime	Java 25 Virtual Threads
Framework	Spring Boot 4.0.4 / Spring Framework 7.x
Seguridad	Spring Security 7 + JWT (jjwt 0.12.6)
Persistencia	Spring Data JPA + H2 (dev) / PostgreSQL (prod)
HTTP Cliente	Spring Cloud OpenFeign 4.2.1
JSON	Jackson 3.x (tools.jackson.*)
Almacenamiento	Simulado con FS local (prod: AWS S3)

---

Flujo de procesamiento

1. POST /api/auth/register  →  Crea usuario + JWT
2. POST /api/documents/upload (multipart/form-data)
      → valida PDF
      → StorageService.store() → /tmp/ledger-lens/…
      → Document{status=PENDING} guardado en BD
      → analysisService.analyzeDocument(id) disparado async
3. @Async VirtualThread (AnalysisService)
      → status = PROCESSING
      → mock mode: simula KPIs deterministas basados en doc.id
      → real mode: llama LlmClient → OpenAI GPT-4o
      → Analysis{ kpis + summary } guardado en BD
      → status = COMPLETED
4. GET /api/analysis/{documentId}  →  AnalysisResponse (202 si aún procesa)
5. GET /api/dashboard/metrics      →  DashboardMetrics (aggregados + serie temporal)

---

Endpoints

Autenticación

Método	Path	Auth	Body	Respuesta
%%INLINE1%%	%%INLINE2%%	No	%%INLINE3%%	%%INLINE4%%
%%INLINE5%%	%%INLINE6%%	No	%%INLINE7%%	%%INLINE8%%

Documentos

Método	Path	Auth	Descripción
%%INLINE9%%	%%INLINE10%%	JWT	Sube PDF + dispara análisis async
%%INLINE11%%	%%INLINE12%%	JWT	Lista documentos del usuario

Análisis

Método	Path	Auth	Descripción
%%INLINE13%%	%%INLINE14%%	JWT	Devuelve análisis completo con KPIs

Dashboard

Método	Path	Auth	Descripción
%%INLINE15%%	%%INLINE16%%	JWT	KPIs agregados + evolución temporal

---

DTOs clave

AnalysisResponse

{
  "analysisId": 1,
  "documentId": 1,
  "fileName": "estado_resultados_2025.pdf",
  "documentType": "INCOME_STATEMENT",
  "kpis": {
    "grossMarginPct": 45.2,
    "ebitdaPct": 18.7,
    "debtEquityRatio": 0.8,
    "currentRatio": 1.9,
    "netProfitMarginPct": 12.3
  },
  "executiveSummary": "## Executive Summary...",
  "analyzedAt": "2026-06-20T10:30:00"
}

DashboardMetrics

{
  "totalAnalyses": 5,
  "avgGrossMarginPct": 43.1,
  "avgEbitdaPct": 17.2,
  "avgDebtEquityRatio": 0.9,
  "avgCurrentRatio": 1.8,
  "avgNetProfitPct": 11.5,
  "lastAnalyzedAt": "2026-06-20T10:30:00",
  "evolution": [
    { "date": "2026-05-01", "grossMarginPct": 41.0, "netProfitMarginPct": 10.2 },
    { "date": "2026-06-01", "grossMarginPct": 45.2, "netProfitMarginPct": 12.3 }
  ]
}

---

KPIs financieros calculados

KPI	Descripción	Rango saludable
Gross Margin %	(Ventas - COGS) / Ventas × 100	> 40% sector servicio
EBITDA %	EBITDA / Ventas × 100	> 15%
Debt-to-Equity	Deuda Total / Patrimonio	< 1.5
Current Ratio	Activos Corrientes / Pasivos Corrientes	> 1.2
Net Profit Margin %	Beneficio Neto / Ventas × 100	> 8%

---

Cómo ejecutar

Requisitos

• JDK 25+
• Maven 3.9+

Modo desarrollo (H2 in-memory, LLM mock)

cd solutions/2026-06-20-ledger-lens-api
mvn clean spring-boot:run

La API arranca en http://localhost:8080. No se requiere PostgreSQL ni clave de LLM — todo funciona en mock mode.

Con PostgreSQL real

export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/ledgerlens
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=secret
export SPRING_JPA_HIBERNATE_DDL_AUTO=update
mvn spring-boot:run

Con LLM real (OpenAI)

export LEDGER_LLM_API_KEY=sk-...
export LEDGER_LLM_MOCK_MODE=false
export LEDGER_LLM_MODEL=gpt-4o
mvn spring-boot:run

Ejemplo rápido con curl

# 1. Registrar usuario
curl -s -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ana García","email":"ana@pyme.com","password":"secreta123"}' | jq .

# 2. Login (guarda el token)
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ana@pyme.com","password":"secreta123"}' | jq -r .token)

# 3. Subir documento PDF
curl -s -X POST http://localhost:8080/api/documents/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/ruta/estado_resultados.pdf" \
  -F "documentType=INCOME_STATEMENT" | jq .

# 4. Obtener análisis (esperar ~1s a que el async complete)
curl -s http://localhost:8080/api/analysis/1 \
  -H "Authorization: Bearer $TOKEN" | jq .

# 5. Dashboard
curl -s http://localhost:8080/api/dashboard/metrics \
  -H "Authorization: Bearer $TOKEN" | jq .

---

Análisis de Negocio

Problema

Las Pymes invierten 4-8 horas/mes en análisis manual de estados financieros, propenso a errores y requiere experiencia financiera que muchos emprendedores no poseen.

Solución LedgerLens

Convierte ese proceso en segundos mediante IA, democratizando el análisis financiero profesional.

Modelo de monetización

Plan	Precio	Análisis/mes	Features
Free	$0	2	KPIs básicos + resumen
Starter	$29/mes	20	+ historiales + comparativas
Pro	$99/mes	Ilimitado	+ proyecciones + benchmarks sectoriales

TAM / Mercado objetivo

• 4.5 millones de Pymes en España → 12% con necesidades de análisis financiero recurrente → 540,000 clientes potenciales
• LTV estimado Starter: $29 × 12 × 2 años = $696
• CAC objetivo: < $50 (marketing de contenido + SEO financiero)

Ventaja competitiva

• Velocidad: segundos vs. horas de análisis manual
• Precio: fracción del coste de un analista/consultor
• Privacidad: datos encriptados, nunca usados para entrenar modelos
• API-first: integrable con ERPs y plataformas contables existentes

---

Referencias

• Fintech AI Automation 2026
• Spring Boot 4.0 Documentation
• Spring Security 7 Reference
• Java 25 Virtual Threads (JEP 444)
• jjwt 0.12.x Migration Guide

---

Análisis FinOps para LedgerLens

Estimación de Costos Operativos Mensuales

Para LedgerLens, una micro-startup de IA en el sector financiero, los costos operativos se dividen principalmente entre el uso del modelo de lenguaje (LLM) y la infraestructura cloud.

1. Estimación de Tokens LLM

Basándonos en un modelo de uso inicial para una micro-startup, asumimos lo siguiente:

• Volumen de documentos: 20 clientes Starter (promedio de 5 documentos/mes por cliente) + 30 usuarios Freemium (promedio de 1 documento/mes por usuario) = 100 + 30 = 130 documentos/mes.
• Tokens por documento: Estimamos un promedio de 7,000 tokens por documento procesado (500 prompt + 5,000 texto de entrada + 1,500 salida de resumen/JSON).

Total de Tokens Mensuales: 130 documentos 7,000 tokens/documento = ~910,000 tokens/mes. Redondeamos a ~1M tokens/mes para incluir un pequeño buffer.

2. Desglose de Costos Mensuales

Categoría	Detalle	Costo Estimado Mensual
LLM (OpenAI)	gpt-4-turbo (800k Input, 200k Output)	$14
Cloud Hosting (AWS)	EC2 t3.small (Compute)	$25
S3 (Almacenamiento, Egress) & Network	$5
Base de Datos (AWS)	RDS PostgreSQL db.t3.micro	$18
Total Costos Mensuales	$62

* Cálculo de LLM: Utilizando gpt-4-turbo (Input: $10/M tokens, Output: $30/M tokens): Input: (800,000 / 1,000,000) $10 = $8 Output: (200,000 / 1,000,000) $30 = $6 * Total LLM: $14/mes

Estimación de Ingresos Mensuales

El modelo de monetización es B2B SaaS freemium. Para la fase inicial de micro-startup, asumimos:

• Plan Starter: $25/mes (10-15 análisis/mes)
• Clientes Pagos: 20 clientes suscritos al plan Starter.

Ingreso Mensual Estimado: 20 clientes * $25/cliente = $500/mes.

Cálculo del Margen de Beneficio

• Ingresos Mensuales: $500
• Costos Operativos Mensuales: $62

Beneficio Bruto: $500 - $62 = $438

Margen de Beneficio: (($438 / $500) * 100) = 87.6% (redondeado a 88%)

El alto margen de beneficio inicial es característico de micro-startups SaaS con una infraestructura lean y un costo unitario de IA relativamente bajo en comparación con el valor percibido por el cliente.

Optimizaciones FinOps Clave

Para mantener y mejorar este margen a medida que LedgerLens escala, se recomiendan las siguientes optimizaciones FinOps:

1. Optimización del Uso de LLM:

* Caché Inteligente: Implementar un sistema de caché para las respuestas del LLM. Si un documento o una sección específica ya ha sido analizada y los resultados son idénticos o muy similares, se puede servir la respuesta desde la caché, ahorrando tokens. * Modelos Híbridos: Utilizar modelos LLM más económicos (ej. %%INLINE24%% o %%INLINE25%%) para tareas de pre-procesamiento o análisis menos críticos, y reservar gpt-4-turbo para la generación del resumen ejecutivo final o para análisis que requieran mayor precisión. * Ingeniería de Prompts: Refinar continuamente los prompts para que sean más eficientes, reduciendo la cantidad de tokens de entrada y guiando al LLM a generar respuestas más concisas, disminuyendo los tokens de salida.

1. Optimización de Infraestructura Cloud:

* Serverless para Procesamiento Asíncrono: Migrar el %%INLINE27%% (que es %%INLINE28%%) a una función serverless (ej. AWS Lambda). Esto permitiría pagar solo por el tiempo de computación exacto durante el procesamiento de cada documento, eliminando el costo de una instancia EC2 siempre activa para tareas intermitentes. * Right-Sizing Continuo: Utilizar herramientas de monitoreo para asegurar que las instancias de EC2 y RDS estén dimensionadas correctamente para la carga de trabajo real, escalando hacia abajo si se encuentran sobreprovisionadas. * Planes de Ahorro/Instancias Reservadas: A medida que el uso se estabilice, considerar la compra de Savings Plans o instancias reservadas en AWS para obtener descuentos significativos en la computación y la base de datos. * Políticas de Retención de Datos: Implementar políticas claras para la eliminación automática de documentos y análisis antiguos de S3 y PostgreSQL que ya no sean necesarios, reduciendo los costos de almacenamiento a largo plazo.

1. Monitoreo y Alertas de Costos:

* Configurar alertas en la consola de AWS (o proveedor cloud) para notificar si los costos superan ciertos umbrales, permitiendo una acción proactiva para evitar gastos inesperados.