Quản lý toàn bộ hạ tầng bằng code

Bắt đầu nhanh

Cài công cụ dòng lệnh và tạo máy chủ đầu tiên trong ba câu lệnh.

# Cài đặt CLI
npm install -g @vnso/cli

# Đăng nhập bằng token lấy từ portal
vnso auth login

# Tạo máy chủ và chờ tới khi sẵn sàng
vnso server create --plan vcloud-05 --region hcm-1 --wait

Xác thực

Mọi yêu cầu cần header Authorization chứa bearer token. Token được tạo trong mục Cài đặt của portal và có thể giới hạn quyền theo phạm vi cũng như theo dải IP.

curl https://api.vnso.vn/v1/servers \
  -H "Authorization: Bearer vnso_pat_9f2c1a8d3e5b7c4f"

Token có ba mức phạm vi: read chỉ đọc, write tạo và sửa tài nguyên, và admin bao gồm cả thanh toán cùng quản lý thành viên. Luôn dùng phạm vi hẹp nhất đủ dùng.

Tạo máy chủ

Yêu cầu trả về ngay lập tức với trạng thái provisioning. Máy chủ chuyển sang running sau trung bình 55 giây.

curl -X POST https://api.vnso.vn/v1/servers \
  -H "Authorization: Bearer $VNSO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "region": "hcm-1",
    "plan": "vcloud-05",
    "image": "ubuntu-24-04-x64",
    "ssh_keys": ["key_9f2c1a"],
    "backups": true,
    "ipv6": true,
    "tags": ["production", "web"]
  }'

Phản hồi 202 Accepted

{
  "server": {
    "id": "srv_8f2a1c9d",
    "name": "web-prod-01",
    "status": "provisioning",
    "region": { "slug": "hcm-1", "name": "TP. Hồ Chí Minh" },
    "plan": { "slug": "vcloud-05", "vcpu": 4, "memory_mb": 8192, "disk_gb": 100 },
    "image": { "slug": "ubuntu-24-04-x64", "name": "Ubuntu 24.04 LTS" },
    "networks": {
      "v4": [{ "address": "103.75.184.22", "type": "public" }],
      "v6": [{ "address": "2405:4802:1e:a::22", "type": "public" }]
    },
    "backups": true,
    "tags": ["production", "web"],
    "created_at": "2026-09-07T14:22:03+07:00",
    "price": { "hourly_vnd": 820, "monthly_vnd": 480000 }
  }
}

Danh sách endpoint

Base URL: https://api.vnso.vn

Xử lý lỗi

Lỗi trả về mã HTTP chuẩn kèm thân JSON có cấu trúc cố định, luôn có mã lỗi máy đọc được và thông điệp tiếng Việt cho người đọc.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Số dư ví không đủ để tạo tài nguyên này.",
    "details": {
      "required_vnd": 480000,
      "available_vnd": 120000
    },
    "request_id": "req_3d9f81ac",
    "docs_url": "https://vnso.vn/docs/api/errors#insufficient_balance"
  }
}

Giới hạn tần suất

Mỗi phản hồi kèm header X-RateLimit-Remaining và X-RateLimit-Reset.

Webhook

Đăng ký URL để nhận sự kiện thời gian thực. Mỗi payload được ký HMAC-SHA256 trong header X-VNSO-Signature và được thử lại theo cấp số nhân trong 24 giờ nếu bạn phản hồi khác 2xx.

SDK và công cụ