API reference
/v1/admin/tcp-billing4 operations
← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures
| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | /v1/admin/tcp-billing | 读取 TCP 流量计费策略与不可变结算快照 | Session |
| POST | /v1/admin/tcp-billing/factor-revisions | 新建仅在目标结算周期开始时生效的 TCP 系数修订 | Session |
| POST | /v1/admin/tcp-billing/settlements | 使用已冻结的最终计量证据结算一个 TCP 流量周期 | Session |
| POST | /v1/admin/tcp-billing/settlements/{settlement_id}/adjustments | 追加退款或全额撤销事实，不修改原结算 | Session |
Contract file：api/control-tcp-billing.openapi.yaml
/v1/admin/tcp-billing读取 TCP 流量计费策略与不可变结算快照
| Status | Description |
|---|---|
200 | TCP 计费概览 Fields： |
401 | 会话无效 |
403 | 权限不足 |
503 | 服务暂不可用 |
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key./v1/admin/tcp-billing/factor-revisions新建仅在目标结算周期开始时生效的 TCP 系数修订
| Name | In | Type | Required | Description |
|---|---|---|---|---|
If-Match | header | string | Yes | expected_head_revision 的强 ETag，例如 "1" |
Idempotency-Key | header | string | Yes | — |
X-Request-ID | header | string | Yes | — |
application/json · Required：Yes
| Name | Type | Required | Description |
|---|---|---|---|
factor | string: 1.0 / 1.1 | Yes | — |
effective_at | string(date-time) | Yes | — |
reason | string | Yes | — |
| Status | Description |
|---|---|
201 | 已建立新修订；相同请求重放通过 Idempotency-Replayed 标识 Fields： |
400 | 输入无效 |
409 | tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict |
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body./v1/admin/tcp-billing/settlements使用已冻结的最终计量证据结算一个 TCP 流量周期
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | — |
X-Request-ID | header | string | Yes | — |
application/json · Required：Yes
| Name | Type | Required | Description |
|---|---|---|---|
tenant_scope_id | string(uuid) | Yes | — |
subscription_id | string(uuid) | Yes | — |
cycle_key | string | Yes | — |
cycle_starts_at | string(date-time) | Yes | — |
cycle_ends_at | string(date-time) | Yes | — |
timezone | string | Yes | — |
metric_version | integer | Yes | — |
source_watermark | string | Yes | — |
finalized_through | string(date-time) | Yes | — |
evidence_sha256 | string | Yes | — |
raw_tcp_bytes | integer(int64) | Yes | — |
| Status | Description |
|---|---|
201 | 已写入不可变结算快照 Fields： |
400 | 输入无效 |
409 | tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict |
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body./v1/admin/tcp-billing/settlements/{settlement_id}/adjustments追加退款或全额撤销事实，不修改原结算
| Name | In | Type | Required | Description |
|---|---|---|---|---|
settlement_id | path | string(uuid) | Yes | — |
Idempotency-Key | header | string | Yes | — |
X-Request-ID | header | string | Yes | — |
application/json · Required：Yes
| Name | Type | Required | Description |
|---|---|---|---|
operation | string: refund / void | Yes | — |
amount_bytes | integer(int64) | Yes | — |
reason | string | Yes | — |
| Status | Description |
|---|---|
201 | 已追加调整事实 Fields： |
400 | 输入无效 |
404 | 资源不存在 |
409 | tcp_billing_revision_conflict 或 tcp_billing_idempotency_conflict |
400 Fix the parameters or body per the field list; do not retry unchanged.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.