已购套餐 user-packages
租户已购买的套餐:购买、续费、更换、加购扩展包与用量查看。
点击任一接口,右侧显示对应的调用示例。
鉴权
请求头带 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。
/api/v2/user-packages列出用户套餐
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
tenant_ids | string | 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。 |
ids | string | 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。 |
package_id | integer | 只列这个基础套餐的用户套餐。 |
package_ids | string | 按基础套餐(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。 |
expire_within_days | integer | 只列这么多天内到期(含已到期)的用户套餐。 |
name | string | 用户套餐名称或其基础套餐名称包含(二者是 OR;% _ 按字面匹配)。 |
customized | boolean | true 只列单独改过额度或不跟随基础套餐的已购套餐,false 只列跟随中且没单独改过的。 |
/api/v2/user-packages购买用户套餐
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
currency | string | 售出币种(ISO 4217)= 购买时用户的账户币种;价格快照 price_*_cents 都按它的最小单位。 |
dry_run | boolean | 只报价不落库 |
duration | string | 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。 |
end_at | string | 套餐到期时间。 |
name | string | 名称 |
package_id必填 | integer | 基础套餐 id |
/api/v2/user-packages/{id}获取用户套餐
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}修改用户套餐
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
backup_group_id | integer | 备用线路分组;null = 没有 |
bandwidth_mbps | integer | 带宽 Mbps,-1 不限 |
cname_domain_id | integer | 接入根域(CNAME 域名);null = 套餐不绑线路 |
cname_hostname | string | 共用接入名的主机记录(按套餐生成时下属站点/转发共用);空 = 还没有 |
cname_mode | PackageCnameMode | CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。 |
connections | integer | 并发连接数,-1 不限 |
custom_cc_rule | boolean | 可自定义 CC 规则 |
domains | integer | 域名数(IP 站每站占 1),-1 不限 |
end_at | string | 套餐到期时间。 |
follow_base | boolean | 跟随基础套餐:改基础套餐的配额类字段时自动同步到本套餐(overrides 里的字段除外) |
http_ports | integer | HTTP/HTTPS 非标端口数(80/443 之外),-1 不限 |
ip_num | integer | 可选 IP 数(「我的 IP」),-1 不限 |
ip_pool_id | integer | 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通 |
ip_site | boolean | 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true) |
ip_site_port | integer | IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数 |
l2 | boolean | 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true) |
name | string | 名称 |
node_group_id | integer | 主线路分组;null = 套餐不绑线路 |
price_month_cents | integer | 购买时锁定的月价 |
price_quarter_cents | integer | 锁定季价 |
price_year_cents | integer | 锁定年价 |
region_id | integer | 区域;null = 套餐不绑线路 |
reset_to_base | boolean | 仅管理员:true = 配额类字段恢复为基础套餐的值、清空 overrides 并恢复跟随(不能与其它字段同时给) |
stream_ports | integer | 四层转发端口数,-1 不限 |
traffic_gb | integer | 每计费周期流量 GB,-1 不限 |
waf_enhanced | boolean | 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false |
websocket | boolean | 可开 WebSocket |
/api/v2/user-packages/{id}删除用户套餐
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}/change-quotes批量报价更换套餐
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
package_id必填 | integer[] | 候选套餐 id,可重复,至多 100 个。 |
/api/v2/user-packages/{id}/changes更换套餐(升级/降级)
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
dry_run | boolean | 只报价不落库 |
package_id必填 | integer | 基础套餐 id |
/api/v2/user-packages/{id}/ips我的 IP
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}/ips选择 IP
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
ip_ids必填 | integer[] | 要选的池内 IP ID 列表。 |
/api/v2/user-packages/{id}/ips/{ip_id}修改已选 IP 的备注
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
remark必填 | string | 备注 |
/api/v2/user-packages/{id}/ips/{ip_id}移除已选 IP
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}/node-groups用户套餐的线路分组
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}/renewals续费用户套餐
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
dry_run | boolean | 只报价不落库 |
duration必填 | string | 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。 |
/api/v2/user-packages/{id}/upgrades列出已购扩展包
鉴权: 用户(部分参数仅管理员)
/api/v2/user-packages/{id}/upgrades加购扩展包
鉴权: 用户(部分参数仅管理员)
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
amount | integer | 份数,默认 1 |
dry_run | boolean | 只报价不落库 |
restore_only | boolean | 纯撤销:只抵已申请下个周期起减少、尚未续费的份数,不收费;这些份数不足 amount 时 409,不转成加购:已随续费排定移除 restore_stale,已被撤销(无排定的挂起)restore_done。 |
upgrade_id必填 | integer | 要加购的扩展包 id。 |
/api/v2/user-packages/{id}/upgrades/{upgrade_id}减少或移除已购扩展包
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
amount | integer | 减少的份数;不带 = 整项移除。 |
/api/v2/user-packages/{id}/usage用户套餐用量
鉴权: 用户(部分参数仅管理员)
已购套餐对象
| 字段 | 类型 | 说明 |
|---|---|---|
action | string | 操作类型:购买、续费、更换套餐或加购扩展包。 |
added | integer[] | 本次新选中的池内 IP ID。 |
amount | integer | 份数,默认 1 |
amount_cents | integer | 正 = 扣款,负 = 退回余额(降级),0 = 不收费(含管理员操作) |
backup_group_id | integer | 备用线路分组;null = 没有 |
bandwidth_mbps | integer | 带宽 Mbps,-1 不限 |
cert_auto | IpCertState | 平台 IP 证书状态。 |
cname_domain_id | integer | 接入根域(CNAME 域名);null = 套餐不绑线路 |
cname_hostname | string | 共用接入名的主机记录(按套餐生成时下属站点/转发共用);空 = 还没有 |
cname_mode | PackageCnameMode | CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。 |
connections | integer | 并发连接数,-1 不限 |
created_at | string | 创建时间 |
currency | string | 售出币种(ISO 4217)= 购买时用户的账户币种;价格快照 price_*_cents 都按它的最小单位。 |
custom_cc_rule | boolean | 可自定义 CC 规则 |
cycle_end | string | 本计费周期结束时间。 |
cycle_start | string | 本计费周期开始时间。 |
domains | integer | 域名数(IP 站每站占 1),-1 不限 |
dry_run | boolean | 只报价不落库 |
duration | string | 时长:月/季/年(加 1/3/12 个月,月末按当月最后一天)。 |
enabled | boolean | 是否启用 |
end_at | string | 套餐到期时间。 |
feature_states | PackageFeatureStates | 平台此刻各套餐付费项是否开通(授权状态不是未开通或已降级);false 的项套餐里含了也暂不生效。 |
follow_base | boolean | 跟随基础套餐:改基础套餐的配额类字段时自动同步到本套餐(overrides 里的字段除外) |
http_ports | integer | HTTP/HTTPS 非标端口数(80/443 之外),-1 不限 |
id | integer | 记录 ID |
in_pool | boolean | 仍在该套餐当前的 IP 池里。 |
ip | string | IP 地址。 |
ip_ids必填 | integer[] | 要选的池内 IP ID 列表。 |
ip_num | integer | 可选 IP 数(「我的 IP」),-1 不限 |
ip_pool_id | integer | 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通 |
ip_site | boolean | 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true) |
ip_site_port | integer | IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数 |
items | UserPackageChangeQuote[] | 逐候选报价,顺序同请求的 package_id(重复的只报一次)。 |
l2 | boolean | 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true) |
last_duration | string | 上次购买/续费的时长(续费弹窗按它预选);null = 管理员按到期时间开通或存量行,不预选。 |
limit | integer | 可选个数,-1 不限。 |
limits | PackageLimits | 有效额度(套餐值 + 扩展包;-1 不限,功能类 0/1)。 |
name | string | 名称 |
node_group_id | integer | 主线路分组;null = 套餐不绑线路 |
node_state | IpNodeState | 持有主节点状态:停用 disabled;否则最近 2 分钟有心跳 online,没有 offline。 |
notice | string | 办理后的提示码:traffic_stats_unavailable = 流量统计(ClickHouse)暂不可用,该套餐已因流量用尽停站(513),恢复会延迟到统计恢复后。没有提示不带。 |
order_id | integer | 订单 id(扣款/退款时) |
overrides | PackageQuotaField[] | 管理员单独改过且与基础套餐不同的配额类字段,自动同步时跳过 |
package_id | integer | 基础套餐 id |
package_name | string | 基础套餐名(套餐列表与订单展示用) |
period | string | 更换套餐时折算所用的价目 |
price_mode | string | 锁定价来源:base = 基准价;auto = 按汇率折算(续费按当前汇率现算);manual = 套餐给该币设的固定价。 |
price_month_cents | integer | 购买时锁定的月价 |
price_quarter_cents | integer | 锁定季价 |
price_year_cents | integer | 锁定年价 |
reason | ChangeQuoteReason | 不能更换的原因,同更换套餐 422 的字段错误(field/code/message)。 |
region | string | 所属区域名称。 |
region_id | integer | 区域;null = 套餐不绑线路 |
remain_cycles | integer | 加购流量类扩展包时计费的周期数(本周期按一整期 + 到期前的后续周期);流量类不按剩余天数折算 |
remain_days | integer | 折算用的剩余天数 |
remark必填 | string | 备注 |
requests | integer | 本计费周期的请求数(已封账小时 + 还没封账的小时现算)。 |
reset_to_base | boolean | 仅管理员:true = 配额类字段恢复为基础套餐的值、清空 overrides 并恢复跟随(不能与其它字段同时给) |
restore_only | boolean | 纯撤销:只抵已申请下个周期起减少、尚未续费的份数,不收费;这些份数不足 amount 时 409,不转成加购:已随续费排定移除 restore_stale,已被撤销(无排定的挂起)restore_done。 |
selected | integer | 已选 IP 个数。 |
sites | object[] | 本套餐里绑定它的 IP 站点。 |
start_at | string | 套餐生效时间。 |
status | string | expired = 已到期(名下站点停服 512,续费恢复) |
stream_ports | integer | 四层转发端口数,-1 不限 |
tenant_id | integer | 所属租户(用户)ID |
traffic_bytes | integer | 本计费周期已用计费流量(字节,已乘补偿系数):已封账小时 + 还没封账的小时现算,与流量超额停站同口径。 |
traffic_gb | integer | 每计费周期流量 GB,-1 不限 |
traffic_limit_gb | integer | 有效流量额度(GB,1 GB = 1024³ 字节,含扩展包);-1 不限。 |
updated_at | string | 更新时间 |
upgrade_id必填 | integer | 要加购的扩展包 id。 |
user_package | UserPackage | 办理后的用户套餐。 |
user_package_id | integer | 办理的用户套餐 id(购买时即新建的那一条,等于 user_package.id);试算(dry_run)没落库,不带。 |
waf_enhanced | boolean | 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false |
websocket | boolean | 可开 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"
}