POST/v1/uploads/{upload_id}/complete

Завршетак отпремања

complete_upload

Када су сви делови примљени, Sursa саставља фајл, пореди SHA-256 целог фајла са sha256 у телу и извршава исте провере као за отпремање једним захтевом: формат по потпису садржаја и антивирусну проверу. Резултат је ready или rejected са reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Свако одбијање при провери формата или антивирусној провери уписује се у дневник ревизије као file.rejected.

Одговор 200 значи да је резултат спреман; 202 значи да се фајл још проверава (processing), а резултат се добија преко GET /v1/uploads/{upload_id}. Ако се статус врати на pending (поновно покретање инстанце API интерфејса прекинуло је проверу), пошаљите complete поново. Понављање complete после резултата враћа исти резултат. Делови који недостају враћају 409 uploads.incomplete (details.missing). sha256 који се разликује од декларисаног при креирању или parts[].etag који се разликује од примљеног дела враћа 422 uploads.checksum_mismatch. Спремно отпремање које се не користи траје 24 сата. Додато у верзији 1.62.0.

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

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

Параметри путање

upload_idstringобавезно
ID отпремања (upl_ и 32 хексадецимална знака).
length ≤ 64

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

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

Објекат: UploadComplete

sha256stringобавезно
SHA-256 целог фајла.
partsarray of UploadPartRef
Необавезна провера делова: ETag сваког дела онако како га враћа PUT …/parts/{n}.
items ≤ 1000

Одговори

200Резултат је спреман: `ready` или `rejected`.

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

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обавезно
Када је отпремање искоришћено (за картицу, архиву или увоз).

202Фајл се још проверава (`processing`).

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

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

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

404Објекат не постоји или вам није доступан. 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

409Стање објекта не дозвољава радњу, на пример дупликат, индексирање у току или посао који је већ обрађен.

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

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

410Објекат је постојао, али више није доступан: линк је искоришћен или је истекао, или је фајл обрисан по истеку рока чувања.

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

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/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Испробајте

API кључ

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

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

Idempotency-Key header

upload_id path *

Idempotency-Key

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

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