Upload File

EndpointCopy Anchor Link

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)Copy Anchor Link

Content-TypeCopy Anchor Link

multipart/form-data

Request BodyCopy Anchor Link

File phải có định dạng cho phép, nội dung khớp phần mở rộng và không vượt giới hạn upload của công ty (mặc định 25 MB/file, ảnh 10 MB/file, theo gói dịch vụ).

Ví dụ cURLCopy Anchor Link

curl -X POST "https://api.hubport.vn/v1/files" \
  -H "Authorization: <JWT>" \
  -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)Copy Anchor Link

Content-TypeCopy Anchor Link

application/json

Request BodyCopy Anchor Link

Ví dụ JSONCopy Anchor Link

{
    "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 ý: Data URI chỉ nhận ảnh (JPG, PNG, GIF, WEBP); extension lưu theo nội dung ảnh thực tế (vd ảnh PNG lưu png). Dung lượng sau khi giải mã không vượt giới hạn ảnh của công ty (mặc định 10 MB), và vẫn kiểm tra hạn mức dung lượng của công ty. Dữ liệu không phải ảnh trả error_data_uri_is_not_image.

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

Content-TypeCopy Anchor Link

application/json

Request BodyCopy Anchor Link

Ví dụ JSONCopy Anchor Link

{
    "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 SchemaCopy Anchor Link

HTTP 201 - Created (hoặc 200 nếu có return_success_as_status_200)Copy Anchor Link

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

Ví dụ Response (Upload file)Copy Anchor Link

{
    "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)Copy Anchor Link

Hạn mức dung lượng (Storage Quota)Copy Anchor Link

Mỗi công ty có hạn mức tổng dung lượng file theo gói dịch vụ Hubport. Trước khi lưu file (multipart hoặc Data URI), API cộng dung lượng file hiện có của công ty với dung lượng file mới: nếu vượt hạn mức, request bị từ chối với HTTP 422 và mã lỗi error_quota_limit_exceed (detail.quota là hạn mức, byte). Hãy xoá bớt file không dùng hoặc nâng cấp gói để tiếp tục upload. Tạo thư mục không bị kiểm tra hạn mức.

Error CodesCopy Anchor Link

Tất cả lỗi validate trả HTTP 422 với body {"error": ["error_..."]}. Lỗi giới hạn kèm thêm detail, ví dụ:

{
    "error": ["error_file_too_large"],
    "detail": { "max_mb": 10, "max_bytes": 10485760, "category": "image" }
}

Request lớn hơn giới hạn tối đa của hệ thống (khoảng 50 MB) bị từ chối với HTTP 413 trước khi tới API.