Documents API — retrieve, upload, validate, and delete - Agente Inteligente para Expedientes Docentes

Every academic document in the system is linked to a docente via their cedula (Venezuelan ID number). Documents carry rich metadata: the physical file location, file hash, OCR processing results (including extracted structured fields), visual-verification state, and a four-state validation workflow (pendiente → aprobado | rechazado | requiere_revision).

TipoDocumento Values

The tipo field on every document must be one of the following 22 values defined in TipoDocumento:

Value	Description
`cedula_identidad`	Venezuelan national ID card
`rif`	Tax identification (RIF)
`partida_nacimiento`	Birth certificate
`titulo_bachiller`	High-school diploma
`titulo_universitario`	Undergraduate degree title
`titulo_postgrado`	Postgraduate degree title
`certificado_notas_bachillerato`	High-school transcript
`certificado_notas_pregrado`	Undergraduate transcript
`certificado_notas_postgrado`	Postgraduate transcript
`acta_grado`	Graduation record/act
`fondo_negro_titulo`	Official notarized title copy (fondo negro)
`nostrificacion`	Foreign degree recognition (nostrificación)
`resolucion_nombramiento`	Institutional appointment resolution
`evaluacion_docente`	Teaching performance evaluation
`diploma_curso`	Short-course diploma
`diploma_taller`	Workshop diploma
`diploma_congreso`	Conference/congress diploma
`constancia_trabajo`	Employment certificate
`constancia_estudio`	Study enrolment certificate
`carta_recomendacion`	Letter of recommendation
`curriculo_vitae`	Curriculum vitae
`otro`	Other / miscellaneous

GET /documentos/

Retrieve the complete detail record for a single document, including all OCR fields and file metadata.

Path Parameters

documento_id

string

required

MongoDB ObjectId of the document (24-character hex string).

Response

{
  "_id": "649ab8d3e4b7c200123456cc",
  "docente_id": "649ab8d3e4b7c200123456ff",
  "docente_cedula": "12345678",
  "tipo": "cedula_identidad",
  "nombre": "Cédula de Identidad - Ana Martinez",
  "descripcion": null,
  "archivo": {
    "ruta": "data/storage/12345678/cedula_identidad.pdf",
    "nombre_original": "cedula_ana_martinez.pdf",
    "formato": "pdf",
    "tamano_bytes": 204800,
    "hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "comprimido": false,
    "ratio_compresion": null
  },
  "ocr": {
    "procesado": true,
    "fecha_procesamiento": "2024-06-01T10:00:00",
    "motor": "tesseract",
    "version_motor": "5.3.0",
    "confianza_promedio": 0.94,
    "idioma_detectado": "es",
    "paginas": 1,
    "campos_extraidos": {
      "nombre_completo": "ANA MARTINEZ",
      "cedula": "12345678",
      "fecha_nacimiento": "1985-03-12"
    }
  },
  "verificacion_visual": {
    "procesado": false,
    "firma": null,
    "sello": null,
    "fecha_verificacion": null,
    "motor": null
  },
  "validacion": {
    "estado": "aprobado",
    "es_copia_fiel": null,
    "fecha_emision_documento": null,
    "fecha_vencimiento": null,
    "observaciones": null,
    "validado_por": "admin@universidad.edu.ve"
  },
  "metadata": {
    "metodo_carga": "carga_manual",
    "version_procesamiento": 1,
    "folio": null,
    "pagina_expediente": null
  },
  "created_at": "2024-06-01T09:00:00",
  "updated_at": "2024-06-01T10:05:00"
}

archivo

object

Physical file metadata. Key sub-fields:

ruta — server-side path under data/storage/
nombre_original — filename as uploaded
formato — file extension: pdf, jpg, jpeg, or png
tamano_bytes — file size in bytes (max allowed: 25 MB = 26,214,400 bytes)
hash_sha256 — SHA-256 integrity hash
comprimido — whether the file was compressed at rest
ratio_compresion — compression ratio if compressed, otherwise null

ocr

object

OCR processing results. Key sub-fields:

procesado — whether OCR has run on this document
confianza_promedio — average confidence score (0.0–1.0)
idioma_detectado — ISO 639-1 language code, typically "es"
paginas — number of pages processed
campos_extraidos — structured key/value pairs extracted from the document text

validacion.estado

string

Current validation state: pendiente, aprobado, rechazado, or requiere_revision.

Error responses:

Status	Detail
`422`	`"ID de documento inválido"` — not a valid MongoDB ObjectId
`404`	`"Documento no encontrado"`
`500`	`"Error de base de datos"`

curl "http://localhost:8000/documentos/649ab8d3e4b7c200123456cc"

GET /documentos//validacion

Retrieve a structured validation audit for a document — format compliance, file size, and OCR reliability — plus a single es_valido_para_expediente boolean.

Path Parameters

documento_id

string

required

MongoDB ObjectId (24-character hex string).

Response

{
  "_id": "649ab8d3e4b7c200123456cc",
  "validaciones": {
    "formato": {
      "valido": true,
      "tipo_esperado": "pdf",
      "tamano_dentro_rango": true,
      "detalle": "200 KB"
    },
    "ocr_confiabilidad": {
      "confianza_promedio": 0.94,
      "paginas_con_baja_confianza": [],
      "idioma_consistente": true
    },
    "metadatos_extraidos": {
      "nombre_completo": "ANA MARTINEZ",
      "cedula": "12345678",
      "fecha_nacimiento": "1985-03-12"
    }
  },
  "es_valido_para_expediente": true
}

validaciones.formato.valido

boolean

true when the file’s formato is one of pdf, jpg, jpeg, or png.

validaciones.formato.tamano_dentro_rango

boolean

true when tamano_bytes <= 26,214,400 (25 MB).

validaciones.ocr_confiabilidad.idioma_consistente

boolean

true when idioma_detectado == "es".

validaciones.metadatos_extraidos

object

Mirror of ocr.campos_extraidos — structured key/value pairs parsed by the OCR engine.

es_valido_para_expediente

boolean

true only when all three conditions hold:

formato.valido == true
formato.tamano_dentro_rango == true
validacion.estado == "aprobado"

Error responses:

Status	Detail
`422`	Invalid MongoDB ObjectId
`404`	Document not found

POST /documentos//agregar-documento

Add a new document record to an existing dossier. JWT (admin) required. The document is created with validacion.estado = "pendiente" and ocr.procesado = false. OCR processing is triggered separately by the background agent.

Path Parameters

cedula

string

required

Venezuelan ID number of the docente who owns this document.

Request Body (`application/json`)

{
  "tipo": "cedula_identidad",
  "nombre": "Cédula de Identidad - Ana Martinez",
  "descripcion": "Copia escaneada, anverso y reverso",
  "archivo_ruta": "data/storage/12345678/cedula_identidad.pdf",
  "archivo_nombre_original": "cedula_ana.pdf",
  "archivo_formato": "pdf",
  "archivo_tamano_bytes": 204800
}

tipo

string

required

Document type — must be a valid TipoDocumento value.

nombre

string

required

Human-readable document name.

descripcion

string

Optional description or notes about the document.

archivo_ruta

string

required

Server-side path to the physical file (relative to the project root).

archivo_nombre_original

string

required

Original filename as provided by the uploader.

archivo_formato

string

default:"pdf"

File extension: pdf, jpg, jpeg, or png.

archivo_tamano_bytes

integer

File size in bytes.

Response (201 Created)

{
  "mensaje": "Documento agregado correctamente",
  "documento_id": "649ab8d3e4b7c200123456cc",
  "docente_cedula": "12345678",
  "tipo": "cedula_identidad",
  "timestamp": "2024-06-01T09:00:00"
}

After insertion, mongo.update_completitud(cedula) is called automatically to recalculate the dossier’s completeness percentage. Error responses:

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

PATCH /documentos//validacion

Update the validation state of a document. JWT (admin) required. After the update, dossier completeness is recalculated.

Path Parameters

documento_id

string

required

MongoDB ObjectId of the document.

Request Body (`application/json`)

{
  "estado": "aprobado",
  "observaciones": "Documento legible, datos coherentes."
}

estado

string

required

New validation state. Must be one of: pendiente, aprobado, rechazado, requiere_revision.

observaciones

string

Optional reviewer notes stored in validacion.observaciones.

Response

{
  "mensaje": "Validación actualizada correctamente",
  "documento_id": "649ab8d3e4b7c200123456cc",
  "estado": "aprobado",
  "timestamp": "2024-06-01T11:00:00"
}

Error responses:

Status	Detail
`401`	Missing or invalid JWT
`403`	Authenticated user does not have the `admin` role
`422`	Invalid ObjectId or `estado` value not in allowed set
`404`	Document not found

curl -X PATCH "http://localhost:8000/documentos/649ab8d3e4b7c200123456cc/validacion" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"estado": "aprobado", "observaciones": "Documento legible."}'

DELETE /documentos/

Permanently delete a document record from MongoDB. JWT (admin) required. The physical file in data/storage/ is not removed by this endpoint. Dossier completeness is recalculated after deletion.

Path Parameters

documento_id

string

required

MongoDB ObjectId of the document to delete.

Response

{
  "mensaje": "Documento eliminado correctamente",
  "documento_id": "649ab8d3e4b7c200123456cc",
  "docente_cedula": "12345678",
  "tipo": "cedula_identidad",
  "timestamp": "2024-06-01T12:00:00"
}

Error responses:

Status	Detail
`401`	Missing or invalid JWT
`403`	Authenticated user does not have the `admin` role
`422`	Invalid MongoDB ObjectId format
`404`	Document not found

Every write operation (POST, PATCH, DELETE) is logged to the auditoria MongoDB collection with the authenticated user’s identity (sub from the JWT), the affected docente_cedula, and a human-readable detalles string.

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documents API — retrieve, upload, validate, and delete

TipoDocumento Values

GET /documentos/

Path Parameters

Response

GET /documentos//validacion

Path Parameters

Response

POST /documentos//agregar-documento

Path Parameters

Request Body (`application/json`)

Response (201 Created)

PATCH /documentos//validacion

Path Parameters

Request Body (`application/json`)

Response

DELETE /documentos/

Path Parameters

Response

Build docs developers (and LLMs) love

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documentation Index

​TipoDocumento Values

​GET /documentos/

​Path Parameters

​Response

​GET /documentos//validacion

​Path Parameters

​Response

​POST /documentos//agregar-documento

​Path Parameters

​Request Body (application/json)

​Response (201 Created)

​PATCH /documentos//validacion

​Path Parameters

​Request Body (application/json)

​Response

​DELETE /documentos/

​Path Parameters

​Response

Build docs developers (and LLMs) love

TipoDocumento Values

GET /documentos/

Path Parameters

Response

GET /documentos//validacion

Path Parameters

Response

POST /documentos//agregar-documento

Path Parameters

Request Body (`application/json`)

Response (201 Created)

PATCH /documentos//validacion

Path Parameters

Request Body (`application/json`)

Response

DELETE /documentos/

Path Parameters

Response