File, grafici e link di download

Carica un'immagine o un PDF una volta sola e richiamalo per id. Inserisci in un documento un grafico costruito dai numeri. Rendi il risultato più leggero. Consegnalo a chi non ha una chiave, con un indirizzo che scade e può essere revocato.

File archiviati

Chiamata	Cosa fa
`POST /api/v1/compose/files`	Carica un file e ottieni un `fileId`. Invia `multipart/form-data` con una parte chiamata `file`, oppure JSON `{"fileBase64": "...", "fileName": "..."}`, oppure i byte grezzi con qualsiasi altro content type. Richiede `documents:compose`.
`GET /api/v1/compose/files` e `/files/{fileId}`	I file dell’organizzazione, o i dati di un singolo file. Richiede `documents:read`.
`DELETE /api/v1/compose/files/{fileId}`	Elimina subito i byte e l'id.

Il tipo lo decidono i byte. Sono accettati PNG, JPEG, WebP e PDF; del nome e del content type dichiarato non ci si fida mai. SVG è rifiutato (è un contenitore di script).
Un PDF viene rifiutato (FILE_REJECTED, details.reason) se è cifrato, danneggiato, ha più di 500 pagine o contiene contenuti attivi: JavaScript, azioni di avvio, file incorporati o moduli che inviano dati.
I file sono cifrati a riposo e appartengono alla tua organizzazione: l’id di un’altra organizzazione risponde 404 STORED_FILE_NOT_FOUND, come uno che non esiste. Scadono dopo 30 giorni per impostazione predefinita (su richiesta possiamo impostare fino a 365 giorni per la tua organizzazione); caricare di nuovo gli stessi byte restituisce lo stesso id e sposta in avanti la scadenza.
Un file al massimo di asset_bytes (10 MB per impostazione predefinita); un numero limitato di file per organizzazione (FILE_LIMIT_REACHED). I caricamenti accettano un Idempotency-Key.

Usare un file

Un'immagine nel payload. Dove il payload conterrebbe un URI data:image/... per :::img o per un img src HTML, invia invece l'id:

{ "receipt": { "$fileId": "7d3f6a52-..." } }

Viene sostituito dall'immagine prima del rendering, al massimo 20 per richiesta. Il tuo payload viene conservato con il riferimento, mai con i pixel.

PDF dopo il documento. settings.attachments accetta fino a 5 id di PDF archiviati, accodati in ordine dopo le pagine generate e prima di filigrana, colore, compressione, metadati e password, così questi si applicano a tutto. Le annotazioni delle pagine accodate vengono eliminate, quindi nessun link o campo modulo del PDF di qualcun altro arriva nel risultato. Le pagine contano per il tuo limite di pagine.

Grafici

Vedi il codice :::chart: un grafico a barre, a linee o a torta dai numeri del payload, nei modelli Word e HTML.

Compressione

settings.compressionLevel (none, lossless, balanced, small) è descritto nella tabella delle impostazioni. Misurato su modelli reali con scripts/measure_compression.py: il risultato dei modelli Word si riduce dal 27 al 60 % anche con lossless (font, struttura) e senza perdita sulle immagini; il risultato dei modelli HTML è già compatto e può crescere, ed è per questo che il file non viene mai restituito più grande di com'era; una pagina ricca di fotografie si riduce di circa il 98 % con balanced, a 150 dpi.

Link di download firmati

Chiamata	Cosa fa
`POST /api/v1/compose/documents/{id}/download-links`	`{"expiresInSeconds"?, "singleUse"?}`. Crea un link. `url` e `token` compaiono solo in questa risposta.
`GET /api/v1/compose/documents/{id}/download-links`	I link di un documento e il loro `state`: `active`, `used`, `expired`, `revoked`. Mai i token.
`DELETE .../download-links/{linkId}` e `DELETE .../download-links`	Revoca un link, o tutti i link attivi del documento.
`GET /dl/{token}`	Pubblico: nessuna chiave, nessun cookie. Restituisce il PDF.

Richiedono documents:download. Anche la pagina del documento nella console elenca i link e li revoca.

Brevi per impostazione predefinita: 1 ora. Puoi chiedere fino al massimo della tua organizzazione (48 ore per impostazione predefinita; su richiesta possiamo impostarne un altro per la tua organizzazione, mai oltre sette giorni); una durata maggiore viene rifiutata, mai accorciata in silenzio.
A prova di manomissione: il token è firmato sul link, sulla tua organizzazione, sul documento e sullo SHA-256 del documento. Il token di un documento non può scaricarne un altro, né quello di un’altra organizzazione. La risposta alla creazione riporta lo SHA-256 così puoi verificare ciò che hai scaricato.
Revocabili, all'istante. singleUse: true brucia il link alla sua prima richiesta, anche se poi il client non riesce a leggere il corpo.
Risposte: 404 DOWNLOAD_LINK_INVALID per un indirizzo sconosciuto, alterato, revocato o già usato (un'unica risposta, così non può essere sondato); 410 DOWNLOAD_LINK_EXPIRED per un link autentico oltre la sua scadenza. Limite di frequenza per indirizzo del chiamante; mai in cache (Cache-Control: no-store).
Ogni creazione, uso e revoca è una voce del registro delle attività. Un documento generato dataless non ha nulla a cui collegarsi.
Il token fa parte del percorso dell'URL, quindi può comparire nei log di accesso lungo il tragitto. Ecco perché la durata predefinita è breve e perché puoi revocarlo.

PDF/A: convertito, non verificato

settings.pdfA chiede una conversione al meglio delle possibilità. Non convalidiamo il risultato con un validatore PDF/A, quindi non diciamo mai che il file è conforme: ogni conversione restituisce l'avviso PDFA_NOT_VERIFIED e output.compose.pdfa.verified è false. Se devi farci affidamento, convalida tu il file.