HIR Casa — Financiamiento Inmobiliario
Precalificador de crédito: de un expediente de Embajadores a un veredicto de riesgo, pasando por extracción de estados de cuenta, motor de políticas y un modelo de machine learning.
Cuatro servicios independientes, cada uno con una responsabilidad -- así entra un expediente y sale un veredicto.
Persiste el Proceso, extrae y clasifica ingresos, orquesta todo lo demás
Manual de Políticas de Crédito v3.1 -- PTI/DTI, segmentación H1–H4
Regresión logística -- probabilidad de morosidad, Flex y Tradicional
Usuario1 (link directo) / Usuario2 (backlog) / Admin -- revisa, corrige, descarga el resultado
POST /api/v1/embajadores/solicitud -- persona + nombre/correo del ejecutor. Sin autenticación (a propósito, es sistema-a-sistema, protegido solo por firewall).
api1 regresa la URL de simple.html con un token de un solo Proceso -- sin esperar a que termine el análisis.
api1 llama a la API de Embajadores, obtiene Solicitud + Estados de Cuenta reales de esa persona.
Motor determinístico primero, IA como respaldo -- cada archivo se pinta en el kanban en cuanto termina, no hasta que acaben todos.
Usuario1 entra directo con el link (sin login); Usuario2 lo ve en su backlog. Ambos pueden arrastrar depósitos entre columnas si la IA se equivocó.
Buró (api1) → Motor de Políticas (api2) → Modelo ML (api3), en ese orden, disparada desde el navegador.
Se descarga el Excel con el veredicto y se manda un correo (una sola vez por Proceso) avisando que el prospecto está listo para revisar.
Los que importan para el flujo real en negrita en la descripción; los marcados _dev son herramientas de prueba, no producción.
| Método | Ruta | Para qué |
|---|---|---|
| POST | /api/v1/embajadores/solicitud | Entrada real desde Embajadores -- crea el Proceso, regresa la URL al instante, analiza en segundo plano |
| GET | /api/v1/procesos | Lista de Procesos (backlog de Usuario2) |
| GET | /api/v1/procesos/{id} | Detalle de un Proceso |
| POST | /api/v1/procesos/suelto | Crea Proceso para la herramienta suelta (estados-cuenta.html) |
| POST | /api/v1/procesos/{id}/archivos/{id}/reescanear | Reanaliza un Estado de Cuenta con más contexto |
| GET | /api/v1/procesos/{id}/archivos/{id}/descargar | Descarga el PDF original guardado |
| POST | /api/v1/procesos/{id}/comentarios | Comentario libre sobre el Proceso |
| POST | /api/v1/procesos/{id}/correcciones | Registra reclasificaciones manuales (auditoría IA vs. usuario) |
| POST | /api/v1/procesos/{id}/notificar-usuario2 | Dispara el correo de "prospecto listo" |
| POST | /api/v1/ingresos/analizar | Extracción de Estados de Cuenta -- motor determinístico o IA |
| POST | /api/v1/ingresos/persistir | Guarda un análisis ya hecho por el frontend |
| POST | /api/v1/clasificacion/persistir | Guarda la clasificación final (tras orquestación) |
| POST | /api/v1/buro/consultar-api | Consulta Buró vía facade BPR Casa (reporte ya existente) |
| POST | /api/v1/solicitud/analizar | Extrae datos de un PDF de Solicitud subido a mano |
| POST | /api/v1/buro/analizar | Extrae datos de un PDF de reporte de Buró subido a mano |
| GET | /api/v1/admin/procesos | Panel de administración -- todos los Procesos, solo lectura |
| GET | /api/v1/admin/monitoreo/veredictos | Veredictos para el monitoreo de modelos (Airflow) |
| POST | /api/v1/_dev/simular-embajadores | Simula el expediente de Embajadores con un JSON de prueba |
| DEL | /api/v1/_dev/cache/{tipo} | Vacía la caché de análisis (forzar reanálisis real) |
| Método | Ruta | Para qué |
|---|---|---|
| POST | /api/v1/policy/evaluate | Aplica el Manual de Políticas -- recibe Buró+Solicitud, regresa segmento y decisión |
| GET | /api/v1/policy/config | Thresholds vigentes (para mostrar "límite vs. valor" en UI) |
| GET | /api/v1/policy/version | Versión del Manual aplicada |
| Método | Ruta | Para qué |
|---|---|---|
| POST | /predecir/ | Corre el modelo ML -- regresa probabilidad, clasificación y monto para Flex y Tradicional |
Los schemas reales (Pydantic) de los 4 endpoints que conectan los servicios entre sí -- campo por campo, tal cual están en el código. Clic para expandir cada uno.
| Campo | Tipo | Notas |
|---|---|---|
| persona | string | UUID de la persona en Embajadores |
| nombre_ejecutor | string | Quién del lado de Embajadores disparó la consulta (auditoría) |
| correo_ejecutor | ||
| (campos extra) | libre | Acepta cualquier campo adicional -- el resto del contrato de Embajadores aún no está confirmado por su equipo, se guarda tal cual |
| Campo | Tipo | Notas |
|---|---|---|
| process_id | string | |
| token | string | Token de un solo Proceso, para entrar sin login |
| url | string | URL de simple.html para el Comercial (Usuario1) |
Obtiene un reporte de Buró YA EXISTENTE por RFC (nunca dispara una consulta nueva) -- regresa en una sola respuesta todo lo que después necesitan tanto api2 como api3.
| Campo | Tipo | Notas |
|---|---|---|
| process_id | string? | Del paso anterior -- ancla el Proceso completo |
| rfc | string |
| Campo | Tipo | Notas |
|---|---|---|
| raw.formato_detectado | enum | institucional | especial | api_real -- 2 layouts distintos según quién consultó |
| raw.nombre_completo / rfc / fecha_nacimiento / score | mixto | score solo en formato institucional |
| raw.mensajes_prevencion[] | lista | PLD | OFAC | PEP | fraude | juicio |
| raw.cuentas[] | lista | Cada línea tal cual aparece en el reporte, sin calcular nada (otorgante, saldo, monto vencido, fechas, clave_observacion...) |
| indicadores | objeto | Mismo cálculo determinístico que ya se usa para reportes en PDF/OCR -- de aquí salen varios de los campos que luego arma buro_credito para api2 |
| score_buro_credito | objeto | Ya en la forma que espera api3 (ScoreBuro): nombreScore, CodigoScore, ValorScore, CodigoRazon, MontoPagar... |
| resumen_reporte | objeto | Ya en la forma ResumenReportePrediccion de api3 (conteos de MOP, cuentas, fechas) |
| cuentas_prediccion | lista | Ya en la forma CuentasPrediccion de api3 (totales revolventes/pagos fijos) |
| Campo | Tipo | Notas |
|---|---|---|
| solicitud.cliente_id | string | |
| solicitud.producto | "tradicional" | "flex" | |
| solicitud.monto_solicitado | float | MXN, > 0 |
| solicitud.ingreso_mensual_verificado | float | MXN -- el YA verificado con estados de cuenta, no el reportado |
| solicitud.antiguedad_laboral_meses | int | |
| solicitud.canal / sucursal_id | string? | Opcionales, solo auditoría |
| buro_credito.score | int | 300–850 |
| buro_credito.fraude_comprobado | bool | MOP99 en alguna cuenta -- rechazo automático |
| buro_credito.quebranto_hipotecario | bool | MOP>3 en cuenta hipotecaria -- rechazo automático |
| buro_credito.mop_maximo_global | int | 0–99 |
| buro_credito.mop_maximo_hipotecario | int | 0–99 |
| buro_credito.saldo_vencido_total | float | Suma en TODAS las líneas (MXN) |
| buro_credito.porcentaje_lineas_atrasadas | float | 0–100 |
| buro_credito.numero_lineas_activas | int | |
| buro_credito.numero_lineas_atrasadas | int | MOP ≥ 2 |
| buro_credito.atrasos_count_30d_12m | int | |
| buro_credito.max_dias_atraso_12m | int | |
| buro_credito.mensualidad_buro_total | float | Para el cálculo de DTI |
| buro_credito.deuda_vigente_pesos | float | Tope de 8000 UDIs |
| Campo | Tipo | Notas |
|---|---|---|
| cliente_id, evaluacion_id, evaluado_en | string / uuid / datetime | |
| version_politica, institucion | string | |
| decision | enum | APROBADO | APROBADO_CON_CONDICIONES | COMITE | RECHAZADO |
| segmento.codigo / titulo / descripcion / razones / referencia_manual | objeto | null | Null si hard checks rechazó |
| score_rating.score / rating / color | objeto | Informativo -- NO determina el segmento |
| hard_checks.aprobado / violaciones[] | objeto | |
| indicadores_financieros.pti / dti | objeto | {valor, limite, en_regla, excedente} cada uno |
| indicadores_financieros.mensualidad_inicial / ingresos_requeridos / requiere_comite_por_excedente | float / float / bool | |
| condiciones.requiere_obligado_solidario / requiere_cotitular / requiere_comite_credito / requiere_aclaracion_buro / razones_condiciones[] | bool×4 / string[] | |
| snapshot_input | dict | Echo completo del request, para auditoría/reproducibilidad |
| Campo | Tipo | Notas |
|---|---|---|
| Solicitud.MontoContratado | float | |
| Prospecto.ProspectoId / FechaNacimiento / EstadoCivil / NumeroDependientes / Egreso / TipoVivienda / Pais | mixto | |
| Prospecto.GradoEstudio | enum | PRIMARIA | SECUNDARIA | MEDIO_SUPERIOR | TÉCNICO | LICENCIATURA_POSGRADO | NINGUNA_DE_LAS_ANTERIORES |
| Prospecto.SegmentoPolitica | "H1"|"H2"|"H3"|"H4" | Viene de la respuesta de api2 |
| Ingresos[].TipoIngreso / Giro / Puesto / MontoIngreso / AntiguedadAnio | lista de objetos | Uno por fuente de ingreso |
| ConsultaBuroCredito.FechaConsulta / ScoreBuroCredito / Cuentas[] | objeto | |
| ConsultaBuroCredito.ResumenReporte | objeto | ~25 campos -- conteos de MOP0-99, cuentas abiertas/cerradas/negativas, fechas de apertura, solicitudes recientes, etc. |
| Campo | Tipo | Notas |
|---|---|---|
| ProspectoId | string (acepta también int) | |
| probabilidadFlex / probabilidadTradicional | float | Probabilidad de morosidad, 0–1 |
| resultadoFlex / resultadoTradicional | int | 0 o 1, según threshold del modelo |
| MontoOtorgadoFlex / MontoOtorgadoTradicional | float | Hoy siempre = monto solicitado (ver nota en sección 4) |
| ClasificacionModeloFlex / ClasificacionModeloTradicional | string | Bajo | Medio | Moderado | Alto | Extremo |
| RecomendacionesFlex / RecomendacionesTradicional | dict |
Cada regla con su fuente y su valor tal cual está en el código hoy -- para que se pueda validar contra el Manual directamente.
tope_renta_efectivo_mxn, Manual secc. 12) está declarado en la configuración pero no se usa en ningún cálculo real -- documentado, no implementado.
Extracción: se intenta primero el motor determinístico (sin IA, lee texto+coordenadas del PDF y concilia contra el total que el banco declara en su resumen). Si el banco no tiene adaptador o no concilia, cae a IA (OpenAI/Anthropic) como respaldo.
| Bancos con motor determinístico (9) | BBVA México, Banamex MiCuenta, Kapital Cuenta Enlace, Inbursa, Mercado Pago, Nu, Bank of America, Citibank/Citigold, Santander México (incl. OCR) |
|---|
Reglas aplicadas por transacción, después de extraer:
| Regla | Valor |
|---|---|
| Efectivo sin comprobante recurrente | se cuenta solo el 60% |
| Conceptos excluidos (override, van a "no laboral") | pensión alimenticia, inversión, préstamo, devolución, beca, traspaso entre cuentas propias |
| Tolerancia de reconciliación vs. total declarado por el banco | ± $1.00 MXN |
Consolidación (varios archivos = varios meses):
Mensualidad inicial (base de PTI y DTI):
| Producto | PTI máx | DTI máx | Coef. adjudicación | Capacidad de pago |
|---|---|---|---|---|
| Tradicional | 28.6% | 40.0% | 1.0× | 3.5× |
| Flex | 33.3% | 45.5% | 1.4× | 3.0× |
Segmentación H1–H4 (solo si pasa hard checks -- fraude/quebranto hipotecario rechazan directo):
| Segmento | Criterio principal | Decisión resultante |
|---|---|---|
| H1 — Óptimo | Saldo vencido ≤ $15,000 · ≤20% líneas atrasadas · MOP ≤ 02 | APROBADO |
| H2 — Viable con validación | Saldo vencido ≤ $250,000 · ≤40% líneas atrasadas | APROBADO_CON_CONDICIONES |
| H3 — Evaluación profunda | Saldo vencido ≤ $500,000 · ≤60% líneas atrasadas | COMITE |
| H4 — Rechazo | Saldo vencido > $500,000 · ≥75% líneas atrasadas · ≥179 días de atraso | RECHAZADO |
Si el PTI o el DTI se exceden del límite de su producto, se agrega el condicionante "requiere Comité de Crédito" sin importar el segmento -- puede subir un H1 o H2 a Comité aunque el Buró se vea bien.
MontoOtorgado siempre regresa el monto solicitado, sin ningún ajuste.
Regresión logística entrenada por producto, predice la probabilidad de morosidad (el frontend muestra su complemento, la probabilidad de pago).
| Producto | Factor (tasaFactor) |
|---|---|
| Flex | 9.9 |
| Tradicional | 11.0 |
| Banda de riesgo | Rango de probabilidad |
|---|---|
| Bajo | < 0.20 |
| Medio | 0.20 – 0.39 |
| Moderado | 0.40 – 0.59 |
| Alto | 0.60 – 0.79 |
| Extremo | ≥ 0.80 |
Cuatro sistemas externos, ninguno construido desde cero por este equipo.
Extracción de estados de cuenta cuando el banco no tiene motor determinístico
Consulta reportes de Buró ya generados, vía APIM con OAuth
Trae Solicitud + Estados de Cuenta reales de cada prospecto
Un correo a Usuario2 cuando un prospecto queda listo para revisar
Lo más urgente hoy: identidad real de usuario.
Usuario2 y Admin hoy son "quien sepa una clave compartida" (API_SHARED_KEY / ADMIN_API_KEY), no cuentas individuales.
Checklist completo ya armado (App Registration ×3 ambientes, roles Admin/Analista, Easy Auth, validate-jwt en APIM) -- bloqueado en acciones del administrador de Azure.
validate-jwt en APIMAPIM ya está enfrente de las 3 APIs, pero hoy no exige ningún token -- las URLs son alcanzables sin autenticación real.
Todo vive en services/frontend, HTML/JS plano -- hoy el "rol" es literalmente cuál clave te sabes. La columna de la derecha es el rol que le tocaría con Entra ID (ver sección 6).
| Pantalla | Ruta | Qué hace | Acceso hoy | Rol futuro |
|---|---|---|---|---|
| index.html | / | Selector -- lleva a Precalificación o Estados de Cuenta | Ninguno | Ninguno |
| simple.html | /precalificacion | Usuario1: entra con el link que manda Embajadores, revisa/corrige un Proceso puntual. Usuario2: ve el backlog completo, elige sobre cuál Proceso trabajar. |
Usuario1: token de Proceso en la URL (sin clave) Usuario2: X-API-Key (API_SHARED_KEY) |
Usuario1: sin cambio (exento de SSO) Usuario2: Analista |
| estados-cuenta.html | /estados-cuenta | Herramienta suelta -- analizar Estados de Cuenta sin depender de un Proceso de Embajadores | X-API-Key (API_SHARED_KEY) |
Analista |
| admin.html | /admin.html | Panel de administración -- todos los Procesos del sistema, resultados y comentarios, solo lectura. No aparece en el selector a propósito. | X-Admin-Key (ADMIN_API_KEY, clave separada) |
Admin |
| harness-tecnico.html | /harness-tecnico.html | El flujo técnico de 4 pasos original (Solicitud → Estados de Cuenta → Buró → Política/ML) -- ya no es la pantalla por defecto, se conserva sin enlazar | X-API-Key |
— |
| dev-simular-embajadores.html | /dev-simular-embajadores.html | Solo dev -- simula el expediente de Embajadores para probar el pipeline completo sin depender de un caso real | X-API-Key (algunos botones no la piden) |
— |
| arquitectura-preca.html | /arquitectura-preca.html | Este documento -- enlazado discretamente desde el selector | Ninguno | Ninguno |
Nada exótico -- herramientas estándar, elegidas por lo que cada parte necesitaba resolver.