Salta ai contenuti

Carica file

Il caricamento avviene in tre passaggi: richiedere un indirizzo di upload, inviare il file e confermare il documento. Un indirizzo di upload può essere generato una sola volta ed è valido per un massimo di 1 ora.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
CampoTipoObbligatorioDescrizione
filenamestringa✅Nome file; il server determina il tipo di file in base all’estensione
file_sizeintero✅Dimensione esatta in byte, maggiore di 0
mime_typestringa—Opzionale; il server non lo utilizza

Risposta:

{
"document_id": "4q8mx2q9z1k7p6ra",
"upload_url": "https://upload.example/...",
"upload_headers": {
"Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"If-None-Match": "*"
},
"finalize_token": "short_lived_token",
"expires_in": 3600
}

Invia un PUT a upload_url con i byte del file grezzo come corpo, e invia ogni intestazione in upload_headers esattamente come indicato.

Terminal window
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

Non inviare la tua chiave API OmniDoc in questa fase. Se l’indirizzo scade o il trasferimento fallisce, richiedine una nuova.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

In caso di successo, viene restituito il documento:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

Solo dopo la conferma il documento viene inserito nella libreria dei file ed è utilizzabile per i lavori.

filename è solo per la visualizzazione; non utilizzarlo come percorso o identificatore univoco. Il server sostituisce i caratteri illegali e genera un nome di download sicuro per i nomi troppo lunghi.

StatoCausa
400Nome o dimensione del file non validi, oppure la dimensione caricata differisce da quella richiesta
401Credenziale o finalize_token non valida o scaduta
403Il finalize_token appartiene a un altro account
410Il file caricato non è stato trovato (trasferimento incompleto o indirizzo scaduto); richiedi un nuovo indirizzo
413Supera il limite di dimensione per file
415Formato non supportato o il contenuto non corrisponde all’estensione
422Il file Office è danneggiato o presenta problemi strutturali.
429Troppi caricamenti
503Il servizio di caricamento è temporaneamente non disponibile; riprova più tardi