POST/v1/uploads

Çok parçalı yükleme başlatma

create_upload

Büyük bir dosya için bir yükleme oturumu açar (kurulumun çok parçalı yükleme limitine kadar, varsayılan 5 GB): ad, içerik türü, boyut ve yüklemeyi neyin kullanacağını belirten purpose: card_file (POST /v1/cards), archive (POST /v1/cards/archive) ya da import_attachment (özel kaynak belgesinin eki). Yanıtta id (upl_ ve ardından 32 onaltılık karakter), part_size parça boyutu ve part_count parça sayısı bulunur. Sonuncusu dışındaki her parça tam olarak part_size bayttır (5–100 MiB) ve son parça kalan kısımdır. Tamamlanmamış bir yükleme 24 saat yaşar (expires_at).

Amacın biçimleri dışındaki bir dosya adı uzantısı 415 uploads.unsupported_format döndürür (içe aktarma eki her uzantıyı kabul eder). Kurulumun limitinden ya da kuruluşun planına göre toplam depolama alanından büyük bir dosya 413 uploads.too_large döndürür. Kuruluşun tamamlanmamış yüklemeleri de sayıldığında yeterli depolama alanı kalmamışsa 402 limits.storage döner.

Parçalar Sursa üzerinden gider (PUT /v1/uploads/{upload_id}/parts/{n}) ve dosya depolamasında kuruluşun anahtarıyla şifrelenir; depolamaya doğrudan bağlantı yoktur. Yüklemeyi yalnızca onu oluşturan API anahtarı ya da kullanıcı görebilir ve kullanabilir. 1.62.0 sürümünde eklendi.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

Idempotency-Keystring
Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).
length ≥ 1, length ≤ 255

İstek gövdesi

application/json

Nesne: UploadCreate

filenamestringzorunlu
Uzantısıyla birlikte dosya adı; biçimi uzantı belirler.
length ≥ 1, length ≤ 255
content_typestring
Bildirilen içerik türü (MIME); dosya imzasıyla karşılaştırılır.
length ≤ 255
sizeinteger (int64)zorunlu
Bayt cinsinden dosya boyutu.
≥ 1
purposeUploadPurposezorunlu
sha256string
Önceden biliniyorsa dosyanın SHA-256 değeri; complete sağlama toplamını bu değerle karşılaştırır.

Yanıtlar

201Yükleme oturumu oluşturuldu.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.
Idempotency-Replayed
true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: Upload

idstringzorunlu
Yüklemenin kimliği (upl_ ve ardından 32 onaltılık karakter).
purposeUploadPurposezorunlu
filenamestringzorunlu
Dosya adı (klasörler olmadan).
content_typestringzorunlu
Bildirilen içerik türü; bildirilmediyse boş.
sizeinteger (int64)zorunlu
Bayt cinsinden dosya boyutu.
sha256string | nullzorunlu
Oluşturmada ya da complete sırasında bildirilen, dosyanın SHA-256 değeri; henüz bilinmiyorsa null.
statusUploadStatuszorunlu
part_sizeinteger (int64)zorunlu
Sonuncusu dışındaki her parçanın boyutu (5 ile 100 MiB arası).
part_countintegerzorunlu
Parça sayısı.
≥ 1, ≤ 1000
parts_receivedintegerzorunlu
Alınan parça sayısı.
≥ 0
partsarray of UploadPartzorunlu
Numaraya göre alınan parçalar (POST /v1/uploads yanıtında boş).
reject_reasonstring | nullzorunlu
Ret nedeni (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Değer listesi genişleyebilir; reddedilmediyse null.
reject_detailsobject | nullzorunlu
Ret ayrıntıları (uzantı, bildirilen ve algılanan biçim, sağlama toplamları); reddedilmediyse null.
created_atstring (date-time)zorunlu
Yüklemenin oluşturulma zamanı.
expires_atstring (date-time)zorunlu
Yüklemeyi tamamlamak ve hazır olduğunda kullanmak için son tarih.
completed_atstring (date-time) | nullzorunlu
Denetimin bittiği zaman (ready ya da rejected).
consumed_atstring (date-time) | nullzorunlu
Yüklemenin kullanıldığı zaman (bir kart, bir arşiv ya da bir içe aktarma tarafından).

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

402Kuruluş bir plan limitine ulaştı (kartlar, depolama ya da kullanıcılar). `error.details` alanında `kind`, `limit` ve `used` bulunur.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

413İstek gövdesi izin verilen en büyük boyutu aşıyor.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

415Dosya biçimi desteklenmiyor.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

Retry-After
İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.
RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← uploads · API başvurusu

curl -X POST 'https://api.sursa.com/v1/uploads' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"document.pdf","size":1,"purpose":"card_file"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Dene

API anahtarı

Anahtar bu sekmenin belleğinde kalır ve yalnızca https://api.sursa.com adresine gönderilir.

İstekler kuruluşunuzun gerçek verileri üzerinde çalışır.

Idempotency-Key header

Idempotency-Key

Bu alan boş bırakılırsa her istek için yeni bir anahtar oluşturulur.

İstek gövdesi (JSON)