Backend PRECA — Guía para Up Back Office
La Carta Dictamen de Up Back Office, paso por paso
Organizada igual que ese wizard: en cada paso, qué debe mostrarse, qué endpoint lo llena, y un ejemplo real. No es una referencia de API genérica — es el camino exacto para lo mostrado en las capturas compartidas.
Entornos
Hay 3 ambientes reales, cada uno con su propio dominio, sus propias claves y su propio APIM -- nunca se comparte un secreto de un ambiente con las URLs de otro.
| Ambiente | Frontend | api1 (base, detrás de APIM) | api2 | api3 |
|---|---|---|---|---|
| Desarrollo | preca-dev.hircasa.com.mx | api-qa.bprcasa.com/hircasamlsbackendpreca-api1-dev | ...-api2-dev | ...-api3-dev |
| QA | preca-qa.hircasa.com.mx | api-qa.bprcasa.com/hircasamlsbackendpreca-api1-qa | ...-api2-qa | ...-api3-qa |
| Producción | preca.hircasa.com.mx | api.hircasa.com/mls/prequalification-1 | .../prequalification-2 | .../prequalification-3 |
Cada ruta de api1/api2/api3 de esta tabla es la BASE detrás de APIM — el path completo de cualquier endpoint de esta guía se le agrega tal cual (ej. en Desarrollo, el Paso 1 completo es https://api-qa.bprcasa.com/hircasamlsbackendpreca-api1-dev/api/v1/up-back-office/solicitud). El secreto compartido interno es distinto en cada ambiente -- debe solicitarse a HIR Casa por separado para Desarrollo, QA y Producción, nunca se reusa el mismo valor entre ambientes.
APIM exige un token Bearer de Entra ID -- confirmado en vivo
GET /healthz sin ningún header respondió 401 {"statusCode":401,"message":"Acceso denegado: Token invalido"} en api2-dev, api3-dev, api1-qa y api1-prod (un rechazo de APIM mismo, antes de llegar al código) -- pero con un token real, obtenido vía OAuth2 client credentials contra la App Registration de Up Back Office (tenant id, client id, client secret y scope propios) y mandado como Authorization: Bearer <token>, la misma llamada respondió 200. Probado en vivo el 10/sep contra api1-dev y api2-dev.
api1-dev es la única ruta que respondía 200 incluso SIN token en /healthz -- no está claro si esa excepción sigue igual para el resto de sus endpoints o si es solo ese path puntual; con el token puesto no hace diferencia, pero vale la pena no asumir que api1-dev "no necesita auth".
Cómo autenticar una llamada, paso a paso
Dos credenciales, dos orígenes distintos. Ninguna se comparte entre ambientes.
| # | Credencial | Protege | A quién pedirla |
|---|---|---|---|
| 1 | Token Bearer de Entra ID | La puerta de entrada en APIM, antes de llegar al código -- toda llamada la necesita, sin excepción | Tenant id / client id / client secret / scope de la App Registration -- ya se compartieron para Desarrollo. Se obtiene un token nuevo por request (o se cachea hasta que expire) con un POST al token endpoint del tenant, flujo client credentials. |
| 2 | Secreto compartido interno | Todo EXCEPTO /api/v1/up-back-office/solicitud: Buró, policy/evaluate, /predecir/, clasificacion/persistir, comentarios, ingresos/persistir | HIR Casa, por ambiente |
/api/v1/up-back-office/solicitud ya NO pide clave de aplicación -- decisión explícita del equipo (10/sep)
Existió una UP_BACK_OFFICE_API_KEY propia (documentada antes en esta guía) -- se quitó a propósito: el equipo decidió que el token de Entra ID validado por APIM es autenticación suficiente para este endpoint puntual, sin una segunda clave encima. Riesgo que vale la pena tener presente: con esto, este endpoint queda protegido ÚNICAMENTE por APIM -- si esa capa llegara a fallar abierta (política mal configurada, deshabilitada por error, etc.) del lado de quien administra APIM, no hay ninguna red de seguridad de este lado. Ningún otro endpoint de esta guía perdió su capa de aplicación -- este cambio es solo para up-back-office/solicitud.
Con el token en mano, cada llamada de esta guía lleva un header más:
POST https://api-qa.bprcasa.com/hircasamlsbackendpreca-api1-dev/api/v1/up-back-office/solicitud Authorization: Bearer <token de Entra ID> Content-Type: application/json POST https://api-qa.bprcasa.com/hircasamlsbackendpreca-api2-dev/api/v1/policy/evaluate Authorization: Bearer <token de Entra ID> X-API-Key: <secreto compartido interno de Desarrollo> Content-Type: application/json
No hay un "probador" embebido dentro de esta misma página — el sandbox donde corre esta guía no puede hacer llamadas de red a hosts arbitrarios. Pero las URLs de arriba SÍ son públicas (se probaron en vivo desde fuera de la red de HIR Casa, sin VPN): lo único que falta para poder probarlas desde cualquier lugar son las credenciales de arriba -- no hace falta estar dentro de la red de HIR Casa, solo tener el token y (según el endpoint) el secreto compartido interno.
Los pasos, de un vistazo
Flujo de PRECA -- solo qué pasa en cada paso. El detalle técnico de cada uno está más abajo, en su propia sección.
Envío de la Solicitud y los documentos (identificación, comprobantes de ingreso, estados de cuenta). Arranca el análisis. 2 Clasificación de Ingresos
Resultado del análisis de estados de cuenta: depósitos clasificados por la IA (laboral / no laboral / incierto), disponibles para reclasificación manual. 3 Clasificación de Buró
Consulta del reporte de Buró de Crédito y evaluación de la política: score, PTI/DTI, y checklist de criterios (cumple / observación). 4 Resultado
Predicción del modelo de ML: montos, dictamen (viable / no viable), y perfil final con probabilidad de riesgo.
Aparte de estos pasos, hay 3 cosas que pueden pasar en cualquier momento, no ligadas a un paso puntual: comentarios, reevaluar, y añadir un ingreso manual — ver esa sección.
Antes de empezar: identificar al prospecto
Esta información se muestra en el frontend de Up Back Office, por lo que cada respuesta debe amarrarse al prospecto correcto de su propio sistema. Varios identificadores entran en juego, y ninguno se cruza-valida automáticamente entre sí:
| Dónde | Campo | Tipo | Quién lo asigna |
|---|---|---|---|
| api1 (paso 1) | persona | string, libre | Up Back Office |
| api1 (paso 2, dentro de ProcessDetail) | prospect_id | string (numérico) | PRECA -- generado determinísticamente a partir del RFC |
| api2 (paso 3) | application.client_id | string (1-50 caracteres) | Up Back Office |
| api3 (paso 5) | Prospecto.ProspectoId | string (acepta también entero) | Up Back Office |
Recomendación: NO hace falta generar ni guardar un ID secundario del lado de Up Back Office — PRECA ya genera uno estable, determinístico a partir del RFC (prospect_id), visible en la respuesta de GET /procesos/ultimo (o GET /procesos/{process_id}) desde el Paso 2 en adelante. Los tres IDs (prospect_id, client_id de api2 y ProspectoId de api3) son string, así que ese mismo valor sirve tal cual para los dos últimos, sin convertir nada. ProspectoId sigue aceptando también un entero (lo convierte a texto), y Prospecto.ProspectoId es solo una llave de unión interna: no llega al modelo, así que cualquier texto consistente sirve. La respuesta de /predecir/ lo regresa como clientId, también string (antes salía entero). Para persona (Paso 1) sigue siendo Up Back Office quien lo asigna — PRECA todavía no conoce al prospecto antes de esa primera llamada. Ninguna API avisa si se mandan IDs inconsistentes entre pasos; mantenerlos amarrados es responsabilidad de quien integra.
Entregar la Solicitud y los documentos
POST /api/v1/up-back-office/solicitud{
"persona": "up-000341",
"ejecutor_nombre": "María Martínez",
"ejecutor_correo": "maria@upbackoffice.com",
"solicitud": {
"persona": {
"nombre": "ALICIA", "apellidoPaterno": "GARCIA", "apellidoMaterno": "MARTINEZ",
"rfc": "GAMA850101ABC", "curp": "GAMA850101MDFRRR01",
"fechaNacimiento": "1985-01-01", "pais": "MX", "estadoCivil": "CASADO",
"numeroDependientes": 2, "gradoEstudio": "LICENCIATURA_POSGRADO",
"tipoVivienda": "PROPIA", "egresoMensual": 8000
},
"domicilio": { "calleNumero": "...", "colonia": "...", "ciudad": "...", "estado": "...", "codigoPostal": "..." },
"ingresosDeclarados": [
{ "tipoIngreso": "COMPROBABLE", "montoMensual": 30000, "antiguedadMeses": 36, "giro": "COMERCIO", "puesto": "GERENTE" }
],
"operacion": { "montoSolicitado": 1000000 }
},
"estados_cuenta": [
{ "nombreArchivo": "bbva-mayo-2026.pdf", "contentType": "application/pdf", "contenidoBase64": "JVBERi0xLjQK..." }
]
}{
"process_id": "dd7196ba-1ebc-4fd6-a4b9-9d939be63853"
}RFC y nombre quedan persistidos de inmediato (síncrono) — se puede mostrar "Expediente recibido" en cuanto llega esta respuesta. Solo el análisis de los archivos (paso 2) corre en segundo plano.
| Código | Cuándo | Body |
|---|---|---|
| 401 | Rechazo de APIM -- falta o es inválido el token Bearer de Entra ID (este endpoint ya no valida ninguna clave propia del lado de la aplicación) | { "statusCode": 401, "message": "..." } |
| 422 (validación de FastAPI) | Falta un campo requerido o tiene el tipo equivocado (ej. ejecutor_correo sin forma de correo) | { "detail": [{ "loc": [...], "msg": "..." }] } |
| 422 (RFC) | El RFC no tiene el formato esperado — probado en vivo hoy | { "detail": "RFC con formato inválido: 'ABC123'. Se esperan 12-13 caracteres (3-4 letras, 6 dígitos de fecha, 3 alfanuméricos de homoclave)." } |
solicitud y estados_cuenta usan el mismo shape ya documentado para Embajadores — el mapa de APIs completo tiene el detalle campo por campo para cualquier dato que no venga en este ejemplo (domicilio completo, todos los valores válidos de gradoEstudio, etc.).
Nota: Buró de Crédito NO va en este payload — eso lo consulta PRECA por su cuenta en el paso 3, con el RFC ya recibido en este paso.
Llamar este endpoint dos veces para la misma persona vuelve a analizar todo desde cero
Si el proceso anterior de esa persona todavía está en curso (no llegó a un dictamen) y esta llamada trae estados_cuenta, PRECA borra los archivos ya analizados del intento anterior y dispara el análisis de nuevo con lo que venga en esta llamada -- reusa el mismo process_id, pero el resultado del paso 2 vuelve a tardar el mismo tiempo. Esto es intencional (mismo motivo que el gotcha de /ingresos/persistir más abajo: la persistencia es por reemplazo, no por acumulación, para que un reintento no duplique transacciones): si el propósito de la segunda llamada es solo reintentar sin cambiar nada, debe reenviarse la lista COMPLETA de estados_cuenta, no un subconjunto ni una lista vacía. Si en cambio el proceso anterior ya llegó a un dictamen, esta llamada crea un process_id nuevo en vez de reusar el anterior -- el registro propio del prospecto debe actualizarse con ese process_id nuevo.
Depósitos clasificados, listos para reclasificar
GET /api/v1/procesos/ultimo?persona={persona}Una sola llamada resuelve CUÁL es el proceso de esta persona (no se asume que process_id ya está guardado del lado de Up Back Office) Y trae el detalle completo -- incluidos los bank_statements -- de una vez. Regresa siempre el proceso MÁS RECIENTE de esa persona por fecha, sin importar su status.
processing_bank_statements sea false. probado en vivo
{
"process_id": "dd7196ba-...",
"processing_bank_statements": true,
"bank_statements": []
}{
"process_id": "dd7196ba-...",
"rfc": "GAMA850101ABC",
"full_name": "ALICIA GARCIA MARTINEZ",
"processing_bank_statements": false,
"average_monthly_labor_income_mxn": 30000.0,
"average_monthly_total_deposits_mxn": 34500.0,
"application": { "ingreso_mensual_declarado": 32000.0, "...": "..." },
"bureau": null,
"bureau_monthly_payment_mxn": null,
"bank_statements": [{
"id": 1, "file_name": "bbva-mayo-2026.pdf", "bank": "BBVA", "period": "Mayo 2026",
"total_labor_mxn": 30000.0, "total_non_labor_mxn": 0.0, "total_uncertain_mxn": 4500.0,
"transactions": [{
"date": "2026-05-07", "description": "Pago de nomina", "amount_mxn": 30000.0,
"ai_classification": "laboral", "confidence": 0.95
}]
}]
}average_monthly_labor_income_mxn (ingreso verificado, solo depósitos laborales) y average_monthly_total_deposits_mxn (promedio de TODOS los depósitos, sin filtrar por clasificación) ya quedan listos aquí, en cuanto processing_bank_statements pasa a false. bureau_monthly_payment_mxn (compromiso mensual en Buró) y bureau.indicadores.max_days_overdue_12m (máx. días de atraso) siguen en null hasta el Paso 3 (Buró) -- si la pantalla que pinta estos cuatro valores se arma antes de ese paso, van a faltar los dos de Buró; hay que volver a llamar este mismo endpoint después de POST /buro/consultar-api para que salgan completos. El ingreso reportado (sin verificar) sigue en application.ingreso_mensual_declarado, disponible desde el Paso 1.
Se guarda el process_id de esta respuesta (aunque sea solo en memoria, para el resto de esta sesión) y se sigue usando explícitamente en cada llamada posterior -- comentarios, correcciones, añadir ingreso, Buró, persistir. Resolverlo por persona no sustituye pasar process_id en el resto del flujo, solo evita depender de que ya estuviera guardado de una visita anterior. Para seguir el polling una vez que el process_id ya se conoce, se puede repetir esta misma llamada o cambiar a GET /api/v1/procesos/{process_id} -- las dos regresan exactamente el mismo shape. Qué significa cada valor de status, y cuándo conviene GET /api/v1/procesos?persona=...&estado=... en vez de este endpoint (para pedir específicamente "el vigente" o "el último completado", incluso si ya hay un intento más nuevo), está en Recuperar el process_id de un prospecto.
Cada transacción trae ai_classification (laboral/no_laboral/incierto). El ingreso consolidado que se usa en el paso 3 es la suma de total_labor_mxn de todos los bank_statements sin error.
Botón "Reclasificar" (arrastrar tarjetas entre columnas)
POST /api/v1/procesos/{process_id}/correcciones{
"corrections": [
{
"entity_id": "archivo_1_transaccion_0",
"field": "ai_classification",
"original_ai_value": "laboral",
"user_corrected_value": "no_laboral"
}
]
}{ "guardadas": 1 }entity_id sigue el formato archivo_{id}_transaccion_{índice} -- {id} es el id del bank_statement (el 1 del ejemplo de arriba) y {índice} la posición de la transacción dentro de su lista transactions, empezando en 0. Después de reclasificar, el ingreso consolidado del paso 3 debe recalcularse sobre las clasificaciones YA corregidas, no sobre las originales de la IA.
Para que GET /procesos/{id} (y /procesos/ultimo) regresen lo editado: ?aplicar=true
POST /api/v1/procesos/{process_id}/correcciones?aplicar=trueSin aplicar, el endpoint solo audita: guarda qué dijo la IA contra qué decidió el analista, pero no cambia las transacciones guardadas, así que el siguiente GET devuelve otra vez la clasificación de la IA. Con ?aplicar=true PRECA además actualiza la clasificación de cada transacción, su monto computable (el efectivo sin comprobante cuenta al porcentaje de la política), los totales del archivo (total_labor_mxn, total_non_labor_mxn, total_uncertain_mxn) y average_monthly_labor_income_mxn.
{ "guardadas": 1, "aplicadas": 1 }En el GET, cada transacción trae edited (true si la clasificación guardada difiere de la que dijo la IA) y original_classification (lo que dijo la IA, solo cuando edited es true). field acepta "clasificacion" o "ai_classification". Reenviar POST /up-back-office/solicitud con estados de cuenta reanaliza desde cero y descarta las ediciones guardadas.
Score, PTI/DTI y el checklist de criterios
POST /api/v1/buro/consultar-api → POST /api/v1/policy/evaluate3a. Reporte de Buró (lo sigue consultando PRECA)
{
"process_id": "dd7196ba-...",
"rfc": "GAMA850101ABC"
}{
"indicadores": {
"fraud_confirmed": false, "mortgage_default": false,
"max_mop_global": 2, "total_overdue_balance": 0.0,
"overdue_lines_pct": 0.0, "total_bureau_monthly_payment": 2500.0,
"current_debt_mxn": 30000.0
},
"raw": { "score": 710, "...": "..." }
}3b. Evaluar política — aquí sale el checklist
{
"application": {
"client_id": "up-000341", "product": "traditional",
"requested_amount": 1000000.0, "verified_monthly_income": 30000.0,
"employment_tenure_months": 36
},
"credit_bureau": {
"score": 710, "fraud_confirmed": false, "mortgage_default": false,
"max_mop_global": 2, "max_mop_mortgage": 0, "total_overdue_balance": 0.0,
"overdue_lines_pct": 0.0, "active_lines_count": 4, "overdue_lines_count": 0,
"late_payments_30d_12m_count": 1, "max_days_overdue_12m": 25,
"total_bureau_monthly_payment": 2500.0, "current_debt_mxn": 30000.0
}
}{
"decision": "APPROVED",
"score_rating": { "score": 710, "rating": "Bueno" },
"segment": { "code": "H1", "title": "BC Perfil Óptimo",
"reasons": ["Saldo vencido $0 ≤ $15,000", "0.0% líneas atrasadas ≤ 20.0%"] },
"hard_checks": { "approved": true, "violations": [] },
"financial_indicators": {
"pti": { "value": 12.24, "limit": 28.6, "compliant": true },
"dti": { "value": 28.9, "limit": 40.0, "compliant": true },
"required_income": 42857.14, "max_eligible_amount": 1117252.16
}
}Cada fila del checklist "Cumple/Observación" del mockup es un elemento de hard_checks.violations (si no aparece ahí, cumple) más las razones en segment.reasons. El score y su calificación salen de score_rating.
Atajo opcional (no obligatorio): si no se quiere reconstruir a mano los payloads de este paso 3b ni del Paso 4 (/predecir/, con su catálogo de valores y el shape de Cuentas), GET /api/v1/procesos/{process_id}/resultado?producto=traditional|flex calcula ambos del lado de PRECA a partir de lo que ya está persistido (Solicitud, Buró, ingreso comprobado) y regresa {"policy": ..., "ml": ..., "ml_omitido_razon": null} en una sola llamada. Sigue siendo válido llamar /policy/evaluate y /predecir/ directo como se documenta arriba -- este endpoint es un camino alterno, no un reemplazo. Ver detalle en la sección de Resultado (Paso 4) más abajo.
Montos, dictamen y la tarjeta final de perfil
POST /predecir/Si el dictamen ya se emitió antes (se retoma un prospecto ya completado, no uno nuevo) — NO hace falta repetir /policy/evaluate ni /predecir/: GET /api/v1/procesos/ultimo?persona=<persona> (o GET /api/v1/procesos/{process_id}, si ya se conoce el ID) ya trae policy/ml con el mismo policy_result/ml_result que se guardó en su momento vía clasificacion/persistir -- se renderiza la pantalla de Resultado directo desde ahí. Si en cambio hay un intento MÁS NUEVO todavía sin dictamen y se quiere el último completado de todos modos, se usa GET /api/v1/procesos?persona=<persona>&estado=COMPLETADO en su lugar. Detalle en Recuperar el process_id de un prospecto.
| En pantalla | Campo |
|---|---|
| Ingreso mínimo mensual | financial_indicators.required_income |
| Monto máximo alcanzado | financial_indicators.max_eligible_amount |
| Dictamen Viable / No viable | decision === "APPROVED" |
segment. Una llamada regresa Flex Y Tradicional juntos. respuesta capturada en vivo
{
"Solicitud": { "MontoContratado": 1000000.0 },
"Prospecto": {
"ProspectoId": "341", "FechaNacimiento": "1985-01-01", "EstadoCivil": "CASADO",
"NumeroDependientes": 2, "Egreso": 20000.0, "TipoVivienda": "PROPIA",
"GradoEstudio": "LICENCIATURA_POSGRADO", "Pais": "MÉXICO", "SegmentoPolitica": "H1"
},
"Ingresos": [{ "TipoIngreso": 0, "Giro": "COMERCIO", "Puesto": "GERENTE", "MontoIngreso": 30000.0, "AntiguedadAnio": 3.0 }],
"ConsultaBuroCredito": {
"FechaConsulta": "2025-04-30", "ScoreBuroCredito": { "...": "del paso 3a" },
"ResumenReporte": { "...": "del paso 3a" },
"Cuentas": [{ "...": "del paso 3a -- OJO abajo" }]
}
}{
"clientId": "341",
"flexProbability": 0.0277722889254045,
"flexResult": 0, "flexGrantedAmount": 1000000.0,
"flexModelClassification": "Low",
"flexRecommendations": {
"title": "A - Perfil Óptimo",
"description": "Cliente con probabilidad baja de incumplimiento.",
"actions": ["Proceso agil", "Anticipos permitidos bajo politica general"]
}
}La tarjeta final ("H1 - Perfil Óptimo" + bullets + % de riesgo) es flexRecommendations.title/.description/.actions[] + flexProbability × 100. flexGrantedAmount siempre es igual al monto solicitado (ver sección 7) — para "monto máximo" se usa max_eligible_amount del paso 3b, no este campo.
Los 5 niveles de flexRecommendations/traditionalRecommendations
No es solo el nivel "A" del ejemplo de arriba — hay 5 en total (services/api3/veredicto/decision.py, SEGMENT_RECOMMENDATIONS), de mejor a peor perfil. title/description/actions son texto fijo por nivel (no cambian por cliente); lo único que varía caso a caso es a cuál de los 5 cae cada respuesta.
| Nivel | title | description | actions |
|---|---|---|---|
| A | A - Perfil Óptimo | Cliente con probabilidad baja de incumplimiento. Se puede otorgar proceso ágil bajo controles operativos estándar. | Proceso agil · Anticipos permitidos bajo politica general |
| B | B - Perfil Viable con Validación | Cliente con riesgo controlable. Requiere mitigantes estructurales antes de adjudicación. | Domiciliacion obligatoria · Evaluar obligado solidario · Seguimiento trimestral |
| C | C - Perfil con Evaluación Profunda | Cliente con riesgo elevado. Requiere mitigación estructural antes de permitir adjudicación. | Obligado solidario obligatorio · Fondo de dacion · Minimo de cuotas en etapa integrante · Restriccion de anticipos · Revision por comite |
| D | D - Perfil Bajo | Cliente con alta probabilidad de incumplimiento. Solo procede bajo mitigantes fuertes o se sugiere no continuar. | Comite obligatorio · Obligado solidario obligatorio · Fondo de dacion maximo · Sin anticipos extraordinarios · Evaluar viabilidad antes de escritura |
| E | E - Perfil Bajo - Rechazo | Cliente con alta probabilidad de incumplimiento. Se sugiere no continuar. | No continuar con el proceso |
Cuál de los 5 le toca a un caso sale de cruzar SegmentoPolitica (H1-H4, del paso 3b) con flexModelClassification/traditionalModelClassification (Low/Medium/Moderate/High/Extreme, de este mismo paso 4) — api3 ya hace ese cruce internamente, el nivel llega calculado en flexRecommendations, no hay que armarlo del lado de Up.
| SegmentoPolitica | Low | Medium | Moderate | High | Extreme |
|---|---|---|---|---|---|
| H1 | A | A | B | C | E |
| H2 | A | B | B | D | E |
| H3 | B | C | C | D | E |
| H4 | C | D | D | E (cualquier otro caso) | E |
SEGMENT_RECOMMENDATIONS hoy, y no corresponde a ningún número que PRECA calcule o regrese: ni /policy/evaluate ni /predecir/ devuelven una tasa de interés en ningún campo (el producto se cobra por comisión administrativa + IVA + seguro de vida, porcentajes fijos, no por tasa). Existe un tasaFactor interno (9.9 para Flex, 11.0 para Tradicional, services/api3/main.py) pero es fijo por PRODUCTO -- igual para los 5 niveles -- y solo se usa como insumo del modelo, nunca se regresa en la respuesta. Antes de mostrar "tasa preferencial" en un frontend, confirmar con el equipo de modelos qué es tasaFactor y si de verdad corresponde a algo mostrable.ConsultaBuroCredito.Cuentas NO es la lista de cuentas del reporte. Es una trampa fácil de caer porque comparten el nombre: Cuentas aquí espera EXACTAMENTE UN objeto (dentro de una lista de 1 elemento) con los 10 totales agregados que ya regresó el paso 3a como cuentas_prediccion (TipoMoneda, TotalCreditosMaximosRevolventes, TotalLimitesCreditoRevolventes, etc.) — nunca la lista de cuentas individuales del reporte crudo (otorgante, tipo_credito, saldo_actual, etc., que vive en raw.cuentas del paso 3a). Mandar la lista de cuentas individuales aquí responde 422 con algo como Cuentas.0.TipoMoneda: Field required — el objeto que se mandó no tiene esos 10 campos porque es la otra forma. La llamada correcta es "Cuentas": [respuestaDelPaso3a.cuentas_prediccion], tal cual, sin transformar nada.Catálogo de valores — EstadoCivil, TipoVivienda, Giro, Puesto, GradoEstudio
EstadoCivil, TipoVivienda, Giro y Puesto ya están validados en serio en api3 (antes eran string libre y un valor mal escrito calculaba la categoría en 0 en silencio, sin ningún error) — un valor fuera de catálogo responde 422 con la lista completa de valores válidos. Son los MISMOS catálogos que ya usa application.estado_civil_normalizado/tipo_vivienda_normalizado/giro_normalizado/puesto_normalizado/grado_estudio en la respuesta de GET /procesos/ultimo (Paso 1) — la forma más segura de llenar estos campos es reusar esos valores directo.
services/api3/procesamiento/catalogos.py (un solo archivo, los diccionarios de traducción) para que coincida -- el resto del código no cambia. SegmentoPolitica y TipoIngreso se quedan sin equivalente en inglés a propósito: ya son códigos/números, no palabras ("H1", 0/1) — no hay nada que traducir.| Campo | Valores válidos (español) | Inglés (borrador, ver gotcha arriba) |
|---|---|---|
| EstadoCivil | SOLTERO | CASADO | UNIÓN LIBRE | DIVORCIADO | VIUDO | SINGLE | MARRIED | DOMESTIC_PARTNERSHIP | DIVORCED | WIDOWED |
| TipoVivienda | PROPIA | PROPIA HIPOTECADA | RENTADA | OWNED | MORTGAGED | RENTED |
| GradoEstudio | PRIMARIA | SECUNDARIA | MEDIO_SUPERIOR | TÉCNICO | LICENCIATURA_POSGRADO | NINGUNA_DE_LAS_ANTERIORES | ELEMENTARY | MIDDLE_SCHOOL | HIGH_SCHOOL | TECHNICAL | BACHELOR_OR_HIGHER | NONE_OF_THE_ABOVE |
| SegmentoPolitica | H1 | H2 | H3 | H4 (el mismo segment.code del paso 3b) | No aplica — ya es un código, no una palabra |
| Puesto | DUEÑO | SOCIO | DIRECTOR | SUBDIRECTOR | GERENTE | ADMINISTRADOR | COORDINADOR | JEFE | ANALISTA | CONSULTOR | ASESOR | VENTAS | COMERCIANTE | ASISTENTE | JUBILADO | OTRO | INDEPENDIENTE (se trata como OTRO) | OWNER | PARTNER | DIRECTOR | DEPUTY_DIRECTOR | MANAGER | ADMINISTRATOR | COORDINATOR | SUPERVISOR | ANALYST | CONSULTANT | ADVISOR | SALES | MERCHANT | ASSISTANT | RETIRED | OTHER | SELF_EMPLOYED (se trata como OTHER) |
| Giro | SALUD | EDUCACION | LEGISLATIVO Y GUBERNAMENTAL | FINANZAS Y SEGUROS | SERVICIOS PROFESIONALES | SERVICIOS DE APOYO A LOS NEGOCIOS | OTROS SERVICIOS | MEDIOS MASIVOS | INMOBILIARIA | COMERCIO MINORISTA | COMERCIO | ALIMENTACION Y HOSPEDAJE | TRANSPORTE AEREO | MANUFACTURA | CONSTRUCCION | ENERGIA | MINERIA, EXTRACCION Y SUMINISTRO | AGRÍCOLA | DIFUSION CULTURAL | CORPORATIVO | ADMINISTRACION | HEALTHCARE | EDUCATION | GOVERNMENT | FINANCE_AND_INSURANCE | PROFESSIONAL_SERVICES | BUSINESS_SUPPORT_SERVICES | OTHER_SERVICES | MASS_MEDIA | REAL_ESTATE | RETAIL | COMMERCE | FOOD_AND_LODGING | AIR_TRANSPORT | MANUFACTURING | CONSTRUCTION | ENERGY | MINING_AND_SUPPLY | AGRICULTURE | CULTURAL_MEDIA | CORPORATE | ADMINISTRATION |
| Pais | MÉXICO (canónico, con acento) | MEXICO (sin acento) o MX — no es un catálogo cerrado: cualquier OTRO país es un valor legítimo (el modelo solo compara contra "MÉXICO" para una bandera booleana), así que un valor distinto nunca se rechaza, solo se deja tal cual. |
| TipoIngreso | 0 = Comprobable, 1 = No comprobable (mismo criterio que tipo_ingreso_normalizado de application) | |
Ejemplo completo — el mismo request de /predecir/ en inglés
Listo para copiar/pegar y usar directo: mismo process_id/ProspectoId de ejemplo que el resto de la guía, con los 4 catálogos bilingües en su versión en inglés. probado en vivo contra api3 real -- regresa exactamente el mismo flexProbability que la versión en español equivalente.
{
"Solicitud": { "MontoContratado": 2000000 },
"Prospecto": {
"ProspectoId": "341",
"FechaNacimiento": "1988-05-10",
"EstadoCivil": "MARRIED",
"NumeroDependientes": 1,
"Egreso": 40000,
"TipoVivienda": "OWNED",
"GradoEstudio": "BACHELOR_OR_HIGHER",
"Pais": "MEXICO",
"SegmentoPolitica": "H1"
},
"Ingresos": [{
"TipoIngreso": 0, "Giro": "COMMERCE", "Puesto": "MANAGER",
"MontoIngreso": 100000, "AntiguedadAnio": 3.0
}],
"ConsultaBuroCredito": {
"FechaConsulta": "2025-04-30",
"ScoreBuroCredito": {
"nombreScore": "BC SCORE", "CodigoScore": "007", "ValorScore": 690,
"CodigoRazon": [], "CodigoError": null, "ClaveUnidadMonetaria": "MX", "MontoPagar": 13000.0
},
"ResumenReporte": { "...": "tal cual regresa el paso 3a (resumen_reporte), sin transformar" },
"Cuentas": [{ "...": "cuentas_prediccion del paso 3a -- UN solo objeto, en lista de 1 (ver gotcha arriba)" }]
}
}ScoreBuroCredito/ResumenReporte/Cuentas nunca se traducen -- son el shape real del reporte de Buró (paso 3a), no vocabulario de PRECA. Solo los 4 campos de catálogo (EstadoCivil, TipoVivienda, Giro, Puesto) y GradoEstudio/Pais aceptan inglés.
Unidad de AntiguedadAnio: va en AÑOS (puede ser decimal), no en meses — application.antiguedad_meses (Paso 1) está en MESES, así que hay que dividir entre 12 antes de mandarlo (ej. 36 meses → 3.0).
/policy/evaluate (Paso 3b). credit_bureau.score en api2 exige 300 ≤ score ≤ 850 (validación dura, 422 si no se cumple) — pero un reporte de Buró real puede traer ValorScore nulo o por debajo de 300 (ej. "thin file", sin historial suficiente). Antes de mandarlo, si score_buro_credito.ValorScore es nulo o menor a 300, hay que mandar 300 fijo en su lugar — no el valor crudo. Sin este piso, esos prospectos truenan con 422 en vez de evaluarse.Guardar el resultado en PRECA
POST /api/v1/clasificacion/persistir, justo después de recibir las respuestas del paso 3b y de /predecir/Este paso es lo que hace que el proceso exista para PRECA más allá de la respuesta que ya llegó a la pantalla de Up Back Office: sin esta llamada, PRECA nunca se enteró de qué dictamen salió ni de qué monto se calculó -- no aparece en el panel interno ni en ninguna métrica. Es opcional en el sentido de que la Carta Dictamen puede mostrarse igual sin ella, pero es la única forma en que PRECA mide lo que pasó.
policy_result es la respuesta completa del paso 3b, ml_result la de /predecir/, tal cual, sin transformar.
{
"process_id": "dd7196ba-...",
"policy_result": {
"decision": "APPROVED",
"score_rating": { "score": 710, "rating": "Bueno" },
"segment": { "code": "H1", "title": "BC Perfil Óptimo", "reasons": ["..."] },
"hard_checks": { "approved": true, "violations": [] },
"financial_indicators": {
"pti": { "value": 12.24, "limit": 28.6, "compliant": true },
"dti": { "value": 28.9, "limit": 40.0, "compliant": true },
"required_income": 42857.14, "max_eligible_amount": 1117252.16
}
},
"ml_result": {
"clientId": "341", "flexProbability": 0.0277722889254045,
"flexResult": 0, "flexGrantedAmount": 1000000.0,
"flexModelClassification": "Low",
"flexRecommendations": { "title": "A - Perfil Óptimo", "...": "..." }
}
}{ "ok": true }Esta llamada requiere el secreto compartido interno (X-API-Key), además del token Bearer de Entra ID que ya piden todas las llamadas -- a diferencia del Paso 1, aquí sí sigue haciendo falta esa segunda capa.
Para la reevaluación (botón "Reevaluar", más abajo), la misma llamada se repite con is_usuario2: true — ver esa sección para el detalle de por qué no pisa el dictamen original.
Atajo opcional — política + ML en una sola llamada
/policy/evaluate) ni de este paso (/predecir/) — se usa: GET /api/v1/procesos/{process_id}/resultado?producto=traditional|flexCalcula ambos del lado de PRECA, a partir de lo que ya está persistido (Solicitud, Buró consultado, ingreso comprobado) -- api1 arma internamente los mismos payloads que se documentan arriba (incluido el catálogo de valores y el shape correcto de Cuentas) y regresa el resultado combinado. Aditivo, no obligatorio: seguir llamando /policy/evaluate + /predecir/ directo, como se documenta en el resto de esta guía, sigue siendo igual de válido -- este es solo un camino alterno más simple para quien prefiera no ensamblar esos payloads.
{
"policy": { "decision": "APPROVED", "segment": { "code": "H1", "...": "..." },
"financial_indicators": { "...": "igual que el paso 3b" } },
"ml": { "flexProbability": 0.02, "flexModelClassification": "Low",
"flexRecommendations": { "...": "igual que /predecir/" }, "...": "..." },
"ml_omitido_razon": null
}ml sale null (con ml_omitido_razon explicando por qué) si hard_checks rechazó (sin segmento no hay ML que correr) o si a la Solicitud le falta giro_normalizado/puesto_normalizado -- nunca tumba la respuesta completa por eso. 409 si al process_id le falta Solicitud, Buró o ingreso comprobado. 422 si producto no es traditional/flex.
Descargar la Carta Dictamen en PDF
GET /api/v1/procesos/{process_id}/carta-dictamen.pdfArma el PDF completo del lado de PRECA (no hace falta ensamblar nada en el frontend de Up Back Office): carta formal con folio, producto, monto solicitado/alcanzado, ingreso comprobado, compromiso de Buró, dictamen (Viable/No viable), observaciones y requerimientos. Solo trae el producto de la Solicitud — el comparativo Tradicional vs. Flex es una herramienta interna de Crédito, no forma parte del documento oficial. Requiere que ese process_id ya tenga Solicitud, Buró consultado e ingreso comprobado — si algo falta, 409.
GET /api/v1/procesos/dd7196ba-.../carta-dictamen.pdf Authorization: Bearer <token de Entra ID> X-API-Key: <secreto compartido interno>
Content-Type: application/pdf Content-Disposition: attachment; filename="carta_dictamen_dd7196ba-....pdf" (bytes del .pdf)
Si el process_id todavía no tiene Solicitud, Buró consultado o ingreso comprobado, 409 con el detalle de qué falta. Si no existe, 404.
Comentarios, reevaluar, añadir ingreso
Tres cosas que no son "un paso" del wizard sino acciones que pueden pasar en cualquier momento -- las tres usan endpoints que YA EXISTEN, ninguna necesita algo nuevo de PRECA.
Saber en qué paso se quedó un proceso: progress
GET /api/v1/procesos/ultimo y GET /api/v1/procesos/{process_id} traen un campo progress que dice en qué paso va el proceso y qué llamar para avanzar — sin tener que deducirlo de qué campos vienen en null. Es de solo lectura y se calcula al momento con lo que ya está guardado; status (PENDIENTE/EN_PROCESO/COMPLETADO) no cambia, y quien ya deduce el estado a mano puede seguir haciéndolo igual.
"progress": {
"stage": "bureau",
"completed": ["application", "income"],
"next_action": "Falta el reporte de Buró: POST /api/v1/buro/consultar-api"
}
stage | Significa | Se considera hecho cuando |
|---|---|---|
| application | Falta la Solicitud (Paso 1) | application trae datos |
| income | Falta el ingreso comprobado (Paso 2). Si processing_bank_statements es true, next_action dice esperar | average_monthly_labor_income_mxn no es null (0 cuenta como hecho) |
| bureau | Falta consultar Buró (Paso 3a) | bureau trae datos |
| policy | Falta el dictamen de política (Paso 3b) guardado en PRECA | policy trae datos — solo se llena con POST /clasificacion/persistir; /resultado calcula pero no guarda |
| ml | Falta la predicción de riesgo (Paso 4) guardada | ml trae datos, o policy.segment es null (hard_checks rechazó: sin segmento no hay ML que correr) |
| complete | No falta nada; next_action es null | Todo lo anterior |
Recuperar el process_id de un prospecto
PRECA lo genera y lo regresa en el Paso 1 — guardarlo de inmediato junto al registro propio del prospecto es lo más simple. Pero si Up Back Office no maneja más de un proceso a la vez por prospecto (nunca guarda dos process_id para la misma persona), no hace falta depender de eso: GET /api/v1/procesos/ultimo?persona=<persona> resuelve, en UNA sola llamada, cuál es el proceso MÁS RECIENTE de esa persona por fecha (sin importar su status) y regresa el detalle completo -- el mismo shape que GET /api/v1/procesos/{process_id}, sin tener que encadenar las dos llamadas.
{
"process_id": "dd7196ba-...",
"embajadores_person_id": "up-000341",
"status": "EN_PROCESO",
"processing_bank_statements": false,
"rfc": "GAMA850101ABC",
"full_name": "ALICIA GARCIA MARTINEZ",
"decision_policy": null,
"bank_statements": []
}Además de average_monthly_labor_income_mxn (ingreso verificado, solo depósitos laborales), el detalle completo (este endpoint y GET /procesos/{id}) trae otros dos campos aplanados y derivados, calculados al consultar -- no se guardan aparte, así que siempre reflejan lo que ya está persistido: bureau_monthly_payment_mxn (compromiso mensual en Buró, suma de bureau.indicadores.total_bureau_monthly_payment; null hasta que hay Buró) y average_monthly_total_deposits_mxn (promedio mensual de TODOS los depósitos de los bank_statements sin error -- laborales + no laborales + inciertos, sin filtrar por clasificación; null hasta que hay al menos un estado de cuenta analizado sin error). El ingreso reportado por la persona (sin verificar) sigue viniendo dentro de application.ingreso_mensual_declarado.
Este es el endpoint recomendado por default. Hay un caso más específico donde no basta con "el más reciente": si puede haber un intento MÁS NUEVO sin terminar mientras se quiere mostrar específicamente el último dictamen YA emitido (o viceversa) -- para eso, GET /api/v1/procesos?persona=<persona> con el query param estado filtra por un status exacto en vez de traer siempre el más reciente sin importar cuál sea.
[
{
"process_id": "dd7196ba-...",
"embajadores_person_id": "up-000341",
"status": "EN_PROCESO",
"processing_bank_statements": false,
"rfc": "GAMA850101ABC",
"full_name": "ALICIA GARCIA MARTINEZ",
"decision_policy": null
}
]Cada elemento trae status, calculado por PRECA a partir de qué pasos ya tiene hechos ese Proceso -- nunca hay que inferirlo desde otros campos:
| Estado | En qué consiste |
|---|---|
| PENDIENTE | Todavía sin RFC, sin ingreso analizado y sin Buró. No aplica al flujo de Up Back Office -- este estado existe para Embajadores, donde el RFC llega DESPUÉS, vía un fetch asíncrono. Como Up Back Office manda el RFC directo en el Paso 1 (validado de formato antes de crear el Proceso), un Proceso de Up Back Office nace directo en EN_PROCESO y nunca pasa por aquí. |
| EN_PROCESO | El estado normal desde el Paso 1 hasta que se emite un dictamen -- cubre analizando estados de cuenta, evaluando Buró, calculando ML, todo ANTES de guardar el resultado final. Para Up Back Office, es el estado desde que se recibe la respuesta del Paso 1 hasta justo antes de llamar clasificacion/persistir con éxito. |
| COMPLETADO | Ya se llamó POST /api/v1/clasificacion/persistir con un policy_result -- decision_policy queda con un valor (ej. APPROVED) y ya no cambia mientras no se llame de nuevo con is_usuario2: true para una reevaluación (esa se guarda aparte, sin pisar el dictamen original -- ver el botón "Reevaluar" más abajo). |
Como la lista viene ordenada del más reciente al más viejo, dos casos de uso reales se resuelven con la MISMA llamada:
- El proceso vigente, para seguir capturando (retomar donde se quedó, mostrar el kanban de ingresos, etc.): el primer elemento cuyo
statusseaPENDIENTEoEN_PROCESO. - El último dictamen ya emitido, para mostrarlo en la Carta Dictamen: el primer elemento cuyo
statusseaCOMPLETADO.
Para el segundo caso no hace falta filtrar en el cliente: el query param estado hace exactamente eso del lado del servidor, incluso si esa persona tiene muchos procesos viejos de por medio.
PENDIENTE | EN_PROCESO | COMPLETADO). probado en vivo
[
{
"process_id": "dd7196ba-...",
"embajadores_person_id": "up-000341",
"status": "COMPLETADO",
"decision_policy": "APROBADO",
"policy_segment": "H1"
}
]{ "detail": "estado debe ser uno de ['COMPLETADO', 'EN_PROCESO', 'PENDIENTE'], no '...'" }Comentarios: a dónde se envían
POST /api/v1/procesos/{process_id}/comentariosEs de un solo sentido: se envía el comentario, sin necesidad de mostrar ningún historial de vuelta en pantalla — el comentario queda asociado al Proceso del lado de PRECA (visible en el panel interno de Usuario2), no algo que la Carta Dictamen deba mostrar.
{ "text": "Falta comprobante del segundo ingreso.", "author": "Carlos Ramos" }{ "id": 7, "author": "Carlos Ramos", "text": "Falta comprobante del segundo ingreso.", "created_at": "2026-09-10T02:00:00+00:00" }Botón "Reevaluar"
/policy/evaluate) y el Paso 4 (/predecir/) con los datos actualizadosNo hay un endpoint de "reevaluar" separado -- es la MISMA llamada del Paso 3b/4, con el verified_monthly_income/requested_amount que haya cambiado. Para conservar el dictamen original y guardar la reevaluación aparte (para poder comparar), se usa is_usuario2: true al llamar POST /api/v1/clasificacion/persistir -- guarda en columnas espejo (decision_policy_usuario2, etc.) sin pisar el resultado original. Es exactamente el mismo mecanismo que ya usa PRECA para separar el dictamen de Usuario1 del de Usuario2.
is_usuario2: true agregado.
{
"process_id": "dd7196ba-...",
"policy_result": { "decision": "APPROVED_WITH_CONDITIONS", "...": "el nuevo resultado del paso 3b" },
"ml_result": { "clientId": "341", "...": "el nuevo resultado de /predecir/" },
"average_monthly_labor_income_mxn": 46500.0,
"is_usuario2": true
}{ "ok": true }Botón "Añadir ingreso"
POST /api/v1/ingresos/persistirEste endpoint REEMPLAZA todos los archivos, no agrega uno solo
Si se manda files con SOLO el ingreso manual nuevo, se borran los estados de cuenta ya analizados en el Paso 2 -- así funciona persistir_estados_cuenta() del lado de PRECA (es idempotente por reemplazo, a propósito, para que un re-análisis no apile duplicados).
El flujo correcto es: (1) GET /api/v1/procesos/{id} para traer bank_statements (shape FileDetail), (2) convertir cada uno al shape FileSummary que pide este endpoint (file_name→file, ai_classification→classification en cada transacción), (3) agregar el nuevo registro manual a esa misma lista, (4) mandar la lista COMPLETA:
{
"process_id": "dd7196ba-...",
"files": [
{ "file": "bbva-mayo-2026.pdf", "...": "el mismo que ya estaba, convertido de FileDetail" },
{
"file": "Ingreso manual - honorarios",
"detected_language": "es", "detected_currency": "MXN", "applied_exchange_rate": 1.0,
"manual": true,
"transactions": [{
"date": null, "description": "Registro manual", "original_amount": 12000.0,
"original_currency": "MXN", "applied_exchange_rate": 1.0, "amount_mxn": 12000.0,
"classification": "laboral", "is_cash": false, "countable_amount_mxn": 12000.0, "manual": true
}],
"total_labor_mxn": 12000.0, "total_non_labor_mxn": 0.0, "total_uncertain_mxn": 0.0, "total_deposits_mxn": 12000.0
}
],
"average_monthly_labor_income_mxn": 42000.0
}{
"ok": true,
"files": [{ "id": 1, "file": "bbva-mayo-2026.pdf" }, { "id": 2, "file": "Ingreso manual - honorarios" }]
}average_monthly_labor_income_mxn también debe recalcularse del lado de Up Back Office (promedio de total_labor_mxn sobre los archivos sin error) -- PRECA no lo deriva solo en este endpoint.
Reglas de negocio
Fuente: Manual de Políticas de Crédito v3.1 (services/api2/app/core/config.py).
Hard checks (rechazo sin excepción, sin Comité)
| Código | Condición |
|---|---|
| HC_FRAUDE | fraud_confirmed = true |
| HC_QUEBRANTO_HIPOTECARIO | mortgage_default = true |
| HC_MOP_HIPOTECARIO_SEVERO | max_mop_mortgage > 7 (y no es 96/97/99) |
PTI / DTI por producto
| Producto | PTI máximo | DTI máximo | Coeficiente |
|---|---|---|---|
| Tradicional | 28.6% | 40.0% | 1.0x |
| Flex | 33.3% | 45.5% | 1.4x |
Segmentación H1-H4
| Segmento | Saldo vencido | % líneas atrasadas | Condicionante |
|---|---|---|---|
| H1 Óptimo | ≤ $15,000 | ≤ 20% | Ninguno |
| H2 Viable con validación | ≤ $250,000 | ≤ 40% | Obligado solidario si >40% |
| H3 Evaluación profunda | ≤ $500,000 | ≤ 60% | Cotitular si >60%; Comité si MOP hipotecario 5-7 |
| H4 Rechazo | > $500,000 | ≥ 75% + ≥179 días | — |
Tabla de decisión final
| Hard checks | Segmento | ¿Comité? | Decisión |
|---|---|---|---|
| Falló | — | — | REJECTED |
| OK | H4 | — | REJECTED |
| OK | H1/H2/H3 | Sí | COMMITTEE |
| OK | H1 | No | APPROVED |
| OK | H2 | No | APPROVED_WITH_CONDITIONS |
Clasificación de riesgo (api3)
| Probabilidad de morosidad | Clasificación |
|---|---|
| < 0.2 | Low |
| 0.2 – 0.4 | Medium |
| 0.4 – 0.6 | Moderate |
| 0.6 – 0.8 | High |
| ≥ 0.8 | Extreme |
Restricciones
El contrato de ENTRADA de api3 está congelado por el modelo entrenado
107 nombres de columna fijos (features_exp.pkl), seleccionados por nombre exacto. No se pueden renombrar sin reentrenar el modelo.
/api/v1/up-back-office/solicitud valida el FORMATO del RFC, no su existencia real
El paso 1 rechaza con 422 un RFC que no tenga la forma de un RFC mexicano (3-4 letras, 6 dígitos de fecha, 3 caracteres de homoclave) antes de guardar nada -- así el error se ve de inmediato, en el mismo paso donde se escribió, en vez de aparecer 2 pasos después como un 404 silencioso al consultar Buró. Lo que esta validación NO cubre es si el RFC existe realmente o corresponde a esa persona -- eso solo lo confirma Buró de Crédito en el paso 3a.