# HƯỚNG DẪN TÍCH HỢP & SỬ DỤNG KOOFR VPS GATEWAY API

Tài liệu hướng dẫn kết nối và tương tác với dịch vụ **Koofr VPS Storage Gateway (1TB Lifetime)** thông qua REST API & WebSocket.

---

## 1. Thông Tin Kết Nối (Base Configuration)

* **Gateway Base URL:** `https://cloud.nthquan.qzz.io`
* **Mã PIN Đăng nhập Web UI:** `112233`
* **Default API Key:** `koofr_gateway_secret_api_key_2026`
* **Vị trí Mount trên VPS:** `/mnt/koofr`
* **Hạn mức Tốc độ (Rate Limit):** 5 Transactions/giây (5 TPS Safe Mode)

---

## 2. Xác Thực API (Authentication)

Tất cả các API yêu cầu xác thực bằng một trong các phương thức sau:

1. **HTTP Header (Khuyên dùng):**
   ```http
   X-API-Key: koofr_gateway_secret_api_key_2026
   ```
2. **Query Parameter:**
   ```http
   https://cloud.nthquan.qzz.io/api/files?key=koofr_gateway_secret_api_key_2026
   ```
3. **Cookie Session:** Đăng nhập qua `POST /api/auth/login` với `password=112233`.

---

## 3. Chi Tiết Các Endpoints & Code Mẫu

### 3.1. Lấy Số Liệu Giám Sát Hệ Thống (System Telemetry)
* **Endpoint:** `GET /api/status`
* **Mô tả:** Trả về dung lượng Koofr 1TB thực tế, SSD Cache 5GB, RAM, CPU VPS và trạng thái dịch vụ Rclone.

**cURL:**
```bash
curl -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  https://cloud.nthquan.qzz.io/api/status
```

**Python:**
```python
import requests

res = requests.get(
    "https://cloud.nthquan.qzz.io/api/status",
    headers={"X-API-Key": "koofr_gateway_secret_api_key_2026"}
)
data = res.json()
print("Koofr Used:", data["koofr"]["used_gb"], "GB /", data["koofr"]["total_gb"], "GB")
print("VPS Cache:", data["cache"]["used_mb"], "MB / 5000 MB")
```

---

### 3.2. Duyệt Danh Sách File & Thư Mục (List Directory)
* **Endpoint:** `GET /api/files`
* **Query Params:**
  * `path` (chuỗi, tùy chọn): Đường dẫn thư mục con (ví dụ `ebooks` hoặc `archive/photos`). Nếu để trống sẽ duyệt thư mục gốc (`root`).

**cURL:**
```bash
curl -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  "https://cloud.nthquan.qzz.io/api/files?path=ebooks"
```

**Python:**
```python
import requests

res = requests.get(
    "https://cloud.nthquan.qzz.io/api/files",
    headers={"X-API-Key": "koofr_gateway_secret_api_key_2026"},
    params={"path": "ebooks"}
)
for item in res.json()["items"]:
    print(f"[{'DIR' if item['is_dir'] else 'FILE'}] {item['name']} ({item['size_human']})")
```

---

### 3.3. Upload File Tốc Độ Cao (Stream Multipart Upload)
* **Endpoint:** `POST /api/files/upload`
* **Body (Multipart Form):**
  * `path`: Thư mục đích trên Koofr (ví dụ `ebooks/2026`).
  * `files`: 1 hoặc nhiều file đính kèm.

**cURL:**
```bash
curl -X POST -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  -F "path=ebooks" \
  -F "files=@document.pdf" \
  https://cloud.nthquan.qzz.io/api/files/upload
```

**Python:**
```python
import requests

url = "https://cloud.nthquan.qzz.io/api/files/upload"
headers = {"X-API-Key": "koofr_gateway_secret_api_key_2026"}

with open("my_book.epub", "rb") as f:
    files = {"files": ("my_book.epub", f, "application/epub+zip")}
    data = {"path": "ebooks"}
    res = requests.post(url, headers=headers, files=files, data=data)
    print("Upload response:", res.json())
```

---

### 3.4. Download File Tốc Độ Cao (Streaming Download & Resume Support)
* **Endpoint:** `GET /api/files/download`
* **Query Params:**
  * `path`: Đường dẫn đầy đủ đến file cần tải (ví dụ `ebooks/my_book.epub`).

**Python:**
```python
import requests

url = "https://cloud.nthquan.qzz.io/api/files/download"
headers = {"X-API-Key": "koofr_gateway_secret_api_key_2026"}
params = {"path": "ebooks/my_book.epub"}

with requests.get(url, headers=headers, params=params, stream=True) as r:
    r.raise_for_status()
    with open("downloaded_book.epub", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)
print("Download finished!")
```

---

### 3.5. Xóa File / Thư Mục (Delete File or Folder)
* **Endpoint:** `DELETE /api/files`
* **Query Params:**
  * `path`: Đường dẫn file hoặc thư mục cần xóa.

**cURL:**
```bash
curl -X DELETE -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  "https://cloud.nthquan.qzz.io/api/files?path=temp_folder/old_file.txt"
```

---

### 3.6. Tạo Thư Mục Mới (Create Directory)
* **Endpoint:** `POST /api/files/mkdir`
* **Body (Form):**
  * `path`: Thư mục cha.
  * `name`: Tên thư mục mới cần tạo.

**cURL:**
```bash
curl -X POST -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  -F "path=ebooks" \
  -F "name=Audiobooks" \
  https://cloud.nthquan.qzz.io/api/files/mkdir
```

---

### 3.7. Kích Hoạt Làm Mới Cache Tức Thì (Instant VFS Cache Refresh)
* **Endpoint:** `POST /api/sync/refresh`
* **Mô tả:** Gửi lệnh bất đồng bộ đến Rclone Remote Control (port 5572) để làm mới cây thư mục tức thì 0ms mà không làm gián đoạn hệ thống.

**cURL:**
```bash
curl -X POST -H "X-API-Key: koofr_gateway_secret_api_key_2026" \
  https://cloud.nthquan.qzz.io/api/sync/refresh
```

---

### 3.8. Kênh WebSocket Telemetry Thời Gian Thực (Live Stream)
* **Endpoint:** `wss://cloud.nthquan.qzz.io/ws/telemetry`
* **Mô tả:** Tự động phát dữ liệu CPU, RAM, Disk, Koofr Quota mỗi 2 giây.

**JavaScript:**
```javascript
const ws = new WebSocket('wss://cloud.nthquan.qzz.io/ws/telemetry');
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log("Telemetry update:", data);
};
```