cdnca

开放接口

/v1/admin/package-addons

6 个接口

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

方法路径摘要认证
GET/v1/admin/package-addons—登录会话
GET/v1/admin/package-addons/assignments—登录会话
GET/v1/admin/package-addons/bindings—登录会话
POST/v1/admin/package-addons/commands—登录会话
GET/v1/admin/package-addons/quote—登录会话
GET/v1/admin/package-addons/subscriptions—登录会话

契约文件：api/control-package-addons.openapi.yaml

接口详情

GET /v1/admin/package-addons

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

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

参数

listPackageAddons 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—

响应

listPackageAddons 响应
状态码说明
200Addon products ordered by descending display ID

字段：total: integer page: integer limit: integer items?: array<Product>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

GET /v1/admin/package-addons/assignments

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

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

参数

listPackageAddonAssignments 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—
userquerystring否Exact user UUID or display ID, or username, email, or phone substring
addon_idquerystring(uuid)否—

响应

listPackageAddonAssignments 响应
状态码说明
200Unrevoked assignments with immutable product snapshots

字段：total: integer page: integer limit: integer items?: array<Assignment>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

GET /v1/admin/package-addons/bindings

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

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

说明（契约原文）

Minimal product choices under the same addon administration permission.

参数

listPackageAddonBindings 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—

响应

listPackageAddonBindings 响应
状态码说明
200Existing catalog product identity and name

字段：total: integer page: integer limit: integer items?: array<object>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/admin/package-addons/commands

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

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

说明（契约原文）

Writes are transactional with audit and actor/scope-bound idempotency receipts. Reusing a key with a different body returns package_addon_conflict. assignment.create is the administrator's free allocation (never charges). assignment.purchase (549) charges the owner tenant's balance at the quoted price on the owner's behalf (the administrator is the recorded actor), creates a paid add-on order, and adds to an existing assignment of the same add-on; a changed price returns package_addon_price_changed, an insufficient available balance returns insufficient_funds (422). Product deletion and assignment deletion retain history. WAF is fixed to one allocation and deletion is rejected while bound policies use it.

参数

commandPackageAddon 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring否Optional correlation ID; the server generates one when absent or invalid.

请求体

application/json · 必填：是

commandPackageAddon 请求体
名称类型必填说明
actionstring: product.create / product.update / product.delete / assignment.create / assignment.purchase / assignment.update / assignment.delete是—
idstring(uuid)否—
expected_revisioninteger否—
productProductFields否—
addon_idstring(uuid)否—
owner_user_idstring(uuid)否—
subscription_idstring(uuid)否—
amountinteger否—
expected_payable_minorinteger否Required by assignment.purchase; the payable amount shown to the operator

响应

commandPackageAddon 响应
状态码说明
200Mutation or exact replay result

字段：id: string(uuid) revision: integer charged_minor: integer order?: Order

409Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
422Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

GET /v1/admin/package-addons/quote

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

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

说明（契约原文）

Price of buying `amount` of an add-on for a sold package now (549). The monthly price is prorated over the remaining days (a started day counts whole, a month is 30 days, half-up to the cent), then the matching automatic package_addon discounts apply (tenant and the owner's user group). Includes the owner tenant's balance and available balance (balance minus active holds).

参数

quotePackageAddonPurchase 参数
名称位置类型必填说明
addon_idquerystring(uuid)是—
subscription_idquerystring(uuid)是—
amountqueryinteger否—

响应

quotePackageAddonPurchase 响应
状态码说明
200Current purchase price

字段：addon_id: string(uuid) subscription_id: string(uuid) tenant_scope_id: string(uuid) owner_user_id: string(uuid) amount: integer monthly_price_minor: integer remaining_days: integer subscription_ends_at: string(date-time) currency: string original_amount_minor: integer discount_amount_minor: integer payable_amount_minor: integer policies: array<AppliedPolicy> balance_minor: integer available_minor: integer merges: boolean

400Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
404Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
409Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET /v1/admin/package-addons/subscriptions

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

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

参数

listPackageAddonEligibleSubscriptions 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—
userquerystring否Exact user UUID or display ID, or username, email, or phone substring
addon_idquerystring(uuid)否—

响应

listPackageAddonEligibleSubscriptions 响应
状态码说明
200Active subscription choices from the authoritative owner projection; addon filter excludes incompatible and duplicate allocations

字段：total: integer page: integer limit: integer items?: array<SubscriptionOption>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表