POST/v1/uploads/{upload_id}/complete

Completare un caricamento

complete_upload

Quando tutte le parti sono state ricevute, Sursa assembla il file, confronta lo SHA-256 dell’intero file con sha256 nel corpo ed esegue gli stessi controlli di un caricamento con una sola richiesta: il formato in base alla firma del contenuto e la scansione antivirus. Il risultato è ready, oppure rejected con reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Ogni rifiuto da parte del controllo del formato o dell’antivirus viene scritto nel registro di audit come file.rejected.

Una risposta 200 indica che il risultato è pronto; 202 indica che il file è ancora in fase di controllo (processing) e il risultato arriva da GET /v1/uploads/{upload_id}. Se lo stato torna a pending (un riavvio di un’istanza dell’API ha interrotto il controllo), invia di nuovo complete. Ripetere complete dopo il risultato restituisce lo stesso risultato. Le parti mancanti restituiscono 409 uploads.incomplete (details.missing). Uno sha256 diverso da quello dichiarato alla creazione, o un parts[].etag diverso da una parte ricevuta, restituisce 422 uploads.checksum_mismatch. Un caricamento pronto e non usato resta disponibile per 24 ore. Aggiunto nella 1.62.0.

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di percorso

upload_idstringobbligatorio
ID del caricamento (upl_ seguito da 32 caratteri esadecimali).
length ≤ 64

Parametri di intestazione

Idempotency-Keystring
Chiave per ripetere in sicurezza una scrittura: da 1 a 255 caratteri ASCII stampabili; si consiglia un UUID v4 per ogni operazione logica. Un nuovo tentativo con la stessa chiave entro 24 ore non esegue di nuovo l’operazione: restituisce la risposta salvata (stato, intestazioni e corpo) con l’intestazione Idempotency-Replayed: true. La stessa chiave con un metodo, un percorso, un Content-Type o un corpo diversi restituisce 409 api.idempotency_mismatch; mentre la prima richiesta è ancora in esecuzione, 409 api.idempotency_in_progress con Retry-After: 1. Dopo una risposta 5xx o 429 la chiave viene rilasciata e un nuovo tentativo esegue di nuovo l’operazione. La chiave vale per l’organizzazione e per chi effettua la chiamata (chiave API, utente o chiave di una fonte personalizzata).
length ≥ 1, length ≤ 255

Corpo della richiesta

application/json

Oggetto: UploadComplete

sha256stringobbligatorio
Lo SHA-256 dell’intero file.
partsarray of UploadPartRef
Controllo facoltativo delle parti: l’ETag di ogni parte come restituito da PUT …/parts/{n}.
items ≤ 1000

Risposte

200Il risultato è pronto: `ready` o `rejected`.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.
Idempotency-Replayed
true indica che la risposta è stata ripetuta da quella salvata per questa Idempotency-Key: l’operazione non è stata eseguita di nuovo.

application/json

Oggetto: Upload

idstringobbligatorio
L’ID del caricamento (upl_ seguito da 32 caratteri esadecimali).
purposeUploadPurposeobbligatorio
filenamestringobbligatorio
Il nome del file (senza cartelle).
content_typestringobbligatorio
Il tipo di contenuto dichiarato; vuoto se non dichiarato.
sizeinteger (int64)obbligatorio
La dimensione del file in byte.
sha256string | nullobbligatorio
Lo SHA-256 del file, dichiarato alla creazione o al complete; null se non è ancora noto.
statusUploadStatusobbligatorio
part_sizeinteger (int64)obbligatorio
La dimensione di ogni parte tranne l’ultima (da 5 a 100 MiB).
part_countintegerobbligatorio
Il numero di parti.
≥ 1, ≤ 1000
parts_receivedintegerobbligatorio
Il numero di parti ricevute.
≥ 0
partsarray of UploadPartobbligatorio
Le parti ricevute per numero (vuoto nella risposta di POST /v1/uploads).
reject_reasonstring | nullobbligatorio
Il motivo del rifiuto (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’enumerazione può crescere; null se non rifiutato.
reject_detailsobject | nullobbligatorio
Dettagli del rifiuto (l’estensione, il formato dichiarato e quello rilevato, i checksum); null se non rifiutato.
created_atstring (date-time)obbligatorio
Momento della creazione del caricamento.
expires_atstring (date-time)obbligatorio
Il termine per completare il caricamento e, una volta pronto, per usarlo.
completed_atstring (date-time) | nullobbligatorio
Momento in cui il controllo è terminato (ready o rejected).
consumed_atstring (date-time) | nullobbligatorio
Momento in cui il caricamento è stato usato (da una scheda, un archivio o un’importazione).

202Il file è ancora in fase di controllo (`processing`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.
Idempotency-Replayed
true indica che la risposta è stata ripetuta da quella salvata per questa Idempotency-Key: l’operazione non è stata eseguita di nuovo.

application/json

Oggetto: Upload

idstringobbligatorio
L’ID del caricamento (upl_ seguito da 32 caratteri esadecimali).
purposeUploadPurposeobbligatorio
filenamestringobbligatorio
Il nome del file (senza cartelle).
content_typestringobbligatorio
Il tipo di contenuto dichiarato; vuoto se non dichiarato.
sizeinteger (int64)obbligatorio
La dimensione del file in byte.
sha256string | nullobbligatorio
Lo SHA-256 del file, dichiarato alla creazione o al complete; null se non è ancora noto.
statusUploadStatusobbligatorio
part_sizeinteger (int64)obbligatorio
La dimensione di ogni parte tranne l’ultima (da 5 a 100 MiB).
part_countintegerobbligatorio
Il numero di parti.
≥ 1, ≤ 1000
parts_receivedintegerobbligatorio
Il numero di parti ricevute.
≥ 0
partsarray of UploadPartobbligatorio
Le parti ricevute per numero (vuoto nella risposta di POST /v1/uploads).
reject_reasonstring | nullobbligatorio
Il motivo del rifiuto (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’enumerazione può crescere; null se non rifiutato.
reject_detailsobject | nullobbligatorio
Dettagli del rifiuto (l’estensione, il formato dichiarato e quello rilevato, i checksum); null se non rifiutato.
created_atstring (date-time)obbligatorio
Momento della creazione del caricamento.
expires_atstring (date-time)obbligatorio
Il termine per completare il caricamento e, una volta pronto, per usarlo.
completed_atstring (date-time) | nullobbligatorio
Momento in cui il controllo è terminato (ready o rejected).
consumed_atstring (date-time) | nullobbligatorio
Momento in cui il caricamento è stato usato (da una scheda, un archivio o un’importazione).

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

409Lo stato dell’oggetto non consente l’azione, ad esempio un duplicato, un’indicizzazione in corso o un job già elaborato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

410L’oggetto esisteva ma non è più disponibile: il link è stato usato o è scaduto, oppure il file è stato eliminato al termine del suo periodo di conservazione.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

Retry-After
Numero di secondi da attendere prima di ripetere la richiesta.
RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (per esempio un UUID) con ogni POST e PATCH. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo la richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← uploads · Riferimento API

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

Chiave API

La chiave resta nella memoria di questa scheda del browser e viene inviata solo a https://api.sursa.com.

Le richieste vengono eseguite sui dati reali della tua organizzazione.

Idempotency-Key header

upload_id path *

Idempotency-Key

Se il campo è vuoto, per ogni richiesta viene generata una nuova chiave.

Corpo della richiesta (JSON)