List company documents

GET 
/company/documents

Ottiene un elenco paginato di tutti i documenti associati all'azienda dell'utente autenticato.

Flusso operativo:

1. Autenticazione tramite JWT valido con ruolo gestore o superiore
2. Validazione dei parametri di paginazione
3. Filtro opzionale per tipo di documento
4. Consultazione paginata al database (solo ultima versione di ciascun documento)
5. Restituzione dei documenti con metadati e percorsi dei file

Requisiti di accesso:

• Autenticazione: Token JWT valido (Bearer token)
• Ruolo minimo: Gestore aziendale (isGestor)
• Permessi: Accesso solo ai documenti della propria azienda

Casi d'uso tipici:

• Consultare fatture e contratti dell'azienda
• Filtrare documenti per categoria (documentType)
• Rivedere lo stato di approvazione dei documenti in sospeso
• Accedere alla cronologia delle versioni recenti

Stati del documento:

• pending: In attesa di revisione da parte dell'amministrazione
• approved: Approvato e disponibile per l'uso
• rejected: Rifiutato con motivo specificato

Considerazioni importanti:

• Restituisce solo l'ultima versione di ciascun documento (esclude versioni obsolete con newVersion: null)
• Tutti i timestamp sono in formato UTC
• Massimo 100 documenti per pagina
• Ordinamento per data di creazione decrescente (i più recenti per primi)
• I file sono archiviati in S3/MinIO con percorsi relativi in filePaths

Esempio di richiesta:

GET /company/documents?page=1&limit=25&documentType=648ac82b769e704acd2c73f5
Authorization: Bearer {token}

Esempio di risposta di successo:

\{
  docs: [
    \{
      _id: 5f8d3b7a9c2d1e

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"page","in":"query","description":"Numero di pagina per la navigazione nei risultati impaginati.\nUtile per suddividere la visualizzazione quando ci sono molti documenti.","required":false,"example":1,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Numero massimo di documenti da restituire per pagina.\nConsente di bilanciare le prestazioni (valori bassi) con la comodità (valori alti).","required":false,"example":25,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"documentType","in":"query","description":"Filtra i documenti per tipo specifico utilizzando il loro ID di MongoDB.\nI tipi disponibili si ottengono dall'endpoint /documents/types.\nUtile per visualizzare solo fatture, contratti o altre categorie.","required":false,"example":"648ac82b769e704acd2c73f5","schema":{"type":"string","format":"ObjectId","pattern":"^[a-f0-9]{24}$"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Lista dei documenti ottenuta con successo.","content":{"application/json":{"schema":{"type":"object","description":"Risposta paginata con elenco dei documenti aziendali","properties":{"docs":{"type":"array","description":"Elenco dei documenti della pagina corrente","items":{"type":"object","description":"Rappresenta un documento aziendale con i suoi metadati.","properties":{"_id":{"type":"string","description":"Identificatore univoco del documento (MongoDB ObjectId)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","example":"5f8d3b7a9c2d1e0f4a6b5c4d"},"name":{"type":"string","description":"Nome descrittivo del documento","minLength":3,"maxLength":100,"example":"Factura Q1 2023"},"status":{"type":"string","description":"Stato di approvazione del documento","enum":["pending","approved","rejected"],"example":"approved"},"documentType":{"type":"string","description":"ID del tipo di documento (riferimento a /documents/types)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","example":"5f8d3b7a9c2d1e0f4a6b5c4e"},"version":{"type":"integer","description":"Numero di versione del documento","minimum":1,"example":1},"filePaths":{"type":"array","description":"Percorsi dei file in S3/MinIO (relativi al bucket)","items":{"type":"string"},"example":["documents/company1/factura_q1.pdf","documents/company1/anexo.pdf"]},"previousVersion":{"type":"string","description":"ID della versione precedente (null se è la prima versione)","format":"ObjectId","pattern":"^[a-f0-9]{24}$","nullable":true,"example":null},"createdAt":{"type":"string","description":"Data di creazione del documento (UTC)","format":"date-time","example":"2023-04-15T09:30:00.000Z"},"updatedAt":{"type":"string","description":"Data dell'ultimo aggiornamento (UTC)","format":"date-time","example":"2023-04-20T14:15:00.000Z"}},"title":"Document"}},"totalDocs":{"type":"integer","description":"Totale documenti trovati (tutte le pagine)","example":15},"limit":{"type":"integer","description":"Limite di documenti per pagina","example":10},"page":{"type":"integer","description":"Pagina corrente","example":1},"totalPages":{"type":"integer","description":"Totale delle pagine disponibili","example":2}},"title":"DocumentsPaginatedResponse"},"example":{"docs":[{"_id":"5f8d3b7a9c2d1e0f4a6b5c4d","name":"Factura Q1 2023","status":"approved","documentType":"5f8d3b7a9c2d1e0f4a6b5c4e","version":1,"filePaths":["documents/company1/factura_q1.pdf"],"createdAt":"2023-04-15T09:30:00.000Z","updatedAt":"2023-04-20T14:15:00.000Z"},{"_id":"5f8d3b7a9c2d1e0f4a6b5c4f","name":"Contrato de Servicios","status":"pending","documentType":"5f8d3b7a9c2d1e0f4a6b5c50","version":2,"filePaths":["documents/company1/contrato_v2.pdf","documents/company1/anexo.pdf"],"createdAt":"2023-05-10T11:20:00.000Z","updatedAt":"2023-05-12T16:45:00.000Z"}],"totalDocs":15,"limit":10,"page":1,"totalPages":2}}}},"401":{"description":"Non autorizzato - Token JWT non valido o mancante","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["NO_TOKEN","TOKEN_NOT_VALID"]}}},"example":{"error":"NO_TOKEN"}}}},"403":{"description":"Vietato - Permessi insufficienti","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"NOT_ALLOWED"}}}}}}
>
  
</StatusCodes>