API SSL/TLS

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 = giá cao hơn giữa giá đã trả và giá niêm yết hiện hành của kỳ. — xem mục Tài khoản đại lý.

Mua & nhận chứng chỉ

Lệnh mua trừ tiền ngay và tạo đơn trong cùng lượt gọi, còn chứng chỉ được cấp sau — khi Sectigo xác minh xong quyền của bạn với tên miền. Lệnh mua trả lời trong vài giây; bạn theo dõi đơn bằng /ssl/info.

1. POST /ssl/buy với {product_code, period, common_name} (thêm csr nếu muốn tự giữ khoá riêng — mục CSR & khoá riêng) kiểm hết — sản phẩm, thời hạn, tên miền, CSR, còn hàng, số dư khả dụng, giới hạn lượt mua — rồi trừ ví và trả HTTP 202: provision_status: "provisioning", charged: true, order_code, price_buy (số đã trừ), key_source và khối dcv (cách xác minh tên miền).
2. Hỏi GET /ssl/info?order_code=… mỗi 1–2 phút. Tên miền tự xác minh (dcv.mode: "auto") thì không phải làm gì; tên miền ngoài ("manual") thì thêm bản ghi CNAME ở dcv.record ngay khi nó xuất hiện (thường dưới một phút sau lệnh mua) — mục Xác minh tên miền.
3. Xác minh xong, chứng chỉ thường được cấp sau 10–60 phút: provision_status: "ready", certificate.available: true. Tải bằng GET /ssl/download (khoá Toàn quyền): certificate · private_key · ca_bundle · fullchain (chứng chỉ nối chuỗi CA — thứ phần lớn máy chủ web cần).

• Không cấp được (Sectigo từ chối, hoặc đơn xác minh quá hạn ở CA) ⇒ provision_status: "failed". Tiền không tự hoàn — bộ phận hỗ trợ được báo và xử lý; liên hệ kèm order_code nếu cần.
• Lệnh mua bị chối ở bước kiểm (thiếu tiền, hết hàng, CSR không dùng được, 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. Ngoại lệ: 400 FAILED ở lệnh mua có thể là giao dịch chưa rõ kết quả (đã trừ tiền mà chưa kịp xác nhận) — đừng mua lại ngay: đối chiếu /ssl/list hoặc liên hệ hỗ trợ trước.
• Luôn gửi Idempotency-Key: một tên miền mua được nhiều chứng chỉ (đơn trùng tên miền là hợp lệ), nên lệnh mua gửi lại mà không kèm khoá là một đơn mới — trừ tiền lần hai. Gửi lại với đúng khoá cũ ⇒ nhận lại kết quả lần đầu (hoặc 409 IDEMPOTENCY_PENDING khi lượt đầu chưa xong). Mất câu trả lời mà không có khoá ⇒ đối chiếu /ssl/list trước khi mua lại.
• Chủ tài khoản luôn nhận email khi có tệp chứng chỉ mới (cấp lần đầu, cấp lại định kỳ, gia hạn xong kèm chứng chỉ mới) hoặc khi cần xác minh lại tên miền — thêm tin Telegram nếu tài khoản đã liên kết Telegram và bật kênh ấy cho từng chứng chỉ ở trang quản lý SSL.

{
    "status": "success",
    "msg": "Đã nhận lệnh mua — chứng chỉ đang được cấp",
    "data": {
        "order_code": "131026SSLA1B2C3D4E5F6",
        "common_name": "khachhang.com",
        "type": "single",
        "product_id": 1,
        "product_code": "positive_ssl",
        "period": 1,
        "provision_status": "provisioning",
        "charged": true,
        "price_buy": 360000,
        "key_source": "server",
        "dcv": {
            "mode": "auto",
            "status": "pending",
            "record": null,
            "action_required": false
        },
        "note": "Tên miền dùng DNS của CloudMoon trong tài khoản này — hệ thống tự xác minh. Hỏi GET /ssl/info?order_code= tới khi provision_status = ready (thường 10–60 phút)."
    }
}

Xác minh tên miền

Sectigo chỉ cấp chứng chỉ khi xác minh được bạn kiểm soát tên miền — bằng một bản ghi CNAME. Khối dcv ở info · list · sync cho biết phải làm gì:

• dcv.mode: auto — tên miền dùng DNS tại đây và nằm trong chính tài khoản đang gọi: hệ thống tự thêm bản ghi, tự xác minh, kể cả ở mỗi lượt cấp lại. manual — mọi trường hợp khác (DNS ở nơi khác, hoặc tên miền thuộc tài khoản khác): bạn tự thêm bản ghi. Báo giá mua cho biết trước (dcv_mode).
• dcv.record: {type: "CNAME", name, value} — có sau khi đơn được tạo ở CA (thường dưới một phút sau lệnh mua); null khi chưa có.
• dcv.status: pending (chưa có bản ghi) · auto_submitted (hệ thống đã tự thêm) · manual (chờ bạn thêm) · validated (đã xác minh) · revalidation_required (lượt cấp lại định kỳ cần bản ghi mới — mục Hạn chứng chỉ & cấp lại).
• dcv.action_required: true — bạn cần thêm hoặc sửa bản ghi ngay.
• Thêm đúng name và value (kiểu CNAME) vào DNS của tên miền. Nhiều trang quản lý DNS chỉ cần phần đứng trước tên miền gốc của name. ⚠ name có thể nằm ở tên miền gốc dù chứng chỉ cho tên miền con (đặt shop.khachhang.com, bản ghi là _….khachhang.com) — cứ đặt đúng tên trả về.
• Thêm xong gọi POST /ssl/sync để kiểm ngay (nhịp 20 giây mỗi đơn); hệ thống cũng tự kiểm định kỳ vài phút một lần nên không gọi cũng được. Bản ghi mới có thể mất vài phút mới tới được mọi máy chủ DNS.
• Giữ bản ghi sau khi chứng chỉ được cấp: nếu mã không đổi, lượt cấp lại định kỳ xác minh lại bằng chính bản ghi ấy; khi CA đưa mã mới, dcv.status chuyển revalidation_required kèm bản ghi mới.
• Tên miền tự xác minh mà về sau chuyển sang tài khoản khác (chuyển quyền, bán trên chợ) hoặc chuyển DNS ra ngoài ⇒ dcv.mode thành manual: hệ thống không ghi vào DNS không còn thuộc bạn, và tự gia hạn (nếu đang bật) bị tắt khi tới lượt tự gia hạn — hãy gia hạn tay.

CSR & khoá riêng

• Không gửi csr ⇒ hệ thống tự sinh cặp khoá và CSR, cất khoá riêng đã mã hoá: key_source: "server", khoá riêng tải về ở /ssl/download (private_key).
• Gửi csr (PEM, bắt đầu bằng -----BEGIN CERTIFICATE REQUEST-----) ⇒ khoá riêng chỉ nằm ở máy bạn: key_source: "customer", /ssl/download trả private_key: null. Hệ thống không giữ bản sao — hãy cất kỹ khoá riêng.
• CSR phải có: Common Name đúng tên đặt mua (wildcard: *.tên-miền; tên miền có dấu thì ở dạng punycode xn--…) · khoá RSA từ 2048 bit, hoặc ECDSA P-256 / P-384 · chữ ký hợp lệ · tối đa 10 KB. Sai ⇒ 400 CSR_INVALID, chưa trừ tiền. Báo giá mua (/ssl/quote) kiểm CSR y như lệnh mua.
• Các lượt cấp lại định kỳ và gia hạn dùng lại CSR của đơn ⇒ chứng chỉ mới vẫn khớp khoá riêng đang dùng. Đổi CSR không làm qua API.

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:

• renewing: true — đơn đang gia hạn (ở pending_dcv hay processing): chứng chỉ đang lưu (nếu có) vẫn tải được tới khi chứng chỉ kỳ mới thay — xem hạn của nó ở cert_expire. Hai trạng thái ấy mà renewing: false là đơn mua mớ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ý SSL: renew · auto_renew · change_cycle · download · sync · cancel. Tên nào vắng mặt thì lệnh ấy đang bị chối (chưa tới cửa sổ gia hạn, chưa có chứng chỉ, đang gia hạn…); auto_renew có mặt nghĩa là đổi được cài đặt — riêng BẬT còn cần dcv.mode: "auto". Không tính nhịp thao tác — xem mục Nhịp thao tác.
• list mặc định bỏ đơn đã huỷ; lọc bằng ?status= theo provision_status. Đơn đã huỷ hoặc hết hạn hẳn được xoá khỏi hệ thống sau khoảng 30 ngày — sau đó info trả 404.

Hạn chứng chỉ & cấp lại

• Thời hạn bạn mua (theo năm) là hạn gói — billing.time_expire. Mỗi chứng chỉ Sectigo chỉ hiệu lực tối đa khoảng 199 ngày (certificate.cert_expire), nên trong suốt thời hạn gói hệ thống tự cấp lại chứng chỉ mới, không thu thêm tiền. Chứng chỉ cuối cùng hết hạn cùng lúc với gói.
• certificate.reissue_at — ngày cấp lại dự kiến (do CA đặt, khoảng 15 ngày trước cert_expire). Cấp lại xong, certificate.cert_expire lùi ra (và reissue_at đổi) kèm email báo — nhận ra chứng chỉ mới bằng cert_expire (issued_at không đổi ở lượt cấp lại định kỳ — đừng dựa vào nó). Tải lại bằng /ssl/download rồi cài lên máy chủ trước cert_expire cũ. Gợi ý: quanh reissue_at, hỏi info mỗi ngày một lần.
• Tên miền tự xác minh: lượt cấp lại tự xác minh lại. Tên miền ngoài: nếu CA đưa mã xác minh mới ⇒ dcv.status: "revalidation_required", dcv.action_required: true và dcv.record mới (kèm email) — thêm bản ghi mới rồi gọi /ssl/sync. Trong lúc chờ, chứng chỉ hiện tại vẫn dùng được tới cert_expire.

Gia hạn & đổi chu kỳ

• Cửa sổ gia hạn: chỉ trong 30 ngày cuối trước hạn gói — từ ngày billing.renew_open_from. Sớm hơn ⇒ 409 RENEW_NOT_OPEN; tới cửa sổ thì renew có mặt trong allowed_actions.
• POST /ssl/renew trừ ví ngay. Giá = giá cao hơn giữa giá bạn đã trả và giá niêm yết hiện hành của kỳ (billing.price_renew; báo giá trước bằng quote với {"order_code": "…", "type": "renew"}). Gói còn hạn ⇒ renew_mode: "renew": hạn mới = hạn cũ + một kỳ, giữ nguyên phần ngày còn lại. Gói đã quá hạn ⇒ "new_order": cấp chứng chỉ mới, hạn tính từ ngày cấp.
• Sau lệnh gia hạn, đơn ở provisioning + renewing: true tới khi CA xác nhận kỳ mới. Gia hạn xong = renewing: false + billing.time_expire mới — CA có thể giữ nguyên tệp chứng chỉ tới lượt cấp lại định kỳ kế (khi ấy không có thư báo). Trong lúc chờ, chứng chỉ đang lưu vẫn tải được — xem certificate.cert_expire, vì nó có thể hết hiệu lực trước khi kỳ mới được cấp. Gia hạn khi gói đã quá hạn thì chứng chỉ cũ (đã hết hiệu lực) được gỡ khỏi đơn — download nhận 409 CERTIFICATE_NOT_READY tới khi chứng chỉ mới được cấp. Trong lúc ấy gia hạn, đổi chu kỳ, huỷ nhận 409 RENEWING. Mỗi đơn tối đa một lượt gia hạn mỗi ngày (429 COOLDOWN).
• Hiếm khi CA chưa xác nhận kịp kết quả ⇒ HTTP 202: tiền đã trừ, bộ phận hỗ trợ đối soát — đừng gửi lại lệnh gia hạn.
• Tự gia hạn (billing.renew_auto, đổi bằng POST /ssl/auto-renew với enabled là boolean — lệnh ĐẶT giá trị, gửi lại không lật ngược): chỉ BẬT được khi dcv.mode: "auto", vì chứng chỉ kỳ mới phải được xác minh lại mà không cần ai thêm bản ghi — tên miền ngoài ⇒ 400 NOT_SUPPORTED, hãy gia hạn tay. Trong 7 ngày cuối trước hạn, hệ thống tự gia hạn 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.
• Đổi chu kỳ (POST /ssl/change-cycle với {order_code, period}): chỉ lên số năm dài hơn đang bán, cần chứng chỉ đã cấp; không trừ tiền lúc đổi — giá kỳ mới (price_renew trong câu trả lời) áp từ lần gia hạn kế. Lần gia hạn ấy cấp chứng chỉ mới, hạn tính từ ngày cấp ⇒ tối đa 30 ngày còn lại của gói hiện tại không được cộng: lệnh gia hạn tay đầu tiên nhận 400 NEW_TERM_CONFIRM_REQUIRED (chưa trừ tiền, msg nêu số ngày), gửi lại kèm accept_new_term: true — dùng lại đúng Idempotency-Key được. ⚠ Đơn đang bật tự gia hạn thì lượt tự gia hạn ấy không hỏi — trừ tiền và bỏ phần ngày còn lại luôn; muốn tự quyết thì tắt tự gia hạn trước. Lệnh đổi chu kỳ không nhận Idempotency-Key (không thu tiền).
• Quá hạn: qua ngày hết hạn gói mà chưa gia hạn, đơn chuyển pending_expired (provision_status: "expired"). Chứng chỉ đã hết hiệu lực — trình duyệt hiện cảnh báo bảo mật với người vào website của bạn. Gia hạn trong 7 ngày kể từ ngày hết hạn ⇒ cấp chứng chỉ mới (new_order). Sau 7 ngày, đơn bị đóng và lần sau phải cấp chứng chỉ mới từ đầu. Khi đơn đã sang expired, mọi lệnh nhận 409 ORDER_EXPIRED.

Luật riêng

• Huỷ (POST /ssl/cancel, confirm = đúng order_code): không hoàn tiền — chứng chỉ đã cấp hay chưa — và không khôi phục. Huỷ không thu hồi chứng chỉ đã cấp: tệp bạn đã tải vẫn hiệu lực tới cert_expire, nhưng đơn không tải lại, không cấp lại, không gia hạn được nữa. Đơn đang gia hạn ⇒ 409 RENEWING (liên hệ hỗ trợ).
• Dịch vụ SSL tạm dừng bán: danh mục, báo giá mua và lệnh mua nhận 503 SERVICE_DISABLED (GET /services/status báo ssl: false); đơn đang có vẫn gia hạn, tải, kiểm tra bình thường. Một sản phẩm ngừng bán thì không còn trong danh mục (báo giá / mua nhận 404), còn đơn đã mua vẫn gia hạn, đổi chu kỳ.
• Hết hàng theo thời hạn: danh mục vẫn bày thời hạn tạm hết với in_stock: false; lệnh mua thời hạn ấy nhận 409 OUT_OF_STOCK (chưa trừ tiền). Gia hạn không bị chặn vì hết hàng.
• Giới hạn lệnh mua qua API: tối đa 10 lượt mua chứng chỉ mỗi giờ (429 RATE_LIMITED) — đếm cả chứng chỉ mua trên web, tính riêng với các sản phẩm khác; không giới hạn số đơn đang chờ cấp. 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: chuyển quyền · ghi chú · xem nhật ký đơn — dùng trang quản lý SSL trên web.
• Chạy thử (X-Sandbox: 1): lệnh mua trả mã SANDBOX… (26 ký tự). Hỏi info bằng mã ấy (vẫn kèm X-Sandbox: 1) — tính từ lúc mua: dưới 10 giây provisioning, chưa có bản ghi; từ giây thứ 10 có bản ghi CNAME mẫu (dcv.status manual, hoặc auto_submitted nếu tên miền tự xác minh); từ giây thứ 40 ready với chứng chỉ mẫu ~199 ngày (dcv.status: "validated"). Chứng chỉ mẫu mang tên miền sandbox-….example — mã chỉ chở sản phẩm, số năm và cờ, không chở tên miền; download trả chuỗi đánh dấu thay cho tệp thật; mua thử kèm csr ⇒ key_source: "customer" và private_key: null. Không lưu gì: huỷ hay đổi chu kỳ mô phỏng không làm info về sau đổi theo, mã không có trong list. Chứng chỉ mẫu đã ready vẫn chưa tới cửa sổ gia hạn ⇒ gia hạn chạy thử nhận 409 RENEW_NOT_OPEN, đúng như đơn thật (trong 40 giây đầu, lúc mẫu còn chờ cấp, nhận 400 NOT_SUPPORTED). Kịch bản PROVISION_FAILED ⇒ lệnh mua vẫn 202, info về failed sau khoảng 40 giây.

Nhịp thao tác trên cùng một chứng chỉ

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