Expedientes API — list, search, and manage dossiers - Agente Inteligente para Expedientes Docentes

An expediente (academic dossier) is the central record for a faculty member (docente). It combines the docente’s personal and institutional profile with the full collection of uploaded documents — scanned certificates, ID copies, degree titles, appointment resolutions, and more. Every document is linked to the dossier via the docente’s Venezuelan ID number (cedula).

GET /docentes

List all docentes with pagination. Supports both classic skip/limit pagination and opaque cursor-based pagination for stable iteration over large collections.

Query Parameters

skip

integer

default:"0"

Number of records to skip. Must be >= 0.

limit

integer

default:"10"

Maximum number of records to return per page. Range: 1–100.

cursor

string

Opaque base64-encoded cursor returned by a previous response as cursor_siguiente. When provided, the query fetches the page after this cursor position, ignoring skip.

Response

{
  "items": [ { "...docente fields..." } ],
  "total": 847,
  "skip": 0,
  "limit": 10,
  "cursor_siguiente": "NjQ5YWI4ZDNlNGI3YzIwMDEyMzQ1Njc4",
  "tiene_mas": true
}

items

array

Array of docente objects. Each _id is serialized as a string.

total

integer

Total number of docentes in the collection (unfiltered).

cursor_siguiente

string | null

Cursor to pass as ?cursor= in the next request. null when there are no more pages.

tiene_mas

boolean

true when additional pages exist beyond the current result.

curl "http://localhost:8000/docentes?limit=20"

No authentication is required for this endpoint.

GET /docentes/buscar

Advanced search with text filters, field-level filters, sorting, and cursor-based pagination.

Query Parameters

string

Text search against docente.apellidos, docente.nombres, and docente.cedula (case-insensitive regex).

departamento

string

Filter by vinculacion_institucional.departamento (exact match).

sede

string

Filter by vinculacion_institucional.sede (exact match).

status

string

Filter by dossier status. Accepted values: activo, inactivo, en_revision, completo, incompleto.

ordenar

string

default:"apellidos"

Sort field. Prefix with - for descending order. Supported values: apellidos, cedula, completitud, -updated_at.

skip

integer

default:"0"

Records to skip.

limit

integer

default:"10"

Records per page (max 100).

cursor

string

Opaque cursor for stable next-page iteration.

Response

Same structure as GET /docentes with the addition of total_pages:

{
  "items": [ { "...docente fields..." } ],
  "total": 42,
  "skip": 0,
  "limit": 10,
  "total_pages": 5,
  "cursor_siguiente": "NjQ5YWI4ZDNlNGI3YzIwMDEyMzQ1Njc4",
  "tiene_mas": true
}

total_pages

integer

Computed as ceil(total / limit). Based on the total matching the applied filters, not the cursor position.

curl "http://localhost:8000/docentes/buscar?q=Martinez&departamento=Matematicas&ordenar=-updated_at"

GET /expediente/

Retrieve a complete dossier — the docente profile plus all associated documents.

Path Parameters

cedula

string

required

Venezuelan ID number (digits only), e.g. 12345678.

Response

{
  "docente": {
    "_id": "649ab8d3e4b7c200123456ff",
    "expediente_numero": "EXP-2024-0042",
    "docente": {
      "cedula": "12345678",
      "nombres": "Ana",
      "apellidos": "Martinez",
      "contacto": { "email_personal": "ana@example.com", "telefono_principal": "0412-5551234" }
    },
    "vinculacion_institucional": { "departamento": "Matematicas", "sede": "Caracas" },
    "completitud": { "porcentaje": 70 },
    "status": "activo"
  },
  "documentos": [ { "...documento fields..." } ],
  "total_documentos": 7
}

docente

object

Full docente record as stored in MongoDB. _id is a string.

documentos

array

All documents belonging to this dossier. Each _id is a string.

total_documentos

integer

Count of documents in the response array.

Error responses:

Status	Detail
`404`	`"Docente no encontrado"`
`500`	`"Error de base de datos"`

curl "http://localhost:8000/expediente/12345678"

GET /expediente//documentos

List documents within a dossier with optional type, validation-state, and ordering filters.

Path Parameters

cedula

string

required

Venezuelan ID number.

Query Parameters

tipo

string

Filter by TipoDocumento value (e.g. cedula_identidad, titulo_universitario). See the full type list.

validacion

string

Filter by validation state: pendiente, aprobado, rechazado, or requiere_revision.

incluir_ocr

boolean

default:"false"

When false (default), the ocr.texto_completo field is stripped from each document to reduce payload size.

ordenar

string

default:"created_at"

Sort order. Use created_at (oldest first) or -updated_at (most recently modified first).

skip

integer

default:"0"

Records to skip.

limit

integer

default:"20"

Records per page (max 100).

Response

{
  "docente_cedula": "12345678",
  "items": [ { "...documento..." } ],
  "total": 7,
  "skip": 0,
  "limit": 20,
  "documentos_incompletos": [
    "titulo_universitario",
    "certificado_notas_pregrado",
    "fondo_negro_titulo"
  ]
}

documentos_incompletos

array

List of the 10 required document types that are not yet present in this dossier. An empty array means the dossier is complete.

GET /expediente//resumen

Return a completeness summary for the dossier in either JSON or plain-text format.

Path Parameters

cedula

string

required

Venezuelan ID number.

Query Parameters

formato

string

default:"json"

Response format: json (default) or texto (plain text report).

JSON Response

{
  "numero_expediente": "EXP-2024-0042",
  "docente_cedula": "12345678",
  "docente_nombre": "Ana Martinez",
  "status": "activo",
  "completitud_porcentaje": 70,
  "documentos_presentes": ["cedula_identidad", "rif", "titulo_bachiller"],
  "documentos_faltantes": ["titulo_universitario", "fondo_negro_titulo"],
  "documentos_requeridos_total": 10,
  "ultima_actualizacion": "2024-06-01T14:32:00"
}

completitud_porcentaje

integer

Percentage of the 10 required documents that are present. Sourced from completitud.porcentaje on the docente record.

documentos_requeridos_total

integer

Always 10 — the fixed list of required document types checked by the system.

Text Response

When formato=texto, the endpoint returns a plain-text report suitable for logging or display:

=== RESUMEN DE EXPEDIENTE ===
Número: EXP-2024-0042
Docente: Ana Martinez
Cédula: 12345678
Departamento: Matematicas
Status: activo
Completitud: 70%

Documentos presentes (7):
  ✓ cedula_identidad (aprobado)
  ✓ rif (pendiente)
  ...

Documentos faltantes (3):
  ✗ titulo_universitario
  ✗ fondo_negro_titulo
  ✗ acta_grado

Última actualización: 2024-06-01 14:32:00

# JSON summary
curl "http://localhost:8000/expediente/12345678/resumen"

# Plain-text summary
curl "http://localhost:8000/expediente/12345678/resumen?formato=texto"

GET /expediente//documento//archivo

Serve the physical file (PDF, JPG, or PNG) stored in data/storage/. Supports both inline rendering (e.g. <iframe>, <img>) and forced download.

Path Parameters

cedula

string

required

Venezuelan ID number of the owning docente.

documento_id

string

required

MongoDB ObjectId of the document.

Query Parameters

token

string

JWT authentication token. Accepted as a query parameter so the URL can be embedded in <img src> or <iframe src> attributes without a custom Authorization header.

descargar

boolean

default:"false"

When true, sets Content-Disposition: attachment to trigger a browser download. Default false renders the file inline.

Authentication

Pass a valid JWT via the ?token=<jwt> query parameter. This endpoint uses verify_token_sse, which reads the token exclusively from the query string — not from the Authorization header. This design enables the URL to be embedded directly in HTML <img src> or <iframe src> attributes where custom request headers are not available.

Response

Returns the raw file with appropriate media type:

Format	`Content-Type`
`pdf`	`application/pdf`
`jpg` / `jpeg`	`image/jpeg`
`png`	`image/png`

Error responses:

Status	Detail
`401`	Missing or invalid `?token=` JWT
`403`	`"Ruta fuera del almacenamiento permitido"` — path traversal attempt blocked
`404`	Document or physical file not found
`422`	Invalid `documento_id` format

# Inline preview via query-string token
curl "http://localhost:8000/expediente/12345678/documento/649ab8d3e4b7c200123456aa/archivo?token=<jwt>"

# Force download
curl "http://localhost:8000/expediente/12345678/documento/649ab8d3e4b7c200123456aa/archivo?token=<jwt>&descargar=true" \
  -o cedula_identidad.pdf

GET /expedientes/buscar-texto

Full-text search across the OCR content of all documents, scored by relevance.

No authentication is required for this endpoint.

This endpoint uses MongoDB’s $text index with $meta: "textScore" relevance scoring. Only documents whose OCR has been processed will appear in results.

Query Parameters

string

required

Search query. Minimum 2 characters. Searches the indexed OCR text of all documents.

tipo

string

Optional filter to restrict results to a specific TipoDocumento value.

campos

string

Comma-separated list of field names from ocr.campos_extraidos to include in each result (e.g. nombre_completo,fecha_nacimiento).

skip

integer

default:"0"

Records to skip.

limit

integer

default:"20"

Records per page (max 100).

Response

{
  "query": "universidad central",
  "resultados": [
    {
      "_id": "649ab8d3e4b7c200123456bb",
      "docente_cedula": "12345678",
      "docente_nombre": "Ana Martinez",
      "tipo": "titulo_universitario",
      "nombre": "Título Universitario - Ana Martinez",
      "relevancia": 4.75,
      "nombre_completo": "Ana Martinez",
      "fecha_nacimiento": "1985-03-12"
    }
  ],
  "total": 3,
  "skip": 0,
  "limit": 20,
  "tiempo_busqueda_ms": 12.4
}

relevancia

number

MongoDB text-search relevance score. Higher values indicate stronger matches.

docente_nombre

string

Full name of the owning docente, enriched from the docentes collection.

tiempo_busqueda_ms

number

Server-side elapsed time in milliseconds for the search operation.

curl "http://localhost:8000/expedientes/buscar-texto?q=universidad+central&campos=nombre_completo,fecha_nacimiento"

POST /expedientes//chat

Ask an AI question about a specific dossier. The LLM receives a structured context built from the docente’s profile, institutional link, completeness metrics, and OCR-extracted document data.

Authentication is required. The model and provider are configured server-side (OpenRouter or Ollama).

Path Parameters

cedula

string

required

Venezuelan ID number of the docente to query.

Request Body

{ "pregunta": "¿Qué documentos le faltan a este docente?" }

pregunta

string

required

The question to ask. Minimum 1 character, maximum 500 characters.

Response

{
  "exito": true,
  "respuesta": "Al docente le faltan los siguientes documentos: titulo_universitario, fondo_negro_titulo y acta_grado.",
  "cedula": "12345678",
  "modelo": "mistralai/mistral-7b-instruct",
  "latencia_ms": 834
}

exito

boolean

Always true on a successful response.

respuesta

string

The LLM-generated answer in Spanish.

modelo

string

Name of the LLM model that generated the response (e.g. mistralai/mistral-7b-instruct).

latencia_ms

integer

Round-trip inference time in milliseconds.

Error responses:

Status	Detail
`401`	Missing or invalid bearer token
`404`	`"Docente con cédula {cedula} no encontrado"`
`503`	`"Servicio LLM no disponible"` or `"El modelo LLM no respondió"`

curl -X POST "http://localhost:8000/expedientes/12345678/chat" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"pregunta": "¿Qué documentos le faltan a este docente?"}'

PUT /expedientes/

Update dossier fields. JWT (admin) required. Updatable fields: nombres, apellidos, email_personal, email_institucional, telefono_principal, telefono_secundario, direccion_completa, departamento, sede, estado_civil, nacionalidad.

Request Body

{
  "nombres": "Ana María",
  "telefono_principal": "0412-9998877",
  "departamento": "Ciencias Básicas"
}

Only send the fields you want to change — all fields are optional. Every update is written to the auditoria collection.

Response

{
  "mensaje": "Expediente actualizado correctamente",
  "cedula": "12345678",
  "campos_actualizados": ["nombres", "telefono_principal", "departamento"],
  "timestamp": "2024-06-01T15:00:00"
}

Error responses:

Status	Detail
`400`	`"No hay datos para actualizar"` — all body fields were null
`401`	Missing or invalid JWT
`403`	Authenticated user does not have the `admin` role
`404`	Docente not found

DELETE /expedientes/

Permanently delete a dossier and all its associated documents. JWT (admin) required. This action is irreversible and is recorded in the auditoria collection.

Response

{
  "mensaje": "Expediente eliminado correctamente",
  "cedula": "12345678",
  "docente": "Ana Martinez",
  "documentos_eliminados": 7,
  "timestamp": "2024-06-01T15:05:00"
}

documentos_eliminados

integer

Number of document records removed from the documentos collection.

Error responses:

Status	Detail
`401`	Missing or invalid JWT
`403`	Authenticated user does not have the `admin` role
`404`	Docente not found

Before deleting, call GET /validacion/expediente/{cedula} to confirm the dossier state and GET /expediente/{cedula}/resumen to record what documents will be lost.

Autenticación

Expedientes y Documentos

Agentes y Sistema

Expedientes API — list, search, and manage dossiers

GET /docentes

Query Parameters

Response

GET /docentes/buscar

Query Parameters

Response

GET /expediente/

Path Parameters

Response

GET /expediente//documentos

Path Parameters

Query Parameters

Response

GET /expediente//resumen

Path Parameters

Query Parameters

JSON Response

Text Response

GET /expediente//documento//archivo

Path Parameters

Query Parameters

Authentication

Response

GET /expedientes/buscar-texto

Query Parameters

Response

POST /expedientes//chat

Path Parameters

Request Body

Response

PUT /expedientes/

Request Body

Response

DELETE /expedientes/

Response

Build docs developers (and LLMs) love

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documentation Index

​GET /docentes

​Query Parameters

​Response

​GET /docentes/buscar

​Query Parameters

​Response

​GET /expediente/

​Path Parameters

​Response

​GET /expediente//documentos

​Path Parameters

​Query Parameters

​Response

​GET /expediente//resumen

​Path Parameters

​Query Parameters

​JSON Response

​Text Response

​GET /expediente//documento//archivo

​Path Parameters

​Query Parameters

​Authentication

​Response

​GET /expedientes/buscar-texto

​Query Parameters

​Response

​POST /expedientes//chat

​Path Parameters

​Request Body

​Response

​PUT /expedientes/

​Request Body

​Response

​DELETE /expedientes/

​Response

Build docs developers (and LLMs) love

GET /docentes

Query Parameters

Response

GET /docentes/buscar

Query Parameters

Response

GET /expediente/

Path Parameters

Response

GET /expediente//documentos

Path Parameters

Query Parameters

Response

GET /expediente//resumen

Path Parameters

Query Parameters

JSON Response

Text Response

GET /expediente//documento//archivo

Path Parameters

Query Parameters

Authentication

Response

GET /expedientes/buscar-texto

Query Parameters

Response

POST /expedientes//chat

Path Parameters

Request Body

Response

PUT /expedientes/

Request Body

Response

DELETE /expedientes/

Response