HIR Casa — Financiamiento Inmobiliario

Cómo se construyó PRECA, y qué le falta para ser una solución formal

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.

4servicios
9bancos con extracción sin IA
3ambientes en Azure (dev / qa / prod)
01

Cómo está construido

Cuatro servicios independientes, cada uno con una responsabilidad -- así entra un expediente y sale un veredicto.

EmbajadoresManda el expediente (Solicitud + Estados de Cuenta)
OpenAI / AnthropicExtrae depósitos cuando no hay motor determinístico para ese banco
Buró Facade (BPR Casa)Consulta un reporte de Buró YA existente por RFC
api1 Solicitud + Estados de Cuenta

Persiste el Proceso, extrae y clasifica ingresos, orquesta todo lo demás

api2 Motor de Políticas

Manual de Políticas de Crédito v3.1 -- PTI/DTI, segmentación H1–H4

api3 Modelo ML

Regresión logística -- probabilidad de morosidad, Flex y Tradicional

Frontend

Usuario1 (link directo) / Usuario2 (backlog) / Admin -- revisa, corrige, descarga el resultado

Flujo paso a paso: de Embajadores al resultado

1
Embajadores manda el expediente

POST /api/v1/embajadores/solicitud -- persona + nombre/correo del ejecutor. Sin autenticación (a propósito, es sistema-a-sistema, protegido solo por firewall).

2
El Proceso se crea y la URL sale al instante

api1 regresa la URL de simple.html con un token de un solo Proceso -- sin esperar a que termine el análisis.

3
En segundo plano: se trae el expediente real

api1 llama a la API de Embajadores, obtiene Solicitud + Estados de Cuenta reales de esa persona.

4
Estados de Cuenta se analizan uno por uno

Motor determinístico primero, IA como respaldo -- cada archivo se pinta en el kanban en cuanto termina, no hasta que acaben todos.

5
Usuario1 o Usuario2 revisa y corrige

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ó.

6
Al pedir el resultado: orquestación completa

Buró (api1) → Motor de Políticas (api2) → Modelo ML (api3), en ese orden, disparada desde el navegador.

7
Resultado + aviso a Usuario2

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.

02

Endpoints

Los que importan para el flujo real en negrita en la descripción; los marcados _dev son herramientas de prueba, no producción.

api1 bank-statement-income-service

MétodoRutaPara qué
POST/api/v1/embajadores/solicitudEntrada real desde Embajadores -- crea el Proceso, regresa la URL al instante, analiza en segundo plano
GET/api/v1/procesosLista de Procesos (backlog de Usuario2)
GET/api/v1/procesos/{id}Detalle de un Proceso
POST/api/v1/procesos/sueltoCrea Proceso para la herramienta suelta (estados-cuenta.html)
POST/api/v1/procesos/{id}/archivos/{id}/reescanearReanaliza un Estado de Cuenta con más contexto
GET/api/v1/procesos/{id}/archivos/{id}/descargarDescarga el PDF original guardado
POST/api/v1/procesos/{id}/comentariosComentario libre sobre el Proceso
POST/api/v1/procesos/{id}/correccionesRegistra reclasificaciones manuales (auditoría IA vs. usuario)
POST/api/v1/procesos/{id}/notificar-usuario2Dispara el correo de "prospecto listo"
POST/api/v1/ingresos/analizarExtracción de Estados de Cuenta -- motor determinístico o IA
POST/api/v1/ingresos/persistirGuarda un análisis ya hecho por el frontend
POST/api/v1/clasificacion/persistirGuarda la clasificación final (tras orquestación)
POST/api/v1/buro/consultar-apiConsulta Buró vía facade BPR Casa (reporte ya existente)
POST/api/v1/solicitud/analizarExtrae datos de un PDF de Solicitud subido a mano
POST/api/v1/buro/analizarExtrae datos de un PDF de reporte de Buró subido a mano
GET/api/v1/admin/procesosPanel de administración -- todos los Procesos, solo lectura
GET/api/v1/admin/monitoreo/veredictosVeredictos para el monitoreo de modelos (Airflow)
POST/api/v1/_dev/simular-embajadoresSimula 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)

api2 credit-policy-engine

MétodoRutaPara qué
POST/api/v1/policy/evaluateAplica el Manual de Políticas -- recibe Buró+Solicitud, regresa segmento y decisión
GET/api/v1/policy/configThresholds vigentes (para mostrar "límite vs. valor" en UI)
GET/api/v1/policy/versionVersión del Manual aplicada

api3 API de Predicción

MétodoRutaPara qué
POST/predecir/Corre el modelo ML -- regresa probabilidad, clasificación y monto para Flex y Tradicional
03

Contratos de datos

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.

Embajadores → api1 POST /api/v1/embajadores/solicitud

Request — SolicitudEmbajadores

CampoTipoNotas
personastringUUID de la persona en Embajadores
nombre_ejecutorstringQuién del lado de Embajadores disparó la consulta (auditoría)
correo_ejecutoremail
(campos extra)libreAcepta cualquier campo adicional -- el resto del contrato de Embajadores aún no está confirmado por su equipo, se guarda tal cual

Response — RespuestaSesionEmbajadores

CampoTipoNotas
process_idstring
tokenstringToken de un solo Proceso, para entrar sin login
urlstringURL de simple.html para el Comercial (Usuario1)
api1 → Buró Facade (BPR Casa) POST /api/v1/buro/consultar-api

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.

Request — SolicitudReporteBuro

CampoTipoNotas
process_idstring?Del paso anterior -- ancla el Proceso completo
rfcstring

Response — dict combinado (raw + indicadores + 2 formatos ya listos para api2/api3)

CampoTipoNotas
raw.formato_detectadoenuminstitucional | especial | api_real -- 2 layouts distintos según quién consultó
raw.nombre_completo / rfc / fecha_nacimiento / scoremixtoscore solo en formato institucional
raw.mensajes_prevencion[]listaPLD | OFAC | PEP | fraude | juicio
raw.cuentas[]listaCada línea tal cual aparece en el reporte, sin calcular nada (otorgante, saldo, monto vencido, fechas, clave_observacion...)
indicadoresobjetoMismo 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_creditoobjetoYa en la forma que espera api3 (ScoreBuro): nombreScore, CodigoScore, ValorScore, CodigoRazon, MontoPagar...
resumen_reporteobjetoYa en la forma ResumenReportePrediccion de api3 (conteos de MOP, cuentas, fechas)
cuentas_prediccionlistaYa en la forma CuentasPrediccion de api3 (totales revolventes/pagos fijos)
api1 → api2 POST /api/v1/policy/evaluate

Request — SolicitudEvaluacion

CampoTipoNotas
solicitud.cliente_idstring
solicitud.producto"tradicional" | "flex"
solicitud.monto_solicitadofloatMXN, > 0
solicitud.ingreso_mensual_verificadofloatMXN -- el YA verificado con estados de cuenta, no el reportado
solicitud.antiguedad_laboral_mesesint
solicitud.canal / sucursal_idstring?Opcionales, solo auditoría
buro_credito.scoreint300–850
buro_credito.fraude_comprobadoboolMOP99 en alguna cuenta -- rechazo automático
buro_credito.quebranto_hipotecarioboolMOP>3 en cuenta hipotecaria -- rechazo automático
buro_credito.mop_maximo_globalint0–99
buro_credito.mop_maximo_hipotecarioint0–99
buro_credito.saldo_vencido_totalfloatSuma en TODAS las líneas (MXN)
buro_credito.porcentaje_lineas_atrasadasfloat0–100
buro_credito.numero_lineas_activasint
buro_credito.numero_lineas_atrasadasintMOP ≥ 2
buro_credito.atrasos_count_30d_12mint
buro_credito.max_dias_atraso_12mint
buro_credito.mensualidad_buro_totalfloatPara el cálculo de DTI
buro_credito.deuda_vigente_pesosfloatTope de 8000 UDIs

Response — EvaluacionResultado

CampoTipoNotas
cliente_id, evaluacion_id, evaluado_enstring / uuid / datetime
version_politica, institucionstring
decisionenumAPROBADO | APROBADO_CON_CONDICIONES | COMITE | RECHAZADO
segmento.codigo / titulo / descripcion / razones / referencia_manualobjeto | nullNull si hard checks rechazó
score_rating.score / rating / colorobjetoInformativo -- NO determina el segmento
hard_checks.aprobado / violaciones[]objeto
indicadores_financieros.pti / dtiobjeto{valor, limite, en_regla, excedente} cada uno
indicadores_financieros.mensualidad_inicial / ingresos_requeridos / requiere_comite_por_excedentefloat / float / bool
condiciones.requiere_obligado_solidario / requiere_cotitular / requiere_comite_credito / requiere_aclaracion_buro / razones_condiciones[]bool×4 / string[]
snapshot_inputdictEcho completo del request, para auditoría/reproducibilidad
api1 → api3 POST /predecir/

Request — DatosCliente

CampoTipoNotas
Solicitud.MontoContratadofloat
Prospecto.ProspectoId / FechaNacimiento / EstadoCivil / NumeroDependientes / Egreso / TipoVivienda / Paismixto
Prospecto.GradoEstudioenumPRIMARIA | 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 / AntiguedadAniolista de objetosUno por fuente de ingreso
ConsultaBuroCredito.FechaConsulta / ScoreBuroCredito / Cuentas[]objeto
ConsultaBuroCredito.ResumenReporteobjeto~25 campos -- conteos de MOP0-99, cuentas abiertas/cerradas/negativas, fechas de apertura, solicitudes recientes, etc.

Response — dict (no hay un schema Pydantic formal en el endpoint)

CampoTipoNotas
ProspectoIdstring (acepta también int)
probabilidadFlex / probabilidadTradicionalfloatProbabilidad de morosidad, 0–1
resultadoFlex / resultadoTradicionalint0 o 1, según threshold del modelo
MontoOtorgadoFlex / MontoOtorgadoTradicionalfloatHoy siempre = monto solicitado (ver nota en sección 4)
ClasificacionModeloFlex / ClasificacionModeloTradicionalstringBajo | Medio | Moderado | Alto | Extremo
RecomendacionesFlex / RecomendacionesTradicionaldict
04

La lógica de cálculo, con valores exactos

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.

1. Estados de cuenta → ingreso laboral ?El tope de $30,000 MXN para renta en efectivo sin depósito (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.

services/api1/app/services/income.py · app/core/config.py (ReglasIngresos) · Manual v3.0 secc. 12

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:

ReglaValor
Efectivo sin comprobante recurrentese 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):

ingreso_promedio = suma(total_laboral de cada archivo SIN error) / cantidad de archivos SIN error Un mes sin ingreso laboral cuenta como $0 (no se descarta -- si se descartara, el promedio se inflaría justo para el perfil de ingreso irregular). Un archivo con ERROR de extracción sí se excluye del denominador -- no es lo mismo "no hubo ingreso" que "no se pudo leer".

2. Motor de políticas -- PTI / DTI y segmentación

services/api2/app/engine/financial.py · segmentation.py · orchestrator.py · Manual v3.1, vigente 2026-06-01

Mensualidad inicial (base de PTI y DTI):

aportacion_capital = (monto / 180 meses) × coef_adjudicacion gasto_administracion = monto × 0.14% iva = gasto_administracion × 16% seguro_vida = monto × 0.05% mensualidad_total = aportacion_capital + gasto_administracion + iva + seguro_vida PTI = (mensualidad_total / ingreso_mensual_verificado) × 100 DTI = ((mensualidad_total + mensualidad_buro) / ingreso_mensual_verificado) × 100
ProductoPTI máxDTI máxCoef. adjudicaciónCapacidad de pago
Tradicional28.6%40.0%1.0×3.5×
Flex33.3%45.5%1.4×3.0×

Segmentación H1–H4 (solo si pasa hard checks -- fraude/quebranto hipotecario rechazan directo):

SegmentoCriterio principalDecisión resultante
H1 — ÓptimoSaldo vencido ≤ $15,000 · ≤20% líneas atrasadas · MOP ≤ 02APROBADO
H2 — Viable con validaciónSaldo vencido ≤ $250,000 · ≤40% líneas atrasadasAPROBADO_CON_CONDICIONES
H3 — Evaluación profundaSaldo vencido ≤ $500,000 · ≤60% líneas atrasadasCOMITE
H4 — RechazoSaldo vencido > $500,000 · ≥75% líneas atrasadas · ≥179 días de atrasoRECHAZADO

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.

3. Modelo de Machine Learning ?El ajuste automático de monto (reducir 10/20/30/40% si el modelo predice morosidad) está comentado en el código -- hoy MontoOtorgado siempre regresa el monto solicitado, sin ningún ajuste.

services/api3/models/model.py · matriz/matrizDecision.py

Regresión logística entrenada por producto, predice la probabilidad de morosidad (el frontend muestra su complemento, la probabilidad de pago).

ProductoFactor (tasaFactor)
Flex9.9
Tradicional11.0
probabilidad = modelo.predict_proba(X)[:, 1] resultado = 1 si probabilidad ≥ threshold (guardado junto al modelo), si no 0
Banda de riesgoRango de probabilidad
Bajo< 0.20
Medio0.20 – 0.39
Moderado0.40 – 0.59
Alto0.60 – 0.79
Extremo≥ 0.80
05

Con qué conversa

Cuatro sistemas externos, ninguno construido desde cero por este equipo.

OpenAI / Anthropic

Extracción de estados de cuenta cuando el banco no tiene motor determinístico

Buró Facade — BPR Casa

Consulta reportes de Buró ya generados, vía APIM con OAuth

API de expediente de Embajadores

Trae Solicitud + Estados de Cuenta reales de cada prospecto

SMTP

Un correo a Usuario2 cuando un prospecto queda listo para revisar

06

Qué falta para ser una solución formal

Lo más urgente hoy: identidad real de usuario.

Falta
Sin usuarios reales

Usuario2 y Admin hoy son "quien sepa una clave compartida" (API_SHARED_KEY / ADMIN_API_KEY), no cuentas individuales.

Planeado
SSO con Entra ID

Checklist completo ya armado (App Registration ×3 ambientes, roles Admin/Analista, Easy Auth, validate-jwt en APIM) -- bloqueado en acciones del administrador de Azure.

Falta
validate-jwt en APIM

APIM ya está enfrente de las 3 APIs, pero hoy no exige ningún token -- las URLs son alcanzables sin autenticación real.

07

Pantallas y acceso

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).

PantallaRutaQué haceAcceso hoyRol futuro
index.html/ Selector -- lleva a Precalificación o Estados de Cuenta NingunoNinguno
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 NingunoNinguno
08

Tecnologías

Nada exótico -- herramientas estándar, elegidas por lo que cada parte necesitaba resolver.

Backend

Python FastAPI Pydantic SQLAlchemy + Alembic SQLite → Postgres pdfplumber OpenAI / Anthropic SDK scikit-learn + joblib pandas pytest

Frontend

HTML / CSS / JS puro Sin framework, sin build step CSS con variables (design tokens) nginx

Infraestructura

Docker Azure App Service for Containers Azure API Management (APIM) Azure DevOps (repos + pipelines) Git

Planeado, no conectado

Microsoft Entra ID (SSO) Azure Database for PostgreSQL