Tham chiếu API: Module Drive

Tài liệu này chi tiết về các điểm cuối API RESTful cho module Drive.

Base path: Tất cả các endpoint đều có tiền tố /api.

---

1. Xác thực

POST /api/auth/exchange

Đổi Shell JWT lấy Drive JWT (phạm vi dịch vụ). Phải gọi trước khi sử dụng bất kỳ endpoint nào yêu cầu xác thực.

Body:

{ "token": "<shell_jwt>" }

Phản hồi:

{
  "access_token": "<drive_jwt>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Tất cả các yêu cầu tiếp theo phải bao gồm Drive JWT:

Authorization: Bearer <drive_jwt>

---

2. API Quản lý Tệp

POST /api/files/upload

Tải lên một tệp mới.

Content-Type: multipart/form-data

Tham số:

• file: Tệp nhị phân (Tối đa 100MB).
• folderId: (Tùy chọn) ID thư mục đích.

Phản hồi: 201 Created — đối tượng siêu dữ liệu tệp.

GET /api/files

Liệt kê các tệp trong tổ chức hiện tại.

Tham số Truy vấn:

• folderId: (Tùy chọn) Lọc theo thư mục.
• q: Tìm kiếm theo tên (tối thiểu 2 ký tự).
• limit: Số kết quả mỗi trang (mặc định 50).
• offset: Độ lệch phân trang (mặc định 0).

Phản hồi:

{ "data": [...], "total": 120 }

GET /api/files/:id/download

Truyền trực tiếp nội dung tệp nhị phân đến client.

Phản hồi: Luồng tệp nhị phân với header Content-Type đúng.

DELETE /api/files/:id

Xóa vĩnh viễn một tệp khỏi cả cơ sở dữ liệu và kho lưu trữ đối tượng.

Phản hồi: 204 No Content

---

3. API Thư mục

GET /api/folders

Liệt kê các thư mục. Truyền parentId để điều hướng vào thư mục con; bỏ qua để lấy thư mục gốc.

Tham số Truy vấn:

• parentId: (Tùy chọn) Lọc theo thư mục cha.

POST /api/folders

Tạo một thư mục mới.

Thân yêu cầu (Body):

{
  "name": "Tài liệu Dự án X",
  "parentId": "uuid"
}

Phản hồi: 201 Created — đối tượng thư mục.

PATCH /api/folders/:id

Đổi tên một thư mục. Người dùng thường chỉ có thể đổi tên thư mục do họ tạo.

Thân yêu cầu (Body):

{ "name": "Tên thư mục mới" }

Phản hồi: Đối tượng thư mục đã cập nhật.

DELETE /api/folders/:id

Xóa một thư mục và tất cả nội dung bên trong (đệ quy: thư mục con + tệp + liên kết chia sẻ).

Phản hồi: 204 No Content

---

4. API Chia sẻ

POST /api/files/:id/share

Tạo một liên kết chia sẻ công khai cho một tệp.

Thân yêu cầu (Body):

{ "ttlDays": 7 }

ttlDays phải là chính xác 1, 3, hoặc 7.

Phản hồi (201 Created):

{
  "data": {
    "url": "https://drive.venizia.ai/s/<token>",
    "expiresAt": "2026-04-01T00:00:00.000Z"
  }
}

GET /api/files/:id/share

Liệt kê tất cả các liên kết chia sẻ đang hoạt động (chưa bị thu hồi) cho một tệp.

Phản hồi:

{
  "data": [
    { "id": "uuid", "token": "...", "expiresAt": "...", "createdBy": "uuid" }
  ]
}

DELETE /api/files/:id/share/:linkId

Thu hồi một liên kết chia sẻ đang hoạt động (xóa mềm qua timestamp revokedAt).

Phản hồi: 204 No Content

---

5. Truy cập Công khai

GET /api/public/files/:token

Tải xuống tệp qua share token. Không yêu cầu xác thực.

Token được xác thực với expiresAt và revokedAt trước khi phục vụ luồng tệp.

Phản hồi: Luồng tệp nhị phân.

---

6. Quản lý Người dùng (Chỉ Admin)

Tất cả các endpoint trong phần này yêu cầu vai trò admin.

GET /api/users

Liệt kê tất cả người dùng. Hỗ trợ tham số page và limit.

POST /api/users

Tạo người dùng cục bộ.

Body: { "email": string, "name"?: string, "roleId"?: string }

Phản hồi: 201 Created

GET /api/users/:id

Lấy thông tin người dùng kèm vai trò đã gán.

PUT /api/users/:id

Cập nhật trạng thái người dùng.

Body: { "status": "active" | "suspended" }

POST /api/users/:id/roles

Gán vai trò cho người dùng.

Body: { "roleId": string }

DELETE /api/users/:id/roles/:roleId

Xóa vai trò khỏi người dùng.

GET /api/users/roles

Liệt kê tất cả các vai trò có sẵn.

---

7. Mã Lỗi Tiêu chuẩn

Mã Trạng thái	Mô tả
413 Payload Too Large	Tệp vượt quá giới hạn 100MB.
403 Forbidden	Truy cập bị từ chối cho tổ chức này hoặc chủ sở hữu tài nguyên.
404 Not Found	Tệp hoặc thư mục không tồn tại.
409 Conflict	Trùng tên thư mục trong cùng một thư mục cha.
500 Server Error	Lỗi Backend hoặc lưu trữ.