CDN

    • CDN > API 文档 > 证书管理

    证书管理

    最近更新时间: 2026-03-25 14:06:51

    1. 快速查阅区

    1.1 核心接口概览

    接口功能 请求方法 接口路径 核心参数 成功响应
    上传 SSL 证书 POST /sslcert name、commonName、pri、ca {"certID":"..."}
    获取证书列表 GET /sslcert marker、limit {"code":200,"certs":[...]}
    获取证书详情 GET /sslcert/<certId> - {"code":200,"cert":{...}}
    删除 SSL 证书 DELETE /sslcert/<certId> - {"code":200}

    注：<certId>为证书ID

    1.2 核心约束

    • 请求域名: fusion.qiniuapi.com
    • 鉴权方式: QBox 鉴权（详见 鉴权指南）
    • 证书格式: PEM 格式，私钥无密码保护，ca 为完整证书链
    • common_name: 须与域名匹配，泛域名证书为 *.example.com

    2. 详细接口说明

    2.1 上传 SSL 证书

    基本信息

    • 请求方法: POST
    • 接口地址: https://fusion.qiniuapi.com/sslcert

    请求参数

    参数名 类型 必填 说明 示例值
    name string 是 证书名称 "test.example.com-2026"
    commonName string 是 通用名称，须与证书匹配 "test.example.com"
    pri string 是 私钥 (PEM 格式，无密码保护) "-----BEGIN PRIVATE KEY-----\n..."
    ca string 是 证书链 (PEM 格式，服务器证书+中间证书) "-----BEGIN CERTIFICATE-----\n..."

    请求示例

    curl -X POST 'https://fusion.qiniuapi.com/sslcert' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"name":"test.example.com-2026","commonName":"test.example.com","pri":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----","ca":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}'

    响应参数

    参数名 类型 说明
    certID string 证书ID

    响应示例

    成功 (HTTP 200):

    {
    "certID": "694d196ee691b4be3e838346"
}

    失败:

    #示例1
{
    "code": 400325,
    "error": "https证书解析失败"
}
#示例2
{
    "code": 400323,
    "error": "证书链验证失败"
}
#示例3
{
    "code": 400324,
    "error": "证书私钥不匹配"
}

    2.2 获取证书列表

    基本信息

    • 请求方法: GET
    • 接口地址: https://fusion.qiniuapi.com/sslcert

    请求参数 (URL Query)

    参数名 类型 必填 说明 示例值
    marker string 否 分页标记，首次传空 ""
    limit int 否 每页数量，默认 10 20

    请求示例

    curl -X GET 'https://fusion.qiniuapi.com/sslcert?marker=&limit=20' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'

    响应参数

    参数名 类型 说明
    marker string 标示下一次从哪个位置开始获取证书列表
    certid string 证书 ID
    name string 证书名称
    common_name string 通用名称
    dnsnames []string DNS 域名
    not_before int 生效时间 (Unix 时间戳)
    not_after int 过期时间 (Unix 时间戳)
    create_time int 创建时间 (Unix 时间戳)

    响应示例

    成功 (HTTP 200):

    {
  "code": 200,
  "error": "",
  "certs": [
    {
      "certid": "694d196ee691b4be3e838346",
      "name": "私有证书",
      "common_name": "test.example.com",
      "dnsnames": ["test.example.com", "test2.example.com"],
      "not_before": 1766620800,
      "not_after": 1774396799,
      "create_time": 1766660462
    }
  ],
  "marker": "2"
}

    2.3 获取证书详情

    基本信息

    • 请求方法: GET
    • 接口地址: https://fusion.qiniuapi.com/sslcert/<certId>

    请求参数

    参数名 类型 说明
    certId string 证书ID

    请求示例

    curl -X GET 'https://fusion.qiniuapi.com/sslcert/694d196ee691b4be3e838346' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'

    响应参数

    参数名 类型 说明
    name string 证书名称
    common_name string 通用名称
    dnsnames []string DNS 域名
    not_before int 生效时间 (Unix 时间戳)
    not_after int 过期时间 (Unix 时间戳)
    create_time int 创建时间 (Unix 时间戳)
    pri string 证书私钥 (PEM 格式)
    ca string 证书内容 (PEM 格式)

    响应示例

    成功 (HTTP 200):

    {
  "code": 200,
  "error": "",
  "cert": {
    "certid": "694d196ee691b4be3e838346",
    "name": "私有证书",
    "common_name": "test.example.com",
    "dnsnames": ["xxx.example.com"],
    "not_before": 1766620800,
    "not_after": 1774396799,
    "pri": "-----BEGIN PRIVATE KEY-----\n...(完整私钥)...",
    "ca": "-----BEGIN CERTIFICATE-----\n...(完整证书链)..."
  }
}

    2.4 删除 SSL 证书

    基本信息

    • 请求方法: DELETE
    • 接口地址: https://fusion.qiniuapi.com/sslcert/<certId>
    • 前置条件: 证书未绑定任何域名

    请求参数

    参数名 类型 说明
    certId string 证书ID

    请求示例

    curl -X DELETE 'https://fusion.qiniuapi.com/sslcert/694d196ee691b4be3e838346' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'

    响应示例

    成功 (HTTP 200):

    {
    "code": 200
}

    失败:

    #示例1
{
    "code": 400401,
    "error": "无此证书"
}
#示例2
{
    "code": 400326,
    "error": "证书已被使用"
}
#示例3
{
    "code": 400611,
    "error": "证书已绑定域名"
}
#示例4
{
    "code": 404908,
    "error": "无权操作该证书"
}
#示例5
{
    "code": 400911,
    "error": "证书已绑定存储域名"
}

    3. 常见问题

    3.1 专属错误码

    错误码 描述 场景 解决方案
    400322 https 证书有效期太短 上传时证书有效期不足 更换较长有效期证书
    400323 证书链验证失败 上传时证书链不完整 拼接 服务器+中间+根证书
    400324 证书私钥不匹配 pri 与 ca 不对应 检查私钥和证书配对
    400325 证书解析失败 PEM 格式错误/已过期 检查格式和有效期
    400326 证书已被使用 删除时有域名绑定 先解绑再删除
    400329 https 证书过期 上传时证书已过期 更换有效证书
    400401 无此证书 certId 不存在 检查 certId
    400500 超过用户绑定证书最大额度 证书数量超限 删除旧证书
    400611 证书已绑定 CDN 域名 删除时证书已绑定 CDN 先解绑 CDN 域名再删除
    400911 证书已绑定存储域名 删除时证书已绑定存储 先解绑存储域名再删除
    404906 https 证书解码失败 PEM 编码错误 检查证书编码格式
    404908 无权操作该证书 证书不属于当前账号 确认证书归属

    3.2 最佳实践

    • 证书上传: PEM 格式，pri 无密码，ca 包含完整链 (服务器+中间证书)
    • 证书更新: 先上传新证书获取 certID，再用域名配置的 httpsconf/sslize 接口更换
    • 泛域名证书: *.example.com 可绑定多个同前缀域名，无需重复上传
    • 过期管理: 定期查列表检查 not_after，提前更新

    参考: 鉴权详见 鉴权指南，错误码详见 公共错误码&通用约束。

    以上内容是否对您有帮助？