Documentos API

La Documents API permite subir, gestionar y consultar los documentos indexados en la plataforma. Cada documento atraviesa una pipeline de procesamiento automatico que lo hace disponible para la busqueda semantica.

Upload

Upload individual

POST /api/documents/upload
Content-Type: multipart/form-data

Campo	Tipo	Obligatorio	Descripcion
`file`	File	Si	Documento a subir
`topicId`	string	No	Categoria de destino
`description`	string	No	Descripcion del documento
`confidentiality`	string	No	Nivel: `public`, `internal`, `confidential`

Ejemplo:

bash

curl -X POST https://api.queria.pro/api/documents/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@contrato_suministro.pdf" \
  -F "topicId=topic_123" \
  -F "description=Contrato anual proveedor ABC" \
  -F "confidentiality=internal"

Respuesta:

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "contrato_suministro.pdf",
    "mimeType": "application/pdf",
    "size": 2458624,
    "status": "UPLOADED",
    "topicId": "topic_123",
    "message": "Documento subido, procesamiento iniciado",
    "createdAt": "2026-03-04T10:30:00Z"
  }
}

Upload multiple

POST /api/documents/upload-multiple
Content-Type: multipart/form-data

Soporta hasta 10 archivos simultaneos. Cada archivo se procesa en paralelo.

Campo	Tipo	Descripcion
`files[]`	File[]	Array de documentos (max 10)
`topicId`	string	Categoria comun para todos los archivos

Respuesta:

json

{
  "success": true,
  "data": {
    "uploaded": 3,
    "documents": [
      { "id": "doc_001", "name": "File1.pdf", "status": "UPLOADED" },
      { "id": "doc_002", "name": "File2.docx", "status": "UPLOADED" },
      { "id": "doc_003", "name": "File3.xlsx", "status": "UPLOADED" }
    ]
  }
}

Import desde URL

POST /api/documents/upload-url

json

{
  "url": "https://ejemplo.com/docs/informe-2025.pdf",
  "topicId": "topic_123",
  "description": "Informe anual descargado del portal"
}

Limites de tamano

Formato	Tamano maximo
PDF	50 MB
DOCX, XLSX, PPTX	25 MB
TXT, CSV, MD	10 MB
HTML	5 MB

Uploads simultaneos maximos: 10 archivos por peticion. Rate limit: 10 uploads por minuto.

Listar y buscar

GET /api/documents

Query parameters:

Parametro	Tipo	Default	Descripcion
`page`	number	1	Pagina actual
`limit`	number	20	Resultados por pagina (max 100)
`search`	string	-	Busqueda en nombre y descripcion
`status`	string	-	Filtra por estado: `UPLOADED`, `PROCESSING`, `VECTORIZED`, `ERROR`
`topicId`	string	-	Filtra por categoria
`mimeType`	string	-	Filtra por tipo de archivo
`sort`	string	`createdAt`	Campo de ordenacion: `name`, `createdAt`, `updatedAt`
`order`	string	`desc`	Direccion: `asc` o `desc`

Ejemplo:

bash

curl -X GET "https://api.queria.pro/api/documents?status=VECTORIZED&topicId=topic_123&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuesta:

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "doc_8f3a2b1c",
        "name": "contrato_suministro.pdf",
        "originalName": "contrato_suministro.pdf",
        "mimeType": "application/pdf",
        "size": 2458624,
        "status": "VECTORIZED",
        "chunkCount": 47,
        "topicId": "topic_123",
        "topicName": "Contratos",
        "createdAt": "2026-03-04T10:30:00Z",
        "updatedAt": "2026-03-04T10:31:15Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 156, "totalPages": 16 }
  }
}

Detalle del documento

Informacion del documento

GET /api/documents/:id

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "contrato_suministro.pdf",
    "originalName": "contrato_suministro.pdf",
    "mimeType": "application/pdf",
    "size": 2458624,
    "status": "VECTORIZED",
    "topicId": "topic_123",
    "topic": {
      "id": "topic_123",
      "name": "Contratos",
      "color": "#3B82F6"
    },
    "description": "Contrato de suministro de servicios",
    "chunkCount": 47,
    "pageCount": 12,
    "processingInfo": {
      "ocrUsed": false,
      "language": "es",
      "processingTime": 15234
    },
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:31:15Z"
  }
}

Chunks del documento

GET /api/documents/:id/chunks

Devuelve los fragmentos de texto indexados con sus metadatos.

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chk_001",
        "content": "Art. 1 - Objeto del contrato. El presente acuerdo...",
        "chunkType": "ARTICLE",
        "chunkIndex": 0,
        "page": 1,
        "metadata": {
          "charCount": 680,
          "tokenCount": 180
        }
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
  }
}

Estado de procesamiento

GET /api/documents/:id/status

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "status": "PROCESSING",
    "currentStep": "EMBEDDING",
    "progress": 72,
    "steps": [
      { "name": "PARSING", "status": "completed", "duration": 1200 },
      { "name": "CHUNKING", "status": "completed", "duration": 800, "chunksCreated": 47 },
      { "name": "EMBEDDING", "status": "in_progress", "progress": 72 },
      { "name": "STORAGE", "status": "pending" }
    ]
  }
}

Estados del documento

Un documento atraviesa los siguientes estados durante el procesamiento:

UPLOADED --> PROCESSING --> VECTORIZED
                |
                +--> ERROR

Estado	Descripcion
`UPLOADED`	Archivo recibido, en espera de procesamiento
`PROCESSING`	Pipeline activo (parsing, chunking, embedding, storage)
`VECTORIZED`	Procesamiento completado, documento disponible para la busqueda
`ERROR`	Error durante el procesamiento

Fases de la pipeline: PARSING -> CHUNKING -> EMBEDDING -> STORAGE.

Gestion

Actualizar metadatos

PUT /api/documents/:id

json

{
  "topicId": "topic_789",
  "description": "Descripcion actualizada del documento",
  "confidentiality": "confidential"
}

Eliminar documento

DELETE /api/documents/:id

Elimina el documento, todos los chunks asociados y los vectores de la base de datos vectorial.

Eliminacion multiple

DELETE /api/documents

json

{
  "documentIds": ["doc_8f3a2b1c", "doc_4d5e6f7g", "doc_1a2b3c4d"]
}

Reprocesar documento

POST /api/documents/:id/reprocess

Relanza la pipeline de procesamiento. Util tras actualizaciones a la configuracion de chunking o embedding.

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "status": "PROCESSING",
    "message": "Reprocesamiento iniciado"
  }
}

Descarga y vista previa

Descarga original

GET /api/documents/:id/download

Devuelve el archivo original con las cabeceras Content-Disposition apropiadas.

Vista previa

GET /api/documents/:id/preview?page=1

json

{
  "success": true,
  "data": {
    "totalPages": 12,
    "currentPage": 1,
    "content": "Texto extraido de la pagina...",
    "previewUrl": "/api/documents/doc_8f3a2b1c/preview-image?page=1"
  }
}

Generacion de documentos

Queria incluye un motor de generacion de documentos basado en templates.

Lista templates

GET /api/doc-engine/templates

Schema template

GET /api/doc-engine/templates/:id/schema

Devuelve el schema de los campos requeridos para el rendering.

Rendering documento

POST /api/doc-engine/render

json

{
  "templateId": "tpl_report_standard",
  "data": {
    "titulo": "Informe Trimestral Q1 2026",
    "autor": "Mario Rossi",
    "secciones": [
      { "titulo": "Resumen", "contenido": "..." },
      { "titulo": "Analisis", "contenido": "..." }
    ]
  },
  "format": "docx"
}

Devuelve el archivo DOCX generado como descarga directa.

Errores comunes

Codigo	Error	Descripcion
`400`	`INVALID_FILE_TYPE`	Formato de archivo no soportado
`413`	`FILE_TOO_LARGE`	El archivo supera el tamano maximo
`422`	`PROCESSING_ERROR`	Error durante el procesamiento del documento

Webhook (Coming Soon)

Eventos de documento para notificaciones asincronas:

Evento	Descripcion
`document.uploaded`	Documento subido
`document.vectorized`	Procesamiento completado
`document.error`	Error de procesamiento

Documentos API ​

Upload ​

Upload individual ​

Upload multiple ​

Import desde URL ​

Limites de tamano ​

Listar y buscar ​

Detalle del documento ​

Informacion del documento ​

Chunks del documento ​

Estado de procesamiento ​

Estados del documento ​

Gestion ​

Actualizar metadatos ​

Eliminar documento ​

Eliminacion multiple ​

Reprocesar documento ​

Descarga y vista previa ​

Descarga original ​

Vista previa ​

Generacion de documentos ​

Lista templates ​

Schema template ​

Rendering documento ​

Errores comunes ​

Webhook (Coming Soon) ​

Documentos API

Upload

Upload individual

Upload multiple

Import desde URL

Limites de tamano

Listar y buscar

Detalle del documento

Informacion del documento

Chunks del documento

Estado de procesamiento

Estados del documento

Gestion

Actualizar metadatos

Eliminar documento

Eliminacion multiple

Reprocesar documento

Descarga y vista previa

Descarga original

Vista previa

Generacion de documentos

Lista templates

Schema template

Rendering documento

Errores comunes

Webhook (Coming Soon)