cdnca

开放接口

/v1/admin/tcp-billing

4 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/admin/tcp-billing读取 TCP 流量计费策略与不可变结算快照登录会话
POST/v1/admin/tcp-billing/factor-revisions新建仅在目标结算周期开始时生效的 TCP 系数修订登录会话
POST/v1/admin/tcp-billing/settlements使用已冻结的最终计量证据结算一个 TCP 流量周期登录会话
POST/v1/admin/tcp-billing/settlements/{settlement_id}/adjustments追加退款或全额撤销事实，不修改原结算登录会话

契约文件：api/control-tcp-billing.openapi.yaml

接口详情

GET /v1/admin/tcp-billing

读取 TCP 流量计费策略与不可变结算快照

operationId
getTCPBillingOverview
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

getTCPBillingOverview 响应
状态码说明
200TCP 计费概览

字段：current: PolicyRevision scheduled: array<PolicyRevision> history: array<PolicyRevision> settlements: array<Settlement>

401会话无效
403权限不足
503服务暂不可用

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/tcp-billing/factor-revisions

新建仅在目标结算周期开始时生效的 TCP 系数修订

operationId
scheduleTCPBillingFactorRevision
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

scheduleTCPBillingFactorRevision 参数
名称位置类型必填说明
If-Matchheaderstring是expected_head_revision 的强 ETag，例如 "1"
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

scheduleTCPBillingFactorRevision 请求体
名称类型必填说明
factorstring: 1.0 / 1.1是—
effective_atstring(date-time)是—
reasonstring是—

响应

scheduleTCPBillingFactorRevision 响应
状态码说明
201已建立新修订；相同请求重放通过 Idempotency-Replayed 标识

字段：policy: PolicyRevision replayed: boolean

400输入无效
409tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/admin/tcp-billing/settlements

使用已冻结的最终计量证据结算一个 TCP 流量周期

operationId
settleTCPBillingCycle
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

settleTCPBillingCycle 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

settleTCPBillingCycle 请求体
名称类型必填说明
tenant_scope_idstring(uuid)是—
subscription_idstring(uuid)是—
cycle_keystring是—
cycle_starts_atstring(date-time)是—
cycle_ends_atstring(date-time)是—
timezonestring是—
metric_versioninteger是—
source_watermarkstring是—
finalized_throughstring(date-time)是—
evidence_sha256string是—
raw_tcp_bytesinteger(int64)是—

响应

settleTCPBillingCycle 响应
状态码说明
201已写入不可变结算快照

字段：settlement: Settlement replayed: boolean

400输入无效
409tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/admin/tcp-billing/settlements/{settlement_id}/adjustments

追加退款或全额撤销事实，不修改原结算

operationId
adjustTCPBillingSettlement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

adjustTCPBillingSettlement 参数
名称位置类型必填说明
settlement_idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring是—

请求体

application/json · 必填：是

adjustTCPBillingSettlement 请求体
名称类型必填说明
operationstring: refund / void是—
amount_bytesinteger(int64)是—
reasonstring是—

响应

adjustTCPBillingSettlement 响应
状态码说明
201已追加调整事实

字段：adjustment: Adjustment settlement: Settlement replayed: boolean

400输入无效
404资源不存在
409tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表