Skip to main content
POST
/
documents
/
upload
Subir Documento
curl --request POST \
  --url http://api.gu1.ai/documents/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "categoryId": "<string>"
}
'
{
  "400": {},
  "401": {},
  "500": {},
  "id": "<string>",
  "name": "<string>",
  "originalFileName": "<string>",
  "fileSize": 123,
  "mimeType": "<string>",
  "storagePath": "<string>",
  "storageProvider": "<string>",
  "categoryId": "<string>",
  "organizationId": "<string>",
  "createdAt": {}
}
Sube archivos asociados a entidades usando multipart/form-data.

​
Autenticación

Este endpoint requiere autenticación mediante token Bearer y contexto de organización. Headers Requeridos:
  • Authorization: Bearer <jwt-token>
  • X-Organization-ID: <organization-id>

​
Parámetros del Form Data

​
file
File
required
El archivo a subir (cualquier tipo soportado)
​
entityId
UUID
ID de la entidad a la que asociar el documento
​
categoryId
UUID
ID de la categoría del documento (UBO, Representante Legal, Corporativo, etc.)

​
Ejemplo de Request

curl -X POST https://api.gu1.ai/documents/upload \
  -H "Authorization: Bearer TU_JWT_TOKEN" \
  -H "X-Organization-ID: TU_ORG_ID" \
  -F "file=@/ruta/al/documento.pdf" \
  -F "entityId=bb0c2d24-b519-40ec-b765-86de831ca0af" \
  -F "categoryId=c5e9a3f2-1234-5678-9abc-def012345678"

​
Respuesta

​
id
UUID
Identificador único del documento
​
name
string
Nombre del documento
​
originalFileName
string
Nombre original del archivo subido
​
fileSize
number
Tamaño del archivo en bytes
​
mimeType
string
Tipo MIME del archivo
​
storagePath
string
Ruta donde se almacena el archivo (clave S3 o ruta local)
​
storageProvider
string
Proveedor de almacenamiento usado (‘s3’ o ‘local’)
​
categoryId
UUID
ID de la categoría del documento (si se asignó)
​
organizationId
UUID
ID de la organización propietaria del documento
​
createdAt
timestamp
Fecha de creación del documento

​
Ejemplo de Respuesta

{
  "id": "d7f8e9c0-1234-5678-9abc-def012345678",
  "name": "document.pdf",
  "description": "Documento subido: document.pdf",
  "type": "other",
  "fileName": "1730649606123_document.pdf",
  "originalFileName": "document.pdf",
  "fileSize": 245678,
  "mimeType": "application/pdf",
  "fileExtension": "pdf",
  "storagePath": "/uploads/1730649606123_document.pdf",
  "storageProvider": "local",
  "securityLevel": "internal",
  "categoryId": "c5e9a3f2-1234-5678-9abc-def012345678",
  "organizationId": "24236b0a-e34d-4218-b3d2-76b101ce8aa9",
  "createdBy": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "createdAt": "2025-11-03T15:30:45.123Z",
  "updatedAt": "2025-11-03T15:30:45.123Z"
}

​
Qué Sucede Después de la Subida

  1. Almacenamiento: El archivo se sube a S3 (si está habilitado) o almacenamiento local
  2. Registro en Base de Datos: Se crea el registro del documento en la base de datos
  3. Versionamiento: Se crea automáticamente la versión inicial (v1)
  4. Relación con Entidad: Si se proporciona entityId, se crea la relación automáticamente
  5. Análisis de Riesgo: Se activa el análisis automático de riesgo si hay reglas configuradas

​
Tipos de Archivo Soportados

  • Documentos: PDF, DOC, DOCX, TXT
  • Imágenes: PNG, JPG, JPEG, GIF
  • Hojas de Cálculo: XLS, XLSX, CSV
  • Otros: Cualquier tipo de archivo

​
Categorías de Documentos

Para obtener las categorías disponibles, usa: 
GET /documents/categories
Categorías comunes incluyen:
  • UBO (Beneficiario Final)
  • Representante Legal
  • Documentos Corporativos
  • Debida Diligencia Reforzada

​
Respuestas de Error

​
400
error
Bad Request - Falta archivo o autenticación
{
  "error": "No file provided"
}
​
401
error
No Autorizado - Token inválido
{
  "error": "Unauthorized - No token provided"
}
​
500
error
Error Interno del Servidor
{
  "error": "Error interno del servidor",
  "details": "Mensaje de error aquí"
}

​
Notas

El sistema detecta automáticamente si el almacenamiento S3 está configurado y lo usa, de lo contrario usa almacenamiento local.
El tamaño máximo del archivo depende de la configuración del servidor (típicamente 50MB).
Incluso si entityId o categoryId no existen, el documento se creará de todos modos. La relación o asignación de categoría simplemente se omitirá.