接口详情
GET /v1/traffic-packages/balances
List current-user balances grouped by metering bucket
- operationId
listMyTrafficPackageBalances- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
All quantities are integer bytes. Only migration-051 grants purchased by the current user participate in the aggregation.
参数
listMyTrafficPackageBalances 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
响应
listMyTrafficPackageBalances 响应| 状态码 | 说明 |
|---|
200 | Current-user byte balances grouped by metering bucket. 字段：items: array<Balance> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/traffic-packages/grants
List grants purchased by the authenticated tenant user
- operationId
listMyTrafficPackageGrants- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
Both tenant and owner user are derived from the current principal. tenant_id is rejected.
参数
listMyTrafficPackageGrants 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
page | query | integer | 否 | Page-jump mode (1-based, max 10000, mutually exclusive with cursor). Uses OFFSET within the same frozen snapshot and returns total. |
|---|
status | query | string: active / exhausted / expired / reversed | 否 | Only grants whose current status matches; filtered before paging, and total follows the filter. A cursor is bound to the status it was issued for. |
|---|
响应
listMyTrafficPackageGrants 响应| 状态码 | 说明 |
|---|
200 | Grants visible under the derived or explicit tenant scope. 字段：items: array<Grant> next_cursor?: string total?: integer(int64) |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/traffic-packages/grants/{grant_id}
Read one grant purchased by the authenticated tenant user
- operationId
getMyTrafficPackageGrant- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
Same tenant and owner scope as the grant list; a grant of another tenant or user is 404. No query parameters are accepted.
参数
getMyTrafficPackageGrant 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
grant_id | path | string(uuid) | 是 | — |
|---|
响应
getMyTrafficPackageGrant 响应| 状态码 | 说明 |
|---|
200 | One traffic package grant. 字段：id: string(uuid) owner_user_id?: object product_snapshot_id: string(uuid) product_name: string allowed_package_names: array<string> price_minor: integer(int64) granted_bytes: integer(int64) remaining_bytes: integer(int64) starts_at: string(date-time) expires_at: string(date-time) expiry_timezone: string priority: integer currency: string metering_scope: string metering_version: string status: string: active / exhausted / expired / reversed revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
404 | Resource is absent or not visible in the authorized scope. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/traffic-packages/products
List current products visible to the authenticated tenant
- operationId
listAvailableTrafficPackageProducts- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
Tenant scope is derived from the current principal. The result includes global products and products targeted to that tenant whose latest lifecycle fact is enabled. Disabled products remain in admin and history.
参数
listAvailableTrafficPackageProducts 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
响应
listAvailableTrafficPackageProducts 响应| 状态码 | 说明 |
|---|
200 | Current products or immutable revision history. 字段：items: array<Product> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/traffic-packages/purchases
Traffic package purchase boundary
- operationId
purchaseTrafficPackageThroughCommerce- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
Tenant and buyer are derived from the current principal. This route never calls trafficpackage.Grant directly. Until a reviewed adapter can invoke packagecommercehttp.Service.PurchaseTraffic unchanged, it always returns traffic_package_purchase_unavailable (503) and performs no write.
参数
purchaseTrafficPackageThroughCommerce 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
purchaseTrafficPackageThroughCommerce 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_snapshot_id | string(uuid) | 是 | — |
|---|
promotion | PromotionReference | 否 | — |
|---|
payment | BalancePayment | ProviderPayment | 是 | — |
|---|
响应
purchaseTrafficPackageThroughCommerce 响应| 状态码 | 说明 |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
503 | Reviewed package-commerce purchase wiring is absent; no write occurred. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/traffic-packages/usage-events
List current-user consumption and refund results
- operationId
listMyTrafficPackageUsageEvents- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
Only consume and refund operations are visible. Internal source event keys, request/trace IDs, product snapshots, ledger IDs, billing IDs, and provider payloads are omitted.
参数
listMyTrafficPackageUsageEvents 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
operation | query | string: consume / refund | 否 | — |
|---|
grant_id | query | string(uuid) | 否 | 只看该流量包（授予）的分录，amount_bytes 只计该包承担的部分。 |
|---|
响应
listMyTrafficPackageUsageEvents 响应| 状态码 | 说明 |
|---|
200 | Sanitized current-user usage and refund results. 字段：items: array<UsageEvent> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/traffic-packages/usage-events/{event_id}/allocations
List bounded allocation details for one visible usage event
- operationId
listMyTrafficPackageUsageAllocations- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：traffic_packages.read
说明（契约原文）
Tenant and owner user are derived from the authenticated principal. The command receipt never embeds allocations; clients page this immutable projection explicitly.
参数
listMyTrafficPackageUsageAllocations 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
event_id | path | string(uuid) | 是 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
响应
listMyTrafficPackageUsageAllocations 响应| 状态码 | 说明 |
|---|
200 | Bounded page of immutable allocation details for one visible usage event. 字段：items: array<Allocation> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表