Chuyển đến nội dung chính
Hà Nội DC
Cloud247
08/11/2026 Cập nhật 11/11/2026 6 phút đọc

Kiến trúc đấu nối Cloud247 REST API v1: Quản lý tổng VPS, đặt đơn tự động & Webhook

Hướng dẫn thiết kế luồng gọi API chuẩn bảo mật cho website đại lý và hệ thống điều phối máy chủ: tách biệt Bearer Token ở Backend, kiểm soát trùng đơn bằng Idempotency-Key và đồng bộ trạng thái qua Webhook whsec_*.

Trọng tâm: GET /v1/services • POST /v1/order-quotes -> POST /v1/orders
Sơ đồ kiến trúc tích hợp Cloud247 REST API v1 cấp phát tự động máy ảo VPS và Proxy IPv4

1. Vì sao không bao giờ gọi thẳng Bearer Token từ trình duyệt (Frontend JS)?

Khi xây dựng trang chủ thương mại hoặc cổng bán lại dịch vụ VPS/Proxy, câu hỏi phổ biến nhất của đội kỹ thuật là có nên dùng fetch() từ trình duyệt gọi thẳng vào https://api.cloud247.vn/v1 hay không.

Câu trả lời kiến trúc chuẩn là KHÔNG nhúng khóa Bearer Token ở tầng trình duyệt. Mọi khóa có quyền orders:create hoặc services:control nếu lộ trong DevTools đều cho phép kẻ tấn công tạo đơn rút cạn số dư Ví hoặc tắt máy ảo. Thay vào đó, hãy áp dụng mô hình Hybrid 2 lớp: đồng bộ danh mục sản phẩm ở bước Build/Server (SSG/SSR) và thực thi mọi lệnh tạo đơn, điều khiển máy ảo từ Backend riêng của bạn.

2. Quy trình chuẩn OpenAPI v1 đặt mua Proxy/VPS không trùng đơn

Cloud247 API v1 được thiết kế theo chuẩn tài chính chặt chẽ với các header bắt buộc X-Currency: VND và Idempotency-Key khi tạo đơn, cùng header tùy chọn Quote-Fingerprint (khuyến nghị gửi kèm để khóa đúng đơn giá vừa báo, tránh chênh lệch giá). Lưu ý mỗi phần tử trong items[] bắt buộc khai báo đủ số lượng phần tử tương ứng trong mảng units[], kèm mật khẩu mặc định trong configuration.password khi dùng chế độ userpass:

Đấu nối điểm cuối api.cloud247.vn/v1 bằng khóa xác thực để đồng bộ danh sách dịch vụ và điều phối xoay IP tự động
Ví dụ báo giá & tạo đơn Proxy hợp lệ chuẩn OpenAPI v1 (Backend)
bash
# Bước 1: Tạo báo giá (bắt buộc có header X-Currency: VND) để lấy Quote-Fingerprint
curl -X POST "https://api.cloud247.vn/v1/order-quotes" \
  -H "Authorization: Bearer $CLOUD247_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Accept-Language: vi" \
  -H "X-Currency: VND" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": 24,
        "billing_cycle_id": 5,
        "qty": 2,
        "auto_renew": true,
        "configuration": {
          "protocol": "socks5",
          "auth_mode": "userpass",
          "password": "ChangeMe-Strong-Pass!247"
        },
        "units": [
          { "configuration": { "username": "pxu_worker01" } },
          { "configuration": { "username": "pxu_worker02" } }
        ],
        "addons": []
      }
    ],
    "promotion_code": null
  }'

# Bước 2: Tạo đơn & thử thanh toán ví kèm Idempotency-Key + Quote-Fingerprint
curl -X POST "https://api.cloud247.vn/v1/orders" \
  -H "Authorization: Bearer $CLOUD247_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Currency: VND" \
  -H "Idempotency-Key: ord-20261108-9f81c2a0" \
  -H "Quote-Fingerprint: <quote_fingerprint_tu_buoc_1>" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ ... ], "promotion_code": null }'

3. Quản lý dàn máy chủ VPS, xoay Proxy và nhúng Console VNC

Sau khi dịch vụ chuyển sang trạng thái active (nhận tức thì qua Webhook xác thực chữ ký HMAC-SHA256 trên header X-Cloud247-Timestamp và X-Cloud247-Signature), đối tác có thể điều khiển toàn bộ vòng đời máy ảo và Proxy ngay từ giao diện quản trị riêng:

  • Liệt kê & kiểm tra trạng thái toàn bộ dịch vụ đang sở hữu: GET /v1/services (phân quyền services:read).
  • Điều khiển nguồn từng máy ảo (start, restart, power-off kèm Idempotency-Key): POST /v1/services/{service}/actions/{action}; cài lại OS & sao lưu qua /maintenance/reinstallations và /maintenance/backups (phân quyền services:control).
  • Cập nhật tài khoản, mật khẩu mới và dải CIDR IP cho phép của Proxy ({ username, new_password, allowed_cidrs } kèm Idempotency-Key): POST /v1/services/{service}/proxy/access-configurations.
  • Khởi tạo phiên cứu hộ HTML5 VNC Console có thời hạn (TTL): POST /v1/services/{service}/maintenance/console-sessions trả về WebSocket/Web URL nhúng trực tiếp.

Bài viết kỹ thuật liên quan

Tiếp tục tham khảo các hướng dẫn vận hành cùng chủ đề trên hệ thống Cloud247:

Tất cả 37 bài viết