Statistics and metrics API — dashboards and KPIs - Agente Inteligente para Expedientes Docentes

The statistics endpoints provide aggregated data for dashboards and reporting without modifying any records. The three /estadisticas routes are public (no authentication required), while /metricas is JWT-protected and returns the four headline KPI values used by the main dashboard.

GET /estadisticas/expedientes

Dashboard-level summary of dossiers, grouped by a chosen dimension. Authentication: Not required.

Query parameters

agrupar_por

string

default:"status"

Grouping dimension. Accepted values:

Value	Description
`status`	Group by docente status (`completo`, `incompleto`, `activo`, …)
`departamento`	Group by `vinculacion_institucional.departamento`
`sede`	Group by `vinculacion_institucional.sede`
`completitud_rango`	Group into four fixed bands: `0-25%`, `25-50%`, `50-75%`, `75-100%`

intervalo

string

Optional temporal filter. Accepted values: dia | mes | trimestre | año. Currently passed through as metadata — use it to label chart axes on the frontend.

Response `200 OK`

{
  "timestamp": "2024-01-15T10:30:00",
  "agrupacion": "status",
  "datos": [
    { "categoria": "incompleto", "cantidad": 45, "porcentaje": 62.5 },
    { "categoria": "completo",   "cantidad": 27, "porcentaje": 37.5 }
  ],
  "total_docentes": 72
}

datos[].categoria

string

The grouped value (status label, department name, sede name, or range string like "25-50%"). Rows where the field is null in MongoDB are labelled "Sin especificar".

datos[].cantidad

integer

Number of docentes in this category.

datos[].porcentaje

number

cantidad / total_docentes × 100, rounded to one decimal place.

total_docentes

integer

Total number of docente documents in the database (all statuses).

cURL example

# Group by completeness range
curl "http://localhost:8000/estadisticas/expedientes?agrupar_por=completitud_rango"

# Group by department
curl "http://localhost:8000/estadisticas/expedientes?agrupar_por=departamento"

GET /estadisticas/documentos

Document-level analysis, with optional filtering by document type and/or validation status. Authentication: Not required.

Query parameters

tipo

string

Filter results to a specific TipoDocumento value (e.g. cedula_identidad, titulo_universitario). When omitted, all types are included.

estado_validacion

string

Filter by validation state. Accepted values: pendiente | aprobado | rechazado | requiere_revision.

Response `200 OK`

{
  "filtros_aplicados": {
    "tipo": null,
    "estado_validacion": null
  },
  "documento_faltante_top": [
    { "tipo": "acta_grado",             "cantidad_faltante": 2 },
    { "tipo": "resolucion_nombramiento", "cantidad_faltante": 5 }
  ],
  "documentos_por_estado": {
    "aprobado":          142,
    "rechazado":          18,
    "pendiente":          63,
    "requiere_revision":   9
  },
  "procesamiento_ocr": {
    "procesados":               210,
    "pendientes":                22,
    "tasa_confianza_promedio": 0.87
  }
}

documento_faltante_top

array

The 10 document types with the lowest count of non-rejected documents — i.e., the types most likely to be missing from dossiers. Sorted ascending by count.

documentos_por_estado

object

Counts for all four validation states across the (optionally filtered) document set.

procesamiento_ocr.tasa_confianza_promedio

number

Average ocr.confianza_promedio over all documents where OCR has been run. 0 if no documents have been processed yet.

GET /estadisticas/completitud

Completeness distribution of dossiers, with per-department breakdown and an automated prioritisation recommendation. Authentication: Not required.

Query parameters

rango_porcentaje

string

default:"0-25,25-50,50-75,75-100"

Comma-separated list of percentage ranges to compute. Each range is expressed as start-end (integers). Default produces four equal quartile bands.

agrupar_por

string

When set to departamento (or omitted), the response includes a per-department breakdown. Pass sede or status to change the primary grouping axis — note that the detailed breakdown pipeline currently always groups by department regardless of this value.

Response `200 OK`

{
  "distribucion_completitud": {
    "0-25%":   { "cantidad": 8,  "porcentaje_total": 11.1 },
    "25-50%":  { "cantidad": 19, "porcentaje_total": 26.4 },
    "50-75%":  { "cantidad": 28, "porcentaje_total": 38.9 },
    "75-100%": { "cantidad": 17, "porcentaje_total": 23.6 }
  },
  "por_departamento": [
    {
      "departamento":        "Ingeniería Civil",
      "docentes":            14,
      "promedio_completitud": 48,
      "docentes_bajo_50%":    9
    },
    {
      "departamento":        "Matemáticas",
      "docentes":            10,
      "promedio_completitud": 71,
      "docentes_bajo_50%":    2
    }
  ],
  "recomendacion": "Priorizar Ingeniería Civil: 9 docentes bajo 50%"
}

distribucion_completitud

object

One key per requested range. Each value contains cantidad (docente count) and porcentaje_total (share of all docentes, rounded to one decimal place).

por_departamento

array

Departments sorted descending by docentes_bajo_50% — the department with the most incomplete dossiers appears first.

recomendacion

string

Auto-generated text recommendation. Returns "Expedientes en buen estado general" when no department has docentes below 50 % completeness.

cURL example

curl "http://localhost:8000/estadisticas/completitud?agrupar_por=departamento"

GET /metricas/

Return the four headline KPIs shown on the main dashboard. Authentication: Authorization: Bearer <token> required.

Response `200 OK`

{
  "totalDocumentos":    210,
  "completitudPromedio": 64.3,
  "docentesAptos":       17,
  "docentesTotales":     72
}

totalDocumentos

integer

Total documents whose validacion.estado is not rechazado.

completitudPromedio

number

Average of completitud.porcentaje across all docentes, rounded to one decimal place. 0.0 if the collection is empty.

docentesAptos

integer

Count of docentes with completitud.porcentaje >= 80. These are considered dossier-complete.

docentesTotales

integer

Total number of docentes registered in the system.

The docentesAptos threshold is ≥ 80 %, not 100 %. A docente with all mandatory documents present but missing optional ones will be counted as apto once the 80 % threshold is met.

cURL example

curl http://localhost:8000/metricas/ \
  -H "Authorization: Bearer $TOKEN"

Autenticación

Expedientes y Documentos

Agentes y Sistema

Statistics and metrics API — dashboards and KPIs

GET /estadisticas/expedientes

Query parameters

Response `200 OK`

cURL example

GET /estadisticas/documentos

Query parameters

Response `200 OK`

GET /estadisticas/completitud

Query parameters

Response `200 OK`

cURL example

GET /metricas/

Response `200 OK`

cURL example

Build docs developers (and LLMs) love

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documentation Index

​GET /estadisticas/expedientes

​Query parameters

​Response 200 OK

​cURL example

​GET /estadisticas/documentos

​Query parameters

​Response 200 OK

​GET /estadisticas/completitud

​Query parameters

​Response 200 OK

​cURL example

​GET /metricas/

​Response 200 OK

​cURL example

Build docs developers (and LLMs) love

GET /estadisticas/expedientes

Query parameters

Response `200 OK`

cURL example

GET /estadisticas/documentos

Query parameters

Response `200 OK`

GET /estadisticas/completitud

Query parameters

Response `200 OK`

cURL example

GET /metricas/

Response `200 OK`

cURL example