POST/v1/uploads/{upload_id}/complete

Completar una pujada

complete_upload

Quan s’han rebut totes les parts, Sursa munta el fitxer, compara l’SHA-256 del fitxer sencer amb sha256 del cos i executa les mateixes comprovacions que per a una pujada en una sola sol·licitud: el format per la signatura del contingut i l’anàlisi antivirus. El resultat és ready, o rejected amb reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Cada rebuig de la comprovació de format o de l’antivirus s’anota al registre d’auditoria com a file.rejected.

Una resposta 200 indica que el resultat ja està llest; 202 indica que el fitxer encara s’està comprovant (processing), i el resultat s’obté de GET /v1/uploads/{upload_id}. Si l’estat torna a pending (un reinici d’una instància de l’API ha interromput la comprovació), torneu a enviar complete. Repetir complete després del resultat retorna el mateix resultat. Si falten parts, es retorna 409 uploads.incomplete (details.missing). Un sha256 diferent del declarat en la creació, o un parts[].etag diferent d’una part rebuda, retorna 422 uploads.checksum_mismatch. Una pujada preparada que no es fa servir es conserva durant 24 hores. Afegit a la 1.62.0.

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de camí

upload_idstringobligatori
L’ID de la pujada (upl_ seguit de 32 caràcters hexadecimals).
length ≤ 64

Paràmetres de capçalera

Idempotency-Keystring
Clau per reintentar una escriptura de manera segura: d’1 a 255 caràcters ASCII imprimibles; es recomana un UUID v4 per operació lògica. Un reintent amb la mateixa clau en un termini de 24 hores no torna a executar l’operació: retorna la resposta desada (estat, capçaleres i cos) amb la capçalera Idempotency-Replayed: true. La mateixa clau amb un mètode, un camí, un Content-Type o un cos diferents retorna 409 api.idempotency_mismatch; mentre la primera sol·licitud encara s’executa, 409 api.idempotency_in_progress amb Retry-After: 1. Després d’una resposta 5xx o 429 la clau s’allibera, i un reintent torna a executar l’operació. L’abast de la clau és l’organització i qui fa la crida (clau d’API, usuari o clau de font personalitzada).
length ≥ 1, length ≤ 255

Cos de la sol·licitud

application/json

Objecte: UploadComplete

sha256stringobligatori
SHA-256 del fitxer sencer.
partsarray of UploadPartRef
Comprovació opcional de les parts: l’ETag de cada part tal com el retorna PUT …/parts/{n}.
items ≤ 1000

Respostes

200El resultat ja està llest: `ready` o `rejected`.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.
Idempotency-Replayed
true indica que la resposta s’ha reproduït a partir de la desada per a aquesta Idempotency-Key: l’operació no s’ha tornat a executar.

application/json

Objecte: Upload

idstringobligatori
ID de la pujada (upl_ seguit de 32 caràcters hexadecimals).
purposeUploadPurposeobligatori
filenamestringobligatori
Nom del fitxer (sense carpetes).
content_typestringobligatori
Tipus de contingut declarat; buit si no s’ha declarat.
sizeinteger (int64)obligatori
Mida del fitxer en bytes.
sha256string | nullobligatori
SHA-256 del fitxer, declarat en la creació o a complete; null si encara no se sap.
statusUploadStatusobligatori
part_sizeinteger (int64)obligatori
Mida de cada part excepte l’última (de 5 a 100 MiB).
part_countintegerobligatori
Nombre de parts.
≥ 1, ≤ 1000
parts_receivedintegerobligatori
Nombre de parts rebudes.
≥ 0
partsarray of UploadPartobligatori
Parts rebudes per número (buit a la resposta de POST /v1/uploads).
reject_reasonstring | nullobligatori
Motiu del rebuig (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’enumeració pot créixer; null si no s’ha rebutjat.
reject_detailsobject | nullobligatori
Detalls del rebuig (l’extensió, el format declarat i el detectat, les sumes de verificació); null si no s’ha rebutjat.
created_atstring (date-time)obligatori
Moment de creació de la pujada.
expires_atstring (date-time)obligatori
Termini per completar la pujada i, quan estigui llesta, per fer-la servir.
completed_atstring (date-time) | nullobligatori
Moment en què va acabar la comprovació (ready o rejected).
consumed_atstring (date-time) | nullobligatori
Moment en què es va fer servir la pujada (per a una entrada, un arxiu comprimit o una importació).

202El fitxer encara s’està comprovant (`processing`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.
Idempotency-Replayed
true indica que la resposta s’ha reproduït a partir de la desada per a aquesta Idempotency-Key: l’operació no s’ha tornat a executar.

application/json

Objecte: Upload

idstringobligatori
ID de la pujada (upl_ seguit de 32 caràcters hexadecimals).
purposeUploadPurposeobligatori
filenamestringobligatori
Nom del fitxer (sense carpetes).
content_typestringobligatori
Tipus de contingut declarat; buit si no s’ha declarat.
sizeinteger (int64)obligatori
Mida del fitxer en bytes.
sha256string | nullobligatori
SHA-256 del fitxer, declarat en la creació o a complete; null si encara no se sap.
statusUploadStatusobligatori
part_sizeinteger (int64)obligatori
Mida de cada part excepte l’última (de 5 a 100 MiB).
part_countintegerobligatori
Nombre de parts.
≥ 1, ≤ 1000
parts_receivedintegerobligatori
Nombre de parts rebudes.
≥ 0
partsarray of UploadPartobligatori
Parts rebudes per número (buit a la resposta de POST /v1/uploads).
reject_reasonstring | nullobligatori
Motiu del rebuig (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. L’enumeració pot créixer; null si no s’ha rebutjat.
reject_detailsobject | nullobligatori
Detalls del rebuig (l’extensió, el format declarat i el detectat, les sumes de verificació); null si no s’ha rebutjat.
created_atstring (date-time)obligatori
Moment de creació de la pujada.
expires_atstring (date-time)obligatori
Termini per completar la pujada i, quan estigui llesta, per fer-la servir.
completed_atstring (date-time) | nullobligatori
Moment en què va acabar la comprovació (ready o rejected).
consumed_atstring (date-time) | nullobligatori
Moment en què es va fer servir la pujada (per a una entrada, un arxiu comprimit o una importació).

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

409L’estat de l’objecte no permet l’acció; per exemple, un duplicat, una indexació en curs o un treball que ja s’ha processat.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

410L’objecte existia però ja no està disponible: l’enllaç ja s’ha fet servir o ha caducat, o el fitxer s’ha eliminat en acabar el seu període de conservació.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

Retry-After
Nombre de segons que cal esperar abans de reintentar la sol·licitud.
RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Reintents segurs

Envieu una capçalera Idempotency-Key (per exemple, un UUID) amb cada POST i PATCH. Un reintent amb la mateixa clau en un termini de 24 hores retorna la resposta desada en lloc de tornar a executar la sol·licitud.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← uploads · Referència de l’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"

Provar

Clau d’API

La clau es queda a la memòria d’aquesta pestanya i només s’envia a https://api.sursa.com.

Les sol·licituds actuen sobre les dades reals de la vostra organització.

Idempotency-Key header

upload_id path *

Idempotency-Key

Si és buit, es genera una clau nova per a cada sol·licitud.

Cos de la sol·licitud (JSON)