API Domain

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ý — cả giá gia hạn mỗi năm (billing.price_renew). — xem mục Tài khoản đại lý.

Đăng ký & theo dõi

Lệnh mua trừ tiền và đăng ký luôn trong lượt gọi — thường xong ngay trong câu trả lời, nhưng một lượt có thể mất tới khoảng một phút: đặt thời gian chờ HTTP từ 90 giây.

1. GET /domain/check?domain=… cho biết tên còn đăng ký được không (available). Muốn biết đúng số sẽ trừ thì gọi POST /domain/quote với {domain, period} (khoá Chỉ đọc gọi được): nó chạy đúng bộ kiểm của lệnh mua — tên, đuôi, số năm, người đứng tên, còn trống, giá năm đầu theo nhà đăng ký — rồi trả amount (số sẽ trừ) và enough (số dư khả dụng đủ chưa).
2. POST /domain/buy với {domain, period} (thêm registrant nếu đăng ký hộ người khác — mục Người đứng tên) và header Idempotency-Key: hệ thống kiểm lại hết rồi trừ ví và gửi đăng ký. Thường nhận HTTP 200 + provision_status: "ready": tên miền đã đăng ký xong. Vùng DNS tại đây được dựng ngay sau đó — sửa bản ghi được khi dns_status là ready (dns có trong allowed_actions); sớm hơn ⇒ 409 DNS_NOT_READY, thử lại sau ít phút.
3. Đuôi nào nhà đăng ký cần duyệt thêm ⇒ HTTP 202 + provisioning + charged: true: đơn đã tồn tại — hỏi GET /domain/info?order_code=… mỗi vài phút tới khi ready.

• Đã trừ tiền mà nhà đăng ký chối ⇒ HTTP 200 + provision_status: "failed" + charged: true (ví dụ dưới). Tiền không tự hoàn — bộ phận hỗ trợ được báo và xử lý (đăng ký lại, hoặc hoàn tiền nếu không làm tiếp được). Đừng gửi lại lệnh mua.
• Lệnh bị chối ở bước kiểm — tên đã có người đăng ký (409 DOMAIN_UNAVAILABLE), thiếu tiền, thiếu thông tin người đứng tên, đuôi không bán… — thì chưa trừ đồng nào. 409 PRICE_CHANGED: giá năm đầu theo nhà đăng ký vừa cao hơn lúc kiểm — báo giá lại rồi gửi lệnh mới với Idempotency-Key mới. Ngoại lệ: 400 FAILED ở lệnh mua có thể là giao dịch chưa rõ kết quả — đừng mua lại ngay: đối chiếu /domain/list hoặc liên hệ hỗ trợ trước.
• Hết thời gian chờ, mất 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 khi lượt đầu chưa xong). Gửi lại cùng tên mà không kèm khoá ⇒ 409 DOMAIN_UNAVAILABLE (đơn của lượt đầu đang giữ tên) — không bị trừ hai lần, nhưng hãy đối chiếu /domain/list để biết lượt đầu ra sao.
• Giá: năm đầu theo nhà đăng ký đúng lúc mua (có thể đang khuyến mãi — is_promo), các năm sau và mọi lần gia hạn theo bảng giá gia hạn. Nhiều đuôi gia hạn đắt hơn hẳn năm đầu (renewal_shock: 1) — xem price_renew trước khi mua. Bảng giá ở /domain/tlds cập nhật mỗi ngày; số chính xác cho một tên cụ thể là /domain/quote.
• Một lệnh mua đăng ký từ 1 tới 10 năm (max_period ở /domain/tlds; vượt ⇒ 400 + data.max_period). Tên miền premium (giá riêng do registry đặt) chưa bán qua đây (400 NOT_SUPPORTED).

{
    "status": "success",
    "msg": "Đã trừ tiền nhưng tên miền chưa đăng ký được — hỗ trợ sẽ xử lý",
    "data": {
        "order_code": "151026DOMAINHNFPVZRQWUOD",
        "domain": "ten-mien-cua-ban.com",
        "period": 1,
        "provision_status": "failed",
        "order_status": "register_failed",
        "charged": true,
        "price_buy": 418950,
        "need_info": false,
        "time_expire": "",
        "registrant_source": "request",
        "note": "Đã trừ tiền nhưng nhà đăng ký chưa nhận tên miền — bộ phận hỗ trợ sẽ xử lý (không cần gửi lại lệnh)."
    }
}

Người đứng tên

Mỗi tên miền có một người đứng tên (registrant) — chủ sở hữu ghi ở nhà đăng ký. Lệnh mua và lệnh chuyển về chọn người đứng tên theo một trong hai cách:

• Không gửi registrant ⇒ dùng hồ sơ Thông tin định danh của tài khoản (khai một lần ở trang tài khoản trên web; email người đứng tên là email tài khoản). Hồ sơ còn thiếu ⇒ 422 IDENTITY_REQUIRED với data.fields (các trường còn thiếu) và data.link (trang cần khai) — chưa trừ tiền; khai xong gửi lại được bằng đúng Idempotency-Key cũ.
• Gửi registrant ⇒ đăng ký hộ người khác (khách của bạn) với thông tin trong lệnh. Hồ sơ của tài khoản không bị đổi.

• Sai ⇒ 422 INVALID_REGISTRANT với data.fields = {trường: lý do} — chưa trừ tiền, sửa rồi gửi lại cùng Idempotency-Key được. Nhà đăng ký cũng có thể chối dữ liệu (email, số điện thoại, quốc gia) ⇒ cùng mã. /domain/quote kiểm registrant y như lệnh mua.
• ⚠ Xác minh email: sau khi đăng ký, nhà đăng ký có thể gửi thư xác minh tới email người đứng tên (với địa chỉ chưa từng xác minh). Không xác nhận trong 14 ngày ⇒ tên miền bị tạm khoá — ngừng phân giải — tới khi xác minh. Đăng ký hộ thì dùng email mà chính người ấy đọc được.
• Người đứng tên gắn với tên miền lúc đăng ký: sửa hồ sơ về sau chỉ áp cho tên miền đăng ký sau đó. Đổi người đứng tên của tên miền đang có không làm qua API — liên hệ hỗ trợ (đổi tên, tổ chức hoặc email người đứng tên có thể khoá việc chuyển nhà đăng ký 60 ngày theo quy định chung của tên miền quốc tế).
• registrant ở info / list: {source, name, company, country, email} — source là profile (hồ sơ tài khoản) hoặc request (khai trong lệnh), email đã che bớt. Chỉ tài khoản đã khai bộ người đứng tên ấy mới thấy chi tiết; tên miền nhận qua chuyển quyền hoặc mua trên Chợ ⇒ {"source": "other"}; tên miền mua trước 15/10/2026 ⇒ null.
• WHOIS privacy (whois_privacy ở lệnh mua): bật ⇒ thông tin người đứng tên được che trên tra cứu WHOIS công khai (với các đuôi hỗ trợ). Không gửi ⇒ theo whois_privacy_default của /domain/tlds (hiện: bật).

Chuyển tên miền về

1. Ở nhà đăng ký hiện tại: mở khoá chuyển (transfer lock) và lấy mã chuyển (auth code / EPP). Tên miền vừa đăng ký hoặc vừa chuyển nhà trong 60 ngày thì chưa chuyển được.
2. POST /domain/quote với {"type": "transfer", "domain": "…"} — giá chuyển về theo nhà đăng ký đúng lúc hỏi, đã trừ chiết khấu (gồm 1 năm hạn: chuyển xong, hạn tên miền được cộng thêm 1 năm). Báo giá không giữ giá: lệnh chuyển hỏi lại giá lúc nó tới và trừ theo giá ấy; giá tăng ngay giữa lúc lệnh kiểm và lúc trừ ⇒ 409 PRICE_CHANGED, chưa trừ tiền. Tên chưa đăng ký ở đâu ⇒ 409 DOMAIN_NOT_REGISTERED — đăng ký mới bằng /domain/buy.
3. POST /domain/transfer với {domain, auth_code} (thêm registrant như lệnh mua) và Idempotency-Key: trừ ví ngay rồi gửi lệnh chuyển ⇒ HTTP 202, provision_status: "provisioning", charged: true.
4. Nhà đăng ký cũ và registry duyệt — thường 5–7 ngày. Hỏi info thưa thôi (vài giờ một lần) tới khi ready.

• Nhà đăng ký chối ngay (mã chuyển sai, tên miền còn khoá, chưa đủ 60 ngày) ⇒ HTTP 200 + failed + charged: true — tiền không tự hoàn, bộ phận hỗ trợ xử lý; đừng gửi lại lệnh. Hãy kiểm mã chuyển và khoá chuyển trước khi gửi.
• ⚠ DNS sau khi chuyển: chuyển xong, tên miền được trỏ về DNS quản lý tại đây với một vùng DNS mới chưa có bản ghi nào. Khi đơn ready và dns_status: "ready", thêm bản ghi (/domain/dns/add) hoặc trỏ sang nameserver riêng (/domain/dns/mode) — không thì website và email dùng tên miền sẽ ngừng hoạt động tới lúc ấy.
• auth_code: 1–255 ký tự in được, không khoảng trắng. Mã chuyển không bao giờ được trả lại qua API.
• Trong lúc chuyển, đơn chỉ đổi được tự gia hạn và ghi chú; lượt chuyển về tính chung giới hạn lượt mua mỗi giờ với lệnh mua (mục Luật riêng).

Trạng thái đơn

provision_status gộp trạng thái đơn 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; order_status cho biết chi tiết. Mỗi ô bên trái ghi provision_status ở trên, order_status ở dưới:

• allowed_actions (ở 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 trang quản lý tên miền: renew · auto_renew · note · delete · dns (thêm / sửa / xoá bản ghi) · dns_mode. Tên nào vắng mặt thì lệnh ấy đang bị chối — vd renew vắng khi hôm nay tên miền đã được gia hạn hoặc hạn đã chạm trần 10 năm. Không tính nhịp thao tác — xem mục Nhịp thao tác.
• billing.time_expire (= time_expire_moon) là ngày bạn đã trả tới — mốc của mọi luật hết hạn. time_expire là hạn đang ghi ở nhà đăng ký: thường khớp ngay sau lệnh gia hạn; khi registrar_renewed: false nó đứng nguyên tới lúc hệ thống gia hạn lại ở nhà đăng ký (chậm nhất quanh ngày hết hạn ở đó) — đừng gửi lại lệnh gia hạn vì nó.
• charged luôn là true: mọi đơn tên miền được tạo cùng lượt trừ tiền. billing.price_renew = giá gia hạn 1 năm hiện hành, đã trừ chiết khấu (price_renew_est là số ước tính cũ lưu trên đơn, chưa trừ chiết khấu — giữ cho tích hợp cũ).
• list trả mọi tên miền của tài khoản — mua trên web lẫn qua API, nhận chuyển quyền — mới nhất trước; lọc bằng ?status= theo provision_status (nhận cả giá trị order_status).

Gia hạn & hết hạn

• POST /domain/renew với {order_code, period} trừ ví ngay: giá = giá gia hạn niêm yết hiện hành × số năm, trừ chiết khấu (làm tròn xuống trên tổng — có thể lệch vài đồng so với billing.price_renew × số năm; nhà đăng ký có thể đổi giá theo năm). Số chính xác là amount của báo giá với đúng period: quote với {"type": "renew", "order_code": "…", "period": …}. Hạn mới = billing.time_expire cộng số năm — kể cả khi gia hạn trễ (những ngày tên miền đã ngừng không được bù, như mọi nhà đăng ký).
• Tổng hạn tối đa 10 năm tính từ hôm nay: vượt ⇒ 400 BAD_REQUEST + data.max_years (số năm còn gia hạn được — báo giá cũng trả max_years). Mỗi tên miền một lượt gia hạn mỗi ngày, tính cả gia hạn trên web và tự gia hạn: lượt thứ hai ⇒ 429 COOLDOWN, Retry-After tới 0 giờ.
• registrar_renewed: false trong câu trả lời ⇒ tiền đã thu và hạn đã cộng, còn phần gia hạn ở nhà đăng ký sẽ được hệ thống tự làm lại — đừng gửi lại lệnh.
• Tự gia hạn (billing.renew_auto; đổi bằng POST /domain/auto-renew với enabled là boolean — lệnh ĐẶT giá trị, gửi lại cùng giá trị không lật ngược): khi còn 7 ngày hoặc ít hơn tới billing.time_expire — kể cả khi đã quá hạn — hệ thống tự trừ ví gia hạn 1 năm, cùng giá với gia hạn tay. Lượt tự gia hạn chạy khi số dư đủ đúng số sẽ trừ — giá gia hạn 1 năm hiện hành đã trừ chiết khấu (billing.price_renew); thiếu ⇒ bỏ qua, thử lại ở lượt kiểm sau (mỗi giờ).
• Quá hạn: qua billing.time_expire mà chưa gia hạn, đơn chuyển pending_expired (provision_status: "expired") — đã quá hạn bạn trả tại đây; khi hạn ở nhà đăng ký (time_expire) cũng đã qua, nhà đăng ký đã huỷ tên miền — website / email ngừng. Vẫn gia hạn được tối đa 30 ngày kể từ ngày hết hạn (tuỳ đuôi — vài đuôi không cho gia hạn sau ngày hết hạn) đúng giá gia hạn thường: hệ thống tự chuộc lại ở nhà đăng ký, đơn về active ngay khi lệnh thành công, tên miền có thể mất tới 1–2 ngày để chạy lại ở mọi nơi (registrar_renewed: false = nhà đang xử lý, hệ thống tự làm tiếp — đừng gửi lại lệnh). Trước khi trừ tiền, hệ thống hỏi nhà đăng ký: chưa hỏi được ⇒ 503 UNAVAILABLE · nhà đang chuộc ⇒ 429 IN_PROGRESS — chưa trừ tiền, gửi lại sau (kể cả cùng Idempotency-Key). Quá hạn chót ⇒ 409 ORDER_EXPIRED: không gia hạn / không chuộc được nữa, đơn chuyển expired, vùng DNS tại đây bị gỡ; lúc tên miền được thả cho người khác đăng ký do registry quyết. Đừng để tới hạn: bật tự gia hạn hoặc gia hạn sớm.
• Dịch vụ tên miền tạm dừng bán (bảo trì) hay đuôi ngừng bán đều không chặn gia hạn tên miền đang có.

DNS

• dns_mode: cloudmoon_managed — DNS quản lý tại đây (mặc định khi mua; nameserver ns1.systemcloudvps.com · ns2.systemcloudvps.com) · external_ns — tên miền trỏ sang nameserver riêng của bạn, bản ghi quản lý ở nơi ấy. Đổi bằng POST /domain/dns/mode: external_ns kèm ns (2–13 hostname); về cloudmoon_managed thì tên miền trỏ lại DNS tại đây với các bản ghi đã lưu (vùng DNS chưa có thì được dựng trước khi trỏ nameserver; dựng hỏng ⇒ 503 UNAVAILABLE, chưa đổi gì). Nameserver mới cần vài giờ để có hiệu lực trên toàn mạng.
• Bản ghi đọc ở GET /domain/dns/list — bản lưu tại đây là nguồn đúng. name rỗng hoặc @ là gốc tên miền; tên con nhiều cấp và wildcard *. được.
• Loại bản ghi: A · AAAA · CNAME (không đặt ở gốc) · MX (priority 0–65535) · TXT (tối đa 2000 ký tự) · NS (chỉ cho tên con — muốn dùng nameserver riêng cho cả tên miền thì đổi dns_mode) · SRV (tên dạng _dịch-vụ._giao-thức, vd _sip._tcp; priority 0–65535; value = trọng-số cổng máy-đích, vd 5 5060 sip.example.com; 0 0 . = tên miền không có dịch vụ này) · CAA (value = cờ thẻ giá-trị, vd 0 issue letsencrypt.org — thẻ issue · issuewild · iodef, giá trị không chứa dấu nháy kép hay gạch ngược; hệ thống lưu giá trị trong nháy kép: 0 issue "letsencrypt.org"). TTL do hệ thống tự đặt (ngắn khi bạn vừa sửa, dài dần khi bản ghi ổn định). Tối đa 200 bản ghi mỗi tên miền (vượt ⇒ 400 + data.max_records).
• sync của mỗi bản ghi: synced — đã có hiệu lực · pending — đã lưu, máy chủ DNS tạm lỗi nên hệ thống tự đẩy lại trong vài phút · error — đẩy chưa được, hệ thống đang thử lại (kéo dài thì liên hệ hỗ trợ).
• Máy chủ DNS chối một bản ghi (vd CNAME trùng tên với bản ghi khác) ⇒ 400: bản ghi mới không được lưu, bản ghi đang sửa giữ giá trị cũ. Xoá mà máy chủ DNS chưa xoá được ⇒ 503 UNAVAILABLE, bản ghi giữ nguyên — gửi lại sau ít phút.
• Sửa DNS cần tên miền đang hoạt động và dùng DNS tại đây (409 DNS_EXTERNAL khi đang dùng nameserver riêng · 409 DNS_NOT_READY khi vùng DNS chưa dựng xong). Tên miền quá hạn hoặc bị tạm ngưng vẫn xem được bản ghi, không sửa được.

Luật riêng

• Xoá khỏi danh sách (POST /domain/delete, confirm = đúng order_code): không hoàn tiền, không khôi phục được. Tên miền vẫn đăng ký ở nhà đăng ký tới hết hạn rồi tự hết (tự gia hạn bị tắt), và vùng DNS tại đây bị gỡ — tên miền đang dùng DNS tại đây sẽ ngừng phân giải. Bị chối khi tên miền đang đăng ký / chuyển về, gặp sự cố chờ hỗ trợ, bị tạm ngưng, hoặc đang rao bán trên Chợ.
• Dịch vụ tên miền tạm dừng bán: tlds · check · price · báo giá mua / chuyển về · lệnh mua · lệnh chuyển về nhận 503 SERVICE_DISABLED (GET /services/status báo domain: false); gia hạn, báo giá gia hạn, info, list, DNS, tự gia hạn, ghi chú, xoá vẫn chạy bình thường. Một đuôi ngừng bán thì không còn trong /domain/tlds (kiểm tên, báo giá, mua, chuyển về nhận 404), còn tên miền đã có của đuôi ấy vẫn gia hạn và dùng DNS bình thường.
• Giới hạn lệnh mua qua API: tối đa 10 lượt mua + chuyển về tên miền mỗi giờ (gộp chung, đếm cả lượt trên web — 429 RATE_LIMITED), tính riêng với các sản phẩm khác. 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.
• Không làm qua API: lấy mã chuyển đi / chuyển tên miền sang nhà đăng ký khác · đổi người đứng tên của tên miền đang có · chuyển quyền sang tài khoản khác · rao bán trên Chợ · xem nhật ký đơn — dùng trang quản lý tên miền trên web.
• Chạy thử (X-Sandbox: 1): kiểm tên, giá và báo giá không hỏi nhà đăng ký — check trả status: "simulated" (chỉ biết tên có đang được một đơn tại đây giữ không), giá năm đầu lấy theo bảng giá (realtime: false). Lệnh mua trả mã SANDBOX… (26 ký tự): hỏi info bằng mã ấy (vẫn kèm X-Sandbox: 1) ⇒ tên miền mẫu sandbox-….<đuôi> ở ready ngay, hạn = hôm mua + số năm; kịch bản PROVISION_FAILED ⇒ lệnh mua 202, info ở provisioning 10 giây đầu rồi failed. Lệnh chuyển về thử ⇒ 202, provisioning 10 giây đầu rồi ready (failed với PROVISION_FAILED). Mã chỉ chở đuôi, số năm và cờ — không chở tên miền. Gia hạn, tự gia hạn, ghi chú, xoá, DNS trên đơn mẫu đi đủ các bước kiểm rồi trả mô phỏng; dns/list trả hai bản ghi mẫu. Không lưu gì: mã không có trong list, lệnh mô phỏng không làm info về sau đổi theo.

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

Các lệnh trên cùng một tên miền 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.