Salt la conținut
Sursa Developers

POST/v1/uploads/{upload_id}/complete

Finalizează o încărcare

complete_upload

Când toate părțile sunt primite, Sursa asamblează fișierul, compară SHA-256 al întregului fișier cu sha256 din corp și execută aceleași verificări ca pentru o încărcare într-o singură cerere: formatul după semnătura conținutului și scanarea antivirus. Rezultatul este ready sau rejected cu reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Fiecare respingere la verificarea formatului sau la scanarea antivirus este înregistrată în jurnalul de audit ca file.rejected.

Un răspuns 200 înseamnă că rezultatul este gata; 202 înseamnă că fișierul este încă în verificare (processing), iar rezultatul se obține cu GET /v1/uploads/{upload_id}. Dacă starea revine la pending (repornirea unei instanțe API a întrerupt verificarea), trimiteți din nou complete. Repetarea complete după rezultat returnează același rezultat. Părțile lipsă returnează 409 uploads.incomplete (details.missing). Un sha256 diferit de cel declarat la creare sau un parts[].etag diferit de o parte primită returnează 422 uploads.checksum_mismatch. O încărcare gata, dar nefolosită, există timp de 24 de ore. Adăugat în 1.62.0.

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de cale

  • upload_idstringobligatoriu

    ID-ul încărcării (upl_ urmat de 32 de caractere hexazecimale).

    length ≤ 64

Parametri de antet

  • Idempotency-Keystring

    Cheie pentru reîncercarea sigură a unei scrieri: 1–255 de caractere ASCII imprimabile; se recomandă un UUID v4 pentru fiecare operație logică. O reîncercare cu aceeași cheie în decurs de 24 de ore nu execută din nou operația: returnează răspunsul salvat (status, antete și corp) cu antetul Idempotency-Replayed: true. Aceeași cheie cu altă metodă, altă cale, alt Content-Type sau alt corp returnează 409 api.idempotency_mismatch; cât timp prima cerere încă rulează – 409 api.idempotency_in_progress cu Retry-After: 1. După un răspuns 5xx sau 429, cheia este eliberată, iar o reîncercare execută din nou operația. Cheia este valabilă în cadrul organizației și al apelantului (cheie API, utilizator sau cheie de sursă personalizată).

    length ≥ 1, length ≤ 255

Corpul cererii

application/json

Obiect: UploadComplete

  • sha256stringobligatoriu

    SHA-256 al întregului fișier.

  • partsarray of UploadPartRef

    Verificarea opțională a părților: ETag-ul fiecărei părți, așa cum îl returnează PUT …/parts/{n}.

    items ≤ 1000

Răspunsuri

200Rezultatul este gata: `ready` sau `rejected`.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

  • Idempotency-Replayed

    true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: Upload

  • idstringobligatoriu

    ID-ul încărcării (upl_ urmat de 32 de caractere hexazecimale).

  • purposeUploadPurposeobligatoriu
  • filenamestringobligatoriu

    Numele fișierului (fără dosare).

  • content_typestringobligatoriu

    Tipul de conținut declarat; gol dacă nu a fost declarat.

  • sizeinteger (int64)obligatoriu

    Dimensiunea fișierului în octeți.

  • sha256string | nullobligatoriu

    SHA-256 al fișierului, declarat la creare sau la complete; null dacă nu este încă cunoscut.

  • statusUploadStatusobligatoriu
  • part_sizeinteger (int64)obligatoriu

    Dimensiunea fiecărei părți, cu excepția ultimei (de la 5 la 100 MiB).

  • part_countintegerobligatoriu

    Numărul de părți.

    ≥ 1, ≤ 1000

  • parts_receivedintegerobligatoriu

    Numărul de părți primite.

    ≥ 0

  • partsarray of UploadPartobligatoriu

    Părțile primite, după număr (gol în răspunsul POST /v1/uploads).

  • reject_reasonstring | nullobligatoriu

    Motivul respingerii (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enumerarea se poate extinde; null dacă nu a fost respinsă.

  • reject_detailsobject | nullobligatoriu

    Detaliile respingerii (extensia, formatul declarat și cel detectat, sumele de control); null dacă nu a fost respinsă.

  • created_atstring (date-time)obligatoriu

    Momentul creării încărcării.

  • expires_atstring (date-time)obligatoriu

    Termenul pentru finalizarea încărcării și, după ce este gata, pentru folosirea ei.

  • completed_atstring (date-time) | nullobligatoriu

    Momentul încheierii verificării (ready sau rejected).

  • consumed_atstring (date-time) | nullobligatoriu

    Momentul folosirii încărcării (de o fișă, o arhivă sau un import).

202Fișierul este încă în verificare (`processing`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

  • Idempotency-Replayed

    true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: Upload

  • idstringobligatoriu

    ID-ul încărcării (upl_ urmat de 32 de caractere hexazecimale).

  • purposeUploadPurposeobligatoriu
  • filenamestringobligatoriu

    Numele fișierului (fără dosare).

  • content_typestringobligatoriu

    Tipul de conținut declarat; gol dacă nu a fost declarat.

  • sizeinteger (int64)obligatoriu

    Dimensiunea fișierului în octeți.

  • sha256string | nullobligatoriu

    SHA-256 al fișierului, declarat la creare sau la complete; null dacă nu este încă cunoscut.

  • statusUploadStatusobligatoriu
  • part_sizeinteger (int64)obligatoriu

    Dimensiunea fiecărei părți, cu excepția ultimei (de la 5 la 100 MiB).

  • part_countintegerobligatoriu

    Numărul de părți.

    ≥ 1, ≤ 1000

  • parts_receivedintegerobligatoriu

    Numărul de părți primite.

    ≥ 0

  • partsarray of UploadPartobligatoriu

    Părțile primite, după număr (gol în răspunsul POST /v1/uploads).

  • reject_reasonstring | nullobligatoriu

    Motivul respingerii (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enumerarea se poate extinde; null dacă nu a fost respinsă.

  • reject_detailsobject | nullobligatoriu

    Detaliile respingerii (extensia, formatul declarat și cel detectat, sumele de control); null dacă nu a fost respinsă.

  • created_atstring (date-time)obligatoriu

    Momentul creării încărcării.

  • expires_atstring (date-time)obligatoriu

    Termenul pentru finalizarea încărcării și, după ce este gata, pentru folosirea ei.

  • completed_atstring (date-time) | nullobligatoriu

    Momentul încheierii verificării (ready sau rejected).

  • consumed_atstring (date-time) | nullobligatoriu

    Momentul folosirii încărcării (de o fișă, o arhivă sau un import).

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

409Starea obiectului nu permite acțiunea, de exemplu o dublură, o indexare în curs sau un job deja procesat.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

410Obiectul a existat, dar nu mai este disponibil: linkul a fost folosit sau a expirat ori fișierul a fost șters la sfârșitul perioadei de păstrare.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← uploads · Referința API