.url`, insieme a `expires_in: 900` |
| Batch perceive V2, modalità ZIP | `zip.url` |
| Ingest V2, al completamento | `output_url` |
Gli URL firmati sono riutilizzabili, non monouso. Lo stesso URL continua a funzionare per GET ripetute finché non trascorrono i 15 minuti. Nulla lo invalida prima, e scaricarlo una volta non lo consuma.
Se ti serve il file per più di 15 minuti, scarica i byte e conservali tu. La rifirma ti dà un link nuovo, non un accesso permanente.
---
## Rifirma
Un link scaduto non è un file perso. Richiedilo di nuovo all'API e questa conia una nuova firma sullo stesso oggetto salvato:
| Job | Rifirma con |
|-----|--------------|
| Conversione V1 asincrona o batch | `GET /v1/convert/batch/{batch_id}` |
| Conversione sincrona V1 interrogata con il tuo id | `GET /v1/convert/status/{job_id}` |
| Operazione perceive V2 | `GET /v2/perceive/{operation_id}` |
| Batch perceive V2 | `GET /v2/perceive/batch/{job_id}` |
| Job ingest V2 | `GET /v2/ingest/{job_id}` |
Ognuno di questi endpoint ricostruisce gli URL dalle object key salvate a ogni chiamata. La rifirma non renderizza nulla, non converte nulla e non addebita ops. Funziona finché l'oggetto è ancora nello storage, che è l'altro orologio di questa pagina.
Un comportamento da gestire nel codice: se la firma non può essere prodotta, il campo torna `null` invece di far fallire la richiesta. Un polling di stato non restituisce mai un 500 a causa di una chiave obsoleta. Quindi controlla che `url`, `download_url` e `output_url` non siano `null` prima di dereferenziarli.
---
## La retention è un altro orologio
Questa è la distinzione che si sbaglia più spesso, quindi eccola in una riga per ciascuna:
- **La scadenza della firma (15 minuti)** decide per quanto tempo funziona un dato URL.
- **La retention (da ore a giorni, in base al piano)** decide per quanto tempo il file esiste.
Sono indipendenti, il che significa che entrambi i casi confusi sono reali:
**Un URL scaduto non significa che il file sia sparito.** Quindici minuti dopo una conversione il link è morto, ma l'oggetto è quasi certamente ancora lì. Interroga di nuovo il job e riottieni un link funzionante.
**Un URL valido non garantisce che il file ci sia ancora.** Se rifirmi un output del piano Founding al minuto 59 e usi il link al minuto 62, nel frattempo lo sweep di retention potrebbe aver eliminato l'oggetto. La firma è valida; l'oggetto no. Il download fallisce a livello di storage, non a livello di API.
La durata della retention è impostata per piano sul tuo abbonamento, e la finestra del piano Founding è di un'ora, abbastanza breve da incontrarla per caso durante lo sviluppo. La tabella per piano è in [Rate limit e quote](/it/docs/reference/rate-limits.md).
Altre due cose sulla retention che vale la pena sapere:
- L'eliminazione viene pianificata e poi eseguita a intervalli, quindi un file può sopravvivere alla propria finestra di qualche minuto. Non costruirci sopra. È tolleranza dello sweeper, non un periodo di grazia.
- Per i progetti con un add-on di storage non viene pianificata alcuna eliminazione. I loro output restano finché non vengono rimossi deliberatamente e contano invece sulla quota di storage dell'add-on.
Separatamente dalla finestra del tuo piano, le catture di HTML renderizzato usate per il punteggio di qualità del render vengono conservate per 90 giorni e possono essere disattivate per singola richiesta con l'header `X-Enconvert-No-Capture: true`. I file sorgente caricati su `POST /v2/ingest/files` vengono eliminati non appena il JSONL è assemblato, con un limite di sicurezza di 24 ore se qualcosa va storto prima.
---
## direct_download: trasmettere invece i byte
Se seguire un URL è un passaggio in più che non vuoi, chiedi i byte nel body della risposta.
### Su perceive V2
`direct_download: true` su `POST /v2/perceive` sostituisce completamente la busta JSON. Il body della risposta è l'artefatto, servito con il content type dell'artefatto stesso.
```bash
curl -X POST https://api.enconvert.com/v2/perceive \
-H "X-API-Key: sk_your_private_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/pricing",
"outputs": ["markdown"],
"direct_download": true
}' \
--output pricing.md
```
Richiede esattamente un output che produca un artefatto: `markdown`, `html_cleaned`, `html_raw`, `screenshot`, `screenshot_full_page`, `pdf`, `links` o `images`, tutti descritti nella [pagina perceive](/it/docs/endpoints/perceive.md). Chiedine due e la chiamata restituisce `400` elencando ciò che hai inviato. `structured` non conta, perché è JSON inline e non un file salvato, quindi può viaggiare insieme senza infrangere la regola.
I metadati che sarebbero stati nel body JSON si spostano negli header: `X-Operation-Id`, `X-Object-Key` e `X-Cache-Hit` sempre, più `X-Render-Quality`, `X-Source-Status-Code`, `X-Content-Hash` e `X-Warnings-Count` quando quei valori esistono. La risposta porta anche `Content-Disposition: attachment`, `Content-Length` e `Cache-Control: no-transform`.
Due endpoint GET accettano `direct_download` come parametro di query:
- `GET /v2/perceive/{operation_id}?direct_download=true&output=markdown` trasmette un artefatto di un'operazione passata. `output` è obbligatorio quando l'operazione ha prodotto più di un artefatto, e un nome sconosciuto restituisce `404`.
- `GET /v2/perceive/batch/{job_id}?direct_download=true` trasmette lo ZIP del batch per i batch con `output_mode: "zip"` il cui archivio è pronto, e altrimenti risponde `400`.
`POST /v2/perceive/batch` rifiuta `direct_download` con `422`. Imposta invece `output_mode` su `"zip"` e scarica l'archivio.
direct_download non salta lo storage. L'artefatto viene prima caricato, poi riletto e trasmesso a te. Per questo un artefatto oltre la sua finestra di retention risponde 410 Gone con un messaggio che ti dice di rieseguire la richiesta, invece di restituire silenziosamente byte vuoti. Il risparmio è un round trip, non una scrittura su storage.
### Sulle conversioni V1
Anche V1 ha un campo `direct_download`, con un comportamento diverso da quello di V2. Sugli endpoint URL decide se l'API restituisce i byte grezzi del file oppure un corpo JSON con un URL di download presigned. Sugli endpoint di upload viene accettato per parità di forma con la richiesta, ma non ha effetto: quegli endpoint rispondono sempre con il corpo JSON.
| Tipo di endpoint | Tipo di chiave | Default | Che cosa torna |
|---|---|---|---|
| Endpoint di upload file | Tutte le chiavi | `true` | JSON con `presigned_url`, qualunque valore imposti. Qui il campo è inerte. |
| Endpoint URL | Chiave privata | `false` | JSON con `presigned_url`. Imposta `true` per i byte grezzi. |
| Endpoint URL | Chiave pubblica / dashboard | `true` (forzato) | JSON con `presigned_url` |
Comportamento delle chiavi pubbliche: Per le chiavi pubbliche e dashboard, direct_download è forzato a true, ma la risposta è un oggetto JSON con un presigned_url (non byte grezzi). Questo evita problemi di timeout del reverse proxy con file di grandi dimensioni che possono richiedere da 60 a 120 secondi per essere convertiti.
Su un endpoint URL, una chiave privata con `direct_download=true` restituisce i byte grezzi del file:
```bash
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
-H "X-API-Key: sk_your_private_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "direct_download": true}' \
--output output.pdf
```
Restrizioni:
- `direct_download` non può essere usato con `async_mode: true` (restituisce `400`)
- `direct_download` non può essere usato con più URL (restituisce `400`)
Entrambe le restrizioni derivano dallo stesso fatto: una volta che la chiamata ha risposto `202` non resta più una risposta in cui mettere i byte. I risultati asincroni si raccolgono tramite polling o webhook. Consulta [Job sincroni e asincroni](/it/docs/concepts/sync-and-async.md).
### Header di risposta
Le conversioni di file caricati, e le conversioni da URL fatte con una chiave pubblica o dashboard, ripetono i metadati della conversione negli header oltre che nel corpo JSON:
| Header | Descrizione |
|--------|-------------|
| `X-Object-Key` | Percorso di storage del file convertito |
| `X-File-Size` | Dimensione del file convertito in byte |
| `X-Conversion-Time` | Tempo impiegato per la conversione in secondi |
| `X-Filename` | Nome del file generato |
Una risposta a byte grezzi (endpoint URL, chiave privata, `direct_download: true`) porta quei quattro header più `Content-Disposition: attachment; filename="{filename}"`, `Content-Length` e `Cache-Control: no-transform`. Una conversione da URL che restituisce JSON a una chiave privata non ne porta nessuno, quindi leggi il corpo.
---
## Domande frequenti
### Quanto restano validi gli URL di download firmati di EnConvert?
Quindici minuti, ovvero 900 secondi, sia su V1 sia su V2. La busta dell'artefatto V2 lo indica esplicitamente come `expires_in: 900`. Non esiste alcun parametro per estenderlo. Recupera di nuovo il job o l'operazione per coniare un URL nuovo sullo stesso file.
### Posso usare un URL firmato più di una volta?
Sì. Gli URL firmati non sono monouso. Lo stesso link serve GET ripetute finché non trascorrono i 15 minuti, e scaricarlo non lo invalida.
### Il mio URL di download è scaduto. Il file è stato eliminato?
Quasi certamente no. La scadenza della firma e la retention del file sono due orologi separati. Interroga di nuovo il job o l'operazione (`GET /v1/convert/batch/{batch_id}`, `GET /v2/perceive/{operation_id}`, `GET /v2/ingest/{job_id}`) e ottieni un link firmato di fresco senza alcun costo in ops, purché il file sia ancora dentro la finestra di retention del tuo piano.
### Per quanto tempo EnConvert conserva i miei file convertiti?
La retention è impostata per piano, e il piano Founding conserva gli output per un'ora. I piani a pagamento li conservano più a lungo, e i progetti con un add-on di storage non vengono mai ripuliti. I numeri per piano sono in [Rate limit e quote](/it/docs/reference/rate-limits.md).
### Cosa significa un 410 Gone su un artefatto di perceive?
L'oggetto ha superato la finestra di retention del tuo piano ed è stato eliminato dallo storage. `direct_download` rilegge l'artefatto dallo storage prima di trasmetterlo, quindi un artefatto scaduto risponde `410` invece di un body vuoto. Riesegui la richiesta perceive per rigenerarlo.
### Come ottengo i byte grezzi invece di un URL di download?
Imposta `direct_download: true`. Su `POST /v2/perceive` richiede esattamente un output che produca un artefatto e il body della risposta diventa quell'artefatto. Sugli endpoint URL V1 con una chiave privata restituisce i byte del file, e non può essere combinato con `async_mode` né con più URL.