# TÀI LIỆU KỸ THUẬT & HƯỚNG DẪN TÍCH HỢP API CLOUD VPS NƯỚC NGOÀI (/vps-nuoc-ngoai)
> **Dự án:** Hệ thống Cloud VPS Nước Ngoài - Shop MMO Studio  
> **Phiên bản:** 1.0 (DigitalOcean Global Cloud Infrastructure)  
> **Base URL:** `https://shopmmostudio.com/api/v1/vps-nuoc-ngoai`  

---

## 1. TỔNG QUAN HỆ THỐNG

Module **Cloud VPS Nước Ngoài** (`/vps-nuoc-ngoai`) cung cấp dịch vụ máy chủ ảo quốc tế tốc độ cao (NVMe Enterprise SSD, mạng 1Gbps), khởi tạo và điều khiển tự động 100% qua giao diện Web và RESTful API:
* **8 Vùng Datacenter Quốc Tế:** Singapore (`sgp1`), New York (`nyc3`), San Francisco (`sfo3`), Amsterdam (`ams3`), Frankfurt (`fra1`), London (`lon1`), Bangalore (`blr1`), Sydney (`syd1`).
* **Đa dạng Hệ điều hành:**
  * **Windows (RDP cổng 3389, User `Administrator`, tự động cài sẵn Google Chrome):** `win-2022`, `win-2019`, `win-10`, `win-11`, `win-2012`.
  * **Linux (SSH cổng 22, User `root`, khởi tạo ~60 giây):** `ubuntu-24`, `ubuntu-22`, `debian-13`, `almalinux-9`, `centos-9`, `rockylinux-9`.
* **Chu kỳ thuê linh hoạt:** `1` tháng (0%), `3` tháng (-5%), `6` tháng (-10%), `12` tháng (-15%).
* **Cơ chế Anti-Spam & Bảo vệ số dư:**
  * Nhịp tạo máy: **10 giây / 1 VPS / tài khoản** (hỗ trợ mua số lượng lớn tuần tự an toàn, không nghẽn đơn).
  * Chỉ trừ tiền đúng từng máy khởi tạo thành công; tự động hoàn tiền 100% ngay lập tức nếu cụm Cloud bận hoặc hệ điều hành/khu vực không khả dụng.
  * Giới hạn thao tác điều khiển nguồn: **60 phút (3600 giây) / 1 lần** trên mỗi VPS.

---

## 2. XÁC THỰC API (AUTHENTICATION)

Tất cả các request gọi API đều truyền API Key & Secret qua HTTP Headers:

```http
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Secret: sk_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
```

---

## 3. CHI TIẾT CÁC ENDPOINTS

### 3.1. Lấy danh sách Gói cấu hình, Hệ điều hành & Datacenter
* **Method:** `GET`
* **URL:** `/api/v1/vps-nuoc-ngoai/plans`
* **Mô tả:** Trả về danh sách các gói VPS đang mở bán (`vps_digitalocean_plans`), bảng giá theo chu kỳ `1, 3, 6, 12` tháng, danh sách `operating_systems` và `regions`. Nếu truyền kèm API Key hợp lệ sẽ trả thêm `user_balance`.

### 3.2. Khởi tạo / Mua Cloud VPS Nước Ngoài
* **Method:** `POST`
* **URL:** `/api/v1/vps-nuoc-ngoai/order` (hoặc `/api/v1/vps-nuoc-ngoai/create`)
* **Request Body (JSON):**
```json
{
  "plan_id": 4,
  "os_code": "win-2022",
  "region": "sgp1",
  "billing_cycle": 1,
  "password": "ShopMMO@2026!x",
  "hostname": "vps-mmo-01"
}
```
* **Tham số:**
  * `plan_id` *(int|string, Bắt buộc)*: ID gói cấu hình (VD: `2`, `3`, `4`, `5` hoặc `"s-2vcpu-4gb"`).
  * `os_code` *(string, Tùy chọn)*: Mã HĐH (hoặc truyền key `image`, mặc định `"win-2022"`).
  * `region` *(string, Tùy chọn)*: Mã vùng Datacenter (mặc định `"sgp1"`).
  * `billing_cycle` *(int, Tùy chọn)*: Chu kỳ thuê `1`, `3`, `6`, `12` tháng (mặc định `1`).
  * `password` *(string, Tùy chọn)*: Mật khẩu máy chủ (8–32 ký tự). Để trống hệ thống tự sinh `ShopMMO@xxxxxx`.
  * `hostname` *(string, Tùy chọn)*: Tên hostname máy chủ.

### 3.3. Danh sách Cloud VPS Nước Ngoài đã mua
* **Method:** `GET`
* **URL:** `/api/v1/vps-nuoc-ngoai/orders` (hoặc `/api/v1/vps-nuoc-ngoai/list`)
* **Query Parameters:** `page`, `limit` (tối đa 100), `status` (`running`, `offline`, `all`), `search`, `sort` (`newest`, `oldest`).

### 3.4. Chi tiết & Đồng bộ Realtime IPv4 / Trạng thái
* **Method:** `GET`
* **URL:** `/api/v1/vps-nuoc-ngoai/detail` (hoặc `/api/v1/vps-nuoc-ngoai/status`)
* **Query Parameters:** `trans_id` (VD: `VPSDO_8F3A91C2`) hoặc `order_id`, tùy chọn `sync=1`.

### 3.5. Điều khiển máy chủ (Reboot / Power Off / Power On / Rebuild...)
* **Method:** `POST`
* **URL:** `/api/v1/vps-nuoc-ngoai/action`
* **Request Body (JSON):**
```json
{
  "trans_id": "VPSDO_8F3A91C2",
  "action": "reboot"
}
```
* **Hành động hỗ trợ (`action`):** `reboot`, `power_cycle`, `shutdown`, `power_off`, `power_on` (`boot`), `enable_ipv6`, `rename` (kèm `new_name`), `rebuild` (kèm `image`).
* **Cooldown:** Giới hạn 60 phút (3600 giây) / 1 lần thao tác trên mỗi VPS.

---

## 4. BẢNG MÃ LỖI (ERROR CODES)

| Error Code | HTTP Code | Ý nghĩa & Hướng xử lý |
| :--- | :--- | :--- |
| `INVALID_API_KEY` | 401 | API Key không hợp lệ hoặc không tồn tại. |
| `INVALID_API_SECRET` | 401 | API Secret không khớp với API Key. |
| `RATE_LIMITED` | 429 | Gọi lệnh tạo VPS nhanh hơn 10 giây/máy. Chờ theo số giây `data.retry_after`. |
| `INSUFFICIENT_BALANCE` | 400 | Số dư ví không đủ để thanh toán gói cấu hình đã chọn. |
| `PLAN_NOT_FOUND` | 400 | ID gói cấu hình không tồn tại hoặc đã ngừng kinh doanh. |
| `INVALID_OS_IMAGE` | 400 | Hệ điều hành không hợp lệ hoặc tạm ngưng (Không trừ tiền — hãy đổi sang `os_code` khác). |
| `REGION_UNAVAILABLE` | 400 | Khu vực Datacenter tạm đầy cấu hình này (Không trừ tiền — hãy đổi sang `region` khác). |
| `ACTION_COOLDOWN` | 429 | Đang trong thời gian chờ 60 phút của thao tác điều khiển trước đó. |
| `OUT_OF_STOCK` | 503 | Hệ thống tạm hết hạn mức tài nguyên Cloud VPS Nước Ngoài. |
| `PROVISION_FAILED` | 500 | Cụm Cloud bận. Hệ thống đã tự động hoàn lại 100% tiền vào ví. |