## 证书 (`certs`)

上传或自动签发的 HTTPS 证书。可绑定到站点;有站点在用时不能删除或停用。

鉴权: 用户（部分参数仅管理员） · 文档: https://www-demo.kuxitong.com/zh/docs/api/certs

### GET `/api/v2/certs`

列出证书 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |
| `name` | string |  | 名称包含。 |
| `domain` | string |  | SAN 包含(域名或 IP 的一部分)。 |
| `scope` | string |  | site = 站点证书;ip = 平台 IP 证书;panel = 面板证书(主控 HTTPS 监听用)。 可选值: ["site","ip","panel"] |
| `enabled` | boolean |  | 是否启用 |
| `expire_days` | integer |  | 只列 N 天内到期(含已过期)的证书。 |
| `id` | integer |  | 证书 id 精确匹配。 |
| `ids` | string |  | 多个证书 id 逗号分隔(至多 200 个),命中其中任一个。 |
| `des` | string |  | 备注包含。 |
| `type` | string |  | 证书类型。 可选值: ["custom","lets","zerossl","zerossl_api"] |
| `dns_api_id` | integer |  | 用此 DNS API 凭据的证书。 |
| `domains` | string |  | 多个域名或 IP,逗号分隔,证书 SAN 里含其中任一个(精确匹配)。 |
| `issue_state` | string |  | ACME 签发状态(上传的证书没有)。 可选值: ["pending","running","issued","failed"] |
| `kind` | string |  | domain = SAN 含域名;ip = SAN 全是 IP。 可选值: ["domain","ip"] |

```sh
curl "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/certs`

创建证书 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `acme` | CertAcmeSummary |  | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 |
| `cert` | string |  | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 |
| `des` | string |  | 备注说明 |
| `enabled` | boolean |  | 是否启用 |
| `key` | string |  | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
| `name` | string | 有 | 名称 |
| `scope` | string |  | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 可选值: ["site","ip","panel"] |
| `type` | string |  | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |

```sh
curl -X POST "https://panel.example.com/api/v2/certs" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/certs/acme-states`

批量查 ACME 签发状态 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | string | 有 | 证书 id,逗号分隔,至多 200 个。 |

```sh
curl "https://panel.example.com/api/v2/certs/acme-states" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/certs/batch`

批量申请 ACME 证书 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `acme_account_id` | integer |  | 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。 |
| `auto_renew` | boolean |  | 不给为 true。 |
| `des` | string |  | 备注说明 |
| `dns_api_id` | integer |  | DNS-01 验证用的 DNS API 凭据(ACME 证书用)。 |
| `items` | CertAcme[] | 有 | 签发状态。 |
| `type` | string |  | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |

```sh
curl -X POST "https://panel.example.com/api/v2/certs/batch" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"domains":["a.example.com"]},{"domains":["b.example.com","www.b.example.com"]}],"type":"lets"}'
```

### POST `/api/v2/certs/batch-issue`

批量重签或续签 ACME 证书 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | integer[] | 有 | 证书 id。 |

```sh
curl -X POST "https://panel.example.com/api/v2/certs/batch-issue" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[1]}'
```

### GET `/api/v2/certs/zerossl-ips`

列出可签 ZeroSSL 证书的 IP · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |

```sh
curl "https://panel.example.com/api/v2/certs/zerossl-ips" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/certs/{id}`

获取证书 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/certs/{id}`

修改证书 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `acme` | CertAcmeSummary |  | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 |
| `cert` | string |  | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 |
| `des` | string |  | 备注说明 |
| `enabled` | boolean |  | 是否启用 |
| `key` | string |  | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
| `name` | string | 有 | 名称 |
| `scope` | string |  | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 可选值: ["site","ip","panel"] |
| `type` | string |  | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/certs/{id}`

删除证书 · 鉴权: 用户（部分参数仅管理员）

```sh
curl -X DELETE "https://panel.example.com/api/v2/certs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/certs/{id}/acme`

获取证书的 ACME 签发状态 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/certs/{id}/acme`

修改证书的自动续签开关 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `auto_renew` | boolean | 有 | 不给为 true。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/certs/{id}/acme" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew":false}'
```

### POST `/api/v2/certs/{id}/bind`

证书绑定到站点 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `site_ids` | integer[] | 有 | 在用此证书的站点。 |

```sh
curl -X POST "https://panel.example.com/api/v2/certs/{id}/bind" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_ids":[1]}'
```

### POST `/api/v2/certs/{id}/issue`

重新签发 ACME 证书 · 鉴权: 用户（部分参数仅管理员）

```sh
curl -X POST "https://panel.example.com/api/v2/certs/{id}/issue" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/certs/{id}/private-key`

导出证书私钥 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `password` | string |  | 当前登录口令。 |
| `totp_code` | string |  | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |

```sh
curl -X POST "https://panel.example.com/api/v2/certs/{id}/private-key" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

证书对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `acme` | CertAcmeSummary |  | 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。 (只读) |
| `acme_account_id` | integer |  | 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。 |
| `ari_end` | string |  | CA 经 ARI 建议的续签窗口结束时间。 |
| `ari_start` | string |  | CA 经 ARI 建议的续签窗口;null = CA 没给,按到期前 cert.acme.renew_before_days 天续签。 |
| `auto_renew` | boolean |  | 不给为 true。 |
| `cert` | string |  | 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。 (只读) |
| `cert_id` | integer |  | 证书 id。 |
| `challenge` | string |  | 验证方式:http-01、dns-01,或 http-file(zerossl_api 的 ZeroSSL 文件验证)。 可选值: ["http-01","dns-01","http-file"] |
| `created_at` | string |  | 创建时间 (只读) |
| `des` | string |  | 备注说明 |
| `dns_api_id` | integer |  | DNS-01 验证用的 DNS API 凭据(ACME 证书用)。 |
| `enabled` | boolean |  | 是否启用 |
| `err_times` | integer |  | 这一轮已失败次数。 |
| `failed` | integer |  | 失败的条数。 |
| `fingerprint` | string |  | 叶证书 SHA-256 指纹(小写十六进制)。 (只读) |
| `id` | integer |  | 记录 ID (只读) |
| `ids` | integer[] | 有 | 证书 id。 |
| `issued_at` | string |  | 最近一次签发成功的时间。 |
| `issuer` | string |  | 证书颁发者。 (只读) |
| `items` | CertAcme[] |  | 签发状态。 |
| `key` | string |  | 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。 |
| `last_error` | string |  | 最近一次错误 |
| `name` | string |  | 名称 |
| `names` | string[] |  | SAN(域名、通配域名或 IP);无 SAN 时取 CN。 (只读) |
| `next_try_at` | string |  | 续签失败终态后,续签扫描最早再试的时刻。 |
| `not_after` | string |  | 证书到期时间。 (只读) |
| `not_before` | string |  | 证书生效时间。 (只读) |
| `ocsp` | boolean |  | 叶证书带 OCSP 地址(节点可装订)。 (只读) |
| `ok` | integer |  | 已排队签发的条数。 |
| `password` | string |  | 当前登录口令。 |
| `renewing` | boolean |  | 当前这轮是续签(失败时旧证书照用)。 |
| `scope` | string |  | 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。 可选值: ["site","ip","panel"] |
| `site_ids` | integer[] |  | 在用此证书的站点。 (只读) |
| `state` | string |  | pending 排队或等重试;running 签发中;issued 已签出;failed 重试用完(已发提醒)。 可选值: ["pending","running","issued","failed"] |
| `tenant_id` | integer |  | 所属租户;null = 平台 IP 证书。 (只读) |
| `totp_code` | string |  | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |
| `type` | string |  | custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。 |
| `updated_at` | string |  | 更新时间 (只读) |
| `version` | integer |  | 证书内容版本,换证 +1。 (只读) |
| `zerossl_order_id` | string |  | zerossl_api 证书当前的 ZeroSSL 订单号;空 = 还没下单。 |
| `zerossl_order_state` | string |  | ZeroSSL 订单状态(draft、pending_validation、issued、cancelled 等);空 = 还没下单。 |