HELPER VPS

Bắt đầu nhanh API VPS, tạo khóa API và máy chủ đầu tiên

API của HELPER VPS là REST API trao đổi JSON qua HTTPS. Một khóa là làm được tất cả: tra cứu cấu hình, tạo máy chủ, quản lý nguồn, gia hạn, xóa. Hãy làm theo từ yêu cầu đầu tiên đến tạo và xóa một máy chủ.

Bước 1. Tạo khóa API

Bạn có thể tạo khóa API sau lần thanh toán đầu tiên. Xem hướng dẫn thanh toán bằng USDT để biết cách thanh toán.

  • Trong mục Khóa API của tài khoản, nhấn Tạo khóa API.
  • Khóa bắt đầu bằng hvp_ chỉ hiển thị một lần. Sao chép ngay và lưu vào trình quản lý mật khẩu.
  • Trên giao diện chỉ còn các ký tự cuối của khóa để nhận ra đang dùng khóa nào.
  • Nhấn Tạo khóa mới là khóa mới hiện ra và khóa cũ ngừng hoạt động ngay.

Khóa là chìa khóa điều khiển cả tài khoản, nên đưa vào biến môi trường để không lộ trong kho mã hay khi chia sẻ màn hình. Ví dụ trong hướng dẫn này bắt đầu bằng việc gán khóa vào một biến trong terminal.

Terminal
export HVP_KEY=hvp_KHOA_CUA_BAN
export HVP=https://helpervps.com/api/v1

Bước 2. Xác thực và yêu cầu đầu tiên

Mọi yêu cầu gửi đến dưới địa chỉ gốc https://helpervps.com/api/v1 và kèm tiêu đề Authorization: Bearer khóa. Yêu cầu đầu tiên hãy tải danh sách máy chủ của bạn. Nếu chưa có máy chủ sẽ trả về danh sách rỗng [].

Terminal
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Mỗi tài khoản gửi được tối đa 300 yêu cầu mỗi phút, tạo máy chủ tối đa 10 lần mỗi 10 phút. Yêu cầu lặp để kiểm tra trạng thái cách nhau vài giây là đủ. Mọi phản hồi đều là JSON, khi lỗi sẽ trả về mã trạng thái kèm dạng {"error": "mã"}.

Bước 3. Chọn cấu hình, khu vực, image

Mọi giá trị dùng khi tạo máy chủ đều lấy từ danh mục. GET /catalog trả về cùng lúc các cấu hình đang bán (plans), khu vực (locations), image (images), tùy chọn bổ sung (addons). Có jq thì lọc xem phần cần thiết tiện hơn.

Terminal
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'
  • Mã cấu hình: như s1, s2, thể hiện loại và kích thước. type là basic (SSD tiêu chuẩn), fast (NVMe hiệu năng cao), cpu (CPU riêng), mem (bộ nhớ cao). monthly là phí hàng tháng tính bằng đô la Mỹ.
  • Mã khu vực: là tên thành phố như frankfurt, singapore, seoul.
  • Mã image: là hệ điều hành như ubuntu-24-04, debian-13, almalinux-10 và ứng dụng như app-docker, app-wordpress.
  • Tùy chọn bổ sung: tỷ lệ sao lưu tự động, kích thước ổ đĩa bổ sung và phí mỗi GB, phí chống DDoS. Tùy chọn không bán trả về null.

Nếu Ubuntu chưa có thì cài bằng apt install -y jq, Mac bằng brew install jq. Đây là cùng danh sách như khi chọn trên giao diện, khác biệt giữa các cấu hình xem kèm ở trang bảng giá sẽ tiện.

Bước 4. Tạo máy chủ

Gửi gói, vị trí, image và tên dưới dạng JSON tới POST /servers. Thanh toán cho kỳ đầu tiên của gói bạn chọn và quá trình tạo máy chủ sẽ bắt đầu.

Terminal
curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

Thành công sẽ trả về mã trạng thái 201 kèm thông tin máy chủ. id là mã máy chủ dạng S-XXXX-XXXX-XXXX, dùng mã này cho mọi yêu cầu sau. root_password có một lần trong phản hồi này nên hãy lưu ngay. Trên trang máy chủ cũng xem được trong 7 ngày.

  • label: tên máy chủ. Gồm chữ Latinh, số, dấu chấm, dấu gạch nối, tối đa 40 ký tự, ký tự khác sẽ đổi thành dấu gạch nối.
  • backups: true là bật sao lưu tự động.
  • extra_disk_gb: kích thước ổ khối NVMe bổ sung. Điền một trong các giá trị sizes_gb của danh mục (50, 100, 250, 500, 1000).
  • ddos_protection: true là bật chống DDoS.

Phí tùy chọn được cộng vào phí hàng tháng của máy chủ, hiển thị ở monthly trong phản hồi, và tự động gia hạn cùng số tiền vào mỗi ngày thanh toán. Mỗi tài khoản tạo được tối đa 10 máy chủ.

Bước 5. Kiểm tra trạng thái và kết nối

Máy chủ mới bắt đầu ở trạng thái creating, sẵn sàng thì thành running và có địa chỉ ipv4. Vòng lặp dưới đây xem trạng thái mỗi 10 giây và hiển thị IP khi thành running. Hãy thay mã máy chủ bằng mã máy chủ của bạn.

Terminal
ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

Trạng thái là một trong các giá trị: creating, running, stopped, rebooting, installing, suspended hoặc check. suspended có nghĩa là máy chủ bị tạm dừng do không được gia hạn vào ngày thanh toán, và check có nghĩa là chúng tôi đang kiểm tra kết quả thiết lập máy chủ. Khi IP xuất hiện, hãy kết nối bằng ssh root@IP. Cách kết nối có trong hướng dẫn đăng nhập lần đầu.

Bước 6. Nguồn, gia hạn, xóa

Terminal
curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"
  • start: bật máy chủ đã dừng (stopped).
  • stop, reboot: tắt hoặc khởi động lại máy chủ đang chạy (running).
  • renew: thanh toán cho 1, 3, 6 hoặc 12 tháng tiếp theo ngay bây giờ. Máy chủ bị tạm dừng cũng sẽ hoạt động lại với yêu cầu này.
  • DELETE: xóa máy chủ và ổ đĩa, trả về {"state": "deleted"}. Thời gian còn lại của tháng đã thanh toán không được hoàn tiền.

Gửi thao tác không thực hiện được ở trạng thái hiện tại sẽ trả về 409 wrong_state. Ví dụ gửi start cho máy chủ đã bật. Cài đặt lại và tạo mật khẩu root mới làm trên trang máy chủ. Thứ tự có trong hướng dẫn cài đặt lại.

Chạy cùng thứ tự bằng Python

Viết cùng luồng bằng script Python sẽ như sau. Dùng thư viện requests (pip install requests).

create_server.py
import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Các mã lỗi hay gặp

  • 401 unauthorized: thiếu khóa hoặc khóa sai. Kiểm tra tiêu đề có dạng Authorization: Bearer hvp_... không.
  • 403 not_allowed: mở ra sau khi lần thanh toán đầu tiên được xác nhận.
  • 400 bad_request: tên trường hoặc giá trị sai. Dùng đúng giá trị trong danh mục.
  • 402 not_enough_balance: số tiền thanh toán dưới $25. Hãy gửi lại với ít nhất $25.
  • 409 limit: đã đạt số máy chủ tối đa tài khoản có thể tạo.
  • 409 not_created: không thể tạo máy chủ, và phí sẽ được chuyển vào tín dụng tài khoản của bạn.
  • 202 checking: chúng tôi đang kiểm tra kết quả thiết lập máy chủ. Đừng gửi lại cùng yêu cầu; hãy kiểm tra danh sách máy chủ của bạn. Máy chủ sẽ được hoàn tất hoặc phí sẽ được trả lại vào tín dụng tài khoản của bạn.
  • 404 not_found: mã máy chủ hoặc địa chỉ không có trong tài khoản của bạn.
  • 409 wrong_state: thao tác không thực hiện được ở trạng thái hiện tại.
  • 429 rate_limited: đã đạt giới hạn yêu cầu mỗi phút. Chờ một chút rồi gửi lại.

Mọi endpoint, trường phản hồi, ví dụ đều được gom trong tài liệu API. Những việc làm được với API và công dụng xem ở trang VPS API.

Hướng dẫn nên xem cùng

Các cấu hình nên làm tiếp sau hướng dẫn này.

Xem tất cả hướng dẫn