HAVI Score — Descripción General

El HAVI Score es el motor de análisis crediticio de la plataforma. Utiliza inteligencia artificial (MoonshotAI + OCR con Tesseract) para analizar documentos financieros y calcular el perfil crediticio de un comprador en segundos.

¿Para qué sirve?

• Portales inmobiliarios — Mostrar al agente si un comprador realmente puede pagar la propiedad
• Instituciones financieras (CILA y similares) — Pre-calificación automática antes de un crédito hipotecario
• Agencias inmobiliarias — Filtrar prospectos y enfocar esfuerzos en compradores calificados

Flujo completo

Comprador                              Backend HAVI
    │                                       │
    ├─ POST /fase1/perfil               →   Crear perfil inicial
    │                                       │
    ├─ POST /fase2/validar/:id          →   Refinar datos (ingresos, deudas, score)
    │                                       │
    ├─ (opcional) POST /onboarding/perfil → Flujo en un solo paso
    │                                       │
    ├─ GET  /matching/:id               →   Ver propiedades compatibles
    │                                       │
    └─ POST /fase3/documentar/:id       →   Documentar interés en una propiedad

HAVI Score — Escala (v2.1)

El score va de 0 a 1000. Niveles:

Rango	Nivel	Riesgo	Descripción
801 – 1000	EXCELENTE	Muy bajo	Crédito preferencial, mejores tasas
601 – 800	ALTO	Bajo	Alta probabilidad de aprobación
401 – 600	MEDIO	Moderado	Aprobación estándar / Rent to Own
0 – 400	BAJO	Alto	Requiere mejorar el perfil

Modelo de cálculo (v2.1)

El score es una suma ponderada de 6 componentes (cada uno 0–100), multiplicada ×10:

Score = round( (Ingreso×0.35 + Tipo×0.12 + Antigüedad×0.18 + Deudas×0.15 + Ahorro×0.10 + ISFH×0.10) × 10 )

Componente	Peso	Qué mide
Ingreso	35%	Ingreso mensual familiar
Antigüedad	18%	Antigüedad laboral
Deudas	15%	Ratio deuda/ingreso (sin deudas declaradas = neutral)
Tipo de ingreso	12%	Asalariado vs independiente
Ahorro	10%	Ahorro vs ingreso anual
ISFH (Salud Financiera)	10%	Ingreso disponible tras el costo de vida digno del estado y las deudas

El modelo incorpora el Factor HAVI v2, un índice de costo de vida por estado (≈0.7–1.3) que ajusta la capacidad de compra a la realidad local (ver doble valor abajo).

Respuesta del score: capacidad y salud financiera (v2.1)

Los endpoints que devuelven el score (onboarding, fase 2, GET /perfil/:id) incluyen, dentro de havi_score, dos bloques nuevos. Llaves reales (snake_case):

{
  "havi_score": {
    "score": 885,
    "nivel": "excelente",
    "capacidad_compra_estimada": {
      "valor_bancario": 4661271,
      "valor_realista": 4794117,
      "factor_havi_v2": 0.9715,
      "ltv": 0.85,
      "pago_mensual_estimado": 39621,
      "credito_max": 3962080,
      "m2_alcanzables": 193,
      "m2_minimo_nucleo": 70,
      "evaluacion_m2": "✅ Holgado",
      "enganche_requerido": 699191,
      "enganche_disponible": 702096,
      "subcuenta_infonavit_estimada": 252096,
      "estatus_enganche": "✅ ALCANZA",
      "renta_equivalente": 23971
    },
    "salud_financiera": {
      "score": 90,
      "costo_vida_digno": 29517,
      "ingreso_disponible": 39515,
      "ratio": 0.4702
    },
    "recomendaciones": ["..."],
    "disclaimer": "Score orientativo; no constituye una aprobación de crédito."
  }
}

Doble valor: Bancario vs Realista

• valor_bancario — lo que aprueba el banco (crédito ÷ LTV).
• valor_realista — ajustado al costo de vida del estado vía Factor HAVI v2 (valor_bancario × clamp(2 − factor, 0.7, 1.3)). Es el valor recomendado para mostrar al usuario.

Compatibilidad

Se conservan las llaves previas (valor_vivienda_max, credito_max, enganche_min, pago_mensual_estimado, renta_estimada). El cambio es aditivo: tu integración actual no se rompe, solo hay campos nuevos disponibles.

Base URL HAVI Score

https://api.havi.app/api/v1

Todos los endpoints de HAVI Score son públicos (no requieren autenticación) salvo los indicados.