HAVI Score — Análisis de Documentos

El módulo de análisis de documentos usa OCR (Tesseract) + MoonshotAI para extraer y validar datos financieros de documentos reales, elevando la precisión del HAVI Score.

Documentos soportados

Tipo	documentType	Qué se extrae
Estado de cuenta bancario	bank_statement	Saldo, ingresos, gastos, banco
Recibo de nómina	payslip	Salario neto, empresa, antigüedad
Identificación oficial	id_document	Nombre, CURP, vigencia
Comprobante de domicilio	proof_of_address	Dirección, vigencia
Declaración fiscal	tax_return	Ingresos anuales, deducciones

---

Subir documento para análisis

Requiere autenticación

POST /api/ai/documents/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

Form data:

• file — Archivo PDF o imagen (.pdf, .jpg, .png)
• documentType — Tipo de documento (ver tabla arriba)

Respuesta 201:

{
  "success": true,
  "data": {
    "documentId": "uuid-documento",
    "status": "processing",
    "documentType": "bank_statement",
    "message": "Documento recibido. El análisis tardará entre 5 y 30 segundos."
  }
}

---

Consultar estado del documento

GET /api/ai/documents/:documentId/status
Authorization: Bearer {token}

Respuesta cuando está procesado:

{
  "success": true,
  "data": {
    "documentId": "uuid-documento",
    "status": "processed",
    "documentType": "bank_statement",
    "extractedData": {
      "banco": "BBVA",
      "saldoActual": 45000,
      "ingresoMensual": 25000,
      "gastosMensuales": 18000,
      "periodoReportado": "Marzo 2026"
    },
    "confidence": 92,
    "haviScoreImpact": "+45 puntos",
    "processedAt": "2026-05-13T10:05:00.000Z"
  }
}

Estados posibles:

Estado	Descripción
pending	En cola de procesamiento
processing	Siendo analizado por IA
processed	Análisis completado
failed	Error en el procesamiento
rejected	Documento ilegible o inválido

---

Listar documentos del usuario

GET /api/ai/documents
Authorization: Bearer {token}

---

Ver URL del documento

GET /api/ai/documents/:documentId/url
Authorization: Bearer {token}

Devuelve una URL temporal pre-firmada para visualizar el documento en S3.

---

Eliminar documento

DELETE /api/ai/documents/:documentId
Authorization: Bearer {token}

---

Reprocesar documento

Si el análisis falló, puedes reprocesarlo:

POST /api/ai/documents/:documentId/reprocess
Authorization: Bearer {token}

---

Resumen de documentos del usuario

GET /api/ai/documents/summary
Authorization: Bearer {token}

Respuesta 200:

{
  "success": true,
  "data": {
    "totalDocuments": 3,
    "processedDocuments": 2,
    "pendingDocuments": 1,
    "haviScoreActual": 715,
    "haviScoreAnterior": 650,
    "mejora": "+65 puntos tras análisis de documentos",
    "documentsTypes": {
      "bank_statement": 1,
      "payslip": 1,
      "id_document": 1
    }
  }
}

---

Solicitar análisis completo

POST /api/ai/analysis/request
Authorization: Bearer {token}
Content-Type: application/json

{
  "documentIds": ["uuid-doc-1", "uuid-doc-2"]
}

Respuesta:

{
  "success": true,
  "data": {
    "analysisId": "uuid-analysis",
    "status": "processing",
    "estimatedSeconds": 20
  }
}

---

Consultar estado del análisis

GET /api/ai/analysis/status/:analysisId
Authorization: Bearer {token}

---

Obtener análisis del usuario

GET /api/ai/analysis
Authorization: Bearer {token}

Devuelve el análisis más reciente con el HAVI Score actualizado y recomendaciones.