接口详情
GET /v1/reseller/customers
A reseller lists its own customers
- operationId
listResellerCustomers- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.read
说明（契约原文）
Tenant session of an active reseller with reseller.customers.read or reseller.customers.manage. Items are the owner users of tenants whose parent_scope_id is the caller's scope (ManagedUser shape, metadata always set, group always null).
参数
listResellerCustomers 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | Username, name, email, phone or display ID substring. |
|---|
status | query | string: active / disabled | 否 | — |
|---|
响应
listResellerCustomers 响应| 状态码 | 说明 |
|---|
200 | One page of customers. 字段：items: array<ManagedUser> page: integer limit: integer total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/reseller/customers
A reseller opens a customer tenant under itself
- operationId
createResellerCustomer- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
Creates tenant + tenant scope + owner user in one transaction with parent_scope_id = the caller's scope (the 480 guard re-checks the active reseller and customer_limit). Audit identity.user.create in both scopes. 422 reseller_customer_limit when the limit is reached; 409 username_conflict.
参数
createResellerCustomer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createResellerCustomer 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
username | string | 是 | — |
|---|
password | string | 是 | 8 to 1024 printable ASCII characters (no space) with at least two of upper case, lower case, digits and symbols; otherwise password_policy_unmet. |
|---|
display_name | string | 是 | — |
|---|
email | string | null | 否 | — |
|---|
phone | string | null | 否 | — |
|---|
remark | string | null | 否 | — |
|---|
qq | string | null | 否 | — |
|---|
响应
createResellerCustomer 响应| 状态码 | 说明 |
|---|
201 | The customer's owner user. 字段：id: string(uuid) display_id: string scope_id: string(uuid) tenant_id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null status: string: active / disabled role: string: tenant_owner / tenant_viewer group_id: string(uuid) | null(uuid) group_name: string | null metadata?: ManagedUserMetadata verification?: ManagedUserVerification reseller?: ManagedUserReseller revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/reseller/customers/{scope_id}/sites
A reseller lists one of its customers' sites (read only)
- operationId
listResellerCustomerSites- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.read
说明（契约原文）
Tenant session of an active reseller with reseller.customers.read or reseller.customers.manage. The scope must be a customer tenant under the caller's active reseller scope (same check as the reseller package-commerce routes); any other scope, the caller's own included, is 403. Items carry only id, display_id and domain, newest first.
参数
listResellerCustomerSites 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
scope_id | path | string(uuid) | 是 | The customer's tenant scope ID. |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
domain | query | string | 否 | Case-insensitive domain substring. |
|---|
响应
listResellerCustomerSites 响应| 状态码 | 说明 |
|---|
200 | One page of the customer's sites. 字段：items: array<object> page: integer limit: integer total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/reseller/customers/{user_id}/status
A reseller suspends (disabled) or resumes (active) one of its customers
- operationId
setResellerCustomerStatus- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
Only the owner user of the caller's own customer tenant; anything else is 404. Disabling revokes the user's sessions. Audit reseller.customer.status in both scopes. 409 version_conflict on a stale expected_revision.
参数
setResellerCustomerStatus 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
user_id | path | string(uuid) | 是 | — |
|---|
请求体
application/json · 必填：是
setResellerCustomerStatus 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
status | string: active / disabled | 是 | — |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
setResellerCustomerStatus 响应| 状态码 | 说明 |
|---|
200 | The customer's owner user after the change. 字段：id: string(uuid) display_id: string scope_id: string(uuid) tenant_id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null status: string: active / disabled role: string: tenant_owner / tenant_viewer group_id: string(uuid) | null(uuid) group_name: string | null metadata?: ManagedUserMetadata verification?: ManagedUserVerification reseller?: ManagedUserReseller revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表