Documents API — Upload, Download, and Version Files - PortalHub

The Documents API manages the documentos table, which stores file metadata and references physical files in the uploads/ directory on the server. Every file upload is scanned for a valid MIME type, versioned automatically by original filename and document type, and linked to a client owner (id_usuario_propietario). Two distinct operations exist for adding a document to the system:

subir.php — a full multipart upload that physically moves a file to disk, performs security checks, and inserts a database record in one step.
registrar.php — a hardcoded server-side seed script that inserts a single document record with fixed values. It is not a callable HTTP endpoint; see its section below for details.

Versioning

When a file is uploaded via subir.php, the server queries for the highest existing version value where id_usuario_propietario, id_tipo_doc, and nombre_original all match. The new record receives version = max + 1. First uploads start at version 1. The file is stored on disk under an obfuscated name (<16-byte hex>_v<version>.<ext>) to prevent direct path enumeration.

CFDI / XML detection

The validacion_cfdi column is a boolean (tinyint(1)) that is automatically set to 1 when the uploaded file has an .xml extension. CFDI files (Comprobante Fiscal Digital por Internet) are the standard Mexican electronic invoice format. All other file types receive validacion_cfdi = 0.

validacion_cfdi indicates that the file is an XML document that may be a CFDI. No structural XML validation is performed by the upload endpoint itself.

Allowed file types

Extension	MIME type
`pdf`	`application/pdf`
`xml`	`text/xml`, `application/xml`
`doc`	`application/msword`
`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`xls`	`application/vnd.ms-excel`
`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`jpg`	`image/jpeg`, `image/pjpeg`
`png`	`image/png`

Maximum file size: 10 MB. Both the extension and the real MIME type (detected via finfo) must match.

GET /backend/modules/documentos/listar.php

Return document metadata, scoped by the caller’s role. Results are ordered by fecha_subida DESC. Authentication: Any authenticated user (checkAuth)

Caller role	Documents returned
`ROL_ADMIN` (`1`)	All documents in the system
`ROL_ASESOR` (`2`)	Documents owned by clients in the advisor’s active `cliente_asesor` assignments
`ROL_CLIENTE` (`3`)	Only documents where `id_usuario_propietario = session user`

Request

No parameters required.

curl -X GET https://your-domain.com/backend/modules/documentos/listar.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

id_documento

integer

Auto-incremented document identifier.

id_usuario_propietario

integer

id_usuario of the client who owns this document.

id_tipo_doc

integer

Foreign key to cat_tipos_documentos.

ruta_archivo

string

Server-relative path to the physical file (e.g., uploads/<hash>_v1.pdf). Do not expose this path to end-users; use the download endpoint instead.

nombre_original

string

The original filename as submitted by the uploader.

version

integer

Version number of this file. Starts at 1 and increments each time a file with the same name and type is uploaded for the same owner.

validacion_cfdi

integer

1 if the file is an XML document (potential CFDI); 0 otherwise.

fecha_subida

timestamp

Timestamp of when the document was uploaded.

nombre_tipo

string

Human-readable document type name from cat_tipos_documentos.

propietario_correo

string

Email address of the document owner.

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`500`	Error al listar documentos

POST /backend/modules/documentos/subir.php

Upload a file to the server. This endpoint expects multipart/form-data, not JSON. The server validates the file extension and MIME type, calculates the next version number, saves the file under an obfuscated name, inserts a record into documentos, and dispatches a notification to the relevant party. Authentication: Any authenticated user (checkAuth)

This endpoint uses multipart/form-data. Do not send Content-Type: application/json. Form fields and the file must be transmitted as multipart parts.

Request fields (multipart/form-data)

archivo

file

required

The file to upload. Must be one of the allowed extensions (pdf, xml, doc, docx, xls, xlsx, jpg, png) and must not exceed 10 MB. The real MIME type is validated server-side against the expected type for the given extension.

id_tipo_doc

integer

required

Foreign key to cat_tipos_documentos. Identifies the document category (e.g., invoice, tax return).

id_cliente

integer

Required when the caller is an Admin (ROL_ADMIN = 1) or Asesor (ROL_ASESOR = 2). Specifies which client owns the document. Advisors must have an active cliente_asesor assignment for this client.

When a ROL_CLIENTE user uploads a file, id_cliente is ignored — the owner is always set to the session user. Admins and Asesors must supply id_cliente explicitly.

curl -X POST https://your-domain.com/backend/modules/documentos/subir.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -F "archivo=@/path/to/declaracion_2023.pdf" \
  -F "id_tipo_doc=2" \
  -F "id_cliente=7"

id_documento

integer

The ID of the newly created document record.

nombre

string

The original filename as received.

version

integer

The version number assigned to this upload.

Notification behaviour

Uploader role	Notification sent to
`ROL_CLIENTE`	Active advisor assigned to the client (if any)
`ROL_ASESOR` or `ROL_ADMIN`	The client identified by `id_usuario_propietario`

Error responses

HTTP	Message
`400`	Faltan datos obligatorios (archivo o tipo de documento)
`400`	El archivo excede el límite de tamaño permitido (10MB)
`400`	Debe especificar el ID del cliente
`400`	Extensión de archivo no permitida
`400`	El contenido del archivo no coincide con su extensión
`401`	No autorizado. Inicie sesión Primero.
`403`	No tiene permiso para subir archivos a este cliente
`405`	Método no permitido
`500`	Error al guardar el archivo
`500`	Error en la base de datos

/backend/modules/documentos/registrar.php

registrar.php is a hardcoded server-side seed script, not an HTTP API endpoint. It inserts a single document record with values that are set as PHP variables directly in the source file ($id_usuario_propietario = 1, $id_tipo_doc = 1, $ruta_archivo = "uploads/factura1.pdf", $version = 1, $validacion_cfdi = 1). It does not read from $_GET, $_POST, or php://input, and it does not call checkAuth() or checkRole().

registrar.php is not a callable HTTP endpoint. It is a utility script intended to be run directly on the server (e.g., via CLI or a one-time web request) to seed a specific hardcoded record. Do not expose it to end-users. To insert document records programmatically, use subir.php instead.

When executed, it inserts one row into documentos using the hardcoded values and returns:

{
  "status": 201,
  "message": "Documento registrado correctamente",
  "data": {
    "id_documento": 10
  }
}

On failure it returns HTTP 500 with "Error al registrar documento".

GET /backend/modules/documentos/descargar.php

Download a document file by its id_documento. The server verifies the caller’s permission before streaming the file with Content-Disposition: attachment. Authentication: Any authenticated user (checkAuth)

The response for a successful download is a raw binary file stream, not a JSON envelope. HTTP headers include Content-Type: application/octet-stream and Content-Disposition: attachment; filename="<nombre_original>".

Query parameters

integer

required

The id_documento of the file to download.

Access control

Caller role	Can download
`ROL_ADMIN` (`1`)	Any document
`ROL_ASESOR` (`2`)	Documents owned by their active assigned clients
`ROL_CLIENTE` (`3`)	Only documents where `id_usuario_propietario = session user`

curl -X GET "https://your-domain.com/backend/modules/documentos/descargar.php?id=9" \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  --output declaracion_2023.pdf

Error responses

HTTP	Message (JSON)
`400`	ID de documento no proporcionado
`401`	No autorizado. Inicie sesión Primero.
`403`	No tiene permisos para descargar este documento
`404`	Documento no encontrado
`404`	Archivo físico no encontrado en el servidor
`500`	Error en el servidor

/backend/modules/documentos/eliminar.php

eliminar.php is a hardcoded server-side utility script, not an HTTP API endpoint. The target record ID is set as a PHP variable directly in the source file ($id_documento = 4). It does not read from any request input and does not call checkAuth() or checkRole().

eliminar.php is not a callable HTTP endpoint. It is a utility script intended to be run directly on the server to delete a specific hardcoded document record. Do not expose it to end-users. Additionally, the physical file in uploads/ is not removed — orphaned files must be cleaned up through a separate process. Restrict access at the web server level in all environments.

When executed, it deletes the row in documentos where id_documento = 4 (hardcoded) and returns:

{
  "status": 200,
  "message": "Documento eliminado correctamente"
}

On failure it returns HTTP 500 with "Error al eliminar documento".

Overview

Endpoints

Documents API — Upload, Download, and Version Files

Versioning

CFDI / XML detection

Allowed file types

GET /backend/modules/documentos/listar.php

Request

Error responses

POST /backend/modules/documentos/subir.php

Request fields (multipart/form-data)

Notification behaviour

Error responses

/backend/modules/documentos/registrar.php

GET /backend/modules/documentos/descargar.php

Query parameters

Access control

Error responses

/backend/modules/documentos/eliminar.php

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Versioning

​CFDI / XML detection

​Allowed file types

​GET /backend/modules/documentos/listar.php

​Request

​Error responses

​POST /backend/modules/documentos/subir.php

​Request fields (multipart/form-data)

​Notification behaviour

​Error responses

​/backend/modules/documentos/registrar.php

​GET /backend/modules/documentos/descargar.php

​Query parameters

​Access control

​Error responses

​/backend/modules/documentos/eliminar.php

Build docs developers (and LLMs) love

Versioning

CFDI / XML detection

Allowed file types

GET /backend/modules/documentos/listar.php

Request

Error responses

POST /backend/modules/documentos/subir.php

Request fields (multipart/form-data)

Notification behaviour

Error responses

/backend/modules/documentos/registrar.php

GET /backend/modules/documentos/descargar.php

Query parameters

Access control

Error responses

/backend/modules/documentos/eliminar.php