POST/v1/uploads/{upload_id}/complete

Selesaikan unggahan

complete_upload

Setelah semua bagian diterima, Sursa merakit file, membandingkan SHA-256 seluruh file dengan sha256 di isi permintaan, dan menjalankan pemeriksaan yang sama seperti untuk unggahan dalam satu permintaan: format menurut tanda tangan konten dan pemindaian antivirus. Hasilnya ready, atau rejected dengan reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Setiap penolakan oleh pemeriksaan format atau antivirus dicatat di log audit sebagai file.rejected.

Respons 200 berarti hasilnya sudah siap; 202 berarti file masih diperiksa (processing), dan hasilnya didapat dari GET /v1/uploads/{upload_id}. Jika status kembali ke pending (restart instans API menginterupsi pemeriksaan), kirim complete lagi. Mengulang complete setelah ada hasil mengembalikan hasil yang sama. Bagian yang belum ada mengembalikan 409 uploads.incomplete (details.missing). sha256 yang berbeda dari yang dideklarasikan saat pembuatan, atau parts[].etag yang berbeda dari bagian yang diterima, mengembalikan 422 uploads.checksum_mismatch. Unggahan siap yang tidak dipakai berlaku selama 24 jam. Ditambahkan di 1.62.0.

Autentikasi

Kirim kunci API di header Authorization: Authorization: Bearer <kunci>.

Parameter path

upload_idstringwajib
ID unggahan (upl_ diikuti 32 karakter heksadesimal).
length ≤ 64

Parameter header

Idempotency-Keystring
Kunci untuk percobaan ulang penulisan yang aman: 1 hingga 255 karakter ASCII yang dapat dicetak; disarankan satu UUID v4 per operasi logis. Percobaan ulang dengan kunci yang sama dalam 24 jam tidak menjalankan operasi lagi: yang dikembalikan adalah respons tersimpan (status, header, dan isi) dengan header Idempotency-Replayed: true. Kunci yang sama dengan metode, path, Content-Type, atau isi yang berbeda mengembalikan 409 api.idempotency_mismatch; selama permintaan pertama masih berjalan, 409 api.idempotency_in_progress dengan Retry-After: 1. Setelah respons 5xx atau 429, kunci dilepaskan, dan percobaan ulang menjalankan operasi lagi. Kunci berlaku dalam lingkup organisasi dan pemanggil (kunci API, pengguna, atau kunci sumber kustom).
length ≥ 1, length ≤ 255

Isi permintaan

application/json

Objek: UploadComplete

sha256stringwajib
SHA-256 seluruh file.
partsarray of UploadPartRef
Pemeriksaan bagian yang opsional: ETag setiap bagian seperti yang dikembalikan oleh PUT …/parts/{n}.
items ≤ 1000

Respons

200Hasilnya sudah siap: `ready` atau `rejected`.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.
Idempotency-Replayed
true berarti respons ini dikirim ulang dari respons tersimpan untuk Idempotency-Key ini: operasi tidak dijalankan lagi.

application/json

Objek: Upload

idstringwajib
ID unggahan (upl_ diikuti 32 karakter heksadesimal).
purposeUploadPurposewajib
filenamestringwajib
Nama file (tanpa folder).
content_typestringwajib
Jenis konten yang dinyatakan; kosong jika tidak dinyatakan.
sizeinteger (int64)wajib
Ukuran file dalam byte.
sha256string | nullwajib
SHA-256 file, yang dinyatakan saat pembuatan atau saat complete; null jika belum diketahui.
statusUploadStatuswajib
part_sizeinteger (int64)wajib
Ukuran setiap bagian kecuali yang terakhir (dari 5 hingga 100 MiB).
part_countintegerwajib
Jumlah bagian.
≥ 1, ≤ 1000
parts_receivedintegerwajib
Jumlah bagian yang sudah diterima.
≥ 0
partsarray of UploadPartwajib
Bagian yang sudah diterima menurut nomor (kosong dalam respons POST /v1/uploads).
reject_reasonstring | nullwajib
Alasan penolakan (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enum dapat bertambah; null jika tidak ditolak.
reject_detailsobject | nullwajib
Detail penolakan (ekstensi, format yang dinyatakan dan yang terdeteksi, checksum); null jika tidak ditolak.
created_atstring (date-time)wajib
Kapan unggahan dibuat.
expires_atstring (date-time)wajib
Tenggat untuk menyelesaikan unggahan dan, setelah siap, untuk memakainya.
completed_atstring (date-time) | nullwajib
Kapan pemeriksaan selesai (ready atau rejected).
consumed_atstring (date-time) | nullwajib
Kapan unggahan dipakai (oleh kartu, arsip, atau impor).

202File masih diperiksa (`processing`).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.
Idempotency-Replayed
true berarti respons ini dikirim ulang dari respons tersimpan untuk Idempotency-Key ini: operasi tidak dijalankan lagi.

application/json

Objek: Upload

idstringwajib
ID unggahan (upl_ diikuti 32 karakter heksadesimal).
purposeUploadPurposewajib
filenamestringwajib
Nama file (tanpa folder).
content_typestringwajib
Jenis konten yang dinyatakan; kosong jika tidak dinyatakan.
sizeinteger (int64)wajib
Ukuran file dalam byte.
sha256string | nullwajib
SHA-256 file, yang dinyatakan saat pembuatan atau saat complete; null jika belum diketahui.
statusUploadStatuswajib
part_sizeinteger (int64)wajib
Ukuran setiap bagian kecuali yang terakhir (dari 5 hingga 100 MiB).
part_countintegerwajib
Jumlah bagian.
≥ 1, ≤ 1000
parts_receivedintegerwajib
Jumlah bagian yang sudah diterima.
≥ 0
partsarray of UploadPartwajib
Bagian yang sudah diterima menurut nomor (kosong dalam respons POST /v1/uploads).
reject_reasonstring | nullwajib
Alasan penolakan (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Enum dapat bertambah; null jika tidak ditolak.
reject_detailsobject | nullwajib
Detail penolakan (ekstensi, format yang dinyatakan dan yang terdeteksi, checksum); null jika tidak ditolak.
created_atstring (date-time)wajib
Kapan unggahan dibuat.
expires_atstring (date-time)wajib
Tenggat untuk menyelesaikan unggahan dan, setelah siap, untuk memakainya.
completed_atstring (date-time) | nullwajib
Kapan pemeriksaan selesai (ready atau rejected).
consumed_atstring (date-time) | nullwajib
Kapan unggahan dipakai (oleh kartu, arsip, atau impor).

401Kredensial tidak dikirim (baik cookie sesi maupun kunci API), atau kunci tidak ditemukan.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

403Tindakan tidak diizinkan: peran tidak memadai, tidak ada akses ke koleksi atau kartu, permintaan berjalan dalam mode “View as”, atau organisasi ditangguhkan atau dihapus (`detail` adalah objek dengan `code: org_suspended | org_deleted`).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

404Objek tidak ada atau tidak tersedia bagi Anda. API tidak mengonfirmasi keberadaan objek yang dibatasi.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

409Status objek tidak memungkinkan tindakan ini, misalnya duplikat, pengindeksan yang sedang berlangsung, atau job yang sudah diproses.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

410Objek pernah ada tetapi tidak lagi tersedia: tautan sudah dipakai atau kedaluwarsa, atau file dihapus pada akhir masa retensinya.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

422Error validasi: isi atau parameter tidak sesuai dengan skema (`detail` berisi daftar error validasi), atau nilai parameter berada di luar rentang (`detail` berisi pesan).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

429Terlalu banyak permintaan (`api.rate_limited`), kuota organisasi untuk menit, hari, atau bulan sudah habis (`api.quota_exceeded`; `error.details` berisi `quota`, `limit`, dan `reset_at`), batas organisasi tercapai, atau layanan jawaban sedang sibuk (`answers.engine_busy`). Tunggu selama waktu di header `Retry-After`.

Header respons

Retry-After
Jumlah detik yang perlu ditunggu sebelum Anda mencoba ulang permintaan.
RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

Kode error

Kode yang dapat dikembalikan endpoint ini di error.code, selain kode umum yang berlaku untuk setiap permintaan.

Percobaan ulang yang aman

Kirim header Idempotency-Key (misalnya UUID) bersama setiap POST dan PATCH. Percobaan ulang dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan permintaan lagi.

Batas laju

Respons berisi header RateLimit dan RateLimit-Policy serta header lama X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons 429 berisi Retry-After dalam detik: tunggu, lalu coba lagi.

← uploads · Referensi 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"

Coba

Kunci API

Kunci hanya disimpan di memori tab ini dan hanya dikirim ke https://api.sursa.com.

Permintaan bekerja pada data asli organisasi Anda.

Idempotency-Key header

upload_id path *

Idempotency-Key

Jika kosong, kunci baru dibuat untuk setiap permintaan.

Isi permintaan (JSON)