Verificación de Pagos Inteligente

Un contratista de la Universidad Nacional debe demostrar, cada mes, que sus aportes a seguridad social están al día antes de que le paguen. Esta aplicación toma ese trámite completo — leer el contrato, el certificado ARL y la planilla PILA, contrastar las cifras con la normativa colombiana y llenar los formatos institucionales — y lo convierte en un asistente de cuatro pasos para la dependencia universitaria que gestiona esos pagos.

Arquitectura y Stack Tecnológico

Arquitectura Central

• Framework: Next.js 16 (App Router), TypeScript, desplegado en Vercel
• Extracción con IA: Vercel AI SDK sobre una cadena de modelos Mistral + OpenAI con fallback automático
• Lectura de documentos: extracción nativa de texto para PDFs digitales y OCR para escaneados y pantallazos
• Reglas de negocio: motor de cálculo puro, parametrizado por vigencia
• Validación: esquemas Zod por tipo de documento (contrato, ARL, planilla, informe)
• Generación de PDF: los formatos oficiales se llenan y se unen con sus anexos
• Estado: store de Zustand a lo largo de los pasos del asistente
• UI: shadcn/ui + Tailwind CSS 4
• Analítica: PostHog detrás de una whitelist tipada de eventos

Arquitectura en Capas

El navegador nunca habla directo con un modelo: cada extracción pasa por un route handler que devuelve NDJSON en streaming, así el asistente va pintando los campos a medida que se reconocen en vez de esperar al documento completo.

Flujo de una Petición

Características Principales

Características de un Vistazo

Carga de varios documentos

Contrato, certificado ARL, planilla PILA pagada y — cuando el contrato lo exige — el informe de actividades, todos de una vez. Cada archivo se perfila y valida antes de la extracción, de modo que un documento equivocado se detecta en la puerta y no a mitad del flujo.

Extracción con nivel de confianza por campo

El modelo devuelve cada campo marcado con su nivel de confianza. El paso 2 muestra esas marcas, así el esfuerzo de revisión se concentra en lo realmente dudoso en vez de releerlo todo. El usuario corrige en línea y los valores corregidos alimentan el resto del flujo.

Validación contra la normativa

Aportes, vigencia y cobertura de la ARL, plazos PILA, porcentajes del informe y la certificación tributaria los revisa cada uno un validador independiente. Cada hallazgo cita la norma exacta de la que sale — y solo normas cuyo texto se verificó directamente.

Motor de cálculo del formato 069

Un motor puro, sin efectos secundarios, calcula la base de aportes y las deducciones. Los parámetros de cada vigencia viven en archivos propios por año, así que pasar la app a un año nuevo es un cambio de parámetros, no una reescritura.

Salida lista para firma

Los dos formatos institucionales oficiales se llenan y se unen con sus anexos en un único PDF descargable.

Destacados Técnicos

No se cita lo que no se ha leído

El catálogo de normas solo lleva reglas cuyo texto se verificó de primera mano, y la regla se extiende a cada frase entrecomillada dentro de los mensajes de validación. Cuando una fuente no se puede abrir, la app lo dice en vez de reconstruirla — en un trámite que termina en una firma, una cita verosímil es peor que ninguna cita.

Analítica que no puede filtrar a una persona

La capa de analítica admite solo enums, conteos, booleanos y claves de campo — nunca valores, nombres, cédulas, montos ni contenido de documentos. La whitelist es un tipo, así que TypeScript la impone en compilación. Los identificadores de regla tampoco se renombran: identifican la situación, no la redacción, así la serie histórica en PostHog sigue siendo comparable.

Manda el Excel oficial

Cuando la investigación normativa y el .xlsx oficial se contradicen, gana el Excel: la app debe reproducir el formato que la Universidad realmente recibe, no el que la norma sugiere.

Nunca sobrescribir en silencio una declaración

Estos formatos son declaraciones firmadas, así que la app nunca normaliza lo que la persona declaró. Cuando detecta una inconsistencia levanta un aviso y deja decidir a la persona, en vez de corregir en silencio un campo que alguien está a punto de firmar.

Fechas que muchas veces no están

Cerca de la cuarta parte de los contratos expresa el plazo solo en días ("doscientos sesenta y ocho (268) días calendario"), así que no se puede leer ninguna fecha de inicio ni de fin, solo una duración. La app infiere las fechas desde el certificado ARL únicamente cuando el emparejamiento es inequívoco; si no, el usuario teclea la fecha de inicio y la de fin se deriva de ella, sin pisar nunca una fecha de fin ya puesta.

Un corpus de casos como arnés de pruebas

Un corpus de fixtures empareja documentos representativos con su resultado esperado — distintos operadores, aseguradoras y formas de contrato, más los casos incómodos: escaneados, pantallazos, páginas rotadas, cobertura vencida, aportes incompletos, varias planillas. Más de una heurística "obvia" ha fallado contra él, y por eso cada cambio de regla o de extractor se vuelve a pasar por el corpus antes de salir. "Funciona con mi documento" no es evidencia.

Impacto y Escalabilidad

• Reemplaza un trámite completamente manual: leer cada documento a mano, cruzar cifras y digitar los formatos.
• El tiempo de revisión se concentra en los campos de baja confianza en vez de en todos.
• Pasar a una vigencia nueva es un solo archivo de parámetros.
• El corpus de casos hace que cada cambio de regla sea verificable antes de salir.
• El uso se mide en PostHog sin guardar un solo valor personal.

---

Notas

Construido con Next.js 16, el Vercel AI SDK sobre Mistral y OpenAI, @pdfme, Zod y shadcn/ui. El repositorio es privado — pertenece al Centro de Prototipado de la Universidad Nacional de Colombia.