版本 2.4.7.20261116085428 · 最新

已购套餐 user-packages

租户已购买的套餐:购买、续费、更换、加购扩展包与用量查看。

点击任一接口,右侧显示对应的调用示例。

套餐鉴权: 用户(部分参数仅管理员)17 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

GET/api/v2/user-packages列出用户套餐

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
sortstring 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
tenant_idsstring 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。
idsstring 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。
package_idinteger 只列这个基础套餐的用户套餐。
package_idsstring 按基础套餐(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
expire_within_daysinteger 只列这么多天内到期(含已到期)的用户套餐。
namestring 用户套餐名称或其基础套餐名称包含(二者是 OR;% _ 按字面匹配)。
customizedboolean true 只列单独改过额度或不跟随基础套餐的已购套餐,false 只列跟随中且没单独改过的。
POST/api/v2/user-packages购买用户套餐

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。

请求体 application/json

字段类型说明
currencystring 售出币种(ISO 4217)= 购买时用户的账户币种;价格快照 price_*_cents 都按它的最小单位。
dry_runboolean 只报价不落库
durationstring 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。
可选值 ["month","quarter","year"]
end_atstring 套餐到期时间。
namestring 名称
package_id必填integer 基础套餐 id
GET/api/v2/user-packages/{id}获取用户套餐

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/user-packages/{id}修改用户套餐

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
backup_group_idinteger 备用线路分组;null = 没有
bandwidth_mbpsinteger 带宽 Mbps,-1 不限
cname_domain_idinteger 接入根域(CNAME 域名);null = 套餐不绑线路
cname_hostnamestring 共用接入名的主机记录(按套餐生成时下属站点/转发共用);空 = 还没有
cname_modePackageCnameMode CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。
可选值 ["site","package"]
connectionsinteger 并发连接数,-1 不限
custom_cc_ruleboolean 可自定义 CC 规则
domainsinteger 域名数(IP 站每站占 1),-1 不限
end_atstring 套餐到期时间。
follow_baseboolean 跟随基础套餐:改基础套餐的配额类字段时自动同步到本套餐(overrides 里的字段除外)
http_portsinteger HTTP/HTTPS 非标端口数(80/443 之外),-1 不限
ip_numinteger 可选 IP 数(「我的 IP」),-1 不限
ip_pool_idinteger 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通
ip_siteboolean 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true)
ip_site_portinteger IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数
l2boolean 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true)
namestring 名称
node_group_idinteger 主线路分组;null = 套餐不绑线路
price_month_centsinteger 购买时锁定的月价
price_quarter_centsinteger 锁定季价
price_year_centsinteger 锁定年价
region_idinteger 区域;null = 套餐不绑线路
reset_to_baseboolean 仅管理员:true = 配额类字段恢复为基础套餐的值、清空 overrides 并恢复跟随(不能与其它字段同时给)
stream_portsinteger 四层转发端口数,-1 不限
traffic_gbinteger 每计费周期流量 GB,-1 不限
waf_enhancedboolean 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false
websocketboolean 可开 WebSocket
DELETE/api/v2/user-packages/{id}删除用户套餐

鉴权: 用户(部分参数仅管理员)

GET/api/v2/user-packages/{id}/change-quotes批量报价更换套餐

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
package_id必填integer[] 候选套餐 id,可重复,至多 100 个。
POST/api/v2/user-packages/{id}/changes更换套餐(升级/降级)

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
dry_runboolean 只报价不落库
package_id必填integer 基础套餐 id
GET/api/v2/user-packages/{id}/ips我的 IP

鉴权: 用户(部分参数仅管理员)

POST/api/v2/user-packages/{id}/ips选择 IP

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
ip_ids必填integer[] 要选的池内 IP ID 列表。
PUT/api/v2/user-packages/{id}/ips/{ip_id}修改已选 IP 的备注

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
remark必填string 备注
DELETE/api/v2/user-packages/{id}/ips/{ip_id}移除已选 IP

鉴权: 用户(部分参数仅管理员)

GET/api/v2/user-packages/{id}/node-groups用户套餐的线路分组

鉴权: 用户(部分参数仅管理员)

POST/api/v2/user-packages/{id}/renewals续费用户套餐

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
dry_runboolean 只报价不落库
duration必填string 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。
可选值 ["month","quarter","year"]
GET/api/v2/user-packages/{id}/upgrades列出已购扩展包

鉴权: 用户(部分参数仅管理员)

POST/api/v2/user-packages/{id}/upgrades加购扩展包

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
amountinteger 份数,默认 1
dry_runboolean 只报价不落库
restore_onlyboolean 纯撤销:只抵已申请下个周期起减少、尚未续费的份数,不收费;这些份数不足 amount 时 409,不转成加购:已随续费排定移除 restore_stale,已被撤销(无排定的挂起)restore_done。
upgrade_id必填integer 要加购的扩展包 id。
DELETE/api/v2/user-packages/{id}/upgrades/{upgrade_id}减少或移除已购扩展包

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
amountinteger 减少的份数;不带 = 整项移除。
GET/api/v2/user-packages/{id}/usage用户套餐用量

鉴权: 用户(部分参数仅管理员)

已购套餐对象

字段类型说明
actionstring 操作类型:购买、续费、更换套餐或加购扩展包。
可选值 ["buy","renew","change","upgrade"]
addedinteger[] 本次新选中的池内 IP ID。
amountinteger 份数,默认 1
amount_centsinteger 正 = 扣款,负 = 退回余额(降级),0 = 不收费(含管理员操作)
backup_group_idinteger 备用线路分组;null = 没有
bandwidth_mbpsinteger 带宽 Mbps,-1 不限
cert_autoIpCertState 平台 IP 证书状态。
cname_domain_idinteger 接入根域(CNAME 域名);null = 套餐不绑线路
cname_hostnamestring 共用接入名的主机记录(按套餐生成时下属站点/转发共用);空 = 还没有
cname_modePackageCnameMode CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。
可选值 ["site","package"]
connectionsinteger 并发连接数,-1 不限
created_atstring 创建时间
只读
currencystring 售出币种(ISO 4217)= 购买时用户的账户币种;价格快照 price_*_cents 都按它的最小单位。
custom_cc_ruleboolean 可自定义 CC 规则
cycle_endstring 本计费周期结束时间。
cycle_startstring 本计费周期开始时间。
domainsinteger 域名数(IP 站每站占 1),-1 不限
dry_runboolean 只报价不落库
durationstring 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。
可选值 ["month","quarter","year"]
enabledboolean 是否启用
end_atstring 套餐到期时间。
feature_statesPackageFeatureStates 平台此刻各套餐付费项是否开通(授权状态不是未开通或已降级);false 的项套餐里含了也暂不生效。
follow_baseboolean 跟随基础套餐:改基础套餐的配额类字段时自动同步到本套餐(overrides 里的字段除外)
只读
http_portsinteger HTTP/HTTPS 非标端口数(80/443 之外),-1 不限
idinteger 记录 ID
只读
in_poolboolean 仍在该套餐当前的 IP 池里。
ipstring IP 地址。
ip_ids必填integer[] 要选的池内 IP ID 列表。
ip_numinteger 可选 IP 数(「我的 IP」),-1 不限
ip_pool_idinteger 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通
ip_siteboolean 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true)
ip_site_portinteger IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数
itemsUserPackageChangeQuote[] 逐候选报价,顺序同请求的 package_id(重复的只报一次)。
l2boolean 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true)
last_durationstring 上次购买/续费的时长(续费弹窗按它预选);null = 管理员按到期时间开通或存量行,不预选。
只读可选值 ["month","quarter","year"]
limitinteger 可选个数,-1 不限。
limitsPackageLimits 有效额度(套餐值 + 扩展包;-1 不限,功能类 0/1)。
namestring 名称
node_group_idinteger 主线路分组;null = 套餐不绑线路
node_stateIpNodeState 持有主节点状态:停用 disabled;否则最近 2 分钟有心跳 online,没有 offline。
可选值 ["online","offline","disabled"]
noticestring 办理后的提示码:traffic_stats_unavailable = 流量统计(ClickHouse)暂不可用,该套餐已因流量用尽停站(513),恢复会延迟到统计恢复后。没有提示不带。
可选值 ["traffic_stats_unavailable"]
order_idinteger 订单 id(扣款/退款时)
overridesPackageQuotaField[] 管理员单独改过且与基础套餐不同的配额类字段,自动同步时跳过
只读
package_idinteger 基础套餐 id
package_namestring 基础套餐名(套餐列表与订单展示用)
只读
periodstring 更换套餐时折算所用的价目
可选值 ["month","quarter","year"]
price_modestring 锁定价来源:base = 基准价;auto = 按汇率折算(续费按当前汇率现算);manual = 套餐给该币设的固定价。
可选值 ["base","auto","manual"]
price_month_centsinteger 购买时锁定的月价
price_quarter_centsinteger 锁定季价
price_year_centsinteger 锁定年价
reasonChangeQuoteReason 不能更换的原因,同更换套餐 422 的字段错误(field/code/message)。
regionstring 所属区域名称。
region_idinteger 区域;null = 套餐不绑线路
remain_cyclesinteger 加购流量类扩展包时计费的周期数(本周期按一整期 + 到期前的后续周期);流量类不按剩余天数折算
remain_daysinteger 折算用的剩余天数
remark必填string 备注
requestsinteger 本计费周期的请求数(已封账小时 + 还没封账的小时现算)。
reset_to_baseboolean 仅管理员:true = 配额类字段恢复为基础套餐的值、清空 overrides 并恢复跟随(不能与其它字段同时给)
restore_onlyboolean 纯撤销:只抵已申请下个周期起减少、尚未续费的份数,不收费;这些份数不足 amount 时 409,不转成加购:已随续费排定移除 restore_stale,已被撤销(无排定的挂起)restore_done。
selectedinteger 已选 IP 个数。
sitesobject[] 本套餐里绑定它的 IP 站点。
start_atstring 套餐生效时间。
statusstring expired = 已到期(名下站点停服 512,续费恢复)
可选值 ["active","expired"]
stream_portsinteger 四层转发端口数,-1 不限
tenant_idinteger 所属租户(用户)ID
只读
traffic_bytesinteger 本计费周期已用计费流量(字节,已乘补偿系数):已封账小时 + 还没封账的小时现算,与流量超额停站同口径。
traffic_gbinteger 每计费周期流量 GB,-1 不限
traffic_limit_gbinteger 有效流量额度(GB,1 GB = 1024³ 字节,含扩展包);-1 不限。
updated_atstring 更新时间
只读
upgrade_id必填integer 要加购的扩展包 id。
user_packageUserPackage 办理后的用户套餐。
user_package_idinteger 办理的用户套餐 id(购买时即新建的那一条,等于 user_package.id);试算(dry_run)没落库,不带。
waf_enhancedboolean 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false
websocketboolean 可开 WebSocket

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

123

123