API DOCUMENTATION

Tài liệu API dịch vụ

Tập trung các endpoint public cho từng dịch vụ (VPS, Hosting, Proxy, ...). Bạn có thể dùng để tích hợp hệ thống của mình với nền tảng.

Tổng quan

Base URL: {BASE_URL}/api (ví dụ: https://your-domain.com/api)
Request / Response format: Content-Type: application/json, Accept: application/json
Xác thực (Authentication): Endpoint yêu cầu xác thực: gửi header X-Api-Key: <API_KEY> (API Key lấy từ tài khoản sau khi đăng nhập).

Ví dụ header

http

X-Api-Key: <API_KEY>

Catalog – Danh mục & gói VPS

Các endpoint công khai để lấy danh mục, gói, template, region, addon và tính coupon.

GET{BASE_URL}/api/client/vps/categories

Lấy danh mục gói VPS

Danh sách danh mục gói VPS đang bật.

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

[
  {
    "id": 1,
    "name": "VPS Giá Rẻ",
    "slug": "vps-gia-re",
    "description": "Các gói VPS chi phí tối ưu",
    "sortOrder": 1,
    "isActive": true
  }
]

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/categories"

GET{BASE_URL}/api/client/vps/plans

Lấy danh sách gói VPS (phân trang)

Danh sách gói VPS có phân trang và bộ lọc.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
page	number	Không	Trang (mặc định 1)
pageSize	number	Không	Số item/trang (mặc định 20, tối đa 50)
q	string	Không	Từ khóa tìm kiếm
providerId	number	Không	Lọc theo nhà cung cấp
regionId	number	Không	Lọc theo region
categoryId	number	Không	Lọc theo danh mục

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "items": [
    {
      "id": 1,
      "name": "VPS 1 vCPU 1GB",
      "slug": "vps-1vcpu-1gb",
      "cpu": 1,
      "ramMb": 1024,
      "diskGb": 20,
      "price": 100000,
      "durationType": "month",
      "durationValue": 1
    }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 20 }
}

Example

cURL

curl -G "{BASE_URL}/api/client/vps/plans" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20"

GET{BASE_URL}/api/client/vps/plans/by-slug/:slug

Chi tiết gói VPS theo slug

Lấy chi tiết một gói VPS để hiển thị trang chi tiết / form mua.

Path parameters

Tham số	Kiểu	Bắt buộc	Mô tả
slug	string	Có	Slug của gói

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "item": {
    "id": 1,
    "name": "VPS 1 vCPU 1GB",
    "slug": "vps-1vcpu-1gb",
    "description": "Gói VPS cơ bản",
    "cpu": 1,
    "ramMb": 1024,
    "diskGb": 20,
    "price": 100000,
    "templateIds": [10, 11],
    "regionIds": [5, 6]
  }
}

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/plans/by-slug/vps-1vcpu-1gb"

GET{BASE_URL}/api/client/vps/templates

Danh sách template OS

Danh sách template OS khả dụng khi tạo VPS.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
providerId	number	Không	Lọc theo nhà cung cấp

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

[
  { "id": 10, "providerId": 1, "code": "ubuntu-22-04", "name": "Ubuntu 22.04 LTS", "osType": "linux" }
]

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/templates"

GET{BASE_URL}/api/client/vps/regions

Danh sách region

Danh sách region khả dụng.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
providerId	number	Không	Lọc theo nhà cung cấp

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

[
  { "id": 5, "providerId": 1, "code": "hcm", "name": "TP. Hồ Chí Minh" }
]

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/regions"

GET{BASE_URL}/api/client/vps/addons

Bảng giá addon theo provider

Bảng giá addon (CPU/RAM/Disk) theo nhà cung cấp.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
providerId	number	Có	ID nhà cung cấp

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "items": [
    {
      "typeAddon": "addon_cpu",
      "productId": 101,
      "name": "Tăng 1 vCPU",
      "pricing": [
        { "months": 1, "label": "1 Tháng", "amount": 30000 },
        { "months": 3, "label": "3 Tháng", "amount": 80000 }
      ]
    }
  ]
}

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/addons?providerId=1"

GET{BASE_URL}/api/client/vps/addons/by-plan

Bảng giá addon theo gói

Bảng giá addon áp dụng cho một gói VPS (có override theo gói).

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
planId	number	Có	ID gói VPS

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "items": [
    {
      "typeAddon": "addon_ram",
      "productId": 202,
      "name": "Tăng 1 GB RAM",
      "pricing": [
        { "months": 1, "label": "1 Tháng", "amount": 20000 },
        { "months": 12, "label": "1 Năm", "amount": 200000 }
      ]
    }
  ]
}

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/addons/by-plan?planId=1"

GET{BASE_URL}/api/client/vps/coupons/quote

Tính giảm giá với coupon

Kiểm tra mã giảm giá và tính tiền sau giảm cho đơn VPS đặt mới.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
code	string	Có	Mã coupon
subtotal	number	Có	Thành tiền trước giảm (VNĐ)

Responses

Mã	Mô tả
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "code": "VPS10",
  "discount": 50000,
  "total": 450000
}

Example

cURL

curl -G "{BASE_URL}/api/client/vps/coupons/quote" \
  --data-urlencode "code=VPS10" \
  --data-urlencode "subtotal=500000"

Orders – Đơn hàng & hóa đơn VPS

Các endpoint cần JWT: danh sách đơn/instance, tạo đơn, tạo hóa đơn.

GETAPI Key{BASE_URL}/api/client/vps/orders

Danh sách đơn/instance VPS của tài khoản

Lấy danh sách instance VPS thuộc tài khoản, có phân trang và filter.

Query parameters

Tham số	Kiểu	Bắt buộc	Mô tả
page	number	Không	Trang (mặc định 1)
pageSize	number	Không	Số item/trang (mặc định 10, tối đa 100)
limit	number	Không	Alias của pageSize (mặc định 10, tối đa 100)
search	string	Không	Tìm theo mã VPS, IP, mã đơn
orderCode	string	Không	Tìm chính xác theo mã đơn (orderCode)
status	string	Không	Lọc trạng thái (vd: running, off)

Responses

Mã	Mô tả
200	Request thành công
401	Thiếu hoặc sai API Key (header X-Api-Key)
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "items": [
    {
      "id": 1,
      "instanceCode": "VPS-2024-0001",
      "orderCode": "VPS-20240101-120000-12345",
      "planId": 1,
      "planPrice": 100000,
      "status": "running",
      "ipAddress": "203.0.113.10",
      "username": "root",
      "osName": "Ubuntu 22.04",
      "expiresAt": "2024-02-01T01:00:00.000Z"
    }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 10 }
}

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/orders?page=1&pageSize=10" \
  -H "X-Api-Key: <API_KEY>"

POSTAPI Key{BASE_URL}/api/client/vps/orders

Tạo đơn VPS

Mua VPS trực tiếp: server trừ số dư, tạo order, gọi provider và trả về thông tin VPS/instances.

Body parameters

Tham số	Kiểu	Bắt buộc	Mô tả
planId	number	Có	ID gói VPS
templateId	number	Có	ID template OS
billingMonths	number	Có	Số tháng thanh toán
addonCpu	number	Không	Số addon CPU (mặc định 0)
addonRam	number	Không	Số addon RAM (mặc định 0)
addonDisk	number	Không	Số addon Disk (mặc định 0)
couponCode	string \| null	Không	Mã giảm giá
note	string \| null	Không	Ghi chú đơn hàng

Request body

application/json

{
  "planId": 1,
  "templateId": 10,
  "billingMonths": 1,
  "addonCpu": 0,
  "addonRam": 0,
  "addonDisk": 0,
  "couponCode": "VPS10",
  "note": "Ghi chú đơn VPS"
}

Responses

Mã	Mô tả
200	Request thành công
401	Thiếu hoặc sai API Key (header X-Api-Key)
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "item": {
    "orderCode": "VPS-20240101-120000-12345",
    "total": 150000,
    "providerTotal": 120000,
    "instances": [
      {
        "id": 10,
        "instanceCode": "VPSI-VPS-20240101-120000-12345-10001",
        "providerInstanceId": "10001",
        "ipAddress": "203.0.113.10",
        "username": "root",
        "password": "******",
        "status": "progressing",
        "expiresAt": "2024-02-01T01:00:00.000Z"
      }
    ]
  }
}

Example

cURL

curl -X POST "{BASE_URL}/api/client/vps/orders" \
  -H "X-Api-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"planId":1,"templateId":10,"billingMonths":1,"addonCpu":0,"addonRam":0,"addonDisk":0,"couponCode":"VPS10","note":"Ghi chú"}'

POSTAPI Key{BASE_URL}/api/client/vps/orders/invoice

Tạo hóa đơn VPS

Tuỳ chọn: tạo hoá đơn thanh toán cho đơn VPS (dùng khi cần thanh toán trước). Với API mua thẳng, dùng POST /client/vps/orders và bỏ qua endpoint này.

Body parameters

Tham số	Kiểu	Bắt buộc	Mô tả
planId	number	Có	ID gói VPS
templateId	number	Có	ID template OS
billingMonths	number	Có	Số tháng thanh toán
addonCpu	number	Không	Số addon CPU
addonRam	number	Không	Số addon RAM
addonDisk	number	Không	Số addon Disk
couponCode	string \| null	Không	Mã giảm giá
note	string \| null	Không	Ghi chú

Request body

application/json

{
  "planId": 1,
  "templateId": 10,
  "billingMonths": 1,
  "addonCpu": 0,
  "addonRam": 0,
  "addonDisk": 0,
  "couponCode": "VPS10",
  "note": "Thanh toán trước"
}

Responses

Mã	Mô tả
200	Request thành công
401	Thiếu hoặc sai API Key (header X-Api-Key)
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "invoiceCode": "INV-2024-0001"
}

Example

cURL

curl -X POST "{BASE_URL}/api/client/vps/orders/invoice" \
  -H "X-Api-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"planId":1,"templateId":10,"billingMonths":1,"addonCpu":0,"addonRam":0,"addonDisk":0,"couponCode":"VPS10","note":"Thanh toán trước"}'

Instances – Hành động trên VPS

Các endpoint cần xác thực (API Key): lấy danh sách OS rebuild, thao tác on/off/restart/renew/rebuild.

GETAPI Key{BASE_URL}/api/client/vps/instances/:id/rebuild-os-options

Danh sách OS có thể rebuild

Lấy danh sách OS mà user có thể chọn để rebuild VPS. VPS không thuộc user → 404.

Path parameters

Tham số	Kiểu	Bắt buộc	Mô tả
id	number	Có	ID instance VPS của user

Responses

Mã	Mô tả
200	Request thành công
401	Thiếu hoặc sai API Key (header X-Api-Key)
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "items": [
    { "osId": 10, "osName": "Ubuntu 22.04 LTS" },
    { "osId": 11, "osName": "Debian 12" }
  ]
}

Example

cURL

curl -X GET "{BASE_URL}/api/client/vps/instances/1/rebuild-os-options" \
  -H "X-Api-Key: <API_KEY>"

POSTAPI Key{BASE_URL}/api/client/vps/instances/:id/action

Thao tác trên VPS

Thực hiện thao tác: on, off, restart, cancel, addon-vps, on-auto-renew, off-auto-renew, renew-vps, confirm-rebuild-vps. Server kiểm tra instance thuộc user.

Path parameters

Tham số	Kiểu	Bắt buộc	Mô tả
id	number	Có	ID instance VPS của user

Body parameters

Tham số	Kiểu	Bắt buộc	Mô tả
action	string	Có	on \| off \| restart \| cancel \| addon-vps \| on-auto-renew \| off-auto-renew \| renew-vps \| confirm-rebuild-vps
addonCpu	number	Không	Khi action=addon-vps
addonRam	number	Không	Khi action=addon-vps
addonDisk	number	Không	Khi action=addon-vps
billingCycle	string	Không	Khi action=renew-vps
couponCode	string \| null	Không	Khi action=renew-vps
osId	number	Không	Khi action=confirm-rebuild-vps

Ghi chú

renew-vps: body cần billingCycle (và tùy chọn couponCode).
confirm-rebuild-vps: body cần osId (từ rebuild-os-options).

Request body

application/json

{ "action": "on" }

Responses

Mã	Mô tả
200	Request thành công
401	Thiếu hoặc sai API Key (header X-Api-Key)
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
404	Tài nguyên không tồn tại hoặc không thuộc về user

Response thành công (200) – ví dụ:

200 OK

{
  "ok": true,
  "message": "Thao tác thành công.",
  "expiresAt": "2024-03-01T01:00:00.000Z"
}

Example

cURL

curl -X POST "{BASE_URL}/api/client/vps/instances/1/action" \
  -H "X-Api-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "on" }'

Mã lỗi HTTP

Các mã trả về thường gặp khi gọi API. Khi tích hợp, nên kiểm tra 401 khi thiếu hoặc sai API Key và hiển thị thông báo lỗi rõ ràng (tiếng Việt).

Mã	Ý nghĩa
200	Request thành công
400	Tham số không hợp lệ, điều kiện nghiệp vụ không thoả
401	Thiếu hoặc sai API Key (header X-Api-Key)
404	Tài nguyên không tồn tại hoặc không thuộc về user
500	Lỗi hệ thống