套餐包查询

套餐包查询接口用于获取当前 API Key 所属账户的点数套餐包、套餐详情，以及证书订单产生的扣除和退款流水。

查询范围

接口只返回当前账户的数据，不接受 account_id，也不会扩展查询父账户或子账户。API Key 需要具备订单管理权限。

通用说明

认证头部

三个接口均需携带以下认证头部：

头部	类型	必填	说明
`X-CC-Auth-Key`	string	是	API 认证密钥
`X-CC-Key-ID`	string	是	API 密钥 ID

套餐包状态

`status`	说明	是否可能可用
`paid`	已支付	是；还需套餐未过期且剩余点数大于 `0`
`processing`	交付中	否
`completed`	已完成	否
`pending_cancel`	待确认取消	否
`canceled`	已取消	否
`expired`	已过期	否

usable 仅表示套餐满足基础使用条件：status=paid、未过期且剩余点数大于 0。具体订单是否可以抵扣，还需要结合产品、组织和域名限制判断。

套餐包对象

列表中的 points_packages[] 与详情接口的 data 使用相同结构。

字段	类型	说明
`id`	string	套餐包 ID
`product_id`	string	套餐包模板产品 ID
`product_name`	string	套餐包名称；模板产品已不存在时为空字符串
`status`	string	套餐包状态，取值见套餐包状态
`total_points`	integer	套餐总点数
`used_points`	integer	已使用点数
`remaining_points`	integer	剩余点数，最小为 `0`
`usable`	boolean	套餐当前是否满足基础使用条件
`created_at`	string	套餐创建时间，RFC 3339 格式
`expires_at`	string	套餐到期时间，RFC 3339 格式
`limit_org`	boolean	是否限制可使用套餐的组织
`org_names`	array[string]	允许使用套餐的组织名称；不限制时返回 `[]`
`limit_domain`	boolean	是否限制可使用套餐的域名
`domains`	array[string]	允许使用套餐的域名；不限制时返回 `[]`
`deductible_products`	array[object]	套餐包可抵扣的产品及点数配置

deductible_products[] 字段：

字段	类型	说明
`product_id`	string	可抵扣产品 ID；产品下架或删除后仍保留该 ID
`product_name`	string	当前产品名称；产品已不存在时为空字符串
`available`	boolean	当前产品是否仍存在且未禁用；不代表指定订单一定可以抵扣
`single_points`	integer / null	单域名每年所需点数；未配置时为 `null`，配置为零点时为 `0`
`wildcard_points`	integer / null	通配符每年所需点数；未配置时为 `null`，配置为零点时为 `0`

空值与历史配置

org_names、domains、deductible_products、points_packages 和 transactions 没有数据时均返回 []，不会返回 null。
single_points、wildcard_points 的 null 表示未配置，数值 0 表示已配置为零点，两者含义不同。
可抵扣产品下架或删除后不会从套餐快照中消失；此时仍返回 product_id，同时 product_name=""、available=false。

查询套餐包列表

GET

/openapi/v3/points-packages

分页查询当前账户的套餐包。结果固定按创建时间倒序返回；创建时间相同时按套餐包 ID 倒序返回。

查询参数

参数	类型	必填	默认值	说明
`page`	integer	否	`1`	页码，最小值为 `1`
`page_size`	integer	否	`20`	每页数量，取值范围为 `1`–`100`
`status`	string	否	-	套餐包状态；多个状态使用英文逗号分隔，例如 `paid,expired`。不传时查询全部六种对外状态

请求示例

bash

curl -G 'https://api.certcloud.cn/openapi/v3/points-packages' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'status=paid,expired'

javascript

const url = new URL('https://api.certcloud.cn/openapi/v3/points-packages')
url.search = new URLSearchParams({
  page: '1',
  page_size: '20',
  status: 'paid,expired',
})

const response = await fetch(url, {
  headers: {
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
})
const data = await response.json()

endpoint, _ := url.Parse("https://api.certcloud.cn/openapi/v3/points-packages")
query := endpoint.Query()
query.Set("page", "1")
query.Set("page_size", "20")
query.Set("status", "paid,expired")
endpoint.RawQuery = query.Encode()

req, _ := http.NewRequest(http.MethodGet, endpoint.String(), nil)
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.get(
    'https://api.certcloud.cn/openapi/v3/points-packages',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    params={
        'page': 1,
        'page_size': 20,
        'status': 'paid,expired',
    },
)
data = response.json()

返回数据

字段	类型	说明
`page`	integer	当前页码
`page_size`	integer	每页数量
`total`	integer	符合条件的套餐包总数
`points_packages`	array[object]	套餐包列表，字段见套餐包对象

200成功

json

{
  "code": "success",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 2,
    "points_packages": [
      {
        "id": "pkg-general-100",
        "product_id": "points-package-general",
        "product_name": "通用证书点数包",
        "status": "paid",
        "total_points": 100,
        "used_points": 10,
        "remaining_points": 90,
        "usable": true,
        "created_at": "2026-01-01T00:00:00+08:00",
        "expires_at": "2026-12-31T00:00:00+08:00",
        "limit_org": false,
        "org_names": [],
        "limit_domain": false,
        "domains": [],
        "deductible_products": [
          {
            "product_id": "prod-dv-basic",
            "product_name": "DV 基础版",
            "available": true,
            "single_points": 2,
            "wildcard_points": 6
          },
          {
            "product_id": "prod-wildcard-only",
            "product_name": "通配符专用版",
            "available": true,
            "single_points": null,
            "wildcard_points": 5
          },
          {
            "product_id": "prod-zero-point",
            "product_name": "活动零点产品",
            "available": true,
            "single_points": 0,
            "wildcard_points": 0
          }
        ]
      },
      {
        "id": "pkg-legacy-product-20",
        "product_id": "points-package-legacy",
        "product_name": "历史点数包",
        "status": "paid",
        "total_points": 20,
        "used_points": 0,
        "remaining_points": 20,
        "usable": true,
        "created_at": "2025-06-01T00:00:00+08:00",
        "expires_at": "2027-06-01T00:00:00+08:00",
        "limit_org": false,
        "org_names": [],
        "limit_domain": false,
        "domains": [],
        "deductible_products": [
          {
            "product_id": "prod-retired",
            "product_name": "",
            "available": false,
            "single_points": 1,
            "wildcard_points": null
          }
        ]
      }
    ]
  }
}

查询套餐包详情

GET

/openapi/v3/points-packages/:id

查询当前账户的单个套餐包。详情只返回套餐包对象，不包含分页字段或流水。

Path 参数

参数	类型	必填	说明
`id`	string	是	套餐包 ID

请求示例

bash

curl 'https://api.certcloud.cn/openapi/v3/points-packages/pkg-org-domain-60' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

javascript

const response = await fetch(
  'https://api.certcloud.cn/openapi/v3/points-packages/pkg-org-domain-60',
  {
    headers: {
      'X-CC-Auth-Key': 'your-auth-key',
      'X-CC-Key-ID': 'your-key-id',
    },
  },
)
const data = await response.json()

req, _ := http.NewRequest(
    http.MethodGet,
    "https://api.certcloud.cn/openapi/v3/points-packages/pkg-org-domain-60",
    nil,
)
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.get(
    'https://api.certcloud.cn/openapi/v3/points-packages/pkg-org-domain-60',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
)
data = response.json()

返回数据

成功时，data 为一个完整的套餐包对象。

200成功

json

{
  "code": "success",
  "data": {
    "id": "pkg-org-domain-60",
    "product_id": "points-package-org-domain",
    "product_name": "组织域名限定点数包",
    "status": "paid",
    "total_points": 60,
    "used_points": 10,
    "remaining_points": 50,
    "usable": true,
    "created_at": "2026-03-01T00:00:00+08:00",
    "expires_at": "2027-03-01T00:00:00+08:00",
    "limit_org": true,
    "org_names": [
      "示例科技有限公司",
      "示例研究院"
    ],
    "limit_domain": true,
    "domains": [
      "example.com",
      "example.net"
    ],
    "deductible_products": [
      {
        "product_id": "prod-ov-pro",
        "product_name": "OV 专业版",
        "available": true,
        "single_points": 3,
        "wildcard_points": 8
      }
    ]
  }
}

详情响应边界

详情接口不会返回 page、page_size、total 或 transactions。需要查询流水时，请调用下方的流水接口。

查询扣除与退款流水

GET

/openapi/v3/points-packages/:id/transactions

分页查询指定套餐包因创建证书订单、取消订单、重颁发或取消重颁发产生的已完成点数变更。接口不返回人工调整套餐总点数、有效期、状态、组织或域名限制的操作记录。

流水固定按创建时间倒序返回；创建时间相同时按流水 ID 倒序返回。

Path 参数

参数	类型	必填	说明
`id`	string	是	套餐包 ID

查询参数

参数	类型	必填	默认值	说明
`page`	integer	否	`1`	页码，最小值为 `1`
`page_size`	integer	否	`20`	每页数量，取值范围为 `1`–`100`

请求示例

bash

curl -G 'https://api.certcloud.cn/openapi/v3/points-packages/pkg-general-100/transactions' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20'

javascript

const url = new URL(
  'https://api.certcloud.cn/openapi/v3/points-packages/pkg-general-100/transactions',
)
url.search = new URLSearchParams({ page: '1', page_size: '20' })

const response = await fetch(url, {
  headers: {
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
})
const data = await response.json()

endpoint, _ := url.Parse(
    "https://api.certcloud.cn/openapi/v3/points-packages/pkg-general-100/transactions",
)
query := endpoint.Query()
query.Set("page", "1")
query.Set("page_size", "20")
endpoint.RawQuery = query.Encode()

req, _ := http.NewRequest(http.MethodGet, endpoint.String(), nil)
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.get(
    'https://api.certcloud.cn/openapi/v3/points-packages/pkg-general-100/transactions',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    params={'page': 1, 'page_size': 20},
)
data = response.json()

返回数据

字段	类型	说明
`page`	integer	当前页码
`page_size`	integer	每页数量
`total`	integer	符合条件的流水总数
`transactions`	array[object]	扣除与退款流水

transactions[] 字段：

字段	类型	说明
`id`	string	流水 ID
`type`	string	流水类型：`deduction`（扣除）或 `refund`（退款）
`operation`	string	业务操作，取值见流水类型与点数符号
`points_delta`	integer	套餐余额变化量：扣除为非正数，退款为非负数；`0` 是合法历史值
`order_id`	string	关联订单 ID；历史关联数据缺失时为空字符串
`username`	string	操作用户名；用户当前无法解析时为空字符串
`created_at`	string	流水创建时间，RFC 3339 格式

流水类型与点数符号

`type`	`operation`	业务含义	`points_delta`
`deduction`	`create_order`	创建证书订单扣点	`<= 0`
`refund`	`cancel_order`	取消证书订单退款	`>= 0`
`deduction`	`reissue`	重颁发扣点	`<= 0`
`refund`	`cancel_reissue`	取消重颁发退款	`>= 0`

points_delta 使用套餐余额变化语义。例如扣除 6 点返回 -6，退回 6 点返回 6。接口不返回每笔流水发生后的历史余额。

200成功

json

{
  "code": "success",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 4,
    "transactions": [
      {
        "id": "1004",
        "type": "refund",
        "operation": "cancel_reissue",
        "points_delta": 4,
        "order_id": "ord-003",
        "username": "demo@example.com",
        "created_at": "2026-08-05T14:00:00+08:00"
      },
      {
        "id": "1003",
        "type": "deduction",
        "operation": "reissue",
        "points_delta": -4,
        "order_id": "ord-003",
        "username": "demo@example.com",
        "created_at": "2026-08-04T13:00:00+08:00"
      },
      {
        "id": "1002",
        "type": "refund",
        "operation": "cancel_order",
        "points_delta": 2,
        "order_id": "ord-001",
        "username": "demo@example.com",
        "created_at": "2026-08-03T12:00:00+08:00"
      },
      {
        "id": "1001",
        "type": "deduction",
        "operation": "create_order",
        "points_delta": -2,
        "order_id": "ord-001",
        "username": "demo@example.com",
        "created_at": "2026-08-01T10:00:00+08:00"
      }
    ]
  }
}

错误响应

HTTP 状态码	`code`	场景
`400`	`invalid_parameters`	`page` 或 `page_size` 超出范围、`status` 包含未知值等参数错误
`401`	`unauthenticated_request`	认证头部缺失或鉴权失败
`401`	`api_key_disabled`	API Key 已禁用
`403`	`permission_denied`	API Key 没有订单管理权限
`403`	`permission_denied`	详情或流水的套餐包不存在、不属于当前账户，或指定 ID 不是套餐包
`500`	`service_internal_error`	服务器内部错误

400参数错误

json

{
  "code": "invalid_parameters",
  "error": "参数无效"
}

403权限不足

json

{
  "code": "permission_denied",
  "error": "权限不足"
}

更多通用错误码见错误码说明。

业务流程

订单管理

ACME

证书管理

电子签名服务

审核链接

签名意愿

预授权签署（两步调用）

凭据管理（签署 PIN / TOTP）

证书标识与状态

密钥管理

人员信息变更

委托授权（仅企业证书）

组织管理

域名管理

账户设置

套餐包查询

通用说明

认证头部

套餐包状态

套餐包对象

查询套餐包列表

查询参数

请求示例

返回数据

查询套餐包详情

Path 参数

请求示例

返回数据

查询扣除与退款流水

Path 参数

查询参数

请求示例

返回数据

流水类型与点数符号

错误响应

订单管理

ACME

证书管理

组织管理

域名管理

套餐包查询 ​

通用说明 ​

认证头部 ​

套餐包状态 ​

套餐包对象 ​

查询套餐包列表 ​

查询参数 ​

请求示例 ​

返回数据 ​

查询套餐包详情 ​

Path 参数 ​

请求示例 ​

返回数据 ​

查询扣除与退款流水 ​

Path 参数 ​

查询参数 ​

请求示例 ​

返回数据 ​

流水类型与点数符号 ​

错误响应 ​

套餐包查询

通用说明

认证头部

套餐包状态

套餐包对象

查询套餐包列表

查询参数

请求示例

返回数据

查询套餐包详情

Path 参数

请求示例

返回数据

查询扣除与退款流水

Path 参数

查询参数

请求示例

返回数据

流水类型与点数符号

错误响应