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, освен общите кодове на всяка заявка.

Безопасни повторни опити

Изпращайте заглавката Idempotency-Key (например UUID) с всяка заявка POST и PATCH. Повторен опит със същия ключ в рамките на 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)