Documenti API

La Documents API consente di caricare, gestire e interrogare i documenti indicizzati nella piattaforma. Ogni documento attraversa una pipeline di elaborazione automatica che lo rende disponibile per la ricerca semantica.

Upload

Upload singolo

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

Campo	Tipo	Obbligatorio	Descrizione
`file`	File	Si	Documento da caricare
`topicId`	string	No	Categoria di destinazione
`description`	string	No	Descrizione del documento
`confidentiality`	string	No	Livello: `public`, `internal`, `confidential`

Esempio:

bash

curl -X POST https://api.queria.pro/api/documents/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@contratto_fornitura.pdf" \
  -F "topicId=topic_123" \
  -F "description=Contratto annuale fornitore ABC" \
  -F "confidentiality=internal"

Risposta:

json

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

Upload multiplo

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

Supporta fino a 10 file simultanei. Ogni file viene elaborato in parallelo.

Campo	Tipo	Descrizione
`files[]`	File[]	Array di documenti (max 10)
`topicId`	string	Categoria comune per tutti i file

Risposta:

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 da URL

POST /api/documents/upload-url

json

{
  "url": "https://esempio.it/documenti/report-2025.pdf",
  "topicId": "topic_123",
  "description": "Report annuale scaricato dal portale"
}

Limiti di Dimensione

Formato	Dimensione Massima
PDF	50 MB
DOCX, XLSX, PPTX	25 MB
TXT, CSV, MD	10 MB
HTML	5 MB

Upload simultanei massimi: 10 file per richiesta. Rate limit: 10 upload al minuto.

Elenco e Ricerca

GET /api/documents

Query parameters:

Parametro	Tipo	Default	Descrizione
`page`	number	1	Pagina corrente
`limit`	number	20	Risultati per pagina (max 100)
`search`	string	-	Ricerca nel nome e descrizione
`status`	string	-	Filtra per stato: `UPLOADED`, `PROCESSING`, `VECTORIZED`, `ERROR`
`topicId`	string	-	Filtra per categoria
`mimeType`	string	-	Filtra per tipo file
`sort`	string	`createdAt`	Campo ordinamento: `name`, `createdAt`, `updatedAt`
`order`	string	`desc`	Direzione: `asc` o `desc`

Esempio:

bash

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

Risposta:

json

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

Dettaglio Documento

Informazioni documento

GET /api/documents/:id

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "contratto_fornitura.pdf",
    "originalName": "contratto_fornitura.pdf",
    "mimeType": "application/pdf",
    "size": 2458624,
    "status": "VECTORIZED",
    "topicId": "topic_123",
    "topic": {
      "id": "topic_123",
      "name": "Contratti",
      "color": "#3B82F6"
    },
    "description": "Contratto di fornitura servizi",
    "chunkCount": 47,
    "pageCount": 12,
    "processingInfo": {
      "ocrUsed": false,
      "language": "it",
      "processingTime": 15234
    },
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:31:15Z"
  }
}

Chunks del documento

GET /api/documents/:id/chunks

Restituisce i frammenti di testo indicizzati con i relativi metadati.

json

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

Stato di elaborazione

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" }
    ]
  }
}

Stati del Documento

Un documento attraversa i seguenti stati durante l'elaborazione:

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

Stato	Descrizione
`UPLOADED`	File ricevuto, in attesa di elaborazione
`PROCESSING`	Pipeline attiva (parsing, chunking, embedding, storage)
`VECTORIZED`	Elaborazione completata, documento disponibile per la ricerca
`ERROR`	Errore durante l'elaborazione

Fasi della pipeline: PARSING -> CHUNKING -> EMBEDDING -> STORAGE.

Gestione

Aggiorna metadati

PUT /api/documents/:id

json

{
  "topicId": "topic_789",
  "description": "Descrizione aggiornata del documento",
  "confidentiality": "confidential"
}

Elimina documento

DELETE /api/documents/:id

Rimuove il documento, tutti i chunks associati e i vettori dal database vettoriale.

Eliminazione multipla

DELETE /api/documents

json

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

Rielabora documento

POST /api/documents/:id/reprocess

Riavvia la pipeline di elaborazione. Utile dopo aggiornamenti alla configurazione di chunking o embedding.

json

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "status": "PROCESSING",
    "message": "Rielaborazione avviata"
  }
}

Download e Anteprima

Download originale

GET /api/documents/:id/download

Restituisce il file originale con gli header Content-Disposition appropriati.

Anteprima

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

json

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

Generazione Documenti

Queria include un motore di generazione documenti basato su template.

Lista template

GET /api/doc-engine/templates

Schema template

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

Restituisce lo schema dei campi richiesti per il rendering.

Rendering documento

POST /api/doc-engine/render

json

{
  "templateId": "tpl_report_standard",
  "data": {
    "titolo": "Report Trimestrale Q1 2026",
    "autore": "Mario Rossi",
    "sezioni": [
      { "titolo": "Riepilogo", "contenuto": "..." },
      { "titolo": "Analisi", "contenuto": "..." }
    ]
  },
  "format": "docx"
}

Restituisce il file DOCX generato come download diretto.

Errori Comuni

Codice	Errore	Descrizione
`400`	`INVALID_FILE_TYPE`	Formato file non supportato
`413`	`FILE_TOO_LARGE`	File supera la dimensione massima
`422`	`PROCESSING_ERROR`	Errore durante l'elaborazione del documento

Webhook (Coming Soon)

Eventi documento per notifiche asincrone:

Evento	Descrizione
`document.uploaded`	Documento caricato
`document.vectorized`	Elaborazione completata
`document.error`	Errore di elaborazione

Documenti API ​

Upload ​

Upload singolo ​

Upload multiplo ​

Import da URL ​

Limiti di Dimensione ​

Elenco e Ricerca ​

Dettaglio Documento ​

Informazioni documento ​

Chunks del documento ​

Stato di elaborazione ​

Stati del Documento ​

Gestione ​

Aggiorna metadati ​

Elimina documento ​

Eliminazione multipla ​

Rielabora documento ​

Download e Anteprima ​

Download originale ​

Anteprima ​

Generazione Documenti ​

Lista template ​

Schema template ​

Rendering documento ​

Errori Comuni ​

Webhook (Coming Soon) ​

Documenti API

Upload

Upload singolo

Upload multiplo

Import da URL

Limiti di Dimensione

Elenco e Ricerca

Dettaglio Documento

Informazioni documento

Chunks del documento

Stato di elaborazione

Stati del Documento

Gestione

Aggiorna metadati

Elimina documento

Eliminazione multipla

Rielabora documento

Download e Anteprima

Download originale

Anteprima

Generazione Documenti

Lista template

Schema template

Rendering documento

Errori Comuni

Webhook (Coming Soon)