POST/v1/uploads

Почетак отпремања у деловима

create_upload

Отвара сесију отпремања за велики фајл (до ограничења инсталације за отпремање у деловима, подразумевано 5 GB): назив, тип садржаја, величина и намена purpose, која говори шта ће користити отпремање: card_file (POST /v1/cards), archive (POST /v1/cards/archive) или import_attachment (прилог документа сопственог извора). Одговор садржи id (upl_ и 32 хексадецимална знака), величину дела part_size и број делова part_count. Сваки део осим последњег има тачно part_size бајтова (од 5 до 100 MiB), а последњи део је остатак. Незавршено отпремање траје 24 сата (expires_at).

Екстензија назива фајла ван формата за дату намену враћа 415 uploads.unsupported_format (прилог увоза прихвата било коју екстензију). Фајл већи од ограничења инсталације или од укупног складишта организације по њеном плану враћа 413 uploads.too_large. Ако нема довољно преосталог складишта, рачунајући незавршена отпремања организације, враћа се 402 limits.storage.

Делови пролазе кроз платформу Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) и шифрују се кључем организације у складишту фајлова; директних линкова ка складишту нема. Отпремање могу да виде и користе само API кључ или корисник који га је креирао. Додато у верзији 1.62.0.

Аутентификација

Пошаљите API кључ у заглављу Authorization: Authorization: Bearer <кључ>.

Параметри заглавља

Idempotency-Keystring
Кључ за безбедан поновни покушај уписа: од 1 до 255 штампаних ASCII знакова; препоручује се UUID v4 за сваку логичку операцију. Поновни покушај са истим кључем у року од 24 сата не извршава операцију поново: враћа сачувани одговор (статус, заглавља и тело) са заглављем Idempotency-Replayed: true. Исти кључ са другим методом, путањом, Content-Type или телом враћа 409 api.idempotency_mismatch; док се први захтев још извршава – 409 api.idempotency_in_progress са Retry-After: 1. После одговора 5xx или 429 кључ се ослобађа и поновни покушај поново извршава операцију. Кључ важи у оквиру организације и позиваоца (API кључ, корисник или кључ сопственог извора).
length ≥ 1, length ≤ 255

Тело захтева

application/json

Објекат: UploadCreate

filenamestringобавезно
Име фајла са екстензијом; екстензија одређује формат.
length ≥ 1, length ≤ 255
content_typestring
Наведени тип садржаја (MIME); пореди се са потписом фајла.
length ≤ 255
sizeinteger (int64)обавезно
Величина фајла у бајтовима.
≥ 1
purposeUploadPurposeобавезно
sha256string
SHA-256 фајла, ако је унапред познат; complete пореди контролни збир фајла са њим.

Одговори

201Сесија отпремања је креирана.

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.
Idempotency-Replayed
true значи да је одговор поново послат из одговора сачуваног за овај Idempotency-Key: операција није поново извршена.

application/json

Објекат: Upload

idstringобавезно
ID отпремања (upl_ и 32 хексадецимална знака).
purposeUploadPurposeобавезно
filenamestringобавезно
Име фајла (без фолдера).
content_typestringобавезно
Наведени тип садржаја; празно ако није наведен.
sizeinteger (int64)обавезно
Величина фајла у бајтовима.
sha256string | nullобавезно
SHA-256 фајла, наведен при креирању или при complete; null ако још није познат.
statusUploadStatusобавезно
part_sizeinteger (int64)обавезно
Величина сваког дела осим последњег (од 5 до 100 MiB).
part_countintegerобавезно
Број делова.
≥ 1, ≤ 1000
parts_receivedintegerобавезно
Број примљених делова.
≥ 0
partsarray of UploadPartобавезно
Примљени делови по броју (празно у одговору на POST /v1/uploads).
reject_reasonstring | nullобавезно
Разлог одбијања (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Набрајање може да се прошири; null ако отпремање није одбијено.
reject_detailsobject | nullобавезно
Детаљи одбијања (екстензија, наведени и откривени формат, контролни збирови); null ако отпремање није одбијено.
created_atstring (date-time)обавезно
Када је отпремање креирано.
expires_atstring (date-time)обавезно
Рок за довршавање отпремања и, када је спремно, за његово коришћење.
completed_atstring (date-time) | nullобавезно
Када је провера завршена (ready или rejected).
consumed_atstring (date-time) | nullобавезно
Када је отпремање искоришћено (за картицу, архиву или увоз).

401Акредитиви нису послати (ни колачић сесије ни API кључ) или кључ није пронађен.

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

402Организација је достигла ограничење плана (картице, складиште или корисници). `error.details` садржи `kind`, `limit` и `used`.

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

403Радња није дозвољена: улога није довољна, нема приступа колекцији или картици, захтев се извршава у режиму „View as“ или је организација суспендована или обрисана (`detail` је објекат са `code: org_suspended | org_deleted`).

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

413Тело захтева прелази дозвољену величину.

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

415Формат фајла није подржан.

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

422Грешка валидације: тело или параметри не одговарају шеми (`detail` је листа грешака валидације) или је вредност параметра ван дозвољеног распона (`detail` је порука).

Заглавља одговора

RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

429Превише захтева (`api.rate_limited`), квота организације за минут, дан или месец је потрошена (`api.quota_exceeded`; `error.details` садржи `quota`, `limit` и `reset_at`), достигнуто је ограничење организације или је сервис за одговоре заузет (`answers.engine_busy`). Сачекајте време наведено у заглављу `Retry-After`.

Заглавља одговора

Retry-After
Број секунди које треба сачекати пре поновног покушаја захтева.
RateLimit-Policy
Ограничења која важе, у формату IETF нацрта draft-ietf-httpapi-ratelimit-headers: ставке раздвојене зарезима "<name>";q=<quota>;w=<window in seconds>. key је учесталост захтева API кључа (квота је налет, прозор је време за потпуно обнављање; за сесију то је user, без акредитива – ip); minute, day и month су квоте организације за календарски минут, дан и месец по UTC.
RateLimit
Колико је преостало од сваког ограничења из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ограничење најстроже ставке у RateLimit-Policy (оне са најмање преосталих захтева).
X-RateLimit-Remaining
Број преосталих захтева по најстрожем ограничењу.
X-RateLimit-Reset
Број секунди до ресетовања најстрожег ограничења.

application/json

Објекат: Error

Кодови грешака

Кодови које ова операција може да врати у error.code, поред општих кодова сваког захтева.

Безбедни поновни покушаји

Уз сваки POST и PATCH захтев пошаљите заглавље Idempotency-Key (на пример UUID). Поновни покушај са истим кључем у року од 24 сата враћа сачувани одговор уместо да поново изврши захтев.

Ограничења учесталости

Одговори садрже заглавља RateLimit и RateLimit-Policy, као и старија X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Одговор 429 садржи заглавље Retry-After у секундама: сачекајте и поновите захтев.

← uploads · API референца

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"

Испробајте

API кључ

Кључ остаје у меморији овог језичка прегледача и шаље се само на https://api.sursa.com.

Захтеви раде са стварним подацима ваше организације.

Idempotency-Key header

Idempotency-Key

Ако је поље празно, за сваки захтев се генерише нови кључ.

Тело захтева (JSON)