API 参考文档 - 括彩云

接口概览

开放接口默认使用 JSON 请求和 JSON 响应。部署后请在商业版后台的开发者设置中查看实际 Base URL、密钥权限和调用限制。

Base URL:
https://api.your-domain.com/openapi/v1

Headers:
Authorization: Bearer <API_KEY>
Content-Type: application/json
Accept: application/json

{
  "success": true,
  "request_id": "req_20260710_102030",
  "data": {}
}

鉴权

每个请求都需要携带 API Key。建议在后台为不同业务系统创建独立密钥，并限制权限范围和来源 IP。

curl -X GET "https://api.your-domain.com/openapi/v1/products" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

请求头	是否必填	说明
Authorization	是	格式为 Bearer <API_KEY>。
Idempotency-Key	创建类接口建议填写	业务侧唯一请求号，用于防止网络重试造成重复订单。
X-Kuocai-Signature	启用签名时填写	如后台开启签名校验，请按后台展示的密钥和算法生成。

厂商与产品

用于同步可售厂商、产品目录、套餐规格和价格。业务系统应只展示返回状态为 available 的产品。

GET/vendors获取厂商

返回已接入并允许对外销售的上游厂商列表。

GET/products?category=cdn&vendor_id=aliyun查询产品

按厂商、分类、售卖状态筛选产品和套餐。

GET/products/{product_id}产品详情

获取产品规格、计费周期、价格、库存和开通所需字段。

订单

订单接口用于创建、查询、续费和取消云资源订单。创建订单请携带 Idempotency-Key，并保存返回的 order_id。

POST/orders创建订单

根据产品 ID、购买数量、计费周期和客户信息创建订单。

GET/orders/{order_id}查询状态

返回订单支付状态、开通状态、资源 ID 和异常原因。

POST/orders/{order_id}/renew续费

对已开通资源提交续费请求，具体周期以产品配置为准。

curl -X POST "https://api.your-domain.com/openapi/v1/orders" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: KC202607100001" \
  -d '{
    "client_order_no": "KC202607100001",
    "product_id": "cdn-basic-100g",
    "quantity": 1,
    "billing_cycle": "month",
    "customer": {
      "customer_id": "cus_10086",
      "contact": "ops@example.com"
    },
    "metadata": {
      "domain": "www.example.com"
    }
  }'

CDN 域名

当产品类型为 CDN 时，可通过域名接口提交加速域名、源站配置、证书状态和缓存刷新任务。

POST/domains创建加速域名

提交域名、源站、协议、所属订单和客户信息。

GET/domains/{domain}/status域名状态

查询审核、解析、证书、加速和异常状态。

POST/domains/{domain}/purge刷新缓存

提交 URL 或目录刷新任务，返回任务 ID 供后续查询。

用量

用量接口用于客户报表、费用预警和成本分析。请按最小必要周期拉取，避免高频全量查询。

GET/usage/bandwidth?resource_id={id}&start={time}&end={time}带宽

返回指定资源在时间范围内的带宽曲线。

GET/usage/traffic?resource_id={id}&start={date}&end={date}流量

返回流量汇总和明细，可用于客户账单展示。

GET/resources资源列表

查询客户名下已开通资源、状态、到期时间和关联订单。

账务

账务接口用于同步余额、资金流水、订单账单和对账数据。财务数据建议按天增量同步。

GET/billing/balance?customer_id={id}余额

返回客户可用余额、冻结余额和授信额度。

GET/billing/transactions资金流水

按客户、订单、交易类型和时间范围查询充值、扣费、退款、调账记录。

GET/billing/statements/{statement_id}账单详情

获取已生成账单的汇总金额、明细项目和导出状态。

回调

回调用于异步同步订单开通、支付、失败、用量预警和账务流水。业务系统收到回调后应返回 2xx，失败时平台会按策略重试。

{
  "event": "order.provisioned",
  "request_id": "req_20260710_102030",
  "created_at": "2026-07-10T10:20:30Z",
  "data": {
    "order_id": "ord_10001",
    "client_order_no": "KC202607100001",
    "resource_id": "res_80001",
    "status": "active"
  }
}

事件	触发时机
order.created	订单创建成功。
order.paid	订单完成支付或余额扣费。
order.provisioned	资源开通完成。
order.failed	资源开通失败或被上游拒绝。
billing.transaction.created	新增充值、扣费、退款或调账流水。
usage.threshold_reached	用量达到后台配置的预警阈值。

错误码

接口错误会返回明确 code、message 和 request_id。排查问题时请保留 request_id，便于后台日志检索。

{
  "success": false,
  "request_id": "req_20260710_102030",
  "error": {
    "code": "validation_failed",
    "message": "product_id is required",
    "details": {
      "field": "product_id"
    }
  }
}

HTTP 状态	code	说明
400	invalid_request	请求格式错误或参数无法解析。
401	unauthorized	缺少 API Key 或密钥无效。
403	forbidden	密钥权限不足或来源 IP 不在白名单。
404	not_found	资源、订单或接口路径不存在。
409	conflict	幂等键重复、订单状态冲突或资源已存在。
422	validation_failed	字段校验失败。
429	rate_limited	请求频率超过后台配置限制。
502	upstream_error	上游厂商接口异常或超时。

安全建议

开放接口会涉及订单、余额和资源开通，建议在正式接入前完成以下检查。

不同系统使用不同 API Key，离职、外包交接或系统下线后及时停用。
为高风险接口开启 IP 白名单、最小权限和幂等键校验。
业务系统记录 request_id、client_order_no、order_id 和回调事件 ID。
不要在前端页面、移动端安装包或公开仓库中暴露 API Key。
生产环境只使用 HTTPS，并定期轮换密钥。