API Hosting

Tổng quan

Địa chỉ gốc của các endpoint trên trang này:

https://cloudmoon.net/api/v1

Giá đại lý: Danh mục, báo giá và lệnh mua trả về (và trừ ví) giá đã trừ chiết khấu theo cấp đại lý; gia hạn theo GIÁ GHI TRÊN ĐƠN (giá lúc mua — đã trừ chiết khấu khi ấy — cập nhật khi nâng gói hoặc đổi chu kỳ) — không theo giá niêm yết hiện hành. — xem mục Tài khoản đại lý.

Mua & đăng nhập panel

Hosting được tạo ngay trong lệnh mua — không xếp hàng như Cloud VPS, không chờ bàn giao như Dedicated Server. Lệnh mua thường mất 10–20 giây; hãy đặt thời gian chờ HTTP của bạn từ 90 giây trở lên.

1. POST /hosting/buy với {product_id, billing_cycle, domain} kiểm hết (gói còn hàng, chu kỳ, tên miền, số dư khả dụng, giới hạn lượt mua) rồi trừ ví và tạo tài khoản panel CyberPanel kèm website. Thành công ⇒ HTTP 200, provision_status: "ready", charged: true, price_buy (số đã trừ) và panel: url · server_ip · username · password.
2. Trỏ bản ghi A của tên miền về panel.server_ip.
3. Đăng nhập panel ở panel.url từ mốc panel.ready_at (khoảng 90 giây sau khi tạo).

• Mật khẩu panel có ngay trong câu trả lời của lệnh mua; về sau đọc lại bằng GET /hosting/info (trường panel.password) hoặc GET /hosting/credentials — cả hai cần khoá Toàn quyền và hosting đang hoạt động (tạm ngưng, bị khoá hay đang chuyển máy chủ thì ẩn). Muốn đổi ⇒ POST /hosting/change-password.
• website_verified: true = website đã có trên máy chủ lúc trả lời; false / null = chưa xác nhận kịp (website đôi khi hiện muộn vài phút, bộ phận kỹ thuật đã được báo để kiểm) — hosting vẫn ready, tài khoản panel dùng được.
• Sự cố sau khi đã trừ tiền (hiếm): HTTP 202, provision_status: "provisioning", charged: true, có order_code, panel: null. Đơn đã tồn tại và đã trả tiền — đừng mua lại. Bộ phận kỹ thuật hoàn tất ⇒ info chuyển ready; không hoàn tất được ⇒ đơn bị huỷ và hoàn đủ số đã trừ: provision_status: "failed" + refunded_amount. Hỏi info thưa thôi — mỗi 5–10 phút là đủ.
• Lệnh mua bị chối (thiếu tiền, hết hàng, tên miền đã có hosting khác dùng, giá vừa tăng…) thì chưa trừ đồng nào. Riêng 409 PRICE_CHANGED: báo giá lại rồi gửi lệnh mới với Idempotency-Key mới.
• Mạng đứt khi đang chờ câu trả lời ⇒ gửi lại với đúng Idempotency-Key cũ: nhận lại kết quả lần đầu (hoặc 409 IDEMPOTENCY_PENDING nếu lượt đầu chưa xong) — không mua hai lần. Không kèm khoá thì lượt gửi lại bị một bước kiểm chối — thường 409 DOMAIN_IN_USE (tên miền đã thuộc hosting vừa tạo), cũng có thể mã khác như 409 OUT_OF_STOCK (lượt đầu vừa lấy chỗ cuối) — nên mất câu trả lời mà không có khoá thì đối chiếu /hosting/list trước khi mua lại. Luôn gửi Idempotency-Key.

{
    "status": "success",
    "msg": "Đã trừ tiền — hosting đang được hoàn tất khởi tạo",
    "data": {
        "order_code": "121026HOSTA1B2C3D4E5F6",
        "domain": "khachhang.com",
        "provision_status": "provisioning",
        "charged": true,
        "product_id": 1,
        "billing_cycle": "onemonth",
        "price_buy": 50000,
        "time_expire": "2026-11-12",
        "panel": null,
        "website_verified": null,
        "note": "Đơn đã trừ tiền, bộ phận kỹ thuật đang hoàn tất khởi tạo — hỏi GET /hosting/info?order_code= tới khi provision_status = ready"
    }
}

Trạng thái đơn

Hosting có hai lớp trạng thái: order_status (thời hạn) và account_status (tài khoản trên máy chủ). provision_status gộp hai lớp thành một chữ cho bộ tích hợp — cùng tên với các sản phẩm khác. Mỗi ô bên trái ghi provision_status ở trên cùng, rồi tới order_status và account_status:

• Chốt trạng thái ở bảng trên chỉ áp cho lệnh thao tác (gia hạn, nâng gói, đổi chu kỳ, đổi mật khẩu, xoá…), báo giá trên đơn và credentials; info · list · usage đọc được đơn ở mọi trạng thái — kể cả đơn đã huỷ (để đối soát refunded_amount) hay đã xoá.
• features — khả năng của API với hosting: renew · auto_renew · change_password · upgrade · change_cycle · delete là true; migrate (chuyển máy chủ) · transfer (chuyển quyền) là false — hai việc này chỉ làm trên trang quản lý hosting.
• allowed_actions (có ở cả list lẫn info) — việc làm được ngay lúc này, theo cùng luật với các nút trên web: tên nào vắng mặt thì lệnh ấy đang bị chối (tạm ngưng, đang hoàn tất khởi tạo, máy chủ bảo trì, đang rao bán trên chợ…). Không tính nhịp thao tác — xem mục Nhịp thao tác.
• marketplace: true — hosting đang được rao bán trên Chợ: xoá, nâng gói, đổi chu kỳ nhận 409 LISTED_ON_MARKETPLACE tới khi huỷ tin rao trên web.

Tên miền & danh mục

• Mỗi hosting gắn một tên miền (domain) — website chính của tài khoản panel. Gửi dạng ten.com hoặc sub.ten.vn: hệ thống bỏ khoảng trắng hai đầu và đổi sang chữ thường; không kèm http://, đường dẫn hay cổng; tối đa 253 ký tự, mỗi nhãn 1–63 ký tự gồm chữ, số, gạch nối (không mở đầu hay kết thúc bằng gạch nối), đuôi 2–63 chữ cái. Sai ⇒ 400 BAD_REQUEST.
• Một tên miền chỉ thuộc một hosting còn hiệu lực (đang hoạt động hoặc đang tạm ngưng) trên toàn hệ thống, kể cả hosting khác của chính bạn ⇒ 409 DOMAIN_IN_USE. Hosting đã xoá hoặc đã dọn thì tên miền dùng lại được. Báo giá mua (/hosting/quote) kiểm tên miền y như lệnh mua.
• Mua hosting không kèm tên miền: tên miền là của bạn, mua ở đâu cũng được — sau khi mua hosting, tự trỏ bản ghi A về panel.server_ip.
• name — tên gợi nhớ, tối đa 150 ký tự; bỏ trống thì lấy tên miền (cắt còn 150 ký tự).
• GET /hosting/products bày các gói đang bán; gói tạm hết hàng vẫn có mặt với in_stock: false (lệnh mua nhận 409 OUT_OF_STOCK) — thêm ?in_stock=1 để chỉ lấy gói còn hàng, lọc thêm ?region= · ?group_code=. cycles là mã các chu kỳ mua được (ngắn → dài); pricing là giá từng chu kỳ: amount (giá bạn trả — đã trừ chiết khấu đại lý) · amount_original (giá niêm yết) · months.
• quota: disk_mb · bandwidth_mb · email · database · websites — 0 là không giới hạn. Mỗi gói thuộc một nhóm (group_code) gắn với một khu vực (region_code · city); nâng gói chỉ trong cùng nhóm.

Thời hạn & gia hạn

• Thời hạn tính từ lúc mua — time_expire (ngày) có ngay trong câu trả lời của lệnh mua, về sau ở billing.time_expire.
• POST /hosting/renew cộng một chu kỳ vào hạn hiện tại (không tính lại từ ngày gửi lệnh) và trừ ví ngay. Giá = giá ghi trên đơn (billing.price_renew, bằng billing.price_buy): giá lúc mua — đã gồm chiết khấu đại lý lúc ấy — và được cập nhật khi nâng gói hoặc đổi chu kỳ; không theo giá niêm yết hiện hành, không áp chiết khấu thêm lần nữa. Báo giá trước: POST /hosting/quote với {"order_code": "…", "type": "renew"}; info.renew_until là hạn mới nếu gia hạn một kỳ.
• Đơn gia hạn theo chu kỳ hiện tại của đơn (billing.billing_cycle), kể cả khi chu kỳ ấy không còn bán cho đơn mới. Muốn kỳ dài hơn ⇒ POST /hosting/change-cycle (mục dưới).
• Tự gia hạn (billing.renew_auto: "on", đổi bằng POST /hosting/auto-renew với enabled là boolean — lệnh ĐẶT giá trị, gửi lại không lật ngược): trong 7 ngày trước hạn, hệ thống tự gia hạn một chu kỳ khi ví đủ tiền — cùng giá với gia hạn tay. Vẫn chạy trong thời gian tạm ngưng: nạp đủ tiền là hosting tự được gia hạn, rồi được mở lại như gia hạn tay.
• Qua ngày hết hạn mà chưa gia hạn, đơn chuyển pending_expired (account_status: suspended). Gói hosting đã bị tạm ngưng — website và email trên gói này ngừng hoạt động. Dữ liệu vẫn còn nguyên. Gia hạn trong 10 ngày kể từ ngày hết hạn ⇒ hạn được cộng và hệ thống mở lại hosting; nếu việc mở lại trên máy chủ chưa xong (máy chủ bảo trì hay trục trặc), tiền và hạn vẫn đã ghi nhận và bộ phận kỹ thuật xử lý tiếp — gia hạn thành công không có nghĩa website chắc chắn chạy lại ngay.
• Sau 10 ngày, tài khoản hosting bị xoá cùng toàn bộ mã nguồn và cơ sở dữ liệu. Đơn chuyển provision_status: "deleted" (account_status: archived) — không gia hạn hay thao tác được nữa (409 ORDER_DELETED). Gia hạn trước hạn, hoặc bật tự gia hạn, là chắc nhất.

Nâng gói & đổi chu kỳ

• POST /hosting/upgrade với {order_code, product_id} — lên gói lớn hơn, giữ chu kỳ. Gói mới phải cùng nhóm (group_code), dung lượng không nhỏ hơn và còn hàng; khác nhóm hay nhỏ hơn ⇒ 400 NOT_SUPPORTED. Máy chủ hiện tại không đủ chỗ cho gói mới ⇒ 409 CAPACITY_UNAVAILABLE — chuyển máy chủ chỉ làm được trên trang quản lý hosting.
• Phí nâng gói = max(0, giá kỳ của gói mới − giá đơn đang trả) × số kỳ còn lại (số kỳ tính từ hôm nay tới hạn, tối thiểu 1). Trừ ví ngay; hạn giữ nguyên; giá kỳ của gói mới (đã trừ chiết khấu đại lý lúc nâng) thành giá gia hạn của đơn.
• applied_on_server: false — đã thu tiền và đơn đã ở gói mới, nhưng máy chủ chưa áp xong hạn mức mới (bộ phận kỹ thuật đã được báo). Đừng gửi lại lệnh nâng gói.
• POST /hosting/change-cycle với {order_code, billing_cycle} — sang chu kỳ dài hơn đang bán, giữ gói: không thu tiền, hạn giữ nguyên; giá kỳ mới (đã trừ chiết khấu lúc đổi) thành giá gia hạn ngay — lần gia hạn kế, tay hay tự động, thu giá ấy và cộng trọn chu kỳ mới. Chu kỳ ngắn hơn, trùng hoặc không còn bán ⇒ 400 BAD_REQUEST. Lệnh này không nhận Idempotency-Key (không thu tiền).
• Mỗi lệnh chỉ đổi một thứ — gói hoặc chu kỳ. Báo giá trước: quote với {order_code, type: "upgrade", product_id} hoặc {order_code, type: "change_cycle", billing_cycle} ⇒ amount (số trừ ngay) · cycles_needed · days_left · price_renew (giá gia hạn sau khi đổi) · enough.

Dung lượng & băng thông

• Số đang dùng là số máy chủ gửi về mỗi giờ: usage.disk_mb · usage.bandwidth_mb và lúc nhận số usage.synced_at có ở list / info.
• GET /hosting/usage trả thêm hạn mức của gói (quota_disk_mb · quota_bandwidth_mb, 0 là không giới hạn) và stale: true khi đã quá 2 giờ chưa có số mới (hoặc chưa có số nào).
• Không có lệnh làm mới tức thì — hỏi thưa thôi, mỗi giờ một lần là đủ.

Luật riêng

• Đổi mật khẩu panel (POST /hosting/change-password): new_password 8–64 ký tự, chỉ gồm chữ, số và !@#$%^&*._-; bỏ trống ⇒ hệ thống sinh 16 ký tự. Mật khẩu mới có trong câu trả lời. Chỉ hosting đang hoạt động.
• Xoá (POST /hosting/delete, confirm = đúng order_code): xoá website và tài khoản panel — không hoàn tiền, không khôi phục. Hosting tạm ngưng vì quá hạn vẫn xoá được; đang hoàn tất khởi tạo, đang chuyển máy chủ, bị khoá hay đang rao bán trên chợ thì bị chối.
• Máy chủ của hosting đang bảo trì: đổi mật khẩu, nâng gói, xoá ⇒ 503 MAINTENANCE (thử lại sau); gia hạn, tự gia hạn, đổi chu kỳ vẫn chạy. Khác với dịch vụ hosting tạm dừng bán: danh mục, báo giá mua và lệnh mua nhận 503 SERVICE_DISABLED, hosting đang có vẫn thao tác bình thường (GET /services/status báo hosting: false).
• Không làm qua API: chuyển máy chủ · chuyển quyền · rao bán trên chợ · đăng nhập panel một chạm · đổi tên gợi nhớ / ghi chú — dùng trang quản lý hosting trên web.
• Giới hạn lệnh mua qua API: tối đa 10 lượt mua hosting mỗi giờ (429 RATE_LIMITED) — đếm cả hosting mua trên web, tính riêng với các sản phẩm khác. Không có giới hạn số đơn chờ (lệnh mua xong ngay). Số dư xét lệnh mua là số dư khả dụng — đã trừ tiền các lệnh mua Cloud VPS còn chờ tạo máy.
• Chạy thử (X-Sandbox: 1): lệnh mua trả ready ngay (HTTP 200) kèm panel mẫu (máy chủ panel.sandbox.example, IP thuộc dải dành cho tài liệu 203.0.113.x); mã SANDBOX… dùng được ở mọi lệnh hosting khi vẫn kèm X-Sandbox: 1. Lệnh mua chạy thử trả lại đúng tên miền bạn gửi, nhưng hỏi info bằng mã ấy thì hosting mẫu mang tên miền sandbox-….example (mã chỉ chở gói, chu kỳ và cờ — tên miền không, còn giá và hạn mức dựng lại từ gói hiện hành mỗi lần hỏi) — và nó không lưu gì: đổi mật khẩu, đổi chu kỳ hay xoá mô phỏng không làm info về sau đổi theo, mã không có trong list. Kịch bản PROVISION_FAILED ⇒ HTTP 202 provisioning + charged: true, và hosting mẫu đứng yên ở provisioning (chỉ còn bật/tắt tự gia hạn) — để thử nhánh chờ kỹ thuật; nhánh huỷ + hoàn không mô phỏng được.

Nhịp thao tác trên cùng một hosting

Các lệnh trên cùng một hosting phải cách lệnh trước một khoảng tối thiểu — nhịp này chỉ áp cho lệnh gửi qua API, để chặn lệnh gửi lặp. Các việc trong cùng một dòng dùng chung một đồng hồ. Gửi sớm hơn ⇒ 429 COOLDOWN (header Retry-After cho biết còn bao nhiêu giây); gửi trong lúc máy đang xử lý lệnh khác ⇒ 429 IN_PROGRESS.

Mã lỗi riêng

Ngoài các mã lỗi chung của mọi endpoint, trang này còn có các mã dưới đây. Hãy rẽ nhánh theo code.