Upload File

Endpoint

POST /v1/files

API này hỗ trợ 2 trường hợp:

Upload file: Gửi file qua multipart/form-data hoặc data_uri (base64).
Tạo thư mục: Gửi JSON với is_directory = true (chỉ áp dụng cho object_type = 10 hoặc 40).

Upload File (multipart/form-data)

Content-Type

multipart/form-data

Request Body

Trường	Kiểu	Bắt buộc	Mô tả
`file`	file	Có	File cần upload (gửi qua form field `file`)
`company_id`	int	Có	ID công ty
`creator_id`	int	Có	ID người upload
`object_type`	int	Có	Loại đối tượng. Xem Object Schema
`object_id`	int	Không	ID đối tượng liên kết (mặc định: 0)
`status`	int	Không	Trạng thái (mặc định: 1)
`is_directory`	bool	Không	Luôn = `false` hoặc không gửi khi upload file
`directory_id`	int	Không	ID thư mục cha (0 = root). Chỉ dùng với `object_type` hỗ trợ thư mục (10, 40)
`description`	string	Không	Mô tả file
`origin`	string	Có	Nguồn gốc file. Xem Object Schema
`return_success_as_status_200`	any	Không	Nếu có trường này, response trả về HTTP 200 thay vì 201

Ví dụ cURL

curl -X POST "https://api.example.com/v1/files" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/image.jpg" \
  -F "company_id=1" \
  -F "creator_id=10" \
  -F "object_type=10" \
  -F "origin=company" \
  -F "status=1" \
  -F "directory_id=0"

Upload File (Data URI / Base64)

Content-Type

application/json

Request Body

Trường	Kiểu	Bắt buộc	Mô tả
`data_uri`	string	Có	Chuỗi Data URI (base64) của ảnh, ví dụ: `data:image/jpeg;base64,/9j/4AAQ...`
`data_uri_title`	string	Có	Tên file (dùng làm `title`)
`company_id`	int	Có	ID công ty
`creator_id`	int	Có	ID người upload
`object_type`	int	Có	Loại đối tượng
`object_id`	int	Không	ID đối tượng liên kết (mặc định: 0)
`status`	int	Không	Trạng thái (mặc định: 1)
`is_directory`	bool	Không	`false` hoặc không gửi
`directory_id`	int	Không	ID thư mục cha
`description`	string	Không	Mô tả file
`origin`	string	Có	Nguồn gốc file

Ví dụ JSON

{
    "data_uri": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "data_uri_title": "webcam-capture.jpg",
    "company_id": 1,
    "creator_id": 10,
    "object_type": 30,
    "origin": "checkin",
    "status": 1
}

Lưu ý: Upload qua Data URI luôn lưu với extension jpg.

Tạo thư mục (Create Directory)

Content-Type

application/json

Request Body

Trường	Kiểu	Bắt buộc	Mô tả
`title`	string	Có	Tên thư mục
`company_id`	int	Có	ID công ty
`creator_id`	int	Có	ID người tạo
`object_type`	int	Có	Chỉ cho phép `10` (File) hoặc `40` (CMS)
`object_id`	int	Không	ID đối tượng liên kết
`status`	int	Không	Trạng thái
`is_directory`	bool	Có	Phải = `true`
`directory_id`	int	Không	ID thư mục cha (0 = root)
`description`	string	Không	Mô tả thư mục
`origin`	string	Có	Nguồn gốc

Ví dụ JSON

{
    "title": "Hình ảnh sản phẩm 2026",
    "company_id": 1,
    "creator_id": 10,
    "object_type": 10,
    "is_directory": true,
    "directory_id": 0,
    "origin": "company",
    "status": 1
}

Response Schema

HTTP 201 - Created (hoặc 200 nếu có `return_success_as_status_200`)

Trả về File Object vừa tạo.

Ví dụ Response (Upload file)

{
    "id": 1234,
    "company_id": 1,
    "creator_id": 10,
    "directory_id": 0,
    "object_type": 10,
    "object_id": 0,
    "md5_hash": "d41d8cd98f00b204e9800998ecf8427e",
    "file_path": "1/202603/1234-1234567890-1741234567.jpg",
    "width": 1920,
    "height": 1080,
    "randomcode": "1234567890",
    "title": "image.jpg",
    "description": "",
    "extension": "jpg",
    "size_in_byte": 204800,
    "origin": "company",
    "customer_id": 0,
    "status": 1,
    "is_directory": 0,
    "ip_address": "192.168.1.1",
    "date_created": 1741234567,
    "date_modified": 1741234567,
    "url": "https://file.example.com/1/202603/1234-1234567890-1741234567.jpg"
}

Quyền hạn (Permissions)

Điều kiện	Mô tả
`file.upload`	Bắt buộc khi `object_type = 10` (File công ty)

Error Codes

Mã lỗi	Mô tả
`error_company_id_required`	ID công ty không được để trống
`error_company_id_notfound`	ID công ty không tìm thấy
`error_user1_id_required`	ID người tạo không được để trống
`error_user_id_notfound`	ID người tạo không tìm thấy
`error_not_permission_upload`	Không có quyền upload (`file.upload`)
`error_parent_directory_not_found`	Thư mục cha không tồn tại hoặc không hợp lệ
`error_parent_directory_forbidden`	Không cho phép tạo thư mục con trong object_type này
`error_max_file_in_one_directory_exceed`	Vượt quá số file tối đa cho phép trong một thư mục (10.000)
`error_max_directory_in_one_directory_exceed`	Vượt quá số thư mục con tối đa cho phép (10.000)
`error_origin_is_required`	`origin` không được để trống
`error_origin_is_invalid`	`origin` không hợp lệ
`error_file_required`	Không có file nào được gửi lên
`error_file_type_invalid`	Định dạng file không được hỗ trợ
`error_file_size_invalid`	File vượt quá 25 MB
`error_quota_limit_exceed`	Vượt quá dung lượng quota được cấp
`error_directory_name_required`	Tên thư mục không được để trống
`error_directory_name_existed`	Tên thư mục đã tồn tại trong cùng thư mục cha
`error_object_type_invalid`	Object type không hợp lệ (khi tạo thư mục)
`error_system_file_can_not_copy`	Lỗi hệ thống khi sao chép file
`error_file_record_can_not_update`	Lỗi hệ thống khi cập nhật record
`error_system_directory_can_not_created`	Không thể tạo thư mục hệ thống
`error_system_directory_can_not_writable`	Thư mục hệ thống không có quyền ghi

Upload File

On this page