接口详情
GET /v1/admin/billing/accounts
List tenant balances for manual administration
- operationId
listBillingAccounts- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.adjustments.manage in a platform scope. Accounts without entries are returned with a zero balance and revision one.
参数
listBillingAccounts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | — |
|---|
scope_ids | query | array<string(uuid)> | 否 | Optional comma-separated set of 1–100 distinct canonical, nonzero tenant scope UUIDs. Intersects the existing search and active-tenant filters before pagination. Unknown, platform and inactive scopes produce no rows; omission preserves the unfiltered behavior. Requires the same billing.adjustments.manage permission as the account list. Reading never creates accounts or postings. |
|---|
响应
listBillingAccounts 响应| 状态码 | 说明 |
|---|
200 | Tenant balance page ordered by tenant name. 字段：items: array<BillingAccount> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/billing/accounts/{id}/ledger
List immutable entries for a selected tenant balance
- operationId
listBillingAccountLedger- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.adjustments.manage in a platform scope. The identifier must resolve to a tenant billing account; a valid tenant account with no postings returns an empty page.
参数
listBillingAccountLedger 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
响应
listBillingAccountLedger 响应| 状态码 | 说明 |
|---|
200 | Newest-first ledger page for the selected tenant account. 字段：items: array<BillingLedgerEntry> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/billing/adjustments
List manual billing adjustment approval requests
- operationId
listBillingAdjustments- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.adjustments.propose or billing.adjustments.approve in a platform scope. Pending and expired are derived from the immutable proposal expiry when no terminal decision exists.
参数
listBillingAdjustments 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
state | query | string: pending / approved / rejected / cancelled / expired | 否 | — |
|---|
响应
listBillingAdjustments 响应| 状态码 | 说明 |
|---|
200 | Newest-first immutable adjustment request page. 字段：items: array<BillingAdjustment> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/billing/adjustments
Propose an MFA-bound manual tenant balance adjustment
- operationId
proposeBillingAdjustment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.adjustments.propose in a platform scope and a max_uses=1 MFA proof bound to the proposal. This operation never changes a balance; a different operator must approve it.
参数
proposeBillingAdjustment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
proposeBillingAdjustment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
account_id | string(uuid) | 是 | — |
|---|
direction | string: credit / debit | 是 | — |
|---|
amount_minor | integer(int64) | 是 | — |
|---|
reason | string | 是 | — |
|---|
expected_account_revision | integer(int64) | 是 | — |
|---|
step_up_token | string | 是 | — |
|---|
响应
proposeBillingAdjustment 响应| 状态码 | 说明 |
|---|
201 | Immutable pending proposal created, or the exact stored response replayed. 字段：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/billing/adjustments/{id}
Read one billing adjustment approval request
- operationId
getBillingAdjustment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getBillingAdjustment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getBillingAdjustment 响应| 状态码 | 说明 |
|---|
200 | Current immutable proposal and optional terminal decision. 字段：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/billing/adjustments/{id}/approve
Approve and atomically post another operator's adjustment
- operationId
approveBillingAdjustment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.adjustments.approve, If-Match revision one, and a separate max_uses=1 MFA proof. Proposal, decision, double-entry postings, balance, audit, and replay receipt commit atomically.
参数
approveBillingAdjustment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
approveBillingAdjustment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
step_up_token | string | 是 | — |
|---|
响应
approveBillingAdjustment 响应| 状态码 | 说明 |
|---|
200 | Approved terminal request or exact stored replay. 字段：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/billing/adjustments/{id}/cancel
Cancel a pending adjustment from the original proposal session
- operationId
cancelBillingAdjustment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
cancelBillingAdjustment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
cancelBillingAdjustment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
cancelBillingAdjustment 响应| 状态码 | 说明 |
|---|
200 | Cancelled terminal request or exact stored replay. 字段：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/billing/adjustments/{id}/reject
Reject another operator's adjustment
- operationId
rejectBillingAdjustment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
rejectBillingAdjustment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
rejectBillingAdjustment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
step_up_token | string | 是 | — |
|---|
响应
rejectBillingAdjustment 响应| 状态码 | 说明 |
|---|
200 | Rejected terminal request or exact stored replay. 字段：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表