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.
1. Richiedi un indirizzo di caricamento
Sezione intitolata “1. Richiedi un indirizzo di caricamento”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
filename | stringa | ✅ | Nome file; il server determina il tipo di file in base all’estensione |
file_size | intero | ✅ | Dimensione esatta in byte, maggiore di 0 |
mime_type | stringa | — | 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}2. Invia il file
Sezione intitolata “2. Invia il file”Invia un PUT a upload_url con i byte del file grezzo come corpo, e invia ogni intestazione in upload_headers esattamente come indicato.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --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.
3. Conferma il documento
Sezione intitolata “3. Conferma il documento”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-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.
Nomi dei file
Sezione intitolata “Nomi dei file”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.
| Stato | Causa |
|---|---|
400 | Nome o dimensione del file non validi, oppure la dimensione caricata differisce da quella richiesta |
401 | Credenziale o finalize_token non valida o scaduta |
403 | Il finalize_token appartiene a un altro account |
410 | Il file caricato non è stato trovato (trasferimento incompleto o indirizzo scaduto); richiedi un nuovo indirizzo |
413 | Supera il limite di dimensione per file |
415 | Formato non supportato o il contenuto non corrisponde all’estensione |
422 | Il file Office è danneggiato o presenta problemi strutturali. |
429 | Troppi caricamenti |
503 | Il servizio di caricamento è temporaneamente non disponibile; riprova più tardi |