Tài liệu API — Tải file lên

Hướng dẫn dùng endpoint tải file lên VCloudShare. File được lưu trữ và trả về link đã mã hoá — không lộ file gốc.

POSThttps://vcloudshare-api.vercel.app/api/v1/filesCần đăng nhập

Tải lên một file bất kỳ (tối đa 50MB) bằng multipart/form-data. Trả về metadata của file kèm link chia sẻ.

Đăng ký tài khoản

API chỉ dành cho tài khoản đã được cấp. Việc đăng ký không mở công khai — bạn cần liên hệ quản trị viên để được tạo tài khoản, sau đó đăng nhập lấy access token.

Liên hệ quản trị viên

Liên hệ quản trị viên để được cấp tài khoản trước khi sử dụng API.

Xác thực

Gửi kèm access token nhận được sau khi đăng nhập trong header Authorization theo dạng Bearer.

Authorization: Bearer <accessToken>

Trường của request

Body phải là multipart/form-data (KHÔNG phải JSON). Chỉ trường file là bắt buộc.

Trường	Kiểu	Bắt buộc	Mô tả
file	binary	Có	File nhị phân cần tải lên (tối đa 50MB).
description	string	Không	Mô tả ngắn cho file (tuỳ chọn).
isPublic	boolean	Không	true để ai có link cũng tải được; mặc định false (chỉ mình bạn).

Ví dụ

cURL

curl -X POST https://vcloudshare-api.vercel.app/api/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/photo.png" \
  -F "description=My photo" \
  -F "isPublic=true"

JavaScript (fetch)

const form = new FormData()
form.append('file', fileInput.files[0])
form.append('description', 'My photo')
form.append('isPublic', 'true')

const res = await fetch('https://vcloudshare-api.vercel.app/api/v1/files', {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: form,
})
const json = await res.json()
console.log(json.data.link)

Phản hồi

Trả về 201 kèm metadata của file. Dùng data.link để chia sẻ hoặc tải xuống.

201 Created

{
  "success": true,
  "message": "File uploaded successfully.",
  "data": {
    "id": "a3d306a4-a16a-4be3-8e4e-51aa0d79865f",
    "fileName": "photo.png",
    "mimeType": "image/png",
    "sizeBytes": 12345,
    "description": "My photo",
    "isActive": true,
    "isPublic": true,
    "link": "https://vcloudshare-api.vercel.app/api/v1/files/public/ZlN5VUUi3DJEjigiusoO6YCUez5...",
    "userId": "7e3a7f5b-6d84-467b-8b3b-d9abdc4b8c2b",
    "createdAt": "2026-07-18T14:30:00.000Z",
    "updatedAt": null
  },
  "version": "1.1.0",
  "author": "The Vi",
  "license": "MIT",
  "requestId": "ed302ae9-ce9c-438c-92c7-f829c6d7e707"
}

Mã lỗi

HTTP	Mã	Ý nghĩa
401	TOKEN_MISSING	Thiếu hoặc sai access token.
403	FORBIDDEN	Tài khoản không đủ quyền tải lên.
422	VALIDATION_FAILED	Input sai định dạng (xem data.details).
422	FILE_TOO_LARGE	File vượt quá giới hạn 50MB.