Documents API

API per la gestione dei documenti.

Lista Documenti

GET /api/documents
Authorization: Bearer <token>

# Query parameters
?page=1
&limit=20
&status=VECTORIZED      # UPLOADED | PROCESSING | VECTORIZED | ERROR
&topicId=<uuid>
&search=contratto       # Ricerca per nome
&sort=createdAt         # name | createdAt | updatedAt
&order=desc             # asc | desc

Response:

{
  "success": true,
  "data": [
    {
      "id": "doc-uuid",
      "name": "Contratto_ACME.pdf",
      "originalName": "Contratto_ACME.pdf",
      "mimeType": "application/pdf",
      "size": 2456789,
      "status": "VECTORIZED",
      "topicId": "topic-uuid",
      "topicName": "Contratti",
      "chunkCount": 45,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Upload Documento

Upload Singolo

POST /api/documents/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <file>
topicId: <uuid>         # Opzionale
description: <string>   # Opzionale

Response:

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Documento.pdf",
    "status": "UPLOADED",
    "message": "Document uploaded, processing started"
  }
}

Upload Multiplo

POST /api/documents/upload-multiple
Authorization: Bearer <token>
Content-Type: multipart/form-data

files[]: <file1>
files[]: <file2>
files[]: <file3>
topicId: <uuid>

Response:

{
  "success": true,
  "data": {
    "uploaded": 3,
    "documents": [
      { "id": "doc-1", "name": "File1.pdf", "status": "UPLOADED" },
      { "id": "doc-2", "name": "File2.pdf", "status": "UPLOADED" },
      { "id": "doc-3", "name": "File3.pdf", "status": "UPLOADED" }
    ]
  }
}

Dettaglio Documento

GET /api/documents/:documentId
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Contratto_ACME.pdf",
    "originalName": "Contratto_ACME.pdf",
    "mimeType": "application/pdf",
    "size": 2456789,
    "status": "VECTORIZED",
    "topicId": "topic-uuid",
    "topic": {
      "id": "topic-uuid",
      "name": "Contratti",
      "color": "#3B82F6"
    },
    "description": "Contratto di fornitura servizi",
    "chunkCount": 45,
    "pageCount": 12,
    "processingInfo": {
      "ocrUsed": false,
      "language": "it",
      "processingTime": 15234
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z"
  }
}

Aggiorna Documento

PUT /api/documents/:documentId
Authorization: Bearer <token>
Content-Type: application/json

{
  "topicId": "new-topic-uuid",
  "description": "Nuova descrizione"
}

Response:

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "name": "Contratto_ACME.pdf",
    "topicId": "new-topic-uuid",
    "description": "Nuova descrizione"
  }
}

Elimina Documento

Singolo

DELETE /api/documents/:documentId
Authorization: Bearer <token>

Response:

{
  "success": true,
  "message": "Document deleted successfully"
}

Multipli

DELETE /api/documents
Authorization: Bearer <token>
Content-Type: application/json

{
  "documentIds": ["doc-1", "doc-2", "doc-3"]
}

Riprocessa Documento

POST /api/documents/:documentId/reprocess
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "id": "doc-uuid",
    "status": "PROCESSING",
    "message": "Reprocessing started"
  }
}

Download Documento

GET /api/documents/:documentId/download
Authorization: Bearer <token>

Response: File binario con headers appropriati.

Preview Documento

GET /api/documents/:documentId/preview
Authorization: Bearer <token>

# Query parameters
?page=1    # Pagina specifica (PDF)

Response:

{
  "success": true,
  "data": {
    "totalPages": 12,
    "currentPage": 1,
    "content": "Testo estratto della pagina...",
    "previewUrl": "/api/documents/doc-uuid/preview-image?page=1"
  }
}

Chunks Documento

Recupera i chunks vettorizzati di un documento.

GET /api/documents/:documentId/chunks
Authorization: Bearer <token>

?page=1
&limit=20

Response:

{
  "success": true,
  "data": [
    {
      "id": "chunk-uuid",
      "content": "Contenuto del chunk...",
      "page": 3,
      "position": 5,
      "metadata": {
        "charCount": 680,
        "tokenCount": 180
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Stato Elaborazione

Polling Status

GET /api/documents/:documentId/status
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "status": "PROCESSING",
    "progress": 65,
    "currentStep": "EMBEDDING",
    "steps": [
      { "name": "PARSING", "status": "completed" },
      { "name": "CHUNKING", "status": "completed" },
      { "name": "EMBEDDING", "status": "in_progress", "progress": 65 },
      { "name": "STORAGE", "status": "pending" }
    ]
  }
}

Stati Possibili

Status	Descrizione
UPLOADED	File ricevuto, in attesa
PROCESSING	Elaborazione in corso
VECTORIZED	Completato con successo
ERROR	Errore durante elaborazione

Errori Comuni

400 Bad Request

{
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "File type not supported. Allowed: pdf, docx, xlsx"
  }
}

413 File Too Large

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds maximum size of 50MB"
  }
}

422 Processing Error

{
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Unable to extract text from document",
    "details": {
      "step": "PARSING",
      "reason": "Corrupted PDF file"
    }
  }
}

Limiti

Parametro	Limite
Max file size (PDF)	50 MB
Max file size (altri)	25 MB
Upload simultanei	10 file
Rate limit upload	10/min
Formati supportati	pdf, docx, doc, xlsx, xls

Webhook Events

Eventi documento (coming soon):

// document.uploaded
{
  "event": "document.uploaded",
  "documentId": "doc-uuid",
  "name": "File.pdf",
  "timestamp": "2024-01-15T10:30:00Z"
}

// document.vectorized
{
  "event": "document.vectorized",
  "documentId": "doc-uuid",
  "chunkCount": 45,
  "timestamp": "2024-01-15T10:35:00Z"
}

// document.error
{
  "event": "document.error",
  "documentId": "doc-uuid",
  "error": "Processing failed",
  "timestamp": "2024-01-15T10:32:00Z"
}