API de Segmentación de Escoreabilidad para Vivienda Social

Este servicio permite a FonVivienda/MIVHED transmitir a los burós de crédito el registro de un solicitante de vivienda social validado, y recibir de vuelta su segmentación de escoreabilidad (A/B/C), en tiempo real y con trazabilidad completa.

Por qué el servicio se llama así

El nombre evita una confusión que apareció en la revisión: este API no devuelve un score. Devuelve una etiqueta de segmento que indica si el solicitante es evaluable y por qué vía. Llamarlo «API de score» daría a entender que el Estado recibe el puntaje de cada ciudadano, que es exactamente lo que el proceso acordado prohíbe.

Objeto del servicio

La banca privada no ha estado financiando la vivienda social porque una porción mayoritaria de los solicitantes carece de historial crediticio tradicional y, sin historial, no existe un perfil de riesgo que sustente la decisión ni la provisión exigida por el Reglamento de Evaluación de Activos (REA).

Este API materializa el Paso 4 y el Paso 5 del proceso acordado: la consulta de evaluación desde FonVivienda hacia los burós y el retorno de la segmentación, de forma programática y sin intervención manual.

Regla de oro: qué NO retorna el buró

Cualquier implementación que incluya score, banda_riesgo, probabilidad_incumplimiento o equivalentes en la respuesta a FonVivienda incumple el API contract y será rechazada por el validador de esquema con 422 · FV-422-011. Esta restricción protege el principio de no constituir una base de scores individuales de acceso general.

Modo de intercambio

El intercambio es uno a uno: una consulta por solicitante, resuelta en línea. Es el flujo que la operación diaria necesita, porque los expedientes llegan de forma continua e incluyen reenvíos por subsanación que deben reevaluarse al momento.

Alcance y límites

Dentro del alcance

• Transmisión del registro del solicitante validado, incluido el consentimiento informado.
• Retorno de la segmentación A/B/C con códigos de razón normalizados.
• Trazabilidad completa: identificador de evaluación, de registro y de petición, con firma verificable.
• Catálogos compartidos y esquemas versionados.

Fuera del alcance

• Entrega del score o de la banda de riesgo a FonVivienda (ver regla de oro).
• El canal buró ↔ banco, que se rige por los contratos comerciales vigentes de cada entidad.
• El API de monitoreo anonimizado FonVivienda ↔ Superintendencia, que se especifica por separado.
• La consulta a fuentes de data alternativa (Unipago/TSS, servicios), que cada buró resuelve internamente.

Ruta de implementación

1. Confirmar el rol de su institución en A quién está dirigido.
2. Leer Antes de empezar y solicitar credenciales de sandbox.
3. Revisar el diccionario de datos y confirmar la disponibilidad de cada campo.
4. Implementar autenticación, firma e idempotencia.
5. Validar el payload contra los JSON Schema publicados.
6. Ejercitar el API contract en el entorno de pruebas con datos ficticios.

A quién está dirigido

Este documento se dirige a quienes deben implementar o revisar el API contract, es decir, la especificación técnica que describe cómo se comunican los sistemas. Todos los demás participantes del convenio aparecen aquí como contexto: intervienen en el proceso, pero no consumen este API.

Destinatarios de este documento

Otros actores

Participan en el proceso general de financiamiento de vivienda social, pero no intervienen en este API contract. Se enumeran para ubicar el API dentro del ecosistema.

Quién hace qué

Arquitectura y flujo de mensajes

Quién llama a quién, en qué orden y con qué mecanismo de transporte. El diagrama refleja la colaboración BPMN acordada, reducida a los intercambios que este API cubre.

Mapa de participantes

Las líneas punteadas indican intercambios fuera del alcance de este API contract. El trazo rojo señala el único canal por el que circula el score.

Secuencia del intercambio

Direcciones y responsabilidades

FonVivienda es el publicador y custodio del API contract: define los esquemas, los catálogos y las reglas de validación. Cada buró implementa el lado receptor y declara su base_url durante el registro (ver Antes de empezar).

Máquina de estados de la evaluación

En el flujo habitual la evaluación nace y termina dentro de la misma petición, en estado COMPLETADA. Los demás estados solo aparecen en la variante de respuesta diferida descrita en la referencia de endpoints.

Antes de empezar

Requisitos de habilitación, entornos disponibles y datos que cada parte debe entregar para completar el registro técnico.

Entornos

La integración recorre tres entornos independientes. Cada uno tiene su propio juego de credenciales, sus propias claves de firma y su propia base de datos: nada se comparte entre ellos. Avanzar de uno al siguiente exige superar la lista de verificación del entorno anterior.

1 · Sandbox — construir y equivocarse sin consecuencias

Primer entorno al que se conecta un buró. Existe para que el equipo de desarrollo pruebe el API contract sin ningún riesgo: si algo se rompe, no afecta a nadie.

2 · Certificación — demostrar que la integración funciona

Réplica fiel de producción en configuración y controles de seguridad, pero sin datos reales de ciudadanos. Aquí se ejecuta y se firma la lista de verificación que habilita el paso a producción. Es también el entorno donde se prueban las versiones nuevas del API contract antes de liberarlas.

3 · Producción — ciudadanos reales

Único entorno donde circulan datos de solicitantes reales, con consentimiento vigente. Todo lo que ocurre aquí queda registrado en la bitácora de auditoría y es exigible ante el regulador.

Registro del participante

Cada buró entrega a la Dirección de Tecnología de FonVivienda:

FonVivienda entrega a cada buró: client_id, client_secret, la clave HMAC de firma, su certificado de servidor y la callback_url por entorno.

Requisitos técnicos mínimos

• TLS 1.2 o superior, con preferencia por TLS 1.3. Se rechazan suites sin forward secrecy.
• Content-Type application/json; charset=utf-8. Codificación UTF-8 obligatoria — los campos de dirección y nombre contienen tildes y la letra ñ.
• Compresión gzip aceptada en petición y respuesta.
• Tamaño máximo de cuerpo: 256 KB. Un registro de solicitante bien formado pesa alrededor de 2 KB; superar el límite devuelve 413.
• Reloj sincronizado por NTP con desviación menor a 60 segundos: la firma incorpora marca de tiempo con ventana antirreplay de 300 segundos.
• Soporte de idempotencia con retención de 24 horas por clave.

Cabeceras obligatorias

Lista de verificación de certificación

Para promover una integración a producción, el buró debe demostrar en el entorno de certificación:

• Resolución síncrona correcta de 1 000 evaluaciones sintéticas consecutivas, dentro del objetivo de latencia.
• Rechazo con 422 de registros inválidos, con el detalle por campo y el código de negocio correspondiente.
• Comportamiento idempotente ante un reenvío con la misma Idempotency-Key.
• Rechazo con 401 ante firma inválida y ante marca de tiempo fuera de la ventana antirreplay.
• Ejecución del modo asíncrono: 202, callback firmado y reintento correcto ante un 500 simulado del receptor.
• Ausencia total de score, banda_riesgo o campos equivalentes en la respuesta.
• Respeto de los límites de tasa con cabeceras RateLimit-* y Retry-After.

Datos que se envían

Diccionario completo del registro del solicitante: las 33 columnas del archivo de muestra del piloto, su equivalente en el modelo JSON, sus reglas de validación y su clasificación de sensibilidad.

Origen de la especificación

El modelo de datos se deriva literalmente del archivo data de ejemplo.xlsx entregado como muestra del piloto: 14 registros del programa Familia Feliz, con nombres y cédulas enmascarados, y 33 columnas (A a AG). Nada se ha inventado: cada campo del JSON tiene una columna de origen trazable, y los campos nuevos se identifican explícitamente.

Diccionario de datos

Clasificación de sensibilidad

Campos que añade el API contract

No existen en el Excel y son obligatorios en el API:

Muestra de datos

Los 14 registros del archivo, con la identificación, los nombres, apellidos y correos ya enmascarados en el origen, y el identificador de hogar sustituido por su forma seudonimizada.

Registro completo en JSON

El registro 1 de la muestra, transformado al modelo del API contract. Obsérvese la normalización de los campos multivalor (Profesión y Contrato laboral vienen separados por ; en el archivo) y el uso de null con campo de disponibilidad.

Catálogos y códigos

Valores admitidos en los campos enumerados. Los catálogos se sirven además por GET /catalogos/{id} con ETag, de modo que la integración no tenga que codificarlos de forma rígida.

Segmentación de escoreabilidad

Códigos de razón de la segmentación

Se devuelven en resultados[].motivos[]. Explican por qué el solicitante quedó en ese segmento, sin revelar el peso ni la fórmula del modelo propietario.

JSON Schema

Esquemas normativos en JSON Schema draft 2020-12. Son la fuente de verdad del API contract: ante cualquier discrepancia entre esta documentación y el esquema, prevalece el esquema.

Descarga y resolución de referencias

Los esquemas se publican en GET /esquemas/{nombre} y se identifican con un $id absoluto y versionado. Se recomienda cachearlos por ETag y validar en tiempo de compilación, no de ejecución.

Esquema del solicitante

Objeto que describe al solicitante. Es la carga útil de POST /evaluaciones en sus dos modos.

Esquema de la petición de evaluación

Sobre que envuelve al solicitante con los metadatos del intercambio.

Esquema del acuse asíncrono

Respuesta 202 cuando la petición se envía con Prefer: respond-async.

Esquema del resultado y del callback

Mismo objeto resultado para la respuesta 200 del modo síncrono, para GET /evaluaciones/{id} y para el evento evaluacion.completada entregado a la callback_url. Nótese la ausencia deliberada de cualquier campo de score.

Esquema de error

Todos los errores siguen RFC 9457 (Problem Details for HTTP APIs) con extensiones propias del API contract.

Documento OpenAPI

Especificación OpenAPI 3.1 del servicio, apta para generar clientes y servidores. Se muestra abreviada; la descarga contiene el documento completo.

Referencia de endpoints

Nueve operaciones cubren el ciclo completo: obtención de token, evaluación síncrona y asíncrona, consulta de una evaluación, callback de retorno, revocación de consentimiento, catálogos, esquemas y sonda de salud.

Códigos HTTP y errores

Semántica exacta de cada código de estado, si debe reintentarse y qué acción corresponde. Un cliente correctamente implementado se comporta de forma distinta ante un 429 y ante un 422: el primero se reintenta, el segundo nunca.

Respuestas de éxito

Errores del cliente (4xx)

Salvo 408, 425 y 429, ningún 4xx debe reintentarse sin modificar la petición.

Errores del servidor (5xx)

Formato del cuerpo de error

Content-Type application/problem+json conforme a RFC 9457.

Catálogo de códigos de negocio

El campo codigo del cuerpo de error es estable entre versiones y es el que deben usar los clientes para bifurcar su lógica; el texto de title y detail puede cambiar.

Política de reintentos

Superados los 6 intentos, el envío se marca como fallido, se registra el X-Request-Id del último intento y se notifica al buzón técnico. No se reintenta indefinidamente: una evaluación atascada bloquea el enrutamiento de ese expediente.

Autenticación y firma

Tres controles se aplican de forma acumulativa: identidad del canal por mTLS, autorización por OAuth 2.0 y autenticidad e integridad del mensaje por firma HMAC-SHA256.

Las tres capas

Obtención del token

• Vigencia del token: 900 segundos. Debe renovarse de forma proactiva al 80 % de su vida.
• No se emiten refresh tokens: el flujo es de máquina a máquina.
• El token es un JWT firmado con RS256; las llaves públicas se publican en /.well-known/jwks.json.
• Nunca debe registrarse el token completo en bitácoras. Registrar únicamente su jti.

Alcances

Firma del mensaje

La cabecera X-FV-Signature transporta la marca de tiempo y la firma:

Construcción de la cadena a firmar

1. Obtener t = segundos Unix del momento del envío.
2. Serializar el cuerpo JSON exactamente como se transmitirá, byte a byte. No se aplica canonicalización: se firma lo que viaja.
3. Concatenar t, un punto y el cuerpo: "{t}.{cuerpo}".
4. Calcular HMAC-SHA256 con la clave secreta compartida y codificar el resultado en hexadecimal minúsculo.

Verificación en el receptor

• Rechazar si |ahora − t| > 300 segundos → 401 · FV-401-005.
• Comparar en tiempo constante (crypto.timingSafeEqual) para evitar ataques de temporización.
• Rechazar si el par (t, v1) ya se procesó dentro de la ventana → 409 · FV-409-002.
• Durante la rotación de claves se aceptan simultáneamente la clave vigente y la anterior, por 7 días.

Idempotencia

Todo POST exige Idempotency-Key con un UUID v4. El receptor guarda, por clave, la huella SHA-256 del cuerpo y la respuesta emitida durante 24 horas.

Límites de uso

Toda respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al agotarse la cuota se devuelve 429 con Retry-After en segundos.

Rotación de credenciales

• Clave HMAC: rotación semestral programada, con solapamiento de 7 días.
• Certificado mTLS: vigencia máxima de 12 meses; aviso a los 60, 30 y 7 días.
• client_secret: rotación anual o inmediata ante sospecha de compromiso.
• Ante un incidente, la revocación es efectiva en menos de 15 minutos y se notifica por el canal de seguridad registrado.

Consentimiento y datos personales

El consentimiento informado del potencial deudor es condición habilitante de todo el intercambio. Sin él, la consulta de información crediticia —tradicional o alternativa— carece de base legal.

El objeto de consentimiento

Evidencia y verificabilidad

FonVivienda conserva la evidencia original (formulario firmado, asiento de aceptación digital con sello de tiempo o grabación) y transmite únicamente su huella criptográfica. Ante un requerimiento del titular o del regulador, la huella permite demostrar que la evidencia no ha sido alterada.

Revocación

Cuando un ciudadano revoca su consentimiento, FonVivienda notifica al buró por POST /consentimientos/revocaciones con el registro_id y la identificacion. El buró debe:

• Detener toda consulta futura asociada a ese titular en un plazo máximo de 24 horas.
• Marcar los resultados previos como derivados de un consentimiento revocado.
• Confirmar la ejecución con 202 y un identificador de tratamiento.

Si la revocación llega mientras una evaluación está EN_PROCESO, esta se resuelve como segmento C con motivo SEG-C-04.

Minimización y retención

Trazabilidad y auditoría

Cada consulta genera un asiento inmutable con: X-Request-Id, registro_id, buro_id, marca de tiempo, resultado de segmento y referencia del consentimiento. Nunca se registra el cuerpo completo con datos personales en bitácoras de aplicación; los campos de nivel Alto y Crítico se enmascaran antes de escribir.

Entorno de pruebas

Genere una petición con datos ficticios, fírmela y envíela al endpoint que usted indique —el receptor de su buró o un servicio de captura de peticiones— para verificar el contrato de extremo a extremo sin escribir una sola línea de código.

Paso 1 · Destino

Indique dónde debe recibirse la petición. Si aún no tiene un receptor, cree un endpoint temporal en un servicio de captura de peticiones y pegue aquí la URL.

Paso 2 · Generar la petición

Se construye a partir de un registro de la muestra del piloto, con cédula sintética de dígito verificador válido e identificador de hogar seudonimizado.

Paso 3 · Validar contra el esquema

Validación local contra el subconjunto normativo del JSON Schema: tipos, obligatoriedad, patrones, enumeraciones, rangos y las reglas cruzadas FV-422-1xx.

Paso 4 · Firmar y enviar

Al enviar se calcula la firma HMAC-SHA256 sobre {timestamp}.{cuerpo} y se arma el juego completo de cabeceras del API contract.

«Enviar en serie» ejecuta 14 peticiones consecutivas, una por solicitante, como haría el cliente real: el API contract no admite agrupar registros en una sola llamada.

Cabeceras que se enviarán

Paso 5 · Respuesta

Consola

Cuerpo de la respuesta

Simulador del callback del buró

Genera el evento evaluacion.completada que el buró enviaría de vuelta a la callback_url de FonVivienda. Sirve para que el equipo de FonVivienda construya y pruebe su receptor antes de que el buró esté listo.

Equivalente en cURL

Copie y ejecute desde una terminal si su receptor no admite peticiones desde el navegador.

Ejemplos de código

Implementaciones de referencia del envío firmado y de la recepción del callback, en las tecnologías de uso más frecuente en el sector.

cURL

Python

Con requests y la biblioteca estándar. Incluye reintentos con retroceso exponencial e idempotencia estable.

C# / .NET

Node.js — receptor del callback

Lado FonVivienda: verificación de firma en tiempo constante y ventana antirreplay antes de aceptar el resultado.

Java