Tài liệu API Cloud VPS Nước Ngoài

Tổng quan API Cloud VPS Nước Ngoài

Thông tin kết nối và cấu trúc RESTful API VPS Nước Ngoài (/vps-nuoc-ngoai)

Tải tài liệu .md .MD

Base URL https://shopmmostudio.com/api/v1/vps-nuoc-ngoai

API Key Tạo API Key ngay

Data Format JSON (application/json)

Nhịp tạo VPS (Anti-Spam) 10 giây / 1 VPS (Mua số lượng lớn đẩy tuần tự cách nhau 10s)

Chu kỳ hỗ trợ 1 tháng 3 tháng (-5%) 6 tháng (-10%) 12 tháng (-15%)

Chưa có API Key? Vui lòng truy cập Quản lý API Keys để tạo API Key và API Secret hoàn toàn miễn phí.

Xác thực API

Cách thức gửi API Key & Secret qua HTTP Request Headers

Tất cả các request gọi API (trừ /plans công khai) đều yêu cầu cung cấp các Header sau:

Header	Ví dụ giá trị	Mô tả
X-API-Key	`sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`	API Key của bạn (bắt đầu bằng `sk_live_`)
X-API-Secret	`sk_secret_a1b2c3d4e5f6g7h...`	API Secret bí mật (bắt đầu bằng `sk_secret_`)
Content-Type	`application/json`	Bắt buộc khi gửi POST request

Ví dụ Headers

HTTP Headers

X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
Content-Type: application/json

1. Danh sách Gói cấu hình, Hệ điều hành & Datacenter

Lấy danh sách các gói Cloud VPS Nước Ngoài đang mở bán, bảng giá theo chu kỳ, mã OS và 8 vùng Datacenter

GET https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/plans

Endpoint này công khai hoặc có thể gửi kèm API Key để nhận kèm thông tin số dư ví hiện tại (user_balance).

Code mẫu

PHP (cURL)

<?php
$ch = curl_init('https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/plans');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

Ví dụ Response thành công (HTTP 200)

JSON

{
  "success": true,
  "timestamp": 1793850000,
  "message": "Lấy danh sách cấu hình Cloud VPS Nước Ngoài thành công",
  "data": {
    "plans": [
      {
        "id": 2,
        "plan_id": "s-1vcpu-2gb",
        "name": "VPS 1-2-50",
        "cpu_cores": 1,
        "ram_mb": 2048,
        "ram_gb": 2,
        "ram_formatted": "2GB",
        "disk_gb": 50,
        "transfer_gb": 2000,
        "price_monthly": 25000,
        "price_formatted": "25.000đ",
        "badge": "Phổ biến",
        "billing_cycles": {
          "1_month": { "months": 1, "discount_percent": 0, "price": 25000 },
          "3_months": { "months": 3, "discount_percent": 5, "price": 71250 },
          "6_months": { "months": 6, "discount_percent": 10, "price": 135000 },
          "12_months": { "months": 12, "discount_percent": 15, "price": 255000 }
        }
      },
      {
        "id": 4,
        "plan_id": "s-2vcpu-4gb",
        "name": "VPS 2-4-80",
        "cpu_cores": 2,
        "ram_mb": 4096,
        "ram_gb": 4,
        "ram_formatted": "4GB",
        "disk_gb": 80,
        "transfer_gb": 4000,
        "price_monthly": 40000,
        "price_formatted": "40.000đ",
        "badge": "Khuyên dùng"
      }
    ],
    "operating_systems": {
      "windows": [
        { "os_code": "win-2022", "name": "Windows Server 2022 Datacenter", "default_user": "Administrator", "default_port": 3389, "auto_chrome": true },
        { "os_code": "win-10", "name": "Windows 10 Pro 64-bit", "default_user": "Administrator", "default_port": 3389, "auto_chrome": true }
      ],
      "linux": [
        { "os_code": "ubuntu-24", "name": "Ubuntu 24.04 LTS (Noble)", "default_user": "root", "default_port": 22 },
        { "os_code": "debian-13", "name": "Debian 13 (Trixie)", "default_user": "root", "default_port": 22 }
      ]
    },
    "regions": [
      { "id": "sgp1", "name": "Singapore (SG)", "country": "Singapore", "is_recommended": true },
      { "id": "nyc3", "name": "New York, Mỹ (US-East)", "country": "United States" },
      { "id": "sfo3", "name": "San Francisco (US-West)", "country": "United States" },
      { "id": "fra1", "name": "Frankfurt, Đức (EU-DE)", "country": "Germany" }
    ],
    "rate_limits": {
      "order_interval_seconds": 10,
      "action_cooldown_seconds": 3600
    },
    "user_balance": 500000
  }
}

2. Khởi tạo / Mua Cloud VPS Nước Ngoài

Trừ số dư tài khoản và khởi tạo máy chủ Cloud VPS Nước Ngoài mới tự động qua API

POST https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/order

Cơ chế Anti-Spam 10 giây / 1 VPS & Tự động cài Chrome:

Mỗi request POST /order khởi tạo đúng 1 máy chủ VPS và chỉ trừ tiền khi tạo thành công trên DigitalOcean.
Khi mua số lượng nhiều (Batch), vui lòng gửi từng request cách nhau tối thiểu 10 giây. Nếu gửi sớm hơn, API sẽ trả về HTTP 429 (RATE_LIMITED) kèm trường retry_after (số giây cần chờ).
Với Hệ điều hành Windows, hệ thống tự động nạp bản Windows (khoảng 5–10 phút) và tự động cài sẵn Google Chrome ngay khi cổng RDP 3389 mở.

Request Body (JSON)

Tham số	Kiểu	Bắt buộc	Mô tả & Giá trị mẫu
plan_id	int \| string	Bắt buộc	ID của gói cấu hình (VD: `2`, `3`, `4`, `5` hoặc mã `"s-2vcpu-4gb"`)
os_code	string	Tùy chọn	Mã hệ điều hành (hoặc truyền key `image`). Mặc định: `"win-2022"`. • Windows: `win-2022`, `win-2019`, `win-10`, `win-11`, `win-2012` • Linux: `ubuntu-24`, `ubuntu-22`, `debian-13`, `almalinux-9`, `centos-9`, `rockylinux-9`
region	string	Tùy chọn	Vùng Datacenter. Mặc định: `"sgp1"` (Singapore). Hỗ trợ: `sgp1`, `nyc3`, `sfo3`, `ams3`, `fra1`, `lon1`, `blr1`, `syd1`.
billing_cycle	int	Tùy chọn	Chu kỳ thuê theo tháng: `1` (0%), `3` (-5%), `6` (-10%), `12` (-15%). Mặc định: `1`.
password	string	Tùy chọn	Mật khẩu Administrator/root (8–32 ký tự, gồm chữ HOA, thường, số/ký tự đặc biệt, không chứa "'\$%`). Để trống hệ thống tự sinh `ShopMMO@xxxxxx`.
hostname	string	Tùy chọn	Tên hostname máy chủ (VD: `"vps-mmo-01"`)

Code mẫu (Mua đơn lẻ & Mua số lượng lớn 10s/VPS)

PHP (cURL)

<?php
$apiKey    = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';

$data = [
    'plan_id'       => 4,                // Gói VPS 2-4-80 (hoặc 's-2vcpu-4gb')
    'os_code'       => 'win-2022',       // Windows Server 2022 Datacenter
    'region'        => 'sgp1',           // Datacenter Singapore
    'billing_cycle' => 1,                // 1 tháng
    'password'      => 'ShopMMO@2026!x', // (Tùy chọn) Để trống tự sinh
    'hostname'      => 'vps-mmo-01'      // (Tùy chọn) Tên máy chủ
];

$ch = curl_init('https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/order');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 90,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . $apiKey,
        'X-API-Secret: ' . $apiSecret,
        'Content-Type: application/json'
    ]
]);
$res = curl_exec($ch);
curl_close($ch);

print_r(json_decode($res, true));

Ví dụ Response thành công (HTTP 201 Created)

JSON

{
  "success": true,
  "message": "Khởi tạo Cloud VPS Nước Ngoài thành công!",
  "data": {
    "order_id": 45,
    "trans_id": "VPSDO_8F3A91C2",
    "droplet_id": 461829310,
    "hostname": "vps-vpsdo-8f3a91c2",
    "plan": {
      "id": 4,
      "name": "VPS 2-4-80",
      "plan_id": "s-2vcpu-4gb",
      "cpu": 2,
      "ram_mb": 4096,
      "disk_gb": 80
    },
    "operating_system": {
      "os_code": "win-2022",
      "name": "Windows Server 2022 Datacenter",
      "is_windows": true,
      "auto_chrome": true
    },
    "connection": {
      "ip": "159.223.68.142",
      "ipv6": "2400:6180:0:d0::142:9001",
      "username": "Administrator",
      "password": "ShopMMO@2026!x",
      "port": 3389,
      "protocol": "RDP"
    },
    "region": "sgp1",
    "billing_cycle": 1,
    "discount_percent": 0,
    "amount": 40000,
    "balance_before": 200000,
    "balance_after": 160000,
    "status": "running",
    "manage_url": "https://shopmmostudio.com/vps-nuoc-ngoai-history?trans_id=VPSDO_8F3A91C2",
    "created_at": "2026-11-05 10:35:00",
    "expires_at": "2026-12-05 10:35:00"
  }
}

3. Danh sách Cloud VPS Nước Ngoài đã mua

Lấy danh sách tất cả máy chủ Cloud VPS Nước Ngoài của bạn kèm tự động đồng bộ IPv4, phân trang và bộ lọc

GET https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/orders

Query Parameters

Tham số	Kiểu	Mặc định	Mô tả
page	int	`1`	Trang cần xem
limit	int	`10`	Số lượng bản ghi mỗi trang (tối đa 100)
status	string	`all`	Lọc theo trạng thái: `running`, `offline`, hoặc `all`
search	string	null	Tìm theo IP, mã đơn (`trans_id`), tên gói (`plan_name`) hoặc tên HĐH

Code mẫu

PHP

<?php
$ch = curl_init('https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/orders?page=1&limit=20&status=running');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);
$res = curl_exec($ch);
curl_close($ch);
print_r(json_decode($res, true));

4. Chi tiết & Đồng bộ IPv4 / Trạng thái Realtime

Xem thông tin chi tiết 1 máy chủ, tự động cập nhật IPv4/IPv6 và trạng thái mới nhất từ DigitalOcean

GET https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/detail

Tính năng Realtime IP & Status Sync: Nếu máy chủ vừa khởi tạo đang ở trạng thái Đang cấp phát... hoặc bạn truyền thêm tham số sync=1, hệ thống sẽ truy vấn trực tiếp DigitalOcean API để lấy địa chỉ IPv4, IPv6, Private IP và cập nhật ngay lập tức!

Query Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
trans_id	string	1 trong 2	Mã đơn hàng Cloud VPS Nước Ngoài (VD: `"VPSDO_8F3A91C2"`)
order_id	int	1 trong 2	ID đơn hàng máy chủ trong hệ thống (VD: `45`)
sync	int	Tùy chọn	Truyền `1` để ép đồng bộ realtime từ DigitalOcean ngay cả khi máy đã có IP

Code mẫu

PHP

<?php
$transId = 'VPSDO_8F3A91C2';

$ch = curl_init('https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/detail?trans_id=' . $transId);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);
$res = curl_exec($ch);
curl_close($ch);
print_r(json_decode($res, true));

5. Điều khiển máy chủ Cloud VPS Nước Ngoài

Gửi lệnh Reboot, Power Off, Shutdown, Power On, Power Cycle, Enable IPv6, Rename hoặc Rebuild

POST https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/action

Quy định Cooldown 60 phút: Để tránh spam lệnh làm khóa tài khoản Cloud, mỗi máy chủ được giới hạn thao tác điều khiển 60 phút (3600 giây) 1 lần. Nếu gọi API trong thời gian chờ, API trả về HTTP 429 (ACTION_COOLDOWN) kèm số giây còn lại.

Request Body (JSON)

Tham số	Kiểu	Bắt buộc	Mô tả
trans_id	string	1 trong 2	Mã giao dịch (VD: `"VPSDO_8F3A91C2"`)
order_id	int	1 trong 2	ID đơn hàng máy chủ
action	string	Bắt buộc	Hành động thực hiện: • `reboot`: Khởi động lại mềm (Soft Reboot) • `power_cycle`: Khởi động lại cứng (Hard Reset) • `shutdown` / `power_off`: Tắt nguồn máy chủ • `power_on` (hoặc `boot`): Bật nguồn máy chủ • `enable_ipv6`: Bật mạng IPv6 cho Droplet • `rename`: Đổi hostname (kèm tham số `new_name`) • `rebuild`: Cài lại Linux chuẩn (kèm tham số `image`)

Code mẫu

PHP

<?php
$data = [
    'trans_id' => 'VPSDO_8F3A91C2',
    'action'   => 'reboot' // reboot, power_off, power_on, power_cycle, enable_ipv6...
];

$ch = curl_init('https://shopmmostudio.com/api/v1/vps-nuoc-ngoai/action');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2',
        'Content-Type: application/json'
    ]
]);
$res = curl_exec($ch);
curl_close($ch);
print_r(json_decode($res, true));

Hệ điều hành & 8 Datacenter Quốc Tế hỗ trợ

Bảng mã tham chiếu os_code và region khi gọi API khởi tạo máy chủ

Windows Server & Desktop (RDP Cổng 3389 • Tự động cài sẵn Google Chrome)

Mã `os_code`	Alias tương thích	Tên phiên bản	Tài khoản RDP
`win-2022`	`windows-2022`	Windows Server 2022 Datacenter	Administrator
`win-2019`	`windows-2019`	Windows Server 2019 Datacenter	Administrator
`win-10`	`windows-10`	Windows 10 Pro 64-bit	Administrator
`win-11`	`windows-11`	Windows 11 Pro 64-bit	Administrator
`win-2012`	`windows-2012`	Windows Server 2012 R2 Lite (~400MB RAM)	Administrator

Linux Distributions (SSH Cổng 22 • Khởi tạo 60 giây)

Mã `os_code`	Alias tương thích	Tên phiên bản	Tài khoản SSH
`ubuntu-24`	`ubuntu-24-04-x64`, `ubuntu24.04`	Ubuntu 24.04 LTS (Noble)	root
`ubuntu-22`	`ubuntu-22-04-x64`, `ubuntu22.04`	Ubuntu 22.04 LTS (Jammy)	root
`debian-13`	`debian-13-x64`, `debian13`	Debian 13 (Trixie)	root
`almalinux-9`	`almalinux-9-x64`, `almalinux9`	AlmaLinux 9 (RHEL Compatible)	root
`centos-9`	`centos-stream-9-x64`, `centos-stream9`	CentOS Stream 9 (64-bit)	root
`rockylinux-9`	`rockylinux-9-x64`, `rocky9`	Rocky Linux 9 (Enterprise)	root

8 Vùng Datacenter Quốc Tế (Regions)

Mã `region`	Địa điểm Datacenter	Đặc điểm
`sgp1`	🇸🇬 Singapore (SG)	Khuyên dùng • Ping VN 30-40ms
`nyc3`	🇺🇸 New York, Mỹ (US-East)	Bờ Đông nước Mỹ • Băng thông lớn
`sfo3`	🇺🇸 San Francisco, Mỹ (US-West)	Bờ Tây nước Mỹ • Kết nối Á-Mỹ nhanh
`ams3`	🇳🇱 Amsterdam, Hà Lan (EU)	Trung tâm mạng Châu Âu
`fra1`	🇩🇪 Frankfurt, Đức (EU-DE)	Datacenter cao cấp trung tâm EU
`lon1`	🇬🇧 London, Anh (EU-UK)	Đường truyền Châu Âu chuẩn Tier 3
`blr1`	🇮🇳 Bangalore, Ấn Độ (IN)	Khu vực Nam Á tốc độ cao
`syd1`	🇦🇺 Sydney, Úc (AU)	Châu Đại Dương • Dải IP sạch

Quy định Anti-Spam & Cooldown

Cơ chế bảo vệ tài khoản Cloud và tối ưu tỉ lệ tạo máy thành công 100%

1. Khi khởi tạo VPS (10 giây / 1 máy)

Để tránh nghẽn đơn và bảo vệ pool tài khoản Cloud, mỗi tài khoản người dùng được tạo tối đa 1 VPS mỗi 10 giây (đồng bộ cả trên giao diện Web và qua API). Khi mua số lượng lớn qua API, chỉ cần đặt sleep(10) giữa các lệnh gọi POST /order.

2. Khi điều khiển nguồn (60 phút / 1 lần)

Mỗi máy chủ Droplet chỉ cho phép thực hiện các thao tác điều khiển (reboot, power_off, power_on, rebuild...) 60 phút 1 lần. Bạn có thể kiểm tra trường action_cooldown.is_available từ GET /detail trước khi gửi lệnh.

Bảng mã lỗi thường gặp

Các mã lỗi (error_code) trả về từ hệ thống API VPS Nước Ngoài

Error Code	HTTP Code	Ý nghĩa & Cách xử lý
`INVALID_API_KEY`	401	API Key không hợp lệ hoặc không tồn tại. Vui lòng kiểm tra lại header X-API-Key.
`INVALID_API_SECRET`	401	API Secret không khớp với API Key đã cung cấp.
`RATE_LIMITED`	429	Gửi lệnh tạo VPS nhanh hơn 10 giây/máy. Đọc trường `data.retry_after` để chờ đúng số giây còn lại rồi gọi lại.
`INSUFFICIENT_BALANCE`	400	Số dư ví không đủ để thanh toán gói VPS theo chu kỳ đã chọn.
`INVALID_OS_IMAGE`	400	Hệ điều hành không hợp lệ hoặc tạm ngưng trên khu vực đã chọn. Hệ thống KHÔNG trừ tiền — hãy đổi sang mã `os_code` khác.
`REGION_UNAVAILABLE`	400	Khu vực Datacenter đang tạm đầy cấu hình này. Hệ thống KHÔNG trừ tiền — hãy đổi sang `region` khác (VD: `sgp1`, `nyc3`, `fra1`).
`ACTION_COOLDOWN`	429	Mỗi thao tác điều khiển VPS chỉ được thực hiện 60 phút 1 lần. Xem `data.retry_after` để biết số giây còn lại.
`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 (chưa trừ tiền).
`PROVISION_FAILED`	500	Khởi tạo máy chủ thất bại do cụm Cloud bận. Hệ thống đã tự động hoàn lại 100% tiền vào số dư ví.