POST/v1/uploads/{upload_id}/complete

Hoàn tất lượt tải lên

complete_upload

Khi đã nhận đủ các phần, Sursa ghép tệp, so sánh SHA-256 của toàn bộ tệp với sha256 trong phần thân và chạy các bước kiểm tra giống như khi tải lên trong một yêu cầu: định dạng theo chữ ký nội dung và quét virus. Kết quả là ready, hoặc rejected kèm reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Mỗi lần bị từ chối ở bước kiểm tra định dạng hoặc quét virus được ghi vào nhật ký kiểm toán dưới dạng file.rejected.

Phản hồi 200 nghĩa là kết quả đã sẵn sàng; 202 nghĩa là tệp vẫn đang được kiểm tra (processing), và kết quả lấy từ GET /v1/uploads/{upload_id}. Nếu trạng thái quay về pending (việc khởi động lại một phiên bản chạy API đã làm gián đoạn quá trình kiểm tra), hãy gửi lại complete. Lặp lại complete sau khi có kết quả sẽ trả về cùng kết quả. Thiếu phần thì trả về 409 uploads.incomplete (details.missing). sha256 khác với giá trị đã khai báo khi tạo, hoặc parts[].etag khác với một phần đã nhận, trả về 422 uploads.checksum_mismatch. Lượt tải lên đã sẵn sàng nhưng không được dùng tồn tại trong 24 giờ. Được thêm trong 1.62.0.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số đường dẫn

upload_idstringbắt buộc
ID của lượt tải lên (upl_ theo sau là 32 ký tự hex).
length ≤ 64

Tham số header

Idempotency-Keystring
Khóa để thử lại an toàn một thao tác ghi: 1 đến 255 ký tự ASCII in được; nên dùng một UUID v4 cho mỗi thao tác logic. Lần thử lại với cùng khóa trong vòng 24 giờ không chạy lại thao tác: dịch vụ trả về phản hồi đã lưu (trạng thái, header và phần thân) kèm header Idempotency-Replayed: true. Cùng khóa nhưng khác phương thức, đường dẫn, Content-Type hoặc phần thân trả về 409 api.idempotency_mismatch; khi yêu cầu đầu tiên vẫn đang chạy, trả về 409 api.idempotency_in_progress kèm Retry-After: 1. Sau phản hồi 5xx hoặc 429, khóa được giải phóng và lần thử lại sẽ chạy lại thao tác. Khóa có phạm vi theo tổ chức và bên gọi (khóa API, người dùng hoặc khóa nguồn tùy chỉnh).
length ≥ 1, length ≤ 255

Phần thân yêu cầu

application/json

Đối tượng: UploadComplete

sha256stringbắt buộc
SHA-256 của toàn bộ tệp.
partsarray of UploadPartRef
Kiểm tra các phần (không bắt buộc): ETag của từng phần như PUT …/parts/{n} đã trả về.
items ≤ 1000

Phản hồi

200Kết quả đã sẵn sàng: `ready` hoặc `rejected`.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.
Idempotency-Replayed
true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: Upload

idstringbắt buộc
ID của lượt tải lên (upl_ theo sau là 32 ký tự hex).
purposeUploadPurposebắt buộc
filenamestringbắt buộc
Tên tệp (không kèm thư mục).
content_typestringbắt buộc
Loại nội dung được khai báo; trống nếu không khai báo.
sizeinteger (int64)bắt buộc
Kích thước tệp tính bằng byte.
sha256string | nullbắt buộc
SHA-256 của tệp, khai báo khi tạo hoặc khi complete; null nếu chưa biết.
statusUploadStatusbắt buộc
part_sizeinteger (int64)bắt buộc
Kích thước của mỗi phần, trừ phần cuối (từ 5 đến 100 MiB).
part_countintegerbắt buộc
Số phần.
≥ 1, ≤ 1000
parts_receivedintegerbắt buộc
Số phần đã nhận.
≥ 0
partsarray of UploadPartbắt buộc
Các phần đã nhận theo số thứ tự (trống trong phản hồi của POST /v1/uploads).
reject_reasonstring | nullbắt buộc
Lý do từ chối (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Tập giá trị có thể mở rộng; null nếu không bị từ chối.
reject_detailsobject | nullbắt buộc
Chi tiết về việc từ chối (phần mở rộng, định dạng được khai báo và định dạng phát hiện được, tổng kiểm); null nếu không bị từ chối.
created_atstring (date-time)bắt buộc
Thời điểm tạo lượt tải lên.
expires_atstring (date-time)bắt buộc
Hạn chót để hoàn tất lượt tải lên và, khi lượt tải lên đã sẵn sàng, để sử dụng nó.
completed_atstring (date-time) | nullbắt buộc
Thời điểm việc kiểm tra kết thúc (ready hoặc rejected).
consumed_atstring (date-time) | nullbắt buộc
Thời điểm lượt tải lên được sử dụng (bởi một thẻ, một tệp nén hoặc một lượt nhập).

202Tệp vẫn đang được kiểm tra (`processing`).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.
Idempotency-Replayed
true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: Upload

idstringbắt buộc
ID của lượt tải lên (upl_ theo sau là 32 ký tự hex).
purposeUploadPurposebắt buộc
filenamestringbắt buộc
Tên tệp (không kèm thư mục).
content_typestringbắt buộc
Loại nội dung được khai báo; trống nếu không khai báo.
sizeinteger (int64)bắt buộc
Kích thước tệp tính bằng byte.
sha256string | nullbắt buộc
SHA-256 của tệp, khai báo khi tạo hoặc khi complete; null nếu chưa biết.
statusUploadStatusbắt buộc
part_sizeinteger (int64)bắt buộc
Kích thước của mỗi phần, trừ phần cuối (từ 5 đến 100 MiB).
part_countintegerbắt buộc
Số phần.
≥ 1, ≤ 1000
parts_receivedintegerbắt buộc
Số phần đã nhận.
≥ 0
partsarray of UploadPartbắt buộc
Các phần đã nhận theo số thứ tự (trống trong phản hồi của POST /v1/uploads).
reject_reasonstring | nullbắt buộc
Lý do từ chối (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Tập giá trị có thể mở rộng; null nếu không bị từ chối.
reject_detailsobject | nullbắt buộc
Chi tiết về việc từ chối (phần mở rộng, định dạng được khai báo và định dạng phát hiện được, tổng kiểm); null nếu không bị từ chối.
created_atstring (date-time)bắt buộc
Thời điểm tạo lượt tải lên.
expires_atstring (date-time)bắt buộc
Hạn chót để hoàn tất lượt tải lên và, khi lượt tải lên đã sẵn sàng, để sử dụng nó.
completed_atstring (date-time) | nullbắt buộc
Thời điểm việc kiểm tra kết thúc (ready hoặc rejected).
consumed_atstring (date-time) | nullbắt buộc
Thời điểm lượt tải lên được sử dụng (bởi một thẻ, một tệp nén hoặc một lượt nhập).

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

404Đối tượng không tồn tại hoặc bạn không có quyền truy cập. API không xác nhận sự tồn tại của đối tượng bị hạn chế quyền truy cập.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

409Trạng thái của đối tượng không cho phép thực hiện hành động, ví dụ bản trùng lặp, đang lập chỉ mục, hoặc tác vụ đã được xử lý.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

410Đối tượng từng tồn tại nhưng không còn khả dụng: liên kết đã được dùng hoặc đã hết hạn, hoặc tệp đã được xóa khi hết thời hạn lưu giữ.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

Retry-After
Số giây cần chờ trước khi thử lại yêu cầu.
RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← uploads · Tài liệu tham chiếu 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"

Dùng thử

Khóa API

Khóa chỉ được giữ trong bộ nhớ của tab này và chỉ được gửi tới https://api.sursa.com.

Yêu cầu tác động lên dữ liệu thật của tổ chức bạn.

Idempotency-Key header

upload_id path *

Idempotency-Key

Khi để trống, mỗi yêu cầu sẽ được tạo một khóa mới.

Phần thân yêu cầu (JSON)