REST API

Vị trí trong portal: API reference tại https://<your-domain>/apidoc (công khai) và API keys tại /api-keys. Vị trí trong admin: Customers › API keys (/customers/apikeys) liệt kê các khóa do khách hàng tạo.

Chức năng

Mọi thao tác khách hàng có thể thực hiện trên portal — xem danh sách và điều khiển VM, xem hóa đơn, quản lý SSH Keys, Kubernetes, lưu trữ, ticket hỗ trợ — đều khả dụng qua REST API có phân phiên bản tại https://<your-domain>/v1/. Khách hàng gọi API này từ script và CI bằng API key có giới hạn phạm vi. Cùng API này cũng cung cấp dữ liệu cho cmp công cụ dòng lệnh và MCP server, đồng thời tài liệu tham khảo được tạo trực tiếp từ bản cài đặt đang chạy, nên luôn liệt kê chính xác các tính năng mà bạn đã bật.

Yêu cầu

Hạng mục	Yêu cầu
Địa chỉ HTTPS công khai	API được phân phối trên domain chính của bạn (và trên domain riêng của từng reseller).
Một API key	Do khách hàng tạo trong portal; xem API keys.
Thành phần phụ thuộc	Không có. Các endpoint của module bạn không bật (ví dụ Kubernetes hoặc Object Storage) sẽ bị ẩn khỏi tài liệu tham khảo và bị từ chối truy cập.

Chuẩn bị hạ tầng

Không cần cài đặt gì thêm. Nếu có reverse proxy phía trước NexCMP, hãy chuyển tiếp /v1/, /mcp, /cli/ và /apidoc tới panel (cấu hình nginx của bộ cài đặt đã thiết lập sẵn điều này).

Kết nối trong NexCMP

Tài liệu tham khảo tương tác

Mở https://cloud.example.com/apidoc (thay thế host bằng tên miền của bạn; khách hàng của reseller sẽ thấy tài liệu tham khảo trên tên miền của reseller, với tên của reseller). Trang này chứa tài liệu endpoint kèm ví dụ request và response bằng curl, cmp CLI, JavaScript, Python và Go, ô tìm kiếm (Ctrl hoặc Cmd + K), cùng bảng điều khiển Try it. Try it chỉ gửi request đến cùng một site, sử dụng key do người truy cập dán vào (được lưu trong phiên trình duyệt); chế độ này mặc định là chỉ đọc, và các lệnh ghi hoặc lệnh có tính phí cần có thêm công tắc kích hoạt và xác nhận.

Bản tải về và tài liệu máy đọc được

Tất cả đều công khai, không cần key và được tạo riêng cho từng site:

URL	Nội dung
/apidoc	Tài liệu tham khảo tương tác.
/v1/public/openapi.json	Tài liệu OpenAPI 3.1.
/v1/public/openapi.yaml	Tương tự, định dạng YAML.
/v1/public/postman.json	Postman collection.
/v1/public/insomnia.json	Bản xuất Insomnia.
/v1/public/api.md	Tài liệu tham khảo dưới dạng một tệp Markdown duy nhất.
/v1/public/api-catalog	JSON rút gọn: thương hiệu, base URL, tiền tố key, mọi scope và từng endpoint kèm method, path, scope cùng thông tin có yêu cầu Idempotency-Key hay không.

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

Trong Postman, chọn Import › Link và dán https://cloud.example.com/v1/public/postman.json. Trang tài liệu tham khảo cũng cung cấp API client dạng tệp đơn cho JavaScript và Python.

Xác thực

Gửi key trong header Authorization:

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• Key của khách hàng bắt đầu bằng vk_. Các key đều gắn liền với site: key được tạo trên cloud.example.com sẽ không hoạt động trên tên miền của reseller.
• Token phiên trình duyệt (pt_...) chỉ dành riêng cho portal; hãy sử dụng key để tự động hóa.
• Các scope của key quyết định những gì key có thể gọi; thiếu scope sẽ trả về HTTP 403 scope_required. Xem API keys.
• Kiểm tra key bằng GET /v1/apikeys/self: trả về tên, scope, thời hạn của key đang gọi và hạn mức rate limit còn lại (mọi key đều có thể gọi endpoint này).

Ví dụ

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

Lấy các trường request chính xác của từng thao tác từ /apidoc.

Lỗi

Mỗi lỗi đều là JSON với code cố định và message dễ đọc:

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	code thường gặp	Ý nghĩa
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	Thiếu key hoặc key không xác định, đã bị thu hồi, hết hạn, IP người gọi nằm ngoài allowlist của key, key từ site khác hoặc API key đã bị tắt.
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	Key thiếu scope; endpoint không khả dụng cho key; tài khoản bị khóa; đã chạm quota; thao tác không được phép trong phiên mạo danh.
404	not_found	Không tìm thấy — cũng được trả về cho các tài nguyên thuộc về người khác.
422	invalid_argument	Lỗi xác thực dữ liệu (trường bị lỗi được nêu rõ trong response).
429	rate_limited	Quá nhiều request; vui lòng chờ Retry-After.
503	maintenance	Chế độ bảo trì đang bật: lệnh đọc hoạt động bình thường, lệnh ghi bị từ chối.

Rate limit

Hạn mức	Mặc định
Mỗi key	120 request mỗi phút
Mỗi tài khoản (tất cả các key gộp lại)	300 request mỗi phút

Mọi response đều chứa X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset; lỗi 429 sẽ có thêm Retry-After.

Idempotency

Các lệnh gây phát sinh chi phí hoặc không thể lặp lại (tạo mới, đổi gói cước, mua, xóa...) bắt buộc phải có header Idempotency-Key (chuỗi bất kỳ tối đa 200 ký tự; UUID là một lựa chọn tốt). Khi gửi lại cùng một key sau khi bị timeout, máy chủ sẽ trả về kết quả ban đầu (kèm Idempotency-Replayed: 1) thay vì lặp lại thao tác. Dùng lại key cho một lệnh khác sẽ nhận về lỗi 422; request vẫn đang xử lý sẽ nhận về 409/Retry-After. Nếu không có header này, lệnh có tính phí sẽ bị từ chối.

Kiểm tra

1. Tạo một key với scope vm:read trong portal (API keys › Create key).

2. Chạy:

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   Bạn sẽ nhận được mã HTTP 200 cùng các header rate-limit.

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" liệt kê các VM của tài khoản. Trong portal, cột Last used của khóa và Key usage log sẽ hiển thị các lượt gọi.

Hạn mức & lưu ý

• Không bao giờ khả dụng cho khóa: nạp tiền, rút tiền, đổi thẻ hoặc tự động nạp tiền, đổi mật khẩu, email hoặc 2FA, xóa tài khoản, tạo, chỉnh sửa hoặc thu hồi các khóa khác. Những thao tác này yêu cầu phiên đăng nhập trên trình duyệt.
• Các module bị ẩn: tài liệu tham khảo và tài liệu OpenAPI chỉ liệt kê các tính năng đã được bật trên trang đó.
• Dung lượng phản hồi và phân trang: các endpoint dạng danh sách đều được phân trang (page, per_page); hãy xem tài liệu OpenAPI cho từng endpoint.
• Thời gian và tiền tệ: tiền tệ tính bằng cent USD trừ khi tên trường có quy định khác.
• Admin API: trang quản trị admin có trang System › Admin › API riêng và các khóa quản trị viên (ofw_...) dùng để quản trị; chúng tách biệt với API khách hàng được mô tả tại đây.
• Phiên bản: tiền tố đường dẫn /v1 là cố định; các trường mới có thể được thêm vào phản hồi.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
Lỗi 401 với khóa mới	Khóa từ domain khác, đã hết hạn hoặc chứa khoảng trắng khi nhập	Hãy tạo khóa trên domain bạn gọi tới; kiểm tra header Authorization: Bearer vk_....
403 scope_required	Thiếu scope	Chỉnh sửa khóa trong portal và thêm scope.
401 key_ip_denied hoặc site_mismatch	Khóa bị giới hạn theo IP khác ("allowed IPs") hoặc được tạo trên domain khác	Thêm IP máy chủ của bạn vào danh sách allowed IPs của khóa, hoặc gọi tới domain nơi khóa được tạo.
Lỗi 404 với VM đang tồn tại	VM thuộc về tài khoản khác	Sử dụng khóa của chủ sở hữu.
Lỗi 400/422 yêu cầu Idempotency-Key	Thao tác tính phí nhưng thiếu header	Thêm Idempotency-Key: <uuid>.
429	Vượt quá giới hạn	Giảm tần suất gọi; sử dụng Retry-After.
/apidoc hiển thị ít hơn dự kiến	Module đã bị tắt	Bật module trong License & updates.