创建（续费）订单

POST

/openapi/v3/orders/:id

创建订单。:id 为产品 ID（product_id）。

注意

alternative_order_id 可以用来防止网络错误导致重复创建订单，建议设置该值。如果同样的值已经提交过，系统会报错，其错误码为 duplicate_alternative_order_id，此时可以通过通过备用 ID 获取订单 ID接口，获取已经提交的订单 ID。
如果您是多租户平台，必须传入稳定且唯一的 user_external_id（终端用户标识），一般可传该用户在您平台中的唯一用户标识。该标识用于识别并隔离该用户在多租户平台中的身份，用于预审核组织复用及 dns-persist 长效验证绑定；不同租户不得共用同一取值。未传时，除显式提供可复用的 organization.id 外，系统不会自动复用已有预审核组织，而会新建组织，且无法使用 dns-persist 长效验证。

Path 参数

参数	类型	必填	说明
id	string	是	产品 ID（`product_id`）。

Body 参数 application/json

参数	类型	必填	说明
certificate	object	是	证书详情。
∟ common_name	string	按需	通用名称。 SSL 证书必传，最长 64 字节。
∟ dns_names	array[string]	否	备用名称（SANs）。每个域名最多 253 个字符，总数受产品限制。支持预审核产品的复用规则见预审核域名复用。
∟ csr	string	按需	证书签名请求。常规 CSR 时必传。 `csr_from=usb-token` 或 `vsign-cloud-csc` 时，创建订单不传 CSR，由对应流程提交。详见 CSR 要求与注意事项。
∟ csr_from	string	否	CSR 私钥来源。可选值和适用规则见 CSR 来源。
∟ sign_hash	string	否	证书签名摘要，默认 SHA256。参考下方签名摘要算法。
∟ un_modify_key	bool	否	仅 TrustAsia 国密双证书续费适用。须与 `renewal_of_order_id` 一起传入。密钥算法为 `SM2` 时，传 `true` 可保留加密证书原私钥。
∟ cross_chain	integer	否	交叉证书链控制。 `-1` 不使用； `0`（默认）使用产品默认配置； `1` 使用交叉证书链。仅支持交叉链的产品有效。
∟ chain_id	integer	否	指定证书链 ID。用于选择证书签发所用的证书链。
∟ validity_days	integer	否	证书自定义有效期（天）。仅部分 CA 和产品可以指定。
∟ custom_expiration_date	string	否	证书自定义过期日期。仅部分 CA 和产品可以指定，格式为 `YYYY-MM-DD`。
validity_months	integer	按需	订单有效期（单位：月）。与下方两个订单有效期字段三选一。 `3` 表示 90 天；其他取值必须为 `12` 的倍数。最终可用范围受产品限制。
validity_days	integer	按需	订单有效期（单位：天）。仅支持自定义有效期的产品可用，传入时至少为 7 天。与 `validity_months`、`custom_expiration_date` 三选一，最大值受产品限制。
custom_expiration_date	string	按需	订单自定义到期日期，格式为 `YYYY-MM-DD`。仅支持自定义有效期的产品可用，最早为当天起 7 天。与 `validity_months`、`validity_days` 三选一。
dcv_method	string	按需	SSL 证书必需，其他证书无需。参考下方域名验证方式。
persist_until	integer	否	仅当 `dcv_method=dns-persist` 时生效。验证值有效期（UNIX 秒）；`0` 表示无限期，其他值必须为未来时间。
persist_policy	string	否	仅当 `dcv_method=dns-persist` 时生效。授权范围：`fqdn`（默认）或 `wildcard`；通配符域名必须使用 `wildcard`。
dcv_scope	string	否	DCV 验证范围。仅支持该能力的 SSL 产品生效。可选值：`base_domain`、`fqdn`。
over_time	string	否	DV 证书订单申请超时时间，单位为秒。仅 DV 订单生效，请传正整数字符串，例如 `2592000`。不传或传 `0` 时按 30 天处理。超过该期限仍未签发时，订单标记为超时；是否自动取消取决于产品配置。
organization	object	否	组织与联系人信息。需要组织审核的 OV/EV SSL 证书产品必传。详见组织复用与新建。
∟ id	string	否	已有组织 ID。必须属于当前 API 账户；复用规则详见组织复用与新建。
∟ name	string	按需	组织名称。新建组织时必传，最长 200 个字符；复用组织时非必传。匹配规则详见组织复用与新建。
∟ address_line1	string	按需	组织地址第一行。新建组织时必传，最长 128 个字符；复用组织时非必传。
∟ address_line2	string	否	组织地址第二行或补充行，最长 64 个字符。完整地址超过 `address_line1` 限制时，请将剩余部分填入本字段。
∟ city	string	按需	城市。新建组织时必传，最长 64 个字符；复用组织时非必传。
∟ state	string	按需	地区。新建组织时必传，最长 64 个字符；复用组织时非必传。
∟ zip_code	string	按需	邮编。新建组织时必传，最长 40 个字符；复用组织时非必传。
∟ country	string	按需	国家或地区代码。新建组织时必传，最长 2 个字符，且须为有效代码；复用组织时非必传。
∟ telephone	string	按需	组织电话。新建组织时必传，最长 32 个字符；复用组织时非必传。
∟ biz_email	string	否	企业邮箱。最长 255 个字符；传入时须为合法邮箱格式。
∟ contact	object	按需	组织联系人。新建组织时必传；复用组织时非必传。复用与更新规则详见组织复用与新建。
∟ skip_duplicate_org_check	bool	否	跳过组织自动匹配。传 `true` 时，无法直接复用已有组织的请求会新建组织。详见组织复用与新建。
∟ audit_method	string	否	组织审核方式。参考下方组织审核方式。
∟ uscc	string	否	单位代码。国内企业通常填写统一社会信用代码，最长 64 个字符。
technical_contact	object	按需	技术联系人。字段规则见 Contact 对象说明。
person_info	object	按需	个人信息。参考 PersonInfo 对象说明。
alternative_order_id	string	否	备用 ID，用于防重复提交。
pay_product_id	integer	按需	支付产品 ID。
skip_force_given_domain	bool	否	跳过自动补入候选赠送域名。传 `true` 时不会自动加入候选域名，已显式提交的域名不受影响。详见赠送域名规则。
vsign_key_pin	string	按需	仅 `csr_from=vsign-cloud-csc` 时使用。云签密钥访问控制码。非云签 CSC 合作伙伴必传。
vsign_key_pin_tip	string	否	仅 `csr_from=vsign-cloud-csc` 时使用。云签密钥访问控制码提示。
renewal_of_order_id	string	否	需要续费的订单 ID。续费订单创建成功后，被续费订单将变为已续费状态。
user_external_id	string	否	终端用户标识。多租户平台必须传入稳定且唯一的值，一般使用该用户在平台中的唯一用户标识。用于隔离预审核组织复用和 `dns-persist` 长效验证绑定；与组织信息同时使用时最长 128 个字符。组织自动匹配规则详见组织复用与新建。渠道客户使用 `dns-persist` 时，须为 1–32 位字母、数字、`_` 或 `-`。
custom_fields	array[object]	否	自定义字段列表，最多 5 项。 `label` 不可重复。
∟ label	string	是	字段标签，长度为 1–50 字节。
∟ value	string	是	字段值，长度为 1–50 字节。
user_agreement	bool	否	是否同意产品用户协议。默认不传视为同意。

字段长度说明

除明确标为“字节”的字段外，本文标注的“字符”均按 Unicode 字符计数。

Contact 对象说明

technical_contact、organization.contact 使用以下结构：

字段	类型	说明
first_name	string	名。最长 128 个字符。
last_name	string	姓。最长 128 个字符。
job_title	string	职位。最长 64 个字符。
telephone	string	电话。最长 32 个字符。
id_type	string	证件类型：`1` 身份证，`2` 护照，`3` 港澳通行证。最长 32 个字符。
id_number	string	证件号码。最长 128 个字符。
email	string	邮箱。非空时须为合法邮箱格式，最长 255 个字符。

organization.contact 的复用与更新规则见组织复用与新建。

PersonInfo 对象说明

person_info 用于需要个人信息的产品，支持引用已有个人预审核信息，或提交新的个人信息：

字段	类型	必填	说明
id	string	否	已有个人预审核信息 ID，必须为数字字符串。提供后可不传下方个人基本信息。
first_name	string	按需	名。未提供 `id` 时必传，最长 64 个字符。
last_name	string	按需	姓。未提供 `id` 时必传，最长 64 个字符。
job_title	string	否	职位，最长 64 个字符。
telephone	string	按需	电话。未提供 `id` 时必传，最长 32 个字符。
email	string	按需	邮箱。未提供 `id` 时必传，最长 255 个字符，且须为合法邮箱格式。
id_type	string	按需	证件类型：`1` 身份证，`2` 护照，`3` 港澳通行证。未提供 `id` 时必传，最长 32 个字符。
id_number	string	按需	证件号码。未提供 `id` 时必传，最长 32 个字符。
pseudonym	string	否	伪名，最长 128 个字符。
address	string	否	地址，最长 256 个字符。
country	string	否	两位国家或地区代码，例如中国 `CN`。最长 2 个字符，且须为有效国家或地区代码。

组织审核方式

organization.audit_method 可选值如下。不传时由所选产品的默认策略决定，具体可用方式受产品限制。

取值	说明
`publicEmail`	公开邮箱。
`publicPhone`	公开电话。

返回数据

参数名称	类型	描述
id	string	订单 ID。
status	string	订单状态，参见订单状态。
organization	object	组织与联系人。支持预审的 OV/EV 订单返回该参数。
∟ id	string	组织 ID。
certificate	object	证书。
∟ id	string	证书 ID。
dcv_val	array[object]	域名验证值。订单需要验证域名时返回。
∟ id	string	验证域名 ID。支持预审的 OV/EV 订单可能返回。
∟ domain	string	待验证域名。
∟ auth_path	string	验证路径或记录名。
∟ auth_val	string	验证值。
∟ verified	bool	是否已完成本系统预检测。预检测通过不代表 CA 验证已通过；CA 可能因多视角验证、CAA 记录等原因得到不同结果。
∟ dcv_method	string	域名验证方式。

bash

# 示例1：申请 DV 证书
curl -X POST 'https://api.certcloud.cn/openapi/v3/orders/trustasia_c1_ssl_dv' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "certificate": {
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n",
      "common_name": "test.isw.app",
      "dns_names": ["test.isw.app"],
      "sign_hash": "SHA256"
    },
    "validity_months": 24,
    "dcv_method": "cname",
    "alternative_order_id": "1234567"
  }'

# 示例2：申请 OV 证书
curl -X POST 'https://api.certcloud.cn/openapi/v3/orders/trustasia_c1_ssl_ov' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "certificate": {
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n",
      "common_name": "test.isw.app",
      "dns_names": ["test.isw.app"],
      "sign_hash": "SHA256"
    },
    "validity_months": 24,
    "dcv_method": "cname",
    "alternative_order_id": "1234569s7",
    "organization": {
      "name": "亚数信息科技（上海）有限公司【测试】",
      "telephone": "021-58895880",
      "address_line1": "徐汇区桂平路391号B座32楼",
      "city": "上海市",
      "state": "上海市",
      "country": "CN",
      "zip_code": "200000",
      "contact": {
        "first_name": "razeen",
        "last_name": "cheng",
        "job_title": "Dev",
        "telephone": "17627679987",
        "email": "test@isw.app"
      }
    },
    "user_external_id": "user_xxxxx"
  }'

javascript

// 示例1：申请 DV 证书
const response = await fetch('https://api.certcloud.cn/openapi/v3/orders/trustasia_c1_ssl_dv', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
  body: JSON.stringify({
    certificate: {
      csr: '-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n',
      common_name: 'test.isw.app',
      dns_names: ['test.isw.app'],
      sign_hash: 'SHA256'
    },
    validity_months: 24,
    dcv_method: 'cname',
    alternative_order_id: '1234567'
  })
})
const data = await response.json()

body := map[string]interface{}{
  "certificate": map[string]interface{}{
    "csr":         "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n",
    "common_name": "test.isw.app",
    "dns_names":   []string{"test.isw.app"},
    "sign_hash":   "SHA256",
  },
  "validity_months":      24,
  "dcv_method":           "cname",
  "alternative_order_id": "1234567",
}
jsonBody, _ := json.Marshal(body)
req, _ := http.NewRequest("POST",
  "https://api.certcloud.cn/openapi/v3/orders/trustasia_c1_ssl_dv",
  bytes.NewBuffer(jsonBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
resp, err := http.DefaultClient.Do(req)

python

import requests

response = requests.post(
    'https://api.certcloud.cn/openapi/v3/orders/trustasia_c1_ssl_dv',
    headers={
        'Content-Type': 'application/json',
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    json={
        'certificate': {
            'csr': '-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n',
            'common_name': 'test.isw.app',
            'dns_names': ['test.isw.app'],
            'sign_hash': 'SHA256',
        },
        'validity_months': 24,
        'dcv_method': 'cname',
        'alternative_order_id': '1234567',
    }
)
data = response.json()

200成功

示例 1：申请 DV 证书

json

{
  "data": {
    "id": "TIT6R0qv",
    "status": "domain_verifing",
    "certificate": {
      "id": "LiIPxxZ5"
    }
  },
  "code": "success"
}

示例 2：申请 OV 证书

json

{
  "data": {
    "id": "qOx0oqou",
    "status": "auditing",
    "certificate": {
      "id": "AdMUPKCa"
    }
  },
  "code": "success"
}

CSR 要求与注意事项

基本要求

CSR 必须是完整、可正确解析的 PKCS#10 证书签名请求。建议使用标准 PEM 格式，包含 -----BEGIN CERTIFICATE REQUEST----- 和 -----END CERTIFICATE REQUEST-----。
CSR 内不得夹带私钥、证书或其他额外内容。私钥应由您自行安全保管，请勿将明文私钥拼接到 csr 字段中。
不支持弱密钥，例如 RSA 1024 位或更低强度的密钥。通用校验支持 RSA 2048 / 3072 / 4096 / 8192 位，ECDSA 和 SM2 密钥必须使用系统及所选产品支持的曲线和长度。具体可用算法和密钥长度以所选产品为准。
CSR 的自签名不得使用 MD2 或 MD5；TrustAsia 系列也不接受使用 SHA-1 自签名的 CSR。建议使用 SHA-256 或更强的签名算法。
CSR 的自签名算法与 certificate.sign_hash 不同；certificate.sign_hash 用于指定最终证书的签名摘要，两者需分别满足要求。

CSR 来源

取值	说明
不传或为空	由调用方在 `certificate.csr` 提供 CSR。
`usb-token`	生成 CSR 的私钥来自 USB Token。一般多用于电子签名认证证书等场景。创建订单时不提交 CSR；后续通过证书提取流程将 CSR 提交至 CA，并将签发的证书提取到 USB Token。
`vsign-cloud-csc`	生成 CSR 的私钥来自云签。创建订单时无需提交 CSR，由云签自动提交。

CSR 主题信息

TrustAsia 和 DigiCert 系列证书对 CSR 中的主题信息没有严格要求，CSR 可正确解析、使用受支持的密钥并正常签名即可。

部分 CA 会校验 CSR 中的主题信息。例如 CFCA 要求 CSR 包含完整的通用名称、组织、国家或地区、省份和城市信息，并要求其与订单信息一致。为了避免 CA 拒绝订单，建议生成 CSR 时保持以下信息与创建订单的请求一致：

CSR 通用名称（CN）与 certificate.common_name。
CSR 备用名称（SAN）与 certificate.dns_names。
CSR 组织名称（O）与 organization.name。
CSR 国家或地区（C）与 organization.country。
CSR 省份（ST）、城市（L）与 organization.state、organization.city。

CSR 复用

TrustAsia 和 DigiCert 系列证书支持在多个订单中复用 CSR。但部分 CA（如 Certum、CFCA）不支持复用已使用的 CSR 或公钥。对于 Certum，已成功提交订单的 CSR 公钥会被记录，后续再次使用可能返回 public_key_blacklisted。

建议每个订单使用新的 CSR

为兼容不同 CA 的要求并降低私钥复用风险，建议每次创建订单时都生成新的密钥对和 CSR。仅重新生成 CSR 但继续使用原密钥，仍可能被 CA 判定为复用已使用的公钥。

签名摘要算法

目前 CertCloud 支持选择的签发算法有：

SHA256
SHA384
SHA512

注意

不是所有的产品都支持这三种算法，下单时请注意。

域名验证方式

目前 CertCloud 支持的域名验证方式有：

DNS TXT 验证（dns）
DNS 长效 TXT 验证（dns-persist）
DNS CNAME 验证（cname）
HTTP 文件验证（file）
邮件验证（email）

DCV 验证范围

dcv_scope 仅对支持该能力的 SSL 产品生效，当前创建订单链路已接入 DigiCert 和 TrustAsia。

base_domain：非文件验证时，按基础域名收敛验证项，可由基础域验证覆盖其子域。
fqdn：非文件验证时，按订单域名范围保留验证项；订单中已有父域时可覆盖其子域。
使用文件验证时，无论传入何种范围，仍须逐个 FQDN 放置验证文件。
不传时，OV/EV 订单默认使用 fqdn；DV 订单由系统及 CA 默认策略决定。

注意

不同产品支持的验证方式不一致，具体支持情况请参考产品列表。域名验证在 CertCloud 的整个订单流程中属于关键环节，详见业务流程与开发前必读 §4 域名审核。

组织复用与新建

以下规则适用于需要组织审核的产品。

指定已有组织

传入 organization.id 时，该 ID 必须属于当前 API 账户。系统会先判断该组织能否用于本次订单：组织所属 CA 和审核类型须与本次订单兼容；如果该 ID 对应的组织不支持复用，系统不会直接复用。满足条件时，系统直接复用该组织。

无法直接复用时，系统会以该组织的已有资料补全本次请求，再进入自动匹配或新建流程；如果该 ID 对应的组织不支持复用，系统会新建一份组织资料并重新审核。

复用组织不表示其余字段一定被忽略。传入的非空组织或联系人字段可能更新组织资料；不能立即更新时，系统会将变更作为待审核修改保存。

自动匹配与租户隔离

未传 organization.id 时，系统会在当前 API 账户内按组织名称、国家或地区、CA、组织联系人邮箱及 user_external_id（如传入）查找可复用组织；地址、城市和电话不参与匹配。没有匹配项时，系统创建新组织。

多租户平台应为每个终端用户传入稳定且唯一的 user_external_id。该标识参与自动匹配，用于隔离不同终端用户的预审核组织；未传时，系统会跳过自动匹配并创建组织。为保持租户隔离，请勿跨租户显式复用同一 organization.id。

跳过重复检查

传 organization.skip_duplicate_org_check=true 时，系统仍会先尝试通过 organization.id 直接复用组织；未能直接复用时，不进行自动匹配而直接新建组织。

预审核域名复用

以下规则适用于支持域名预审核的产品。

系统仅在当前 API 账户与订单所属组织范围内，查找与订单域名相同或其上级的预审核域名。
只有通过订单所需审核类型，且验证有效期剩余超过 12 小时的域名，才能作为已完成的预审核结果复用；仅名称匹配不代表已通过预审核。
已通过预审核的域名可复用于相同域名。采用非文件验证方式时，还可复用于其子域名；采用文件验证方式时，仅可复用于该域名自身。
未找到可复用的预审核域名时，系统会为本次订单创建域名预审核资料并继续验证流程。

注意

当传入的 dcv_method 与可复用预审核域名当前的验证方式不一致时，系统不会修改该预审核域名的验证方式。因此，订单返回的域名验证方式可能与请求中传入的 dcv_method 不一致，属于正常现象。

赠送域名规则

skip_force_given_domain 仅控制本接口是否自动补入候选赠送域名，并不代表产品是否支持赠送域名。

不传或传 false 时，系统会根据所选产品和通用名称尝试补入候选域名；传 true 时不自动补入，已在请求中显式提交的域名不受影响。
赠送规则仅适用于支持附加域名且未关闭赠送能力的 SSL 或私有 SSL 产品。IP 通用名称、候选域名已存在，或产品未配置可用赠送规则时，不会补入。
通用候选规则为：example.com 可补入 www.example.com，www.example.com 可补入 example.com，*.example.com 可补入 example.com。普通非 www 子域名不自动补入候选域名。
不同 CA、产品和账户配置可能有额外限制或不同的候选规则。最终签发域名及是否免费以产品配置和 CA 受理结果为准。

订单管理

证书管理

组织管理

域名管理

创建（续费）订单

Contact 对象说明

PersonInfo 对象说明

组织审核方式

返回数据

CSR 要求与注意事项

基本要求

CSR 来源

CSR 主题信息

CSR 复用

签名摘要算法

域名验证方式

组织复用与新建

指定已有组织

自动匹配与租户隔离

跳过重复检查

预审核域名复用

赠送域名规则

创建（续费）订单 ​

Contact 对象说明 ​

PersonInfo 对象说明 ​

组织审核方式 ​

返回数据 ​

CSR 要求与注意事项 ​

基本要求 ​

CSR 来源 ​

CSR 主题信息 ​

CSR 复用 ​

签名摘要算法 ​

域名验证方式 ​

组织复用与新建 ​

指定已有组织 ​

自动匹配与租户隔离 ​

跳过重复检查 ​

预审核域名复用 ​

赠送域名规则 ​

创建（续费）订单

Contact 对象说明

PersonInfo 对象说明

组织审核方式

返回数据

CSR 要求与注意事项

基本要求

CSR 来源

CSR 主题信息

CSR 复用

签名摘要算法

域名验证方式

组织复用与新建

指定已有组织

自动匹配与租户隔离

跳过重复检查

预审核域名复用

赠送域名规则