API del backend: qué JSON lee el frontend
Base: http://localhost:8080. Todo es JSON en UTF-8. La misma información, navegable, está en Swagger: http://localhost:8080/swagger-ui.html (el JSON de OpenAPI está en /v3/api-docs).
El backend no filtra ni pagina: entrega los datos y el frontend filtra, busca, pagina y calcula los indicadores.
Resumen de endpoints
| Método y ruta | Pantalla que lo usa | Devuelve |
|---|---|---|
GET /api/jobs |
Jobs | Jobs disponibles |
GET /api/datasets |
Jobs | Carpetas de data/ |
POST /api/executions |
Jobs | La ejecución creada |
GET /api/executions |
Ejecuciones, Jobs, Calidad | Historial |
GET /api/executions/{id} |
Ejecuciones | Estado, resultado y etapas |
GET /api/executions/{id}/log |
Ejecuciones | Texto: salida del proceso |
GET /api/executions/{id}/quality |
Calidad | Reporte de calidad |
GET /api/executions/{id}/rejected |
Calidad | Filas rechazadas y su motivo |
GET /api/dashboard/performance |
Dashboard | Filas de la tabla RENDIMIENTO |
GET /api/dashboard/courses |
Dashboard | Filas de la tabla CURSOS_RESUMEN |
GET /api/dashboard/tables |
Dashboard | Conteo de filas de cada tabla |
GET /api/dashboard/loads |
Dashboard | Filas insertadas y actualizadas por cada carga |
Jobs
GET /api/jobs
[
{ "type": "RENDIMIENTO_ACADEMICO", "label": "Rendimiento académico", "input": "DATASET" },
{ "type": "ALERTA_ASISTENCIA", "label": "Alerta de Asistencia", "input": "DATASET" },
{ "type": "CARGA_ORACLE", "label": "Carga a Oracle (insertar y actualizar)", "input": "EXECUTION" },
{ "type": "LECTURA_ORACLE", "label": "Lectura desde Oracle", "input": "NONE" }
]
input dice qué debe enviar el formulario:
| Valor | Qué se envía en POST /api/executions |
|---|---|
DATASET |
dataset: una carpeta de GET /api/datasets |
EXECUTION |
sourceExecutionId: una ejecución de RENDIMIENTO_ACADEMICO en estado SUCCEEDED |
NONE |
Nada más |
GET /api/datasets
["con-errores", "limpio"]
Ejecuciones
POST /api/executions
Cuerpo:
{ "jobType": "CARGA_ORACLE", "dataset": null, "sourceExecutionId": "91b4edb1-ee70-4392-b37a-46d7eea1e108" }
Responde 202 con la ejecución (misma forma que un elemento de GET /api/executions), en estado RUNNING.
GET /api/executions
De la más reciente a la más antigua.
[
{
"id": "2863f42f-1842-4ad9-a85d-b16da73be0a4",
"jobType": "RENDIMIENTO_ACADEMICO",
"jobLabel": "Rendimiento académico",
"status": "SUCCEEDED",
"dataset": "con-errores",
"sourceExecutionId": null,
"startedAt": "2026-11-15T17:43:32.482Z",
"finishedAt": "2026-11-15T17:43:58.120Z",
"durationMs": 25638,
"exitCode": 0
}
]
status |
Significado |
|---|---|
RUNNING |
El proceso de Spark sigue corriendo. finishedAt, durationMs y exitCode son null |
SUCCEEDED |
Terminó bien |
REJECTED |
La puerta de calidad bloqueó el lote (demasiadas filas rechazadas) |
FAILED |
El proceso falló; el motivo está en el log |
GET /api/executions/{id}
{
"execution": { "id": "…", "jobType": "CARGA_ORACLE", "status": "SUCCEEDED", "…": "…" },
"result": {
"published": true,
"rowsByTable": { "SEMESTRES": 6, "CURSOS": 9, "ESTUDIANTES": 120, "NOTAS": 4320, "ASISTENCIA": 17280, "RENDIMIENTO": 1080, "CURSOS_RESUMEN": 9 },
"loads": [ { "table": "ESTUDIANTES", "inserted": 1, "updated": 119 } ],
"totalRows": 22824,
"insertedRows": 230,
"updatedRows": 22594,
"durationMs": 10344
},
"stages": []
}
resultesnullmientras el job no termina. Su forma depende del job:CARGA_ORACLE:rowsByTable,loads(por tabla:insertedyupdated),totalRows,insertedRows,updatedRows,durationMs.LECTURA_ORACLE:rowsByTable,totalRows,durationMs.RENDIMIENTO_ACADEMICOyALERTA_ASISTENCIA:received,accepted,rejected,rejectedRatio,maxRejectedRatio,goldRows,durationMs.
stagessolo tiene datos en los jobs de transformación. Cada elemento:stage(BRONZE,VALIDATION,QUARANTINE,SILVER,QUALITY_GATE,GOLD,EXPORT),status(RUNNING,COMPLETED,BLOCKED,SKIPPED,FAILED),timestamp,rows,durationMs,detail. Una etapa aparece dos veces (al empezar y al terminar): el frontend se queda con la última.
GET /api/executions/{id}/log
Texto plano con las últimas 200 líneas de la salida del proceso.
Calidad de datos
Solo existe en ejecuciones de RENDIMIENTO_ACADEMICO y ALERTA_ASISTENCIA.
GET /api/executions/{id}/quality
{
"rulesVersion": "2.0.0",
"received": 21759,
"accepted": 21514,
"rejected": 245,
"rejectedRatio": 0.01126,
"maxRejectedRatio": 0.05,
"published": true,
"decision": "Publicado: las filas válidas pasan a Gold y las observadas quedan en cuarentena",
"tables": [
{ "table": "notas", "received": 4331, "accepted": 4265, "rejected": 66, "rejectedRatio": 0.015239, "withinTolerance": true }
],
"dimensions": { "COMPLETITUD": 1, "VALIDEZ": 35, "UNICIDAD": 13, "INTEGRIDAD": 191, "CONSISTENCIA": 5 },
"reasons": [
{ "table": "notas", "rule": "NOTA_FUERA_DE_RANGO", "dimension": "VALIDEZ", "description": "La nota esta fuera de la escala 0 a 20", "rows": 11 }
],
"checks": [
{ "name": "Rechazo en notas", "passed": true, "detail": "66 de 4331 filas rechazadas (1.52 %); máximo 5.00 %" }
]
}
| Campo | Para qué sirve en la pantalla |
|---|---|
received, accepted, rejected |
Filas que llegaron, las que se quedaron y las que no |
rejectedRatio, maxRejectedRatio |
Porcentaje rechazado y el máximo que se tolera |
published, decision |
Si el lote pasó la puerta de calidad y por qué |
tables |
Lo mismo, por tabla |
dimensions |
Rechazos por tipo de problema |
reasons |
Cada regla incumplida: tabla, regla, descripción y cuántas filas |
checks |
Los controles que deben cumplirse para publicar |
Responde 404 si la ejecución no tiene reporte de calidad.
GET /api/executions/{id}/rejected
Las filas que no pasaron, con el motivo y el registro original tal como venía en el CSV.
[
{
"tabla": "asistencia",
"fila": 1528,
"clave": "VG260011 · EIA · 2026-II · 7",
"motivos": ["ESTADO_INVALIDO"],
"registro": { "estudiante_id": "VG260011", "curso_id": "EIA", "periodo": "2026-II", "semana": "7", "fecha": "2026-09-28", "estado": "X" }
}
]
fila es el número de línea en el CSV de origen. motivos puede traer más de una regla. Si no hubo rechazos, devuelve [].
Dashboard (lee de Oracle)
GET /api/dashboard/performance
Una fila por estudiante y curso, de la tabla RENDIMIENTO.
[
{
"estudiante_id": "VG260041",
"nombres": "Fabricio",
"apellidos": "Aguilar Huertas",
"seccion": "B",
"curso_id": "APS",
"curso": "Administración de Proyectos de Sistemas",
"periodo": "2026-II",
"promedio": 16.1,
"nota_final": 16,
"asistencia_pct": 1,
"condicion": "APROBADO"
}
]
asistencia_pctva de 0 a 1.promedioynota_finalpueden sernull(matrícula con evaluaciones pendientes).condicion:APROBADO,DESAPROBADO,INHABILITADOoPENDIENTE.
Con estas filas el frontend calcula los indicadores, los gráficos y los filtros por curso, sección, condición y estudiante.
GET /api/dashboard/courses
[
{
"curso_id": "APS",
"curso": "Administración de Proyectos de Sistemas",
"docente": "Mg. Carla Rojas Palomino",
"periodo": "2026-II",
"matriculados": 120,
"aprobados": 101,
"desaprobados": 19,
"promedio": 15.27,
"asistencia_promedio": 0.9335,
"tasa_aprobacion": 0.8417
}
]
GET /api/dashboard/tables
[
{ "tabla": "NOTAS", "filas": 4320, "ultima_carga": "2026-11-15T17:23:37.763412" }
]
ultima_carga es null si la tabla está vacía.
GET /api/dashboard/loads
Qué hizo cada ejecución del job de carga en cada tabla (tabla CARGAS), de la más reciente a la más antigua.
[
{ "ejecucion_id": "6283fedf-251e-4c67-be9d-40f7f5f613df", "tabla": "NOTAS", "filas_insertadas": 55, "filas_actualizadas": 4265, "fecha_carga": "2026-11-15T18:04:50.120000" }
]
filas_insertadas: filas que no existían y se crearon en esa carga.filas_actualizadas: filas que ya existían (misma clave) y se volvieron a escribir.
El frontend agrupa por ejecucion_id para mostrar una carga a la vez.
Errores
Todos los errores tienen esta forma (ProblemDetail):
{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Elija un dataset de: [con-errores, limpio]", "instance": "/api/executions" }
El frontend muestra el campo detail.
| Código | Cuándo |
|---|---|
400 |
Falta un dato o no es válido (job desconocido, dataset inexistente, ejecución de origen no válida, job sin compilar) |
404 |
La ejecución no existe o no tiene reporte de calidad |
503 |
No se pudo consultar Oracle |
500 |
Error inesperado |