HAVI Score — Onboarding y Perfiles

Estos endpoints crean y gestionan el perfil financiero de un comprador para calcular su HAVI Score.

Respuesta v2.1 — capacidad y salud financiera

La respuesta real de estos endpoints incluye el objeto havi_score con el score (0–1000), el nivel, y los bloques capacidad_compra_estimada (doble valor Bancario/Realista, m² alcanzables, enganche con subcuenta INFONAVIT) y salud_financiera (ISFH). Ver el detalle de campos y el modelo de 6 componentes en HAVI Score — Descripción General. Los campos previos se conservan (cambio aditivo).

---

Opción A — Onboarding completo en un paso

Crea el perfil completo con toda la información en una sola llamada.

POST /api/v1/onboarding/perfil
Content-Type: application/json

Body:

{
  "nombre": "Juan Pérez",
  "email": "juan@email.com",
  "telefono": "+52 55 1234 5678",
  "ingresoMensual": 35000,
  "gastosMensuales": 15000,
  "deudas": 5000,
  "empleoEstable": true,
  "antiguedadLaboral": 36,
  "presupuesto": {
    "min": 1500000,
    "max": 3000000
  },
  "tipoPropiedad": ["Departamento", "Casa"],
  "ciudadInteres": "Ciudad de México",
  "enganche": 300000
}

Respuesta 201:

{
  "status": "success",
  "data": {
    "perfilId": "uuid-perfil",
    "haviScore": 715,
    "scoreLabel": "Bueno",
    "riskLevel": "moderate",
    "creditoEstimado": 2100000,
    "mensualidadEstimada": 18500,
    "mensaje": "Tu perfil tiene buena capacidad de pago. Puedes calificar para propiedades de hasta $2,100,000 MXN.",
    "propiedadesCompatibles": 38
  }
}

---

Opción B — Flujo en dos fases

Fase 1 — Crear perfil inicial

POST /api/v1/fase1/perfil
Content-Type: application/json

Body:

{
  "nombre": "Juan Pérez",
  "email": "juan@email.com",
  "telefono": "+52 55 1234 5678",
  "presupuesto": {
    "min": 1500000,
    "max": 3000000
  },
  "ciudadInteres": "Ciudad de México"
}

Respuesta 201:

{
  "status": "success",
  "data": {
    "perfilId": "uuid-perfil",
    "etapa": "fase1_completada",
    "mensaje": "Perfil inicial creado. Continúa con la validación financiera."
  }
}

Fase 2 — Refinar perfil con datos financieros

POST /api/v1/fase2/validar/:perfilId
Content-Type: application/json

Body:

{
  "ingresoMensual": 35000,
  "gastosMensuales": 15000,
  "deudas": 5000,
  "empleoEstable": true,
  "antiguedadLaboral": 36,
  "enganche": 300000,
  "tipoPropiedad": ["Departamento"]
}

Respuesta 200:

{
  "status": "success",
  "data": {
    "perfilId": "uuid-perfil",
    "haviScore": 715,
    "scoreLabel": "Bueno",
    "riskLevel": "moderate",
    "creditoEstimado": 2100000,
    "mensualidadEstimada": 18500,
    "etapa": "calificado"
  }
}

---

Obtener perfil por ID

GET /api/v1/perfil/:perfilId

Útil para compartir resultados o retomar un perfil existente.

Respuesta 200:

{
  "status": "success",
  "data": {
    "perfilId": "uuid-perfil",
    "nombre": "Juan Pérez",
    "email": "juan@email.com",
    "haviScore": 715,
    "scoreLabel": "Bueno",
    "riskLevel": "moderate",
    "creditoEstimado": 2100000,
    "etapa": "calificado",
    "createdAt": "2026-05-13T10:00:00.000Z"
  }
}

---

Verificar si ya existe un perfil

Antes de crear un perfil nuevo, verifica si el email ya tiene uno:

POST /api/v1/perfil/verificar
Content-Type: application/json

{
  "email": "juan@email.com"
}

Respuesta si existe:

{
  "status": "success",
  "exists": true,
  "data": {
    "perfilId": "uuid-perfil",
    "haviScore": 715,
    "etapa": "calificado"
  }
}

Respuesta si no existe:

{
  "status": "success",
  "exists": false
}

---

Reclamar prospecto (para agencias)

Requiere autenticación

Solo agency_admin autenticados.

POST /api/v1/prospectos/:perfilId/reclamar
Authorization: Bearer {token}

Vincula el perfil del comprador como prospecto de tu agencia.

---

Listar prospectos de la agencia

GET /api/v1/prospectos
Authorization: Bearer {token del agency_admin}