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.

ExpedienteIngresosBuróResultado
Auth de hoy: toda llamada pasa primero por APIM, que exige un token Bearer de Entra ID (App Registration propia de Up Back Office, flujo client credentials -- confirmado en vivo el 10/sep). /api/v1/up-back-office/solicitud no pide nada más de este lado -- decisión explícita del equipo: se confía en APIM para ESE endpoint, sin una segunda clave de aplicación encima. Todo lo demás (Buró, api2, api3, comentarios, persistir) sigue pidiendo además el secreto compartido interno por X-API-Key. Detalle completo en Entornos.

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.

AmbienteFrontendapi1 (base, detrás de APIM)api2api3
Desarrollopreca-dev.hircasa.com.mxapi-qa.bprcasa.com/hircasamlsbackendpreca-api1-dev...-api2-dev...-api3-dev
QApreca-qa.hircasa.com.mxapi-qa.bprcasa.com/hircasamlsbackendpreca-api1-qa...-api2-qa...-api3-qa
Producciónpreca.hircasa.com.mxapi.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.

#CredencialProtegeA quién pedirla
1Token Bearer de Entra IDLa puerta de entrada en APIM, antes de llegar al código -- toda llamada la necesita, sin excepciónTenant 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.
2Secreto compartido internoTodo EXCEPTO /api/v1/up-back-office/solicitud: Buró, policy/evaluate, /predecir/, clasificacion/persistir, comentarios, ingresos/persistirHIR 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.

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óndeCampoTipoQuién lo asigna
api1 (paso 1)personastring, libreUp Back Office
api1 (paso 2, dentro de ProcessDetail)prospect_idstring (numérico)PRECA -- generado determinísticamente a partir del RFC
api2 (paso 3)application.client_idstring (1-50 caracteres)Up Back Office
api3 (paso 5)Prospecto.ProspectoIdstring (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.

Paso 1 · Expediente

Entregar la Solicitud y los documentos

Si el analista termina de capturar la Solicitud y los documentos del prospecto (Solicitud de inscripción, identificación, comprobantes de ingreso) — se usa: POST /api/v1/up-back-office/solicitud
POST /api/v1/up-back-office/solicitud Envía la Solicitud y los Estados de Cuenta (archivos crudos) de una sola vez. probado en vivo hoy
Request (recortado)
{
  "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..." }
  ]
}
Response 200 — capturada en vivo
{
  "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ódigoCuándoBody
401Rechazo 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.

se espera a que termine el análisis
Paso 2 · Clasificación de Ingresos

Depósitos clasificados, listos para reclasificar

Si el analista entra a la pantalla de Clasificación de Ingresos (o sigue ahí mientras el análisis termina) — se usa: 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.

GET /api/v1/procesos/ultimo?persona={persona} Se hace polling sobre esta misma llamada (ej. cada 3s) hasta que processing_bank_statements sea false. probado en vivo
Mientras sigue analizando
{
  "process_id": "dd7196ba-...",
  "processing_bank_statements": true,
  "bank_statements": []
}
Cuando termina (recortado)
{
  "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)

Si el analista arrastra una transacción a otra columna (laboral / no laboral / incierto) y ese cambio debe quedar auditado del lado de PRECA (IA vs. usuario) — se usa: POST /api/v1/procesos/{process_id}/correcciones
POST/api/v1/procesos/{process_id}/correcciones Un solo request puede mandar varias reclasificaciones juntas.
Request
{
  "corrections": [
    {
      "entity_id": "archivo_1_transaccion_0",
      "field": "ai_classification",
      "original_ai_value": "laboral",
      "user_corrected_value": "no_laboral"
    }
  ]
}
Response 200
{ "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

Si después de reclasificar se vuelve a consultar el proceso (retomar, refrescar, otra pantalla) y debe verse lo que corrigió el analista, no lo que dijo la IA — se usa: POST /api/v1/procesos/{process_id}/correcciones?aplicar=true

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

Response 200 con aplicar=true
{ "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.

con el RFC ya conocido
Paso 3 · Clasificación de Buró

Score, PTI/DTI y el checklist de criterios

Si el analista avanza a la pantalla de Clasificación de Buró (score y checklist "Cumple / Observación") — se usa, en este orden: POST /api/v1/buro/consultar-api → POST /api/v1/policy/evaluate

3a. Reporte de Buró (lo sigue consultando PRECA)

POST /api/v1/buro/consultar-api Con el RFC ya obtenido en el paso 1. ejemplo representativo -- sin acceso al facade real desde aquí
Request
{
  "process_id": "dd7196ba-...",
  "rfc": "GAMA850101ABC"
}
Response 200 (recortado)
{
  "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

POST /api/v1/policy/evaluate Con el ingreso consolidado del paso 2 y los indicadores del paso 3a. respuesta capturada en vivo
Request
{
  "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
  }
}
Response 200
{
  "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.

Paso 4 · Resultado

Montos, dictamen y la tarjeta final de perfil

Si el analista llega a la pantalla de Resultado (ingreso mínimo, monto máximo, dictamen Viable/No viable, tarjeta de perfil con probabilidad de riesgo) — se usa: la respuesta del paso 3b (arriba) + 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 pantallaCampo
Ingreso mínimo mensualfinancial_indicators.required_income
Monto máximo alcanzadofinancial_indicators.max_eligible_amount
Dictamen Viable / No viabledecision === "APPROVED"
POST /predecir/ Solo si el paso 3b regresó segment. Una llamada regresa Flex Y Tradicional juntos. respuesta capturada en vivo
Request (recortado -- shape completo en el diagrama)
{
  "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" }]
  }
}
Response 200
{
  "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.

Niveltitledescriptionactions
AA - Perfil ÓptimoCliente con probabilidad baja de incumplimiento. Se puede otorgar proceso ágil bajo controles operativos estándar.Proceso agil · Anticipos permitidos bajo politica general
BB - Perfil Viable con ValidaciónCliente con riesgo controlable. Requiere mitigantes estructurales antes de adjudicación.Domiciliacion obligatoria · Evaluar obligado solidario · Seguimiento trimestral
CC - Perfil con Evaluación ProfundaCliente 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
DD - Perfil BajoCliente 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
EE - Perfil Bajo - RechazoCliente 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.

SegmentoPoliticaLowMediumModerateHighExtreme
H1AABCE
H2ABBDE
H3BCCDE
H4CDDE (cualquier otro caso)E
"Tasa preferencial disponible" -- si algún documento de referencia trae ese texto como una acción más del nivel A, no está en 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.
Gotcha — 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.

Los campos de catálogo también aceptan su equivalente en inglés (columna derecha de la tabla) — api3 lo traduce internamente al español antes de calcular, así que el resultado es idéntico mandando cualquiera de los dos idiomas. Ojo: ese catálogo en inglés es una PROPUESTA (de Claude, armada en esta sesión) — gobernanza todavía no cerraba su propio diccionario oficial al momento de escribir esto. Si gobernanza define después otros nombres en inglés, hay que actualizar 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.
CampoValores válidos (español)Inglés (borrador, ver gotcha arriba)
EstadoCivilSOLTERO | CASADO | UNIÓN LIBRE | DIVORCIADO | VIUDOSINGLE | MARRIED | DOMESTIC_PARTNERSHIP | DIVORCED | WIDOWED
TipoViviendaPROPIA | PROPIA HIPOTECADA | RENTADAOWNED | MORTGAGED | RENTED
GradoEstudioPRIMARIA | SECUNDARIA | MEDIO_SUPERIOR | TÉCNICO | LICENCIATURA_POSGRADO | NINGUNA_DE_LAS_ANTERIORESELEMENTARY | MIDDLE_SCHOOL | HIGH_SCHOOL | TECHNICAL | BACHELOR_OR_HIGHER | NONE_OF_THE_ABOVE
SegmentoPoliticaH1 | H2 | H3 | H4 (el mismo segment.code del paso 3b)No aplica — ya es un código, no una palabra
PuestoDUEÑ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)
GiroSALUD | 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 | ADMINISTRACIONHEALTHCARE | 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
PaisMÉ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.
TipoIngreso0 = 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.

POST /predecir/
Request
{
  "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).

Gotcha — el score de Buró tiene un piso de 300 antes de llamar /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

Si el analista ya vio el Resultado en pantalla y ese dictamen debe quedar medido del lado de PRECA (panel interno, auditoría, métricas de PSI/calidad) — se usa: 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ó.

POST/api/v1/clasificacion/persistir policy_result es la respuesta completa del paso 3b, ml_result la de /predecir/, tal cual, sin transformar.
Request
{
  "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", "...": "..." }
  }
}
Response 200
{ "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

Si no se quiere reconstruir a mano los payloads del paso 3b (/policy/evaluate) ni de este paso (/predecir/) — se usa: 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ó 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.

GET /api/v1/procesos/{process_id}/resultado?producto=flex respuesta capturada en vivo, con predicción real del modelo
Response 200 (recortado)
{
  "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

Si el analista quiere el documento OFICIAL del dictamen (para archivar, mandar por correo, o entregar al prospecto/Comercial) — se usa: GET /api/v1/procesos/{process_id}/carta-dictamen.pdf

Arma 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/{process_id}/carta-dictamen.pdf Regresa el archivo binario, no JSON. respuesta capturada en vivo
Request
GET /api/v1/procesos/dd7196ba-.../carta-dictamen.pdf
Authorization: Bearer <token de Entra ID>
X-API-Key: <secreto compartido interno>
Response 200
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"
}
stageSignificaSe considera hecho cuando
applicationFalta la Solicitud (Paso 1)application trae datos
incomeFalta el ingreso comprobado (Paso 2). Si processing_bank_statements es true, next_action dice esperaraverage_monthly_labor_income_mxn no es null (0 cuenta como hecho)
bureauFalta consultar Buró (Paso 3a)bureau trae datos
policyFalta el dictamen de política (Paso 3b) guardado en PRECApolicy trae datos — solo se llena con POST /clasificacion/persistir; /resultado calcula pero no guarda
mlFalta la predicción de riesgo (Paso 4) guardadaml trae datos, o policy.segment es null (hard_checks rechazó: sin segmento no hay ML que correr)
completeNo falta nada; next_action es nullTodo 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.

GET/api/v1/procesos/ultimo?persona={persona} 404 si esa persona nunca tuvo un Proceso. probado en vivo
Response 200 (recortado)
{
  "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.

GET/api/v1/procesos?persona={persona} Regresa una LISTA, ordenada del más reciente al más viejo (puede haber más de un Proceso histórico para la misma persona) -- ProcessSummary, no el detalle completo.
Response 200 (recortado)
[
  {
    "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:

EstadoEn qué consiste
PENDIENTETodaví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_PROCESOEl 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.
COMPLETADOYa 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 status sea PENDIENTE o EN_PROCESO.
  • El último dictamen ya emitido, para mostrarlo en la Carta Dictamen: el primer elemento cuyo status sea COMPLETADO.

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.

GET/api/v1/procesos?persona={persona}&estado=COMPLETADO Mismo endpoint, con el filtro aplicado antes de ordenar/recortar -- regresa solo Procesos con ese status exacto (PENDIENTE | EN_PROCESO | COMPLETADO). probado en vivo
Response 200
[
  {
    "process_id": "dd7196ba-...",
    "embajadores_person_id": "up-000341",
    "status": "COMPLETADO",
    "decision_policy": "APROBADO",
    "policy_segment": "H1"
  }
]
422 — valor de estado que no existe
{ "detail": "estado debe ser uno de ['COMPLETADO', 'EN_PROCESO', 'PENDIENTE'], no '...'" }

Comentarios: a dónde se envían

Si el analista de Up Back Office deja una nota (ej. "Falta comprobante del segundo ingreso") — se envía a: POST /api/v1/procesos/{process_id}/comentarios

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

POST/api/v1/procesos/{process_id}/comentarios
Request
{ "text": "Falta comprobante del segundo ingreso.", "author": "Carlos Ramos" }
Response 200
{ "id": 7, "author": "Carlos Ramos", "text": "Falta comprobante del segundo ingreso.", "created_at": "2026-09-10T02:00:00+00:00" }

Botón "Reevaluar"

Si el analista corrige algo (reclasificación manual, ingreso corregido) y aprieta "Reevaluar" — se usa: repetir el Paso 3b (/policy/evaluate) y el Paso 4 (/predecir/) con los datos actualizados

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

POST/api/v1/clasificacion/persistir Mismo endpoint de la sección anterior, con is_usuario2: true agregado.
Request (recortado)
{
  "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
}
Response 200
{ "ok": true }

Botón "Añadir ingreso"

Si el analista agrega un ingreso manual (sin PDF) desde el botón "Añadir ingreso" — se usa: POST /api/v1/ingresos/persistir

Este 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:

POST/api/v1/ingresos/persistir La lista completa: lo que ya había + el registro manual nuevo.
Request (recortado)
{
  "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
}
Response 200
{
  "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ódigoCondición
HC_FRAUDEfraud_confirmed = true
HC_QUEBRANTO_HIPOTECARIOmortgage_default = true
HC_MOP_HIPOTECARIO_SEVEROmax_mop_mortgage > 7 (y no es 96/97/99)

PTI / DTI por producto

ProductoPTI máximoDTI máximoCoeficiente
Tradicional28.6%40.0%1.0x
Flex33.3%45.5%1.4x

Segmentación H1-H4

SegmentoSaldo vencido% líneas atrasadasCondicionante
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 checksSegmento¿Comité?Decisión
Falló——REJECTED
OKH4—REJECTED
OKH1/H2/H3SíCOMMITTEE
OKH1NoAPPROVED
OKH2NoAPPROVED_WITH_CONDITIONS

Clasificación de riesgo (api3)

Probabilidad de morosidadClasificación
< 0.2Low
0.2 – 0.4Medium
0.4 – 0.6Moderate
0.6 – 0.8High
≥ 0.8Extreme

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.