Tài liệu API Đại lý Cloudzone

Phiên bản tài liệu: 09/2026 - thay cho bản PDF v1 (04/2024). Trang này được cập nhật khi API có điểm cuối mới.

1. Bắt đầu nhanh

1. Nhận bộ khóa: sau khi ký hợp đồng đại lý, Cloudzone cấp api-username, api-app, api-secret và đăng ký danh sách IP máy chủ của bạn - API chỉ nhận lời gọi từ các IP đã cấp phép.
2. Lấy auth-token:

POST https://api-agency.cloudzone.vn/api/agency/get-auth-token
{
  "api-username": "...",
  "api-app": "...",
  "api-secret": "..."
}

3. Gọi API: mọi lời gọi sau đó kèm đủ 4 header: api-username, api-app, api-secret, auth-token.

curl -H "api-username: ..." -H "api-app: ..." -H "api-secret: ..." -H "auth-token: ..." \
  https://api-agency.cloudzone.vn/api/agency/get-info

2. Danh mục điểm cuối

Tài khoản & nạp tiền

Method	Đường dẫn	Chức năng
GET	/get-info	Thông tin đại lý, số dư hiện tại
GET	/get-info-recharge	Thông tin nạp tiền
POST	/request-recharge	Tạo yêu cầu nạp tiền
GET	/get-detail-payment	Chi tiết một giao dịch thanh toán
GET	/get-qr-by-oam	Lấy mã QR nạp tiền
POST	/check-trans-by-oam	Kiểm tra giao dịch nạp đã về chưa
GET	/order/get-list-transaction	Lịch sử giao dịch của đại lý

Danh mục sản phẩm

Method	Đường dẫn	Chức năng
GET	/product/get-product	Toàn bộ gói đang bán được cấp cho đại lý (VPS, proxy, hosting, và khoá storage nếu có quyền Lưu trữ)
GET	/product/get-detail-product?productId=...	Chi tiết một gói
GET	/product/get-os · /product/get-os-vps-nn	Danh sách hệ điều hành
GET	/product/get-billing-cycle	Các chu kỳ thanh toán
GET	/product/get-state · /product/get-state-type-2	Bảng trạng thái dịch vụ

Đặt dịch vụ mới

Method	Đường dẫn	Chức năng
POST	/order/create-new-order	Đặt VPS Việt Nam hoặc gói Lưu trữ Cloudzone Box
POST	/order/create-new-order-vps-nn	Đặt VPS nước ngoài
POST	/order/create-new-order-proxy	Đặt Proxy
POST	/order/check-domain-by-hosting rồi /order/create-new-order-hosting	Kiểm tên miền và đặt Hosting
POST	/order/create-addon-vps	Nâng cấp CPU/RAM/ổ cứng cho VPS đang chạy

Quản lý dịch vụ đang có

Method	Đường dẫn	Chức năng
GET	/vps-vn/get-list-vps · /vps-vn/get-detail-vps	Danh sách / chi tiết VPS Việt Nam
POST	/vps-vn/action-vps	Bật, tắt, khởi động lại, cài lại VPS
GET	/vps-nn/get-list-vps · /vps-nn/get-detail-vps	Danh sách / chi tiết VPS nước ngoài
POST	/vps-nn/action-vps	Thao tác VPS nước ngoài
GET	/proxy/get-list-proxy · /proxy/get-detail-proxy	Danh sách / chi tiết Proxy
POST	/proxy/action-proxy	Thao tác Proxy
GET	/hosting/get-detail-hosting	Chi tiết Hosting
POST	/hosting/action-hosting	Thao tác Hosting

Lưu trữ Cloudzone Box

Method	Đường dẫn	Chức năng
GET	/storage/get-list-storage	Mọi gói lưu trữ của đại lý
GET	/storage/get-detail-storage?storage-id=...	Chi tiết một gói
POST	/storage/expire-storage	Gia hạn gói
POST	/storage/upgrade-storage	Nâng lên gói lớn hơn
POST	/storage/set-password	Đặt mật khẩu box để giao khách cuối

3. Hướng dẫn chi tiết: bán Cloudzone Box qua API

Nhóm điểm cuối mới nhất (09/2026). Đại lý cần được cấp quyền Lưu trữ trước - liên hệ Cloudzone.

3.1. Xem gói và giá

GET /product/get-product trả thêm khóa storage gồm 5 gói: 50 GB (712), 100 GB (713), 200 GB (714), 500 GB (715), 1 TB (716). Chỉ có ba chu kỳ monthly, semi_annually, annually - gọi quarterly sẽ bị từ chối.

3.2. Đặt gói mới

POST /order/create-new-order
{ "product-id": 712, "billing-cycle": "monthly", "quantity": 1 }

quantity bắt buộc bằng 1 - mỗi lời gọi tạo đúng một tài khoản box. Tiền trừ ngay vào số dư. Phản hồi trả về storage-id, box-userid, box-url và storage-status: "waiting" - tài khoản được tạo bởi tác vụ nền trong vài phút, gọi get-detail-storage tới khi trạng thái thành on.

3.3. Trạng thái gói

Trạng thái	Nghĩa
waiting	Đã trả tiền, đang chờ tạo tài khoản
creating	Đang tạo
on	Đang chạy
expire	Hết hạn - tài khoản tạm treo, dữ liệu còn nguyên
loi	Tạo thất bại nhiều lần, Cloudzone đã được báo để xử lý

3.4. Gia hạn

POST /storage/expire-storage
{ "storage-id": 12, "billing-cycle": "annually" }

Bỏ trống billing-cycle thì lấy chu kỳ hiện tại. Gia hạn được cả gói on lẫn expire - gói đang treo do hết hạn sẽ tự mở lại trong vài phút.

3.5. Nâng gói

POST /storage/upgrade-storage
{ "storage-id": 12, "product-id": 713 }

Chỉ nâng lên gói lớn hơn. Số tiền thu là phần chênh của quãng chưa dùng, không thu trọn chu kỳ mới; next-due-date giữ nguyên. Dung lượng mới có hiệu lực trong vài phút.

3.6. Nâng cấp VPS đang chạy

POST /order/create-addon-vps
{ "vps-id": 1000688561, "addon-cpu": 2, "addon-ram": 4, "addon-disk": 20 }

Khai ít nhất một trong ba, giá trị là số nguyên dương (addon-disk theo GB). Tiền tính theo phần thời gian còn lại của chu kỳ, trừ ngay vào số dư. VPS chuyển sang upgrading trong lúc áp cấu hình, xong thì về on. Điều kiện: VPS thuộc đại lý và đang on.

3.7. Giao tài khoản cho khách cuối

POST /storage/set-password
{ "storage-id": 12 }

Phản hồi trả về box-userid, box-url và box-password. Khách cuối đăng nhập thẳng vào box bằng cặp thông tin này, không cần tài khoản Portal.

4. Điều cần biết khi bán lại

• Cloudzone chỉ làm việc với đại lý: tài khoản đứng tên đại lý, mọi hỗ trợ và trách nhiệm với khách cuối thuộc về đại lý.
• Thư nhắc gia hạn gửi về email đại lý, không gửi cho khách cuối - đại lý chủ động nhắc khách của mình.
• Giao diện box mang thương hiệu Cloudzone. Cần phiên bản trắng nhãn cho thương hiệu riêng, liên hệ Cloudzone để dựng máy chủ riêng.