{ "components": { "schemas": { "AccountClosure": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "AccountClosureInput": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" }, "current_password": { "type": "string" }, "request_id": { "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "confirm", "request_id" ], "type": "object" }, "AccountClosureList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountClosure" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "AccountClosureReview": { "additionalProperties": false, "properties": { "acknowledge_finance": { "type": "boolean" }, "approve": { "type": "boolean" }, "decision": { "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "AccountCorrection": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "type": "string" } }, "required": [ "name", "current_password" ], "type": "object" }, "Activation": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false }, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "device_id": { "description": "产品范围内的设备指纹，通常是 64 位小写十六进制；由 SDK 从当前机器计算。", "type": "string" }, "device_name": { "description": "便于识别设备的名称，不作为安全身份依据。", "type": "string" }, "generation": { "description": "设备绑定代次，用于让旧设备凭证失效。", "type": "integer" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "服务器最后一次收到该设备活动的 UTC 时间。", "format": "date-time", "type": "string" }, "lease_expires_at": { "anyOf": [ { "description": "浮动席位租约到期时间，过期席位可被回收。", "format": "date-time", "type": "string" }, { "description": "浮动席位租约到期时间，过期席位可被回收。", "type": "null" } ], "description": "浮动席位租约到期时间，过期席位可被回收。" }, "license_id": { "description": "许可证 UUID；它不是 lv_lic_ 开头的授权码。", "format": "uuid", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "released_at": { "anyOf": [ { "description": "设备释放时间；尚未释放时为 null。", "format": "date-time", "type": "string" }, { "description": "设备释放时间；尚未释放时为 null。", "type": "null" } ], "description": "设备释放时间；尚未释放时为 null。" }, "session_id": { "description": "浮动运行实例的会话标识；设备绑定模式可能省略。", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "released" ], "type": "string" }, "virtual_machine": { "description": "SDK 是否检测到虚拟机。", "type": "boolean" } }, "required": [ "id", "product_id", "license_id", "device_id", "virtual_machine", "device_name", "status", "generation", "created_at", "last_seen_at", "released_at" ], "type": "object" }, "ActivationList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Activation" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "AdminPlanList": { "additionalProperties": false, "properties": { "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "settings": { "$ref": "#/components/schemas/DefaultPlan" } }, "required": [], "type": "object" }, "AttemptList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "type": "array" }, { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "type": "null" } ], "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。" } }, "required": [], "type": "object" }, "Audit": { "additionalProperties": false, "properties": { "action": { "description": "审计动作标识，例如 product.create、license.renew。", "type": "string" }, "actor_id": { "description": "执行操作的账号 UUID。", "format": "uuid", "type": "string" }, "actor_kind": { "description": "操作来源：session 登录会话、api_key 管理 Key、system 系统任务。", "enum": [ "session", "api_key", "system" ], "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "type": "string" }, "resource_id": { "description": "被操作资源的 UUID。", "maxLength": 36, "type": "string" } }, "required": [ "id", "action", "resource_id", "created_at" ], "type": "object" }, "AuditList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Audit" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" } }, "required": [ "items", "limit", "offset" ], "type": "object" }, "AutoRenewal": { "additionalProperties": false, "properties": { "amount_cents": { "description": "本笔金额，百分之一货币单位；流水可为正（入账）或负（支出）。", "minimum": 0, "type": "integer" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "plan_name": { "description": "方案显示名称。", "type": "string" }, "policy_version": { "description": "保存自动续费时接受的服务政策版本。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "disabled", "enabled", "insufficient_balance", "price_changed", "plan_changed", "plan_unavailable", "account_unavailable" ], "type": "string" }, "term_months": { "description": "合同购买的月数。", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" }, "version": { "description": "自动续费配置的版本号。", "type": "string" } }, "required": [ "mode", "enabled", "plan", "plan_name", "currency", "price_version", "term_months", "amount_cents", "status", "version", "updated_at" ], "type": "object" }, "AutoRenewalInput": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "plan": { "type": "string" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "price_version": { "type": "string" }, "term_months": { "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" } }, "required": [ "enabled", "expected_version" ], "type": "object" }, "AutoRenewalResult": { "additionalProperties": false, "properties": { "next_renewal_at": { "anyOf": [ { "description": "预计下一次续费时间，UTC；无需续费或未启用时可能为 null。", "format": "date-time", "type": "string" }, { "description": "预计下一次续费时间，UTC；无需续费或未启用时可能为 null。", "type": "null" } ], "description": "预计下一次续费时间，UTC；无需续费或未启用时可能为 null。" }, "setting": { "$ref": "#/components/schemas/AutoRenewal", "description": "当前自动续费配置。" } }, "required": [ "setting", "next_renewal_at" ], "type": "object" }, "BatchInput": { "additionalProperties": false, "properties": { "days": { "description": "renew 必填：增加的有效天数（1–36500）；其他操作不使用。", "maximum": 36500, "minimum": 1, "type": "integer" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "entries": { "description": "create 必填：1–100 个客户条目；其他操作省略。", "items": { "additionalProperties": false, "properties": { "customer": { "description": "厂商自定义的客户标识或备注；不等于客户门户登录邮箱。", "maxLength": 120, "type": "string" }, "customer_email": { "description": "客户门户关联邮箱；没有关联时为空字符串。", "maxLength": 254, "type": "string" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] } }, "required": [], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" }, "ids": { "description": "renew、revoke、apply_policy 必填：1–100 个不重复的许可证 UUID；create 时省略。", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "policy_id": { "description": "create 和 apply_policy 必填：目标授权策略 UUID。", "format": "uuid", "type": "string" }, "preview_token": { "description": "预览接口返回的加密确认令牌；apply_policy 必填，有效 600 秒，资源改变后须重新预览。", "type": "string", "writeOnly": true }, "product_id": { "description": "create 必填：新许可证所属产品 UUID。", "format": "uuid", "type": "string" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation" ], "type": "object" }, "BatchItem": { "additionalProperties": false, "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "properties": { "customer": { "description": "厂商自定义的客户标识或备注；不等于客户门户登录邮箱。", "type": "string" }, "customer_email": { "description": "客户门户关联邮箱；没有关联时为空字符串。", "type": "string" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。" }, "first_activated_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。", "type": "null" } ], "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "license_key": { "description": "完整客户授权码，在软件激活时输入。产品初始化代码与示例下载不包含该密钥；离线申请使用 SDK 输出的对应凭证。", "type": "string" }, "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "BatchResult": { "additionalProperties": false, "properties": { "count": { "description": "当前分组的数量，或本次批量成功处理的条数。", "type": "integer" }, "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/BatchItem" }, "type": "array" }, "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "request_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation", "items", "count" ], "type": "object" }, "BillingEmailPreview": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "link": { "format": "uri", "type": "string" }, "reply_to": { "description": "公开支持邮箱及计费邮件的 Reply-To。为空时隐藏联系方式。不改变已有 SMTP From 地址，也不创建收件箱。", "maxLength": 254, "type": "string" }, "subject": { "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "id", "to", "subject", "body", "link" ], "type": "object" }, "BillingEmailTestInput": { "additionalProperties": false, "properties": { "kind": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" }, "locale": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "kind", "to" ], "type": "object" }, "BillingJob": { "additionalProperties": false, "properties": { "attempts": { "description": "任务累计尝试次数。", "type": "integer" }, "available_at": { "description": "任务最早可被执行的 UTC 时间。", "format": "date-time", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "last_error": { "description": "最近一次失败的错误分类；成功或未失败时可为空。", "type": "string" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "pending", "running", "done", "failed" ], "type": "string" } }, "required": [ "id", "month", "status" ], "type": "object" }, "BillingJobList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/BillingJob" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "BillingNotificationPreference": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "locale", "version", "updated_at" ], "type": "object" }, "BillingNotificationPreferenceInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "GET 返回的版本；偏好尚未保存时为空。值过时则返回 BILLING_EMAIL_PREFERENCE_CONFLICT。", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" } }, "required": [ "expected_version" ], "type": "object" }, "BillingNotificationPreferencesResult": { "additionalProperties": false, "properties": { "platform": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "preferences": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "recipient": { "format": "email", "type": "string" } }, "required": [ "preferences", "platform", "recipient" ], "type": "object" }, "BillingNotificationSettings": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "连续覆盖期结束前的提醒阈值，按 24 小时一天计算，升序保存。延迟启动的工作进程只选最近的剩余阈值，不补发所有错过的提醒。", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "公开支持邮箱及计费邮件的 Reply-To。为空时隐藏联系方式。不改变已有 SMTP From 地址，也不创建收件箱。", "maxLength": 254, "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "reminder_days", "support_email", "version" ], "type": "object" }, "BillingNotificationSettingsInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "GET 返回的版本。值过时则返回 BILLING_EMAIL_SETTINGS_CONFLICT。", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "连续覆盖期结束前的提醒阈值，按 24 小时一天计算，升序保存。延迟启动的工作进程只选最近的剩余阈值，不补发所有错过的提醒。", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "公开支持邮箱及计费邮件的 Reply-To。为空时隐藏联系方式。不改变已有 SMTP From 地址，也不创建收件箱。", "maxLength": 254, "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "BundleInput": { "additionalProperties": false, "properties": { "language": { "description": "下载包的 SDK 语言标识。", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } }, "required": [ "language" ], "type": "object" }, "BuyPlan": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "price_version": { "type": "string" }, "renewal": { "default": false, "description": "明确的预付续费。立即收款并延长预付覆盖期。下一个额度周期接在已有付费或赠送覆盖期之后，不重置当前用量。续费使用最近的付费套餐与币种；已过期客户也可以正常购买。", "type": "boolean" }, "request_id": { "maxLength": 80, "type": "string" }, "term_months": { "default": 1, "description": "合约时长。省略时默认为一个月。复用 request_id 时更改时长会返回 409。", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "CSRF": { "additionalProperties": false, "properties": { "csrf_token": { "type": "string" } }, "required": [ "csrf_token" ], "type": "object" }, "CancelCustomerRefund": { "additionalProperties": false, "properties": { "confirm_service_stays_cancelled": { "description": "服务取消已在审核前执行时必填。明确限定范围的待审核申请可撤回，不会停止或恢复服务。", "type": "boolean" } }, "type": "object" }, "ChangePassword": { "additionalProperties": false, "properties": { "current_password": { "description": "12–128 个 UTF-8 字节，而非字符", "type": "string", "writeOnly": true }, "password": { "description": "12–128 个 UTF-8 字节，而非字符", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "必填，并须与密码完全一致", "type": "string", "writeOnly": true } }, "required": [ "current_password", "password", "password_confirmation" ], "type": "object" }, "ClosureExportCredential": { "additionalProperties": false, "properties": { "download_url": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "export_deadline": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ClosureExportLogin": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" } }, "required": [ "email", "current_password" ], "type": "object" }, "CommerceNotice": { "additionalProperties": false, "properties": { "body": { "description": "服务通知正文。", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "effective_at": { "anyOf": [ { "description": "通知所述变更的生效时间；没有时为 null。", "format": "date-time", "type": "string" }, { "description": "通知所述变更的生效时间；没有时为 null。", "type": "null" } ], "description": "通知所述变更的生效时间；没有时为 null。" }, "emailed_at": { "anyOf": [ { "description": "通知邮件发送时间；尚未发送时为 null。", "format": "date-time", "type": "string" }, { "description": "通知邮件发送时间；尚未发送时为 null。", "type": "null" } ], "description": "通知邮件发送时间；尚未发送时为 null。" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "kind": { "description": "流水或通知的类别标识。", "type": "string" }, "read_at": { "anyOf": [ { "description": "通知阅读时间；未读时为 null。", "format": "date-time", "type": "string" }, { "description": "通知阅读时间；未读时为 null。", "type": "null" } ], "description": "通知阅读时间；未读时为 null。" }, "reference": { "description": "关联业务的标识，用于追踪来源。", "type": "string" }, "title": { "description": "服务通知标题。", "type": "string" } }, "required": [], "type": "object" }, "CommerceNoticeList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/CommerceNotice" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CommercePolicy": { "additionalProperties": false, "properties": { "documents": { "properties": { "privacy": { "type": "string" }, "refunds": { "type": "string" }, "terms": { "type": "string" } }, "type": "object" }, "locale": { "type": "string" }, "pending": { "items": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "effective_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" }, "ready": { "type": "boolean" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "CommercePolicyInput": { "additionalProperties": false, "properties": { "expected_version": { "type": "string" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" } }, "required": [ "profile", "published", "expected_version" ], "type": "object" }, "CommerceResult": { "additionalProperties": true, "type": "object" }, "Confirmation": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" } }, "required": [ "confirm" ], "type": "object" }, "Consumption": { "additionalProperties": false, "properties": { "feature": { "description": "本次消耗的功能标识。", "type": "string" }, "limit": { "description": "本周期套餐内的功能次数上限。", "type": "integer" }, "overage": { "description": "本周期累计超过 limit 的次数，不是金额；功能超额上限由授权策略决定。", "type": "integer" }, "period": { "description": "计次周期的标识：按月为 YYYY-MM，按日为 YYYY-MM-DD，终身为 lifetime。日/月边界按 UTC。", "type": "string" }, "quantity": { "description": "本次业务申请的次数，整数 1–1000000000。", "type": "integer" }, "remaining": { "description": "remaining = max(0, limit - used - reserved)，不含超额次数。", "type": "integer" }, "reserved": { "description": "本周期仍有效的预留次数，尚未扣除。", "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "下次重置时间，UTC ISO 8601 日期；终身计次为 null。" }, "used": { "description": "本周期已确认扣除的次数，不包含预留。", "type": "integer" } }, "required": [], "type": "object" }, "ConsumptionResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "设备绑定或运行会话 UUID。保存后用于后续授权请求，不是许可证密钥。", "format": "uuid", "type": "string" }, "consumption": { "$ref": "#/components/schemas/Consumption" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "当前心跳间隔，单位秒；计次不更新签名或心跳调度。", "type": "integer" } }, "required": [ "activation_id", "consumption" ], "type": "object" }, "CustomerAssignment": { "additionalProperties": false, "properties": { "email": { "description": "客户门户登录邮箱；空字符串用于解除关联。", "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "type": "string" } }, "required": [ "email" ], "type": "object" }, "CustomerControlsInput": { "additionalProperties": false, "anyOf": [ { "required": [ "device_enabled" ] }, { "required": [ "api_enabled" ] } ], "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerControlsResult": { "additionalProperties": false, "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [ "device_enabled", "api_enabled" ], "type": "object" }, "CustomerDataExportInput": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "reason": { "maxLength": 500, "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "reason" ], "type": "object" }, "CustomerLicenses": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "email", "items" ], "type": "object" }, "CustomerOverageConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "price_version": { "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" } }, "required": [ "price_version", "policy_version", "terms_accepted", "overage_accepted" ], "type": "object" }, "CustomerRefundInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "明确范围时，在批准时执行取消；省略范围时，明确确认后可立即执行符合条件的取消。", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message", "request_id" ], "type": "object" }, "CustomerRefundQuote": { "anyOf": [ { "$ref": "#/components/schemas/RefundQuote" }, { "$ref": "#/components/schemas/ScopedRefundPreview" } ] }, "CustomerRefundQuoteInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "明确范围时，在批准时执行取消；省略范围时，明确确认后可立即执行符合条件的取消。", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message" ], "type": "object" }, "CustomerReleaseInput": { "additionalProperties": false, "description": "提交前确认释放。send_email 可选择将临时代码加入队列，发送到已验证客户邮箱；generation 防止基于过时设备视图操作。", "properties": { "generation": { "minimum": 1, "type": "integer" }, "send_email": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerReleaseResult": { "additionalProperties": false, "properties": { "email_queued": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "status": { "const": "released", "type": "string" }, "transfer": { "anyOf": [ { "$ref": "#/components/schemas/TransferCode" }, { "type": "null" } ] } }, "required": [ "id", "status", "transfer", "email_queued" ], "type": "object" }, "CustomerSession": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [], "type": "object" }, "DatabaseStatus": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "database": { "type": "string" }, "host": { "type": "string" }, "open_connections": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "connected", "host", "database" ], "type": "object" }, "DefaultPlan": { "additionalProperties": false, "properties": { "allow_customer_api_overage": { "default": false, "description": "只允许客户选择 API 超额设置，与设备权限独立。为 false 时，API 用量遵循管理员规则。无限 API 仍保持无限。", "type": "boolean" }, "allow_customer_device_overage": { "default": false, "description": "只允许客户选择设备超额设置。为 false 时，设备用量遵循管理员规则，忽略已保存的客户设备偏好，直到重新启用。", "type": "boolean" }, "default_currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "default_plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, "required": [ "default_plan", "default_currency" ], "type": "object" }, "DeliveryList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "type": "null" } ], "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [], "type": "object" }, "DeviceProfile": { "additionalProperties": false, "properties": { "hardware_id": { "description": "基于产品和硬件身份的 SHA-256；无法取得时为空字符串，要求硬件的策略将拒绝。", "type": "string" }, "platform": { "description": "本机操作系统：windows、linux 或 darwin（macOS）。", "enum": [ "windows", "linux", "darwin" ], "type": "string" }, "system_id": { "description": "基于产品和系统身份的 SHA-256，小写十六进制 64 字符。", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "const": 3, "description": "设备指纹协议版本，当前固定为 3。", "type": "integer" }, "virtual_machine": { "description": "SDK 检测到是否在虚拟机中运行，布尔值。", "type": "boolean" } }, "required": [ "version", "system_id", "hardware_id", "virtual_machine", "platform" ], "type": "object" }, "DeviceReleaseOperation": { "additionalProperties": false, "properties": { "activation_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "attempts": { "description": "Licentivo 保留的处理失败尝试次数。", "type": "integer" }, "available_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, { "description": "操作完成时间；待处理时省略。", "type": "null" } ], "description": "操作完成时间；待处理时省略。" }, "connection_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "created_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "error_code": { "description": "稳定的处理或审核原因；成功后为空。", "type": "string" }, "expected_generation": { "description": "预期设备绑定代次，在撤销事务中比较。", "minimum": 1, "type": "integer" }, "license_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "operation_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "source": { "description": "此次撤销操作的来源。", "enum": [ "logout", "launch", "admin" ], "type": "string" }, "status": { "description": "由服务端管理的当前生命周期或处理状态。", "enum": [ "pending", "succeeded", "stale", "manual_review" ], "type": "string" } }, "required": [ "operation_id", "license_id", "activation_id", "expected_generation", "source", "status" ], "type": "object" }, "EligibleReleases": { "additionalProperties": false, "properties": { "authorization": { "additionalProperties": true, "type": "object" }, "items": { "items": { "$ref": "#/components/schemas/Release" }, "type": "array" } }, "required": [], "type": "object" }, "Email": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [ "email" ], "type": "object" }, "EmailChangeConfirmation": { "additionalProperties": false, "properties": { "token": { "maxLength": 2048, "minLength": 32, "type": "string" } }, "required": [ "token" ], "type": "object" }, "Empty": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "EmptyRefundPreviewInput": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "Error": { "additionalProperties": false, "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "properties": { "error": { "additionalProperties": false, "description": "错误对象或一次投递的错误分类，见子字段或当前类型。", "properties": { "code": { "description": "稳定的错误码，供程序分支判断。", "type": "string" }, "message": { "description": "用于阅读的错误原因，不应依赖此文本做程序判断。", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "服务器为本次 HTTP 请求生成的 UUID，用于查日志。不是许可证 ID，也不是幂等请求编号。", "format": "uuid", "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "FeatureReservation": { "additionalProperties": false, "properties": { "consumption": { "$ref": "#/components/schemas/Consumption", "description": "这次功能计次的回执，包含本次扣除、累计用量、剩余额度和下次重置时间。" }, "expires_at": { "description": "预留的截止时间，UTC；必须在此之前确认。", "format": "date-time", "type": "string" }, "operation_id": { "description": "最初预留时使用的业务编号，重试保持不变。", "type": "string" }, "reservation_id": { "description": "预留编号，确认或取消时传入此值。", "format": "uuid", "type": "string" }, "status": { "description": "pending 可执行业务；committed 已扣次；canceled 和 expired 已关闭且未扣次。", "enum": [ "pending", "committed", "canceled", "expired" ], "type": "string" } }, "required": [ "reservation_id", "operation_id", "status", "expires_at", "consumption" ], "type": "object" }, "FeatureUsage": { "additionalProperties": false, "properties": { "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "type": "string" }, "license_id": { "description": "许可证 UUID；它不是 lv_lic_ 开头的授权码。", "format": "uuid", "type": "string" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "type": "string" }, "quantity": { "description": "该功能在此周期累计使用的次数。", "type": "integer" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [ "license_id", "feature", "period", "quantity", "updated_at" ], "type": "object" }, "ForumAuthor": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ForumImage": { "additionalProperties": false, "properties": { "height": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" }, "width": { "type": "integer" } }, "required": [ "id", "url", "width", "height", "size" ], "type": "object" }, "ForumModerationInput": { "additionalProperties": false, "description": "要求平台管理员浏览器会话。至少提供一个字段；省略字段保留当前值。置顶适用于已发布或隐藏主题，不会恢复已删除内容。", "minProperties": 1, "properties": { "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": [], "type": "object" }, "ForumReply": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "body", "author", "images", "created_at", "updated_at", "can_edit", "can_delete" ], "type": "object" }, "ForumReplyInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true } }, "required": [ "body" ], "type": "object" }, "ForumTopic": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_moderate": { "type": "boolean" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "last_reply_at": { "format": "date-time", "type": "string" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "reply_count": { "type": "integer" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "body", "category", "language", "locked", "pinned", "author", "images", "reply_count", "created_at", "updated_at", "last_reply_at", "can_edit", "can_delete", "can_moderate" ], "type": "object" }, "ForumTopicDetail": { "additionalProperties": false, "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "replies": { "items": { "$ref": "#/components/schemas/ForumReply" }, "type": "array" }, "topic": { "$ref": "#/components/schemas/ForumTopic" }, "total": { "type": "integer" } }, "required": [ "topic", "replies", "total", "limit", "offset" ], "type": "object" }, "ForumTopicInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "title": { "maxLength": 180, "minLength": 2, "type": "string" } }, "required": [ "title", "body", "category", "language" ], "type": "object" }, "ForumTopicList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ForumTopic" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ForumTranslationInput": { "additionalProperties": false, "properties": { "reply_id": { "format": "uuid", "type": "string" }, "target_language": { "description": "选择 GET /forum/translation 返回的语言。", "type": "string" } }, "required": [ "target_language" ], "type": "object" }, "ForumTranslationResult": { "additionalProperties": false, "properties": { "body": { "description": "翻译后的纯文本。使用 textContent 渲染，绝不能作为 HTML。", "type": "string" }, "cached": { "type": "boolean" }, "provider": { "type": "string" }, "source_language": { "description": "DeepL 报告的检测到的原文语言。", "type": "string" }, "target_language": { "description": "所选的提供方目标语言。", "type": "string" }, "title": { "description": "翻译后的主题标题；回复时为空。", "type": "string" } }, "required": [ "title", "body", "source_language", "target_language", "cached", "provider" ], "type": "object" }, "Health": { "additionalProperties": false, "properties": { "status": { "enum": [ "ok", "ready" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ID": { "additionalProperties": false, "properties": { "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "Invite": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" } }, "required": [ "email", "name", "role" ], "type": "object" }, "Invited": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "active_devices": { "description": "该统计范围内按产品和设备去重的活跃设备数。", "type": "integer" }, "base_covered": { "description": "本期基础费用是否已由已购套餐覆盖。", "type": "boolean" }, "base_micros": { "description": "基础金额，百万分之一货币单位。", "type": "integer" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "finalized_at": { "anyOf": [ { "description": "账单确认时间；尚未确认时为 null。", "format": "date-time", "type": "string" }, { "description": "账单确认时间；尚未确认时为 null。", "type": "null" } ], "description": "账单确认时间；尚未确认时为 null。" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "overage_devices": { "description": "超过所含额度的设备数量。", "type": "integer" }, "paid_at": { "anyOf": [ { "description": "账单付款时间；未付款时为 null。", "format": "date-time", "type": "string" }, { "description": "账单付款时间；未付款时为 null。", "type": "null" } ], "description": "账单付款时间；未付款时为 null。" }, "payment_mode": { "description": "收款环境：sandbox 测试、live 正式。", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "plan_name": { "description": "方案显示名称。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "refunded_at": { "anyOf": [ { "description": "账单退款时间；未退款时为 null。", "format": "date-time", "type": "string" }, { "description": "账单退款时间；未退款时为 null。", "type": "null" } ], "description": "账单退款时间；未退款时为 null。" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "draft", "finalized", "void" ], "type": "string" }, "total_cents": { "description": "账单合计，百分之一货币单位；付款状态见 paid_at。", "type": "integer" }, "total_micros": { "description": "账单合计，百万分之一货币单位。", "type": "integer" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" }, "voided_at": { "anyOf": [ { "description": "账单作废时间；未作废时为 null。", "format": "date-time", "type": "string" }, { "description": "账单作废时间；未作废时为 null。", "type": "null" } ], "description": "账单作废时间；未作废时为 null。" } }, "required": [ "id", "month", "currency", "status", "total_cents" ], "type": "object" }, "InvoiceList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Key": { "additionalProperties": false, "properties": { "allow_http": { "description": "允许此密钥注册或更新 HTTP Launch 站点来源，包括测试服务器域名、私有 IP 地址和内部主机名。Licentivo API 请求仍使用 HTTPS。", "type": "boolean" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "expires_at": { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "prefix": { "description": "管理 Key 的前 14 个字符，仅供识别，不能代替完整 Key。", "type": "string" }, "revoked": { "description": "是否已吊销；过期是否失效还需检查 expires_at。", "type": "boolean" }, "scope": { "description": "read 可读取；write 同时允许读取与写入。写入还要求 Key 创建者当前为有效 Owner。", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "id", "prefix", "scope", "revoked", "allow_http" ], "type": "object" }, "KeyBundle": { "additionalProperties": false, "properties": { "keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "format": "uuid", "type": "string" }, "protocol": { "type": "string" }, "runtime_policy_source": { "const": "current_license_policy", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "KeyCreate": { "additionalProperties": false, "properties": { "allow_http": { "default": false, "description": "允许此密钥注册或更新 HTTP Launch 站点来源，包括测试服务器域名、私有 IP 地址和内部主机名。Licentivo API 请求仍使用 HTTPS。", "type": "boolean" }, "expires_days": { "description": "从创建时起多少天后失效，1–365 天。", "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "scope": { "description": "read 可读取；write 同时允许读取与写入。写入还要求 Key 创建者当前为有效 Owner。", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "name", "scope", "expires_days" ], "type": "object" }, "KeyList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Key" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items" ], "type": "object" }, "KeyRotated": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "properties": { "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "key": { "description": "Full secret returned on creation or rotation. Owners may also view saved license keys on demand in a browser session. Store privately; the prefix cannot authenticate.", "type": "string" }, "prefix": { "description": "管理 Key 的前 14 个字符，仅供识别，不能代替完整 Key。", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeySecret": { "additionalProperties": false, "example": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "properties": { "allow_http": { "description": "允许此密钥注册或更新 HTTP Launch 站点来源，包括测试服务器域名、私有 IP 地址和内部主机名。Licentivo API 请求仍使用 HTTPS。", "type": "boolean" }, "expires_at": { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "key": { "description": "完整秘密，仅创建或轮换时返回。服务器应私密保存，不能用 prefix 代替。", "type": "string" }, "prefix": { "description": "管理 Key 的前 14 个字符，仅供识别，不能代替完整 Key。", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeyUpdate": { "additionalProperties": false, "properties": { "allow_http": { "description": "允许此密钥注册或更新 HTTP Launch 站点来源，包括测试服务器域名、私有 IP 地址和内部主机名。Licentivo API 请求仍使用 HTTPS。", "type": "boolean" } }, "required": [ "allow_http" ], "type": "object" }, "KeyUpdated": { "additionalProperties": false, "properties": { "allow_http": { "description": "允许此密钥注册或更新 HTTP Launch 站点来源，包括测试服务器域名、私有 IP 地址和内部主机名。Licentivo API 请求仍使用 HTTPS。", "type": "boolean" }, "id": { "description": "Unique record identifier.", "format": "uuid", "type": "string" } }, "required": [ "id", "allow_http" ], "type": "object" }, "LaunchCommerceEvent": { "additionalProperties": false, "properties": { "account_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "launch_product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "legacy_license_id": { "description": "仅用于 entitlement.migrated。保留已有许可证、到期时间、扩展能力和设备记录；旧密钥及设备凭据失去运行时访问权限。", "format": "uuid", "type": "string" }, "plan_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "type": { "description": "带版本的完整快照商业事件类型。", "enum": [ "entitlement.created", "entitlement.renewed", "entitlement.upgraded", "entitlement.downgraded", "entitlement.refunded", "entitlement.suspended", "entitlement.expired", "entitlement.resumed", "entitlement.migrated" ], "type": "string" }, "valid_from": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "valid_until": { "anyOf": [ { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, { "description": "绝对购买到期时间，使用 UTC；仅永久策略可为 null。", "type": "null" } ], "description": "绝对购买到期时间，使用 UTC；仅永久策略可为 null。" }, "version": { "description": "此权益引用的单调递增完整快照版本，不是投递尝试次数。", "minimum": 1, "type": "integer" } }, "required": [ "event_id", "environment", "type", "entitlement_ref", "account_ref", "launch_product_id", "plan_ref", "version", "valid_from" ], "type": "object" }, "LaunchConnection": { "additionalProperties": false, "properties": { "audience": { "description": "Launch 登录断言的精确预期接收方。", "type": "string" }, "created_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "enabled": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "description": "服务端选择的在线验证间隔，单位秒。", "type": "integer" }, "id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "issuer": { "description": "精确的受信 Launch 来源。", "type": "string" }, "offline_seconds": { "description": "允许的有限离线间隔，单位秒；为零时必须在线验证。", "type": "integer" }, "session_seconds": { "description": "授权会话的最长有效时间，单位秒。", "type": "integer" }, "updated_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" } }, "required": [ "id", "issuer", "audience", "environment", "enabled" ], "type": "object" }, "LaunchConnectionInput": { "additionalProperties": false, "properties": { "audience": { "description": "Launch 登录断言的精确预期接收方。", "maxLength": 255, "minLength": 1, "type": "string" }, "enabled": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "default": 600, "description": "服务端选择的在线验证间隔，单位秒。", "maximum": 86400, "minimum": 600, "type": "integer" }, "issuer": { "description": "精确的受信 Launch 来源，不带路径或末尾斜杠。默认使用 HTTPS。使用 HTTP 时，发起请求的 API 密钥必须启用 allow_http；支持私有 IP 和内部主机名。不会向此来源发起回调或发现请求。", "format": "uri", "type": "string" }, "offline_seconds": { "default": 0, "description": "0 表示必须在线验证。正数离线有效期必须至少为 3 × heartbeat_seconds。账号授权不允许永久离线。", "maximum": 86400, "minimum": 0, "type": "integer" }, "public_keys": { "additionalProperties": { "description": "固定受信的规范 Base64URL 编码 Ed25519 公钥，32 字节。", "type": "string" }, "description": "以密钥 ID 为索引的完整受信 Launch Ed25519 公钥集合。", "maxProperties": 16, "minProperties": 1, "type": "object" }, "session_seconds": { "default": 86400, "description": "至少为 3 × heartbeat_seconds。", "maximum": 2592000, "minimum": 1800, "type": "integer" } }, "required": [ "issuer", "audience", "environment", "public_keys", "enabled" ], "type": "object" }, "LaunchDeviceReleaseInput": { "additionalProperties": false, "properties": { "account_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "expected_generation": { "description": "预期设备绑定代次，在撤销事务中比较。", "minimum": 1, "type": "integer" }, "operation_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, "required": [ "operation_id", "account_ref", "entitlement_ref", "environment", "expected_generation" ], "type": "object" }, "LaunchEvent": { "additionalProperties": false, "properties": { "applied_at": { "anyOf": [ { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, { "description": "快照应用成功或判定为 stale 的时间。", "type": "null" } ], "description": "快照应用成功或判定为 stale 的时间。" }, "attempts": { "description": "Licentivo 保留的处理失败尝试次数。", "type": "integer" }, "available_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "connection_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "created_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "error_code": { "description": "稳定的处理或审核原因；成功后为空。", "type": "string" }, "event_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "status": { "description": "由服务端管理的当前生命周期或处理状态。", "enum": [ "pending", "applied", "stale", "manual_review" ], "type": "string" } }, "required": [ "connection_id", "event_id", "status", "attempts", "available_at" ], "type": "object" }, "LaunchExchangeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "上次成功激活返回的 data.activation_id。除首次 activate 外，验证、心跳、计次、解绑必须填写。", "format": "uuid", "type": "string" }, "app_version": { "description": "当前软件版本，格式为 major.minor.patch，如 1.0.0。有维护期或版本范围限制时必须填写，不能把版本冒充为旧版。", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "SDK 根据产品和本机系统、硬件身份计算的 64 位小写十六进制 SHA-256。不能任意填写固定值。", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "控制台显示的设备名称，最多 120 字符，不决定设备身份。", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK 自动生成的本机身份资料。策略要求硬件、拒绝虚拟机或启用硬件迁移时按策略提供。" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "本次消耗的功能标识。", "maxLength": 64, "type": "string" }, "identity_token": { "description": "一次性、带类型的 Ed25519 Launch 身份 JWT；不信任任何权益声明作为购买权限。", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "本次 Launch 授权操作的 Launch 连接 ID。", "format": "uuid", "type": "string" }, "license_key": { "const": "", "description": "省略或留空。账号交换绝不使用长期许可证密钥。", "type": "string" }, "product_id": { "description": "产品 UUID，必须与许可证所属产品一致。", "format": "uuid", "type": "string" }, "quantity": { "description": "本次业务申请的次数，整数 1–1000000000。", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "SDK 能力协商。当前绑定尚未保留票据时，请求仅限解绑的退出票据；已保留有效退出票据时省略，稳定状态的心跳因此不增加票据查询。", "type": "boolean" }, "reservation_id": { "description": "预留编号，确认或取消时传入此值。", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "可选预留有效秒数，30–3600；默认 900，周期重置时会提前结束。", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "浮动授权必填：每个运行实例新建一个 UUID，同一实例的后续请求沿用。绑定设备模式可省略。", "format": "uuid", "type": "string" } }, "required": [ "product_id", "device_id", "identity_token", "launch_connection_id", "environment" ], "type": "object" }, "LaunchPlanMappingInput": { "additionalProperties": false, "properties": { "launch_product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "policy_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "policy_version": { "description": "映射授权策略的预期当前版本。", "minimum": 1, "type": "integer" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, "required": [ "launch_product_id", "product_id", "policy_id", "policy_version" ], "type": "object" }, "LaunchSessionRevocation": { "additionalProperties": false, "properties": { "account_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "completed_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "connection_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "created_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "reason": { "description": "可选审计原因，空值与省略等价。forced_logout 要求 session 范围；password_changed 和 account_disabled 要求 account 范围。", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "released_devices": { "description": "已释放的当前设备绑定代次数量；保留较新的登录。", "minimum": 0, "type": "integer" }, "revoked_before": { "description": "account 范围返回。新认证的 auth_time 必须严格大于此 UTC 截止时间，按 Unix 秒精度比较。此前已知的 sid 永久保持撤销。", "format": "date-time", "type": "string" }, "revoked_credentials": { "description": "原事件新撤销的设备凭据数量。", "minimum": 0, "type": "integer" }, "revoked_sessions": { "description": "原事件新撤销的授权会话数量。", "minimum": 0, "type": "integer" }, "scope": { "description": "session 撤销此连接内某个 Launch sid 对应的所有产品和设备会话；account 撤销已有账号会话，并拒绝旧认证断言。", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "session 范围必填且不能为空；account 范围省略或留空。这是 Launch 登录 sid，不是 Licentivo 授权会话或设备 ID。", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" }, "status": { "const": "succeeded", "description": "由服务端管理的当前生命周期或处理状态。", "type": "string" } }, "required": [ "connection_id", "event_id", "environment", "account_ref", "scope", "status", "revoked_sessions", "revoked_credentials", "released_devices", "created_at", "completed_at" ], "type": "object" }, "LaunchSessionRevocationInput": { "additionalProperties": false, "oneOf": [ { "properties": { "reason": { "enum": [ "", "forced_logout" ] }, "scope": { "const": "session" }, "sid": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sid" ] }, { "properties": { "reason": { "enum": [ "", "password_changed", "account_disabled" ] }, "scope": { "const": "account" }, "sid": { "const": "" } } } ], "properties": { "account_ref": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "可选一致性检查。省略或留空时使用连接环境；非空时必须匹配。此字段不会改变计费，也不提供免费的授权测试。", "enum": [ "", "live", "sandbox" ], "type": "string" }, "event_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "reason": { "description": "可选审计原因，空值与省略等价。forced_logout 要求 session 范围；password_changed 和 account_disabled 要求 account 范围。", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "scope": { "description": "session 撤销此连接内某个 Launch sid 对应的所有产品和设备会话；account 撤销已有账号会话，并拒绝旧认证断言。", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "session 范围必填且不能为空；account 范围省略或留空。这是 Launch 登录 sid，不是 Licentivo 授权会话或设备 ID。", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" } }, "required": [ "event_id", "account_ref", "scope" ], "type": "object" }, "Lease": { "additionalProperties": false, "properties": { "key_id": { "description": "签名公钥的 UUID，必须存在于产品的 trusted_keys 中。", "format": "uuid", "type": "string" }, "payload": { "description": "原始授权 JSON 字节的 Base64URL 编码（不带填充）。解码仅用于阅读；必须验证签名。", "type": "string" }, "signature": { "description": "Ed25519 签名的 Base64URL 编码。验签使用 LicenovaLease/v1\\n 前缀与 payload 原始字节，不能重新序列化 JSON。", "type": "string" }, "version": { "const": 1, "description": "签名封装协议版本，当前固定为 1。", "type": "integer" } }, "required": [ "version", "key_id", "payload", "signature" ], "type": "object" }, "LeaseClaims": { "additionalProperties": false, "description": "解码原始签名内容字节。缺少 runtime_policy 时，TTL 最多为 86400 秒；否则执行签名中的策略。未验证签名和上下文时，绝不能信任 payload。", "properties": { "activation_id": { "format": "uuid", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/SignedCapabilities" }, "device_id": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "expires_at": { "maximum": 253402300799, "type": "integer" }, "features": { "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "issued_at": { "type": "integer" }, "key_id": { "format": "uuid", "type": "string" }, "license_id": { "format": "uuid", "type": "string" }, "max_devices": { "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "offline_request_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "runtime_policy": { "$ref": "#/components/schemas/RuntimePolicy" }, "tenant_id": { "format": "uuid", "type": "string" }, "version": { "const": 1, "type": "integer" } }, "required": [], "type": "object" }, "LegalAcceptance": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "type": "string" }, "api_overage_accepted": { "type": "boolean" }, "device_overage_accepted": { "type": "boolean" }, "digest": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "type": "string" }, "overage_accepted": { "type": "boolean" }, "price_version": { "type": "string" }, "reference": { "type": "string" }, "scope": { "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "LegalAcceptanceList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/LegalAcceptance" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "LegalConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" } }, "required": [], "type": "object" }, "License": { "additionalProperties": false, "description": "首次成功激活前，到期时间为 null。时长在签发时形成快照；再次激活绝不重置。", "example": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "customer": { "description": "厂商自定义的客户标识或备注；不等于客户门户登录邮箱。", "type": "string" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "first_activated_at": { "anyOf": [ { "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。", "format": "date-time", "type": "string" }, { "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。", "type": "null" } ], "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "key_prefix": { "description": "授权码的短前缀，仅供识别和搜索，不能用于授权。", "type": "string" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "policy_id": { "description": "授权策略 UUID；签发时必须与产品对应。", "format": "uuid", "type": "string" }, "policy_version": { "description": "策略版本号；修改完整规则时必须带上刚读取的版本以防覆盖他人修改。", "type": "integer" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [ "id", "product_id", "key_prefix", "mode", "status" ], "type": "object" }, "LicenseCapabilities": { "additionalProperties": false, "example": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "license_id": { "description": "许可证 UUID；它不是 lv_lic_ 开头的授权码。", "format": "uuid", "type": "string" }, "license_model": { "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "从首次激活起的版本维护天数；0 表示不限制维护期限。", "type": "integer" }, "maintenance_until": { "anyOf": [ { "description": "可获取新版本的维护截止时间；未激活或不限制时可能为 null。", "format": "date-time", "type": "string" }, { "description": "可获取新版本的维护截止时间；未激活或不限制时可能为 null。", "type": "null" } ], "description": "可获取新版本的维护截止时间；未激活或不限制时可能为 null。" }, "max_version": { "description": "最高允许的软件版本；空字符串不设上限。", "type": "string" }, "min_version": { "description": "最低允许的软件版本；空字符串不设下限。", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [ "license_id", "product_id", "license_model", "maintenance_days", "maintenance_until", "min_version", "max_version", "updated_at" ], "type": "object" }, "LicenseCapabilityResult": { "additionalProperties": false, "example": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "properties": { "customer_email": { "description": "客户门户关联邮箱；没有关联时为空字符串。", "type": "string" }, "license": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "许可证的扩展权益快照。" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每个计次周期内包含的功能使用次数上限，不是分页条数。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "type": "array" }, "usage": { "anyOf": [ { "description": "功能计次的实际用量记录；无记录时可能为 null。", "items": { "$ref": "#/components/schemas/FeatureUsage" }, "type": "array" }, { "description": "功能计次的实际用量记录；无记录时可能为 null。", "type": "null" } ], "description": "功能计次的实际用量记录；无记录时可能为 null。" } }, "required": [], "type": "object" }, "LicenseCreate": { "additionalProperties": false, "description": "使用许可证自身的 duration_days 签发。定期或试用许可证要求 1–36500 天；永久许可证要求省略或 null。从首次成功激活开始计时。", "properties": { "customer": { "description": "客户名称或订单标识，用于后台检索，最多 254 字符。", "maxLength": 254, "type": "string" }, "customer_email": { "description": "客户门户关联邮箱；没有关联时为空字符串。", "format": "email", "maxLength": 254, "type": "string" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "policy_id": { "description": "该产品下的授权策略 UUID。", "format": "uuid", "type": "string" }, "product_id": { "description": "产品 UUID。", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id" ], "type": "object" }, "LicenseKeyReveal": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "key": { "description": "Original full license key, revealed only to a current Owner session.", "type": "string" }, "key_prefix": { "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/License" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "LicenseSecret": { "additionalProperties": false, "example": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "properties": { "duration_days": { "description": "首次激活后享有的有效天数。永久许可证为 null。", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间，UTC ISO 8601；首次激活前为 null，永久许可证也为 null。" }, "first_activated_at": { "anyOf": [ { "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。", "format": "date-time", "type": "string" }, { "description": "首次成功激活时间；未激活时为 null，续期或换机不会重置。", "type": "null" } ], "description": "首次成功激活时间，UTC ISO 8601；尚未激活为 null。换机不重置。" }, "id": { "description": "许可证记录 UUID，管理查询、续期或吊销时使用。不是激活码。", "format": "uuid", "type": "string" }, "key": { "description": "完整许可证密钥，以 lv_lic_ 开头，只在签发时显示一次，厂商需要私密保存并交给对应客户。", "type": "string" }, "key_prefix": { "description": "完整密钥的前缀，供后台识别，不能用于激活。", "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseUpdate": { "additionalProperties": false, "properties": { "customer": { "description": "厂商自定义的客户标识或备注；不等于客户门户登录邮箱。", "maxLength": 254, "type": "string" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "maximum": 10000, "minimum": 1, "type": "integer" }, "policy_id": { "description": "将此许可证切换到同一产品下的策略。更换策略时需要当前有效的 preview_token；保留许可证密钥、原有效期和已用次数。", "format": "uuid", "type": "string" }, "preview_token": { "description": "POST /licenses/policy-preview 为此许可证与目标策略返回的令牌。", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "suspended", "revoked" ], "type": "string" } }, "required": [], "type": "object" }, "LicensingWebhook": { "additionalProperties": false, "properties": { "created_at": { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, "enabled": { "description": "是否允许 HTTP，仅用于本地开发。", "type": "boolean" }, "events": { "description": "该 Webhook 订阅的事件类型数组，不得重复或为空。", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "updated_at": { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, "url": { "description": "事件通知接收地址，生产环境使用公开 HTTPS URL。", "type": "string" } }, "required": [ "id", "name", "url", "events", "enabled", "created_at", "updated_at" ], "type": "object" }, "LicensingWebhookInput": { "additionalProperties": false, "properties": { "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "events": { "description": "该 Webhook 订阅的事件类型数组，不得重复或为空。", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "type": "string" }, "secret": { "description": "Webhook 验签秘密，非空为 32–200 字符；更新省略则保留。返回空字符串表示没有重新签发。", "maxLength": 200, "minLength": 32, "type": "string", "writeOnly": true }, "url": { "description": "事件通知接收地址，生产环境使用公开 HTTPS URL。", "format": "uri", "maxLength": 2000, "type": "string" } }, "required": [ "name", "url", "events", "enabled" ], "type": "object" }, "LicensingWebhookList": { "additionalProperties": false, "properties": { "event_types": { "description": "服务器支持订阅的全部授权事件类型。", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/LicensingWebhook" }, "type": "array" } }, "required": [], "type": "object" }, "LicensingWebhookSecret": { "additionalProperties": false, "properties": { "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "secret": { "description": "Webhook 验签秘密，非空为 32–200 字符；更新省略则保留。返回空字符串表示没有重新签发。", "type": "string" } }, "required": [], "type": "object" }, "LoggedOut": { "additionalProperties": false, "properties": { "logged_out": { "type": "boolean" } }, "required": [ "logged_out" ], "type": "object" }, "Login": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "password": { "description": "12–128 个 UTF-8 字节，而非字符", "type": "string", "writeOnly": true } }, "required": [ "email", "password" ], "type": "object" }, "LogoutTicket": { "additionalProperties": false, "properties": { "activation_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "expected_generation": { "description": "预期设备绑定代次，在撤销事务中比较。", "minimum": 1, "type": "integer" }, "operation_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "release_token": { "description": "仅限解绑的能力凭据。不能激活、验证、刷新或消耗功能。撤销待完成期间，只保留在 SDK 退出日志中。", "pattern": "^lv_out_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "operation_id", "product_id", "activation_id", "expected_generation", "release_token" ], "type": "object" }, "MailConnection": { "additionalProperties": false, "properties": { "check_status": { "enum": [ "verified", "limited" ], "type": "string" }, "delivery_mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "message": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "ok": { "description": "受限检查时为 false：尚未确认凭据或投递成功。", "type": "boolean" }, "status": { "enum": [ "connected" ], "type": "string" } }, "required": [ "status", "mode", "delivery_mode", "ok", "check_status" ], "type": "object" }, "MailInput": { "additionalProperties": false, "description": "部分更新加密的平台邮件设置。保留省略的字段和其他提供方配置；API 密钥或 SMTP 密码留空时保留已有秘密。所选当前服务必须配置完整。生产环境不可使用文件模式。要求平台管理员会话与 CSRF 令牌；厂商管理 API 密钥不能更改平台邮件设置。", "properties": { "from": { "type": "string" }, "host": { "maxLength": 253, "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password": { "description": "省略或留空可保留已有 SMTP 密码。", "maxLength": 1000, "type": "string", "writeOnly": true }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderInput" }, "mailgun": { "$ref": "#/components/schemas/MailgunInput" }, "postmark": { "$ref": "#/components/schemas/MailProviderInput" }, "resend": { "$ref": "#/components/schemas/MailProviderInput" } }, "required": [], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "maxLength": 254, "type": "string" } }, "required": [], "type": "object" }, "MailJob": { "additionalProperties": false, "properties": { "attempts": { "type": "integer" }, "cancel_reason": { "enum": [ "", "platform_disabled", "customer_disabled", "coverage_changed", "reminder_window_changed", "renewal_state_changed", "purchase_unavailable", "workspace_unavailable", "recipient_unavailable", "unknown_notification" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "", "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "billing_test" ], "type": "string" }, "mode": { "enum": [ "", "sandbox", "live" ], "type": "string" }, "recipient": { "type": "string" }, "status": { "enum": [ "pending", "running", "delivered", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "status", "attempts" ], "type": "object" }, "MailJobList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/MailJob" }, "maxItems": 50, "type": "array" } }, "required": [ "items" ], "type": "object" }, "MailProviderInput": { "additionalProperties": false, "properties": { "api_key": { "description": "提供方 API 密钥；Postmark 使用 Server API Token。省略或留空可保留已保存的秘密。", "maxLength": 4096, "type": "string", "writeOnly": true }, "from": { "description": "已验证的发件邮箱；选择此提供方为当前服务时必填。", "type": "string" } }, "required": [], "type": "object" }, "MailProviderSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "type": "boolean" }, "domain": { "description": "Mailgun 发送域名；其他提供方为空。", "type": "string" }, "from": { "type": "string" }, "region": { "description": "Mailgun 区域；其他提供方为空。", "enum": [ "", "us", "eu" ], "type": "string" } }, "required": [ "from", "domain", "region", "api_key_configured" ], "type": "object" }, "MailQueued": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "pending" ], "type": "string" } }, "required": [ "job_id", "status" ], "type": "object" }, "MailSettings": { "additionalProperties": false, "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password_configured": { "type": "boolean" }, "port": { "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderSettings" }, "mailgun": { "$ref": "#/components/schemas/MailProviderSettings" }, "postmark": { "$ref": "#/components/schemas/MailProviderSettings" }, "resend": { "$ref": "#/components/schemas/MailProviderSettings" } }, "required": [ "resend", "brevo", "postmark", "mailgun" ], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "mode", "port", "password_configured", "providers" ], "type": "object" }, "MailgunInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Mailgun 账号 API 密钥或域名发送密钥。省略或留空可保留已保存的秘密。", "maxLength": 4096, "type": "string", "writeOnly": true }, "domain": { "description": "发送域名，启用 Mailgun 时必填；不得包含协议、路径或端口。", "maxLength": 253, "type": "string" }, "from": { "description": "已验证的发件邮箱；启用 Mailgun 时必填。", "type": "string" }, "region": { "default": "us", "description": "发送域名所在区域；US 和 EU 使用不同的固定 API 地址。", "enum": [ "us", "eu" ], "type": "string" } }, "required": [], "type": "object" }, "ManagementKeyBundle": { "additionalProperties": false, "properties": { "keys": { "description": "该产品的当前和历史签名公钥数组。", "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "ManualRefundInput": { "additionalProperties": false, "properties": { "customer_agreement": { "maxLength": 3000, "type": "string" }, "evidence": { "maxLength": 3000, "type": "string" } }, "required": [ "customer_agreement", "evidence" ], "type": "object" }, "Me": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "tenant_id", "id", "role", "is_platform_admin" ], "type": "object" }, "Member": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "role", "status", "verified" ], "type": "object" }, "MemberList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items" ], "type": "object" }, "MemberUpdate": { "additionalProperties": false, "properties": { "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "MonthInput": { "additionalProperties": false, "properties": { "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "month" ], "type": "object" }, "Notice": { "additionalProperties": false, "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "OfflineReleaseResult": { "additionalProperties": false, "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "properties": { "activation_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "deactivated": { "description": "是否允许 HTTP，仅用于本地开发。", "type": "boolean" } }, "required": [ "activation_id", "deactivated" ], "type": "object" }, "OfflineRequest": { "additionalProperties": false, "properties": { "activation_id": { "description": "设备绑定或浮动会话记录的 UUID。", "format": "uuid", "type": "string" }, "app_version": { "description": "当前软件的 major.minor.patch 版本号。", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "type": "integer" }, "device_id": { "description": "产品范围内的设备指纹，通常是 64 位小写十六进制；由 SDK 从当前机器计算。", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "便于识别设备的名称，不作为安全身份依据。", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK 生成的设备身份信息；提供该对象时，其必填字段均须提供。" }, "license_key": { "description": "完整客户授权码，在软件激活时输入。产品初始化代码与示例下载不包含该密钥；离线申请使用 SDK 输出的对应凭证。", "pattern": "^lv_(lic|tmp|dev)_[A-Za-z0-9_-]{43}$", "type": "string", "writeOnly": true }, "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "enum": [ "activate", "deactivate" ], "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" }, "session_id": { "description": "浮动运行实例的会话标识；设备绑定模式可能省略。", "format": "uuid", "type": "string" }, "version": { "const": 1, "description": "策略中为修改版本号；产品版本为 major.minor.patch；离线协议中固定为 1。", "type": "integer" } }, "required": [ "version", "request_id", "created_at", "operation", "product_id", "license_key", "device_id" ], "type": "object" }, "OfflineResponse": { "additionalProperties": false, "example": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "properties": { "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "enum": [ "activate", "deactivate" ], "type": "string" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeResult", "description": "离线操作的实际授权结果；激活返回签名租约，释放返回 deactivated。" }, { "$ref": "#/components/schemas/OfflineReleaseResult", "description": "离线操作的实际授权结果；激活返回签名租约，释放返回 deactivated。" } ], "description": "离线操作的实际授权结果；激活返回签名租约，释放返回 deactivated。" }, "version": { "const": 1, "description": "策略中为修改版本号；产品版本为 major.minor.patch；离线协议中固定为 1。", "type": "integer" } }, "required": [ "version", "request_id", "operation", "result" ], "type": "object" }, "OnboardingInput": { "additionalProperties": false, "properties": { "description": { "description": "产品的文字说明，可为空字符串。", "maxLength": 1000, "type": "string" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "features": { "default": [ "export" ], "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "type": "integer" }, "license_model": { "default": "node_locked", "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "max_devices": { "default": 1, "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "default": "trial", "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited 限时离线、none 不允许离线、permanent 不另设离线时长上限；仍受许可证到期时间限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited：1–31536000 秒，且启用心跳时至少为 3 × heartbeat_seconds；none/permanent：0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "request_id", "name" ], "type": "object" }, "OnboardingResult": { "additionalProperties": false, "example": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "properties": { "config": { "$ref": "#/components/schemas/SDKConfig", "description": "测试用 SDK 配置，包含许可证秘密，请私密保存。" }, "license_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "license_key": { "description": "完整客户授权码，在软件激活时输入。产品初始化代码与示例下载不包含该密钥；离线申请使用 SDK 输出的对应凭证。", "type": "string" }, "next": { "description": "已安排的下月默认计费方案；没有时为 null。", "type": "string" }, "policy_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "product_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id", "license_id", "license_key", "config", "next" ], "type": "object" }, "OperatorProfile": { "additionalProperties": false, "properties": { "backup_region": { "maxLength": 500, "type": "string" }, "contact": { "maxLength": 500, "type": "string" }, "country": { "maxLength": 500, "type": "string" }, "financial_retention_years": { "description": "为零或省略时表示未确认，不包含在公开文档中。", "maximum": 30, "minimum": 0, "type": "integer" }, "hosting_provider": { "maxLength": 500, "type": "string" }, "mail_provider": { "maxLength": 500, "type": "string" }, "markets": { "maxLength": 500, "type": "string" }, "operator": { "maxLength": 500, "type": "string" }, "processing_grounds": { "maxLength": 500, "type": "string" }, "server_region": { "maxLength": 500, "type": "string" }, "transfer_safeguards": { "maxLength": 500, "type": "string" } }, "required": [], "type": "object" }, "OriginalRefundInput": { "additionalProperties": false, "properties": { "amount": { "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "OriginalRefundResult": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" } }, "type": "object" }, "OveragePlan": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "是否在用完 API 额度后拒绝继续调用。", "type": "boolean" }, "api_unit_micros": { "description": "每次超额运行 API 调用的价格，百万分之一货币单位。", "minimum": 0, "type": "integer" }, "base_micros": { "description": "基础金额，百万分之一货币单位。", "type": "integer" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "description": { "description": "计费方案的文字说明。", "type": "string" }, "enabled": { "description": "该计费方案是否允许购买。", "type": "boolean" }, "hard_limit": { "description": "是否达到设备额度后拒绝新增计费设备。", "type": "boolean" }, "included_api_calls": { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "name": { "description": "计费方案的显示名称。", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "public": { "description": "该计费方案是否公开展示。", "type": "boolean" }, "renewal_only": { "description": "是否仅供符合条件的原客户续费。", "type": "boolean" }, "sort_order": { "description": "计费方案的显示排序值。", "type": "integer" }, "terms": { "anyOf": [ { "description": "可购买期限及对应价格数组。", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, { "description": "可购买期限及对应价格数组。", "type": "null" } ], "description": "可购买期限及对应价格数组。" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "OveragePreference": { "additionalProperties": false, "properties": { "block_api_overage": { "description": "是否拦截超过套餐内 API 额度的运行调用。", "type": "boolean" }, "block_device_overage": { "description": "是否拦截超过套餐内设备额度的新增计费设备。", "type": "boolean" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" }, "version": { "description": "超额使用偏好配置的版本号。", "type": "string" } }, "required": [ "mode", "block_device_overage", "block_api_overage", "version", "updated_at" ], "type": "object" }, "OverageSettings": { "additionalProperties": false, "properties": { "customer_api_settings_enabled": { "description": "管理员是否允许客户自行设置 API 超额拦截。", "type": "boolean" }, "customer_device_settings_enabled": { "description": "管理员是否允许客户自行设置设备超额拦截。", "type": "boolean" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/OveragePlan", "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。" }, { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "null" } ], "description": "当前用于判断超额的套餐或默认计费规则快照；未启用时可能为 null。" }, "preference": { "$ref": "#/components/schemas/OveragePreference", "description": "当前账号保存的超额使用偏好。" } }, "required": [ "preference", "plan", "customer_device_settings_enabled", "customer_api_settings_enabled" ], "type": "object" }, "OverageSettingsInput": { "additionalProperties": false, "properties": { "block_api_overage": { "type": "boolean" }, "block_device_overage": { "type": "boolean" }, "expected_version": { "description": "使用 GET 返回的 preference.version；首次保存时为空。其他标签页已修改时返回 409；至少提供一项超额使用选择。", "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "PaddleCheck": { "additionalProperties": false, "properties": { "connected": { "description": "是否启用此事件订阅。", "type": "boolean" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "PaddleOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "本地结账意图保存时间，使用 UTC。", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "经验证付款启用服务或记入钱包充值的 UTC 时间。purchase_id 和 upgrade_id 均为 null 时表示充值。" }, "created_at": { "description": "本地结账意图保存时间，使用 UTC。", "format": "date-time", "type": "string" }, "currency": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "本地结账意图保存时间，使用 UTC。", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "后端确认 Paddle 交易完成的 UTC 时间。" }, "purchase_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的服务购买或续费，与 upgrade_id 互斥。" }, "refunded_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "request_id": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "status": { "description": "支付生命周期；已收款但需要经营者审核和退款时包括 paid_unapplied。", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "transaction_id": { "anyOf": [ { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, { "type": "null" } ], "description": "已绑定的 Paddle Billing 交易标识；原创建结果仍待确认时为 null。" }, "upgrade_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的升级报价，与 purchase_id 互斥。" } }, "required": [ "id", "request_id", "mode", "transaction_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "paid_at", "applied_at", "created_at" ], "type": "object" }, "PaddleOrderInput": { "additionalProperties": false, "description": "支付一份已冻结的购买或升级，或使用 amount 和 currency、且不提供服务 ID 来创建钱包充值。稳定的 request_id 返回原付款；不允许改变其意图、金额或币种。只有独立验证完成的付款才可记入钱包或启用服务。充值完成后返回钱包。创建结果不确定时，通过原 Webhook 恢复，绝不盲目重新创建。", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "仅钱包充值必填。显示用小数金额必须在配置限制内。服务订单拒绝客户端金额。", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "仅钱包充值必填，并且此提供方必须启用该币种。", "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的服务购买或续费，与 upgrade_id 互斥。" }, "request_id": { "description": "调用方生成的稳定请求密钥。重放返回原结账。", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的升级报价，与 purchase_id 互斥。" } }, "required": [ "request_id" ], "type": "object" }, "PaddleOrderList": { "additionalProperties": false, "properties": { "items": { "description": "此管理员或工作空间可见的记录。", "items": { "$ref": "#/components/schemas/PaddleOrder" }, "type": "array" }, "total": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PaddleOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "打开已绑定 Paddle 交易的本地结账页面。", "format": "uri", "type": "string" }, "client_token": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "order": { "$ref": "#/components/schemas/PaddleOrder", "description": "工作空间范围内的 Paddle 服务付款记录。" }, "return_url": { "description": "充值返回钱包控制台 URL，服务付款返回定价核对 URL。仅凭返回 URL 绝不能证明付款。", "format": "uri", "type": "string" } }, "required": [ "order", "client_token", "approval_url", "return_url" ], "type": "object" }, "PaddleReconcileInput": { "additionalProperties": false, "properties": { "transaction_id": { "description": "可选的原 txn_ ID，用于恢复丢失的创建响应。后端独立验证本地订单、租户、产品、币种和金额。不能替换已经绑定的交易。", "type": "string" } }, "required": [], "type": "object" }, "PaddleSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "description": "是否启用此事件订阅。", "type": "boolean" }, "checkout_url": { "description": "将此已批准域名页面用作 Paddle 默认支付链接。", "format": "uri", "type": "string" }, "client_token": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "currencies": { "description": "当前环境允许的货币代码数组。", "items": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "type": "array" }, "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "maximum_cents": { "description": "钱包最高充值额，使用最小货币单位；默认 100000，且不能小于 minimum_cents。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "钱包最低充值额，使用最小货币单位；默认 100。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "version": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "webhook_secret_configured": { "description": "是否启用此事件订阅。", "type": "boolean" }, "webhook_url": { "description": "将此绝对 URL 注册为 Paddle 通知目标。", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "api_key_configured", "webhook_secret_configured", "version", "webhook_url", "checkout_url" ], "type": "object" }, "PaddleSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "静态加密保存。为空时保留已有值，除非 clear_api_key 为 true。", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_api_key": { "description": "是否启用此事件订阅。", "type": "boolean" }, "clear_webhook_secret": { "description": "是否启用此事件订阅。", "type": "boolean" }, "client_token": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "currencies": { "description": "当前环境允许的货币代码数组。", "items": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "type": "array" }, "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "expected_version": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "maximum_cents": { "description": "钱包最高充值额，使用最小货币单位；默认 100000，且不能小于 minimum_cents。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "钱包最低充值额，使用最小货币单位；默认 100。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "webhook_secret": { "description": "用于认证精确原始 Webhook 请求体的私有端点密钥。", "maxLength": 1000, "type": "string", "writeOnly": true } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "expected_version" ], "type": "object" }, "PaddleWebhookEvent": { "description": "未经修改的 Paddle Billing 事件，通过 Paddle-Signature 认证，并通过 Paddle API 独立核对。", "type": "object" }, "PasswordSet": { "additionalProperties": false, "properties": { "password_set": { "type": "boolean" } }, "required": [ "password_set" ], "type": "object" }, "PayPalCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "PayPalInput": { "additionalProperties": false, "properties": { "clear_secret": { "type": "boolean" }, "client_id": { "maxLength": 1000, "type": "string" }, "client_secret": { "description": "留空保留已保存的 Secret，除非 clear_secret=true", "maxLength": 1000, "type": "string", "writeOnly": true }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" } }, "required": [ "enabled", "mode", "client_id", "merchant_id", "webhook_id", "currencies", "minimum_cents", "maximum_cents", "expected_version" ], "type": "object" }, "PayPalOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "本笔金额，百分之一货币单位；流水可为正（入账）或负（支出）。", "type": "integer" }, "approval_url": { "description": "PayPal 付款批准页面地址；仅展示，不代表已付款。", "format": "uri", "type": "string" }, "capture_id": { "description": "PayPal 收款交易编号。", "type": [ "string", "null" ] }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "credited_at": { "anyOf": [ { "description": "充值实际入账时间；尚未入账时为 null。", "format": "date-time", "type": "string" }, { "description": "充值实际入账时间；尚未入账时为 null。", "type": "null" } ], "description": "充值实际入账时间；尚未入账时为 null。" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_order_id": { "description": "PayPal 返回的订单编号，不是本地记录 UUID。", "type": [ "string", "null" ] }, "purchase_id": { "description": "关联的套餐合同 UUID。", "type": [ "string", "null" ] }, "refunded_cents": { "description": "累计已退款金额，百分之一货币单位。", "type": "integer" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "creating", "created", "credited", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "关联升级记录 UUID；没有时为空字符串。", "format": "uuid", "type": "string" }, { "description": "关联升级记录 UUID；没有时为空字符串。", "type": "null" } ], "description": "关联升级记录 UUID；没有时为空字符串。" } }, "required": [], "type": "object" }, "PayPalOrderList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/PayPalOrder" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [], "type": "object" }, "PayPalRefund": { "additionalProperties": false, "properties": { "amount_cents": { "description": "申请原路现金退款的金额，以分计。", "type": "integer" }, "attempts": { "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "paypal_refund_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "request_id": { "type": "string" }, "reserved": { "description": "钱包金额仍被预留时为 true。传输超时后继续保留预留，直到核对同一请求。", "type": "boolean" }, "status": { "enum": [ "pending", "completed", "failed" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "request_id", "mode", "currency", "amount_cents", "reason", "status", "reserved", "attempts", "paypal_refund_id", "created_at", "updated_at" ], "type": "object" }, "PayPalSettings": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 1000, "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "secret_configured": { "type": "boolean" }, "version": { "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [], "type": "object" }, "PaymentChannel": { "additionalProperties": false, "properties": { "currencies": { "description": "当前环境允许的货币代码数组。", "items": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "type": "array" }, "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "provider": { "description": "支付提供方：PayPal、Paddle 或 Waffo Pancake。", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "version": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "wallet_topup": { "description": "是否启用此事件订阅。", "type": "boolean" } }, "required": [ "provider", "name", "enabled", "mode", "currencies", "wallet_topup" ], "type": "object" }, "PaymentChannelInput": { "additionalProperties": false, "properties": { "paddle_enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "paddle_version": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "paypal_enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "paypal_version": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "waffo_enabled": { "description": "可选 Waffo 开关；省略字段时保留当前状态。", "type": "boolean" }, "waffo_version": { "description": "更改 Waffo 开关时必须提供的配置版本。", "type": "string" } }, "required": [ "paypal_enabled", "paddle_enabled", "paypal_version", "paddle_version" ], "type": "object" }, "PaymentChannels": { "additionalProperties": false, "properties": { "items": { "description": "此管理员或工作空间可见的记录。", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "PendingPlan": { "additionalProperties": false, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "effective_month": { "description": "安排生效的 UTC 月，YYYY-MM。", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" } }, "required": [], "type": "object" }, "Period": { "additionalProperties": false, "properties": { "base_covered": { "description": "本期基础费用是否已由已购套餐覆盖。", "type": "boolean" }, "base_micros": { "description": "基础金额，百万分之一货币单位。", "type": "integer" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "hard_limit": { "description": "是否达到设备额度后拒绝新增计费设备。", "type": "boolean" }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "payment_mode": { "description": "收款环境：sandbox 测试、live 正式。", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "plan_name": { "description": "方案显示名称。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" } }, "required": [ "month", "plan", "currency", "price_version" ], "type": "object" }, "PlanChange": { "additionalProperties": false, "properties": { "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" } }, "required": [ "plan", "currency" ], "type": "object" }, "PlanGift": { "additionalProperties": false, "properties": { "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftBatch": { "additionalProperties": false, "properties": { "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "start_mode": { "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" } }, "required": [ "id", "actor_id", "request_id", "plan", "plan_name", "currency", "price_version", "term_months", "mode", "start_mode", "reason", "user_count", "tenant_count", "created_at" ], "type": "object" }, "PlanGiftCancellation": { "additionalProperties": false, "properties": { "cancelled": { "type": "boolean" } }, "required": [ "cancelled" ], "type": "object" }, "PlanGiftInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "term_months", "mode", "start_mode", "reason", "request_id", "fingerprint" ], "type": "object" }, "PlanGiftList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlanGiftRow" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlanGiftPreview": { "additionalProperties": false, "properties": { "fingerprint": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/PlanGiftTarget" }, "type": "array" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan_name": { "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" }, "value_cents": { "type": "integer" } }, "required": [ "fingerprint", "plan_name", "value_cents", "user_count", "tenant_count", "mode", "term_months", "start_mode", "items" ], "type": "object" }, "PlanGiftPreviewInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "mode", "reason" ], "type": "object" }, "PlanGiftResult": { "additionalProperties": false, "properties": { "batch": { "$ref": "#/components/schemas/PlanGiftBatch" }, "items": { "items": { "$ref": "#/components/schemas/PlanGift" }, "type": "array" } }, "required": [ "batch", "items" ], "type": "object" }, "PlanGiftRow": { "additionalProperties": false, "properties": { "actor_email": { "type": "string" }, "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftTarget": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "previous_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "price_version": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "user_id", "email", "tenant_id", "tenant_name", "starts_at", "ends_at", "previous_end", "plan", "plan_name", "currency", "price_version", "value_cents" ], "type": "object" }, "PlanInput": { "additionalProperties": false, "properties": { "api_hard_limit": { "type": "boolean" }, "api_unit_amount": { "description": "每次成功 API 调用的非负小数价格，最多六位小数", "type": "string" }, "base_amount": { "description": "非负小数，最多两位小数", "type": "string" }, "currency": { "description": "必须配置；EUR 目录方案已禁用", "pattern": "^[A-Z]{3}$", "type": "string" }, "description": { "maxLength": 1000, "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "description": "当前版本；创建时为空", "type": "string" }, "hard_limit": { "type": "boolean" }, "included_api_calls": { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "maximum": 1000000000, "minimum": 0, "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "public": { "type": "boolean" }, "renewal_only": { "description": "是否仅供符合条件的原客户续费。", "type": "boolean" }, "sort_order": { "maximum": 10000, "minimum": 0, "type": "integer" }, "terms": { "description": "1、3、6 和 12 个月各有且仅有一项，每项有独立的可用状态和总价。", "items": { "$ref": "#/components/schemas/PlanTermInput" }, "maxItems": 4, "minItems": 4, "type": "array" }, "unit_amount": { "description": "非负小数，最多六位小数", "type": "string" } }, "required": [ "plan", "currency", "name", "base_amount", "unit_amount" ], "type": "object" }, "PlanList": { "additionalProperties": false, "properties": { "billing_unit": { "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "default_plan": { "anyOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "maximum_cents": { "type": "integer" }, "minimum_cents": { "type": "integer" }, "payment_channels": { "description": "可用支付渠道配置。只显示已启用、且匹配当前计费环境和购买币种的渠道。", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "timezone": { "type": "string" } }, "required": [], "type": "object" }, "PlanPurchase": { "additionalProperties": false, "properties": { "api_calls": { "description": "当前统计范围内成功且计量的运行 API 次数；不包含这里的管理请求。", "type": "integer" }, "api_hard_limit": { "description": "是否在用完 API 额度后拒绝继续调用。", "type": "boolean" }, "api_overage_cents": { "description": "本周期 API 超额消费，百分之一货币单位。", "type": "integer" }, "api_unit_micros": { "description": "每次超额运行 API 调用的价格，百万分之一货币单位。", "minimum": 0, "type": "integer" }, "base_cents": { "description": "该合同首次实际支付的基础金额，百分之一货币单位；赠送可能为 0。", "type": "integer" }, "cancelled_at": { "anyOf": [ { "description": "合同取消时间；未取消时为 null。", "format": "date-time", "type": "string" }, { "description": "合同取消时间；未取消时为 null。", "type": "null" } ], "description": "合同取消时间；未取消时为 null。" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "current_cycle_index": { "description": "当前额度周期的序号。", "maximum": 11, "minimum": 0, "type": "integer" }, "current_upgrade_id": { "description": "当前生效升级记录的 UUID；没有时为空字符串。", "type": "string" }, "cycle_ends_at": { "description": "当前额度周期结束时间，UTC。", "format": "date-time", "type": "string" }, "cycle_starts_at": { "description": "当前额度周期开始时间，UTC。", "format": "date-time", "type": "string" }, "effective_included_devices": { "description": "当前实际生效的设备额度。", "minimum": 0, "type": "integer" }, "effective_plan": { "description": "升级或赠送继承后当前实际生效的方案标识。", "type": "string" }, "effective_plan_name": { "description": "升级或赠送继承后当前实际生效的方案标识。", "type": "string" }, "ends_at": { "anyOf": [ { "description": "套餐或周期结束时间，UTC；尚未生效时可能为 null。", "format": "date-time", "type": "string" }, { "description": "套餐或周期结束时间，UTC；尚未生效时可能为 null。", "type": "null" } ], "description": "套餐或周期结束时间，UTC；尚未生效时可能为 null。" }, "entitlement_cents": { "description": "当前权益对应的合同价格基数，百分之一货币单位。", "minimum": 0, "type": "integer" }, "gift_batch_id": { "description": "赠送批次标识；普通购买可为空。", "type": "string" }, "gift_follows_current": { "default": false, "description": "赠送是否沿用原合同的当前有效权益。", "type": "boolean" }, "hard_limit": { "description": "是否达到设备额度后拒绝新增计费设备。", "type": "boolean" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "included_api_calls": { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "overage_cents": { "description": "当前周期设备超额消费，百分之一货币单位。", "type": "integer" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "description": "方案显示名称。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "refunded_cents": { "description": "累计已退款金额，百分之一货币单位。", "type": "integer" }, "renewal": { "description": "是否为续费合同。", "type": "boolean" }, "renewal_of": { "description": "被续费合同的 UUID；没有时为空字符串。", "type": "string" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "type": "string" }, "service_credit_basis_cents": { "description": "服务补偿计算使用的金额基数，百分之一货币单位。", "type": "integer" }, "service_credit_basis_seconds": { "description": "服务补偿计算使用的时间基数，单位秒。", "type": "integer" }, "source": { "description": "权益来源，例如 purchase 购买或 gift 赠送。", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "anyOf": [ { "description": "套餐或周期开始时间，UTC。", "format": "date-time", "type": "string" }, { "description": "套餐或周期开始时间，UTC。", "type": "null" } ], "description": "套餐或周期开始时间，UTC。" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "pending", "active", "cancelled", "expired" ], "type": "string" }, "term_months": { "default": 1, "description": "合同购买的月数。", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "total_api_calls": { "description": "整个合同累计运行 API 次数。", "type": "integer" }, "total_api_overage_cents": { "description": "整个合同累计 API 超额费用，百分之一货币单位。", "type": "integer" }, "total_device_overage_cents": { "description": "整个合同累计设备超额费用，百分之一货币单位。", "type": "integer" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" } }, "required": [], "type": "object" }, "PlanTermInput": { "additionalProperties": false, "properties": { "amount": { "description": "非负的期限总价，最多两位小数。一个月的金额必须等于 base_amount。", "type": "string" }, "enabled": { "type": "boolean" }, "months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "amount" ], "type": "object" }, "PlanTermPrice": { "additionalProperties": false, "properties": { "base_cents": { "description": "该合同首次实际支付的基础金额，百分之一货币单位；赠送可能为 0。", "minimum": 0, "type": "integer" }, "enabled": { "description": "是否启用此事件订阅。", "type": "boolean" }, "months": { "default": 1, "description": "该购买期限的月数。", "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "base_cents" ], "type": "object" }, "PlanUpgrade": { "additionalProperties": false, "properties": { "amount_cents": { "description": "本笔金额，百分之一货币单位；流水可为正（入账）或负（支出）。", "type": "integer" }, "api_hard_limit": { "description": "是否在用完 API 额度后拒绝继续调用。", "type": "boolean" }, "api_unit_micros": { "description": "每次超额运行 API 调用的价格，百万分之一货币单位。", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "升级实际生效时间；尚未生效时为 null。", "format": "date-time", "type": "string" }, { "description": "升级实际生效时间；尚未生效时为 null。", "type": "null" } ], "description": "升级实际生效时间；尚未生效时为 null。" }, "base_cents": { "description": "该合同首次实际支付的基础金额，百分之一货币单位；赠送可能为 0。", "type": "integer" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "cycle_seconds": { "description": "升级价格计算使用的周期秒数。", "type": "integer" }, "ends_at": { "description": "套餐或周期结束时间，UTC；尚未生效时可能为 null。", "format": "date-time", "type": "string" }, "expires_at": { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, "hard_limit": { "description": "是否达到设备额度后拒绝新增计费设备。", "type": "boolean" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "included_api_calls": { "anyOf": [ { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "type": "integer" }, { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "type": "null" } ], "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。" }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "parent_id": { "description": "主升级记录 UUID；主记录本身为空字符串。", "format": "uuid", "type": "string" }, "parts": { "description": "跨多个合同或覆盖段的升级分项数组。", "items": { "$ref": "#/components/schemas/UpgradePart" }, "type": "array" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "plan_name": { "description": "方案显示名称。", "type": "string" }, "previous_base_cents": { "description": "升级前同期限合同价格，百分之一货币单位。", "type": "integer" }, "previous_plan_name": { "description": "升级前的方案显示名称。", "type": "string" }, "previous_upgrade_id": { "description": "上一份升级记录 UUID；没有时为空字符串。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "purchase_id": { "description": "关联的套餐合同 UUID。", "format": "uuid", "type": "string" }, "remaining_seconds": { "description": "计算升级差价时的剩余覆盖秒数。", "type": "integer" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "pending", "applied", "expired" ], "type": "string" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" } }, "required": [ "id", "request_id", "mode", "purchase_id", "previous_upgrade_id", "plan", "plan_name", "previous_plan_name", "currency", "price_version", "previous_base_cents", "base_cents", "amount_cents", "included_devices", "unit_micros", "hard_limit", "included_api_calls", "api_unit_micros", "api_hard_limit", "remaining_seconds", "cycle_seconds", "ends_at", "expires_at", "status", "created_at", "applied_at" ], "type": "object" }, "PlatformOperation": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "actor_email": { "type": "string" }, "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "details": { "description": "只包含明确管理变更的 JSON 字符串，绝不包含密码、令牌或支付凭据。", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "resource_id": { "type": "string" }, "tenant_id": { "type": "string" }, "user_email": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "id", "actor_id", "action", "user_id", "tenant_id", "resource_id", "reason", "details", "request_id", "created_at", "actor_email", "user_email" ], "type": "object" }, "PlatformOperationList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformOperation" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformOverview": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "counts": { "additionalProperties": false, "properties": { "active_packages": { "type": "integer" }, "active_workspaces": { "type": "integer" }, "disabled_users": { "type": "integer" }, "enabled_plans": { "type": "integer" }, "expiring_packages": { "type": "integer" }, "failed_mail": { "type": "integer" }, "gift_packages": { "type": "integer" }, "new_users": { "type": "integer" }, "suspended_workspaces": { "type": "integer" }, "users": { "type": "integer" }, "verified_users": { "type": "integer" } }, "required": [ "users", "verified_users", "disabled_users", "new_users", "active_workspaces", "suspended_workspaces", "active_packages", "expiring_packages", "gift_packages", "failed_mail", "enabled_plans" ], "type": "object" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_enabled": { "type": "boolean" } }, "required": [ "counts", "mode", "paypal_enabled", "at" ], "type": "object" }, "PlatformReason": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformRevocation": { "additionalProperties": false, "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "type": "object" }, "PlatformUser": { "additionalProperties": false, "properties": { "admin_note": { "description": "平台私有备注，客户资料字段保持不变。", "maxLength": 2000, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "email": { "format": "email", "type": "string" }, "email_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "last_login_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "note_version": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "tenant_status": { "enum": [ "active", "suspended" ], "type": "string" }, "tenant_updated_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "tenant_id", "tenant_name", "tenant_status", "tenant_updated_at", "email", "name", "role", "status", "is_platform_admin", "email_verified_at", "created_at", "updated_at", "last_login_at", "admin_note", "note_version" ], "type": "object" }, "PlatformUserDetail": { "additionalProperties": false, "properties": { "counts": { "additionalProperties": false, "properties": { "licenses": { "type": "integer" }, "products": { "type": "integer" }, "users": { "type": "integer" } }, "required": [ "users", "products", "licenses" ], "type": "object" }, "payments": { "items": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paid_cents": { "type": "integer" }, "refunded_cents": { "type": "integer" } }, "required": [ "mode", "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "purchases": { "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "user": { "$ref": "#/components/schemas/PlatformUser" }, "wallets": { "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" } }, "required": [ "user", "counts", "wallets", "purchases", "payments" ], "type": "object" }, "PlatformUserList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformUser" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformUserUpdate": { "additionalProperties": false, "anyOf": [ { "required": [ "status", "expected_updated_at" ] }, { "required": [ "admin_note", "expected_note_version" ] } ], "properties": { "admin_note": { "maxLength": 2000, "type": "string" }, "expected_note_version": { "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformWorkspaceStatus": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "PlatformWorkspaceUpdate": { "additionalProperties": false, "properties": { "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "status", "reason", "expected_updated_at" ], "type": "object" }, "Policy": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "联网时多久发送一次心跳，单位秒。0 关闭周期心跳，和允许离线时长分别设置。", "type": "integer" }, "id": { "description": "策略 UUID，签发许可证时作为 policy_id。", "format": "uuid", "type": "string" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited：有限离线；none：不允许离线；permanent：不另设离线时长上限，但仍受许可证有效期限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "允许的离线秒数：limited 为 1–31536000，none/permanent 为 0。这不是心跳间隔。启用心跳时，新的有限离线策略必须满足 offline_seconds \u003e= 3 × heartbeat_seconds；浮动席位租约也必须至少覆盖三个心跳间隔。", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" }, "version": { "description": "策略版本号，每次修改递增。应用到旧许可证时用于核对预览是否仍有效。", "type": "integer" } }, "required": [ "id", "product_id", "mode", "version" ], "type": "object" }, "PolicyCapabilities": { "additionalProperties": false, "properties": { "allow_vm": { "description": "是否允许虚拟机。", "type": "boolean" }, "device_match": { "description": "system 按系统身份匹配，hardware 按硬件身份匹配。", "enum": [ "system", "hardware" ], "type": "string" }, "license_model": { "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "从首次激活起的版本维护天数；0 表示不限制维护期限。", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_version": { "description": "最高允许的软件版本；空字符串不设上限。", "type": "string" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每个计次周期内包含的功能使用次数上限，不是分页条数。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "最低允许的软件版本；空字符串不设下限。", "type": "string" }, "policy_id": { "description": "授权策略 UUID；签发时必须与产品对应。", "format": "uuid", "type": "string" }, "policy_version": { "description": "策略版本号；修改完整规则时必须带上刚读取的版本以防覆盖他人修改。", "type": "integer" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "require_hardware": { "description": "是否要求设备提供可用硬件身份。", "type": "boolean" }, "self_release_limit": { "description": "客户门户在滚动 30 天内可自助释放设备的次数，0–100；0 禁止自助释放。", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "浮动席位无心跳后的租约秒数，20–86400；须搭配策略要求的心跳和离线规则。", "maximum": 86400, "minimum": 20, "type": "integer" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "PolicyCapabilitiesInput": { "additionalProperties": false, "description": "定义签发模式、设备或席位上限、功能和运行时规则。策略不保存有效时长。必须提供 policy_version，防止过时编辑。", "properties": { "allow_vm": { "description": "是否允许虚拟机。", "type": "boolean" }, "device_match": { "description": "system 按系统身份匹配，hardware 按硬件身份匹配。", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "type": "integer" }, "license_model": { "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "从首次激活起的版本维护天数；0 表示不限制维护期限。", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "最高允许的软件版本；空字符串不设上限。", "type": "string" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每个计次周期内包含的功能使用次数上限，不是分页条数。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "最低允许的软件版本；空字符串不设下限。", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited 限时离线、none 不允许离线、permanent 不另设离线时长上限；仍受许可证到期时间限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited：1–31536000 秒，且启用心跳时至少为 3 × heartbeat_seconds；none/permanent：0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "policy_version": { "description": "策略版本号；修改完整规则时必须带上刚读取的版本以防覆盖他人修改。", "minimum": 1, "type": "integer" }, "require_hardware": { "description": "是否要求设备提供可用硬件身份。", "type": "boolean" }, "self_release_limit": { "description": "客户门户在滚动 30 天内可自助释放设备的次数，0–100；0 禁止自助释放。", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "浮动席位无心跳后的租约秒数，20–86400；须搭配策略要求的心跳和离线规则。", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "policy_version" ], "type": "object" }, "PolicyCreate": { "additionalProperties": false, "description": "定义签发模式、设备或席位上限、功能和运行时规则。策略不保存有效时长。", "properties": { "allow_vm": { "description": "是否允许虚拟机。", "type": "boolean" }, "device_match": { "description": "system 按系统身份匹配，hardware 按硬件身份匹配。", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "允许使用的功能标识数组，如 [\"export\"]。标识需与软件的 CheckFeature 参数一致。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "联网时多久发送一次心跳，单位秒。0 关闭周期心跳，和允许离线时长分别设置。", "type": "integer" }, "license_model": { "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "从首次激活起的版本维护天数；0 表示不限制维护期限。", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "同一许可证可绑定的设备数，1–10000；浮动模式下用作并发席位数。", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "最高允许的软件版本；空字符串不设上限。", "type": "string" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每个计次周期内包含的功能使用次数上限，不是分页条数。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "最低允许的软件版本；空字符串不设下限。", "type": "string" }, "mode": { "description": "perpetual 为永久许可证；timed 为限期；trial 为试用。不是计费套餐的订阅类型。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "策略名称，如 30 天专业版。", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited：有限离线；none：不允许离线；permanent：不另设离线时长上限，但仍受许可证有效期限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "允许的离线秒数：limited 为 1–31536000，none/permanent 为 0。这不是心跳间隔。启用心跳时，新的有限离线策略必须满足 offline_seconds \u003e= 3 × heartbeat_seconds；浮动席位租约也必须至少覆盖三个心跳间隔。", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "产品 UUID。", "format": "uuid", "type": "string" }, "require_hardware": { "description": "是否要求设备提供可用硬件身份。", "type": "boolean" }, "self_release_limit": { "description": "客户门户在滚动 30 天内可自助释放设备的次数，0–100；0 禁止自助释放。", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "浮动席位无心跳后的租约秒数，20–86400；须搭配策略要求的心跳和离线规则。", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "product_id", "name", "mode", "max_devices" ], "type": "object" }, "PolicyList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Policy" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "PolicyPreview": { "additionalProperties": false, "properties": { "changes": { "description": "每个许可证的修改前后对照及阻塞原因。", "items": { "additionalProperties": false, "properties": { "active": { "description": "公钥对象中表示当前签名密钥；策略预览中表示活跃设备或会话数量。", "type": "integer" }, "after": { "additionalProperties": false, "description": "应用目标策略后的权益；许可证期限保持原值。", "properties": { "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "type": "string" }, "type": "array" }, "license_model": { "description": "node_locked 绑定设备，floating 浮动席位。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "可获取新版本的维护截止时间；未激活或不限制时可能为 null。", "type": "null" } ], "description": "可获取新版本的维护截止时间；未激活或不限制时可能为 null。" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "type": "integer" }, "max_version": { "description": "最高允许的软件版本；空字符串不设上限。", "type": "string" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "最低允许的软件版本；空字符串不设下限。", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "license_model", "meter_rules", "maintenance_until", "min_version", "max_version" ], "type": "object" }, "before": { "additionalProperties": false, "description": "当前已签发的许可证权益和期限。", "properties": { "capabilities": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "许可证的扩展权益快照。" }, "duration_days": { "description": "许可证自身的有效天数，从首次成功激活开始。timed/trial 签发时必填 1–36500，永久授权省略或 null；不保存在策略中。", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。" }, "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "type": "string" }, "type": "array" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "type": "integer" }, "meter_rules": { "description": "功能计次规则数组；空数组表示没有配置功能计次。", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "是否允许功能使用次数超额。", "type": "boolean" }, "feature": { "description": "被计次的功能标识，必须包含在策略 features 中。", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "允许的最大超额次数；allow_overage 为 false 时不启用超额。", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "capabilities", "meter_rules" ], "type": "object" }, "blocked_reason": { "description": "无法应用的原因；空字符串表示当前没有阻塞。", "type": "string" }, "customer": { "description": "厂商自定义的客户标识或备注；不等于客户门户登录邮箱。", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "id", "customer", "before", "after", "blocked_reason", "active" ], "type": "object" }, "type": "array" }, "expires_in": { "const": 600, "description": "预览令牌有效秒数，当前为 600。", "type": "integer" }, "note": { "description": "面向开发者的补充说明。", "type": "string" }, "policy_version": { "description": "策略版本号；修改完整规则时必须带上刚读取的版本以防覆盖他人修改。", "type": "integer" }, "preview_token": { "description": "预览接口返回的加密确认令牌；apply_policy 必填，有效 600 秒，资源改变后须重新预览。", "type": "string" } }, "required": [ "changes", "policy_version", "preview_token", "expires_in", "note" ], "type": "object" }, "PolicySyncResult": { "additionalProperties": false, "properties": { "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "synced_licenses": { "description": "在同一事务内同步的关联且未吊销许可证数量。", "minimum": 0, "type": "integer" } }, "required": [ "id", "synced_licenses" ], "type": "object" }, "PolicyUpdate": { "additionalProperties": false, "description": "定义签发模式、设备或席位上限、功能和运行时规则。策略不保存有效时长。", "properties": { "features": { "description": "功能标识数组，最多 32 个且不能重复；每项为 1–64 个 ASCII 字母、数字、点、横线或下划线。", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "type": "integer" }, "max_devices": { "description": "同一许可证最多同时绑定的设备或占用的浮动席位数。", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited 限时离线、none 不允许离线、permanent 不另设离线时长上限；仍受许可证到期时间限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited：1–31536000 秒，且启用心跳时至少为 3 × heartbeat_seconds；none/permanent：0", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [], "type": "object" }, "PreviewInput": { "additionalProperties": false, "properties": { "ids": { "description": "待操作的许可证 UUID 数组，1–100 个且不能重复。", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "policy_id": { "description": "授权策略 UUID；签发时必须与产品对应。", "format": "uuid", "type": "string" } }, "required": [ "policy_id", "ids" ], "type": "object" }, "Price": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "是否在用完 API 额度后拒绝继续调用。", "type": "boolean" }, "api_unit_micros": { "description": "每次超额运行 API 调用的价格，百万分之一货币单位。", "minimum": 0, "type": "integer" }, "base_micros": { "description": "基础金额，百万分之一货币单位。", "type": "integer" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "description": { "description": "计费方案的文字说明。", "type": "string" }, "enabled": { "description": "该计费方案是否允许购买。", "type": "boolean" }, "hard_limit": { "description": "是否达到设备额度后拒绝新增计费设备。", "type": "boolean" }, "included_api_calls": { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "包含的活跃设备额度。", "type": "integer" }, "name": { "description": "计费方案的显示名称。", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" }, "public": { "description": "该计费方案是否公开展示。", "type": "boolean" }, "renewal_only": { "description": "是否仅供符合条件的原客户续费。", "type": "boolean" }, "sort_order": { "description": "计费方案的显示排序值。", "type": "integer" }, "terms": { "description": "可购买期限及对应价格数组。", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, "unit_micros": { "description": "每个超额活跃设备的单价，百万分之一货币单位。", "type": "integer" }, "updated_at": { "description": "资源最后修改时间，UTC 日期字符串。", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "Product": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "创建时间，UTC ISO 8601 日期。", "format": "date-time", "type": "string" }, "description": { "description": "产品说明。", "type": "string" }, "id": { "description": "产品 UUID，SDK 配置和创建策略时使用。", "format": "uuid", "type": "string" }, "name": { "description": "产品名称。", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "active 可正常激活；disabled 会拒绝运行授权请求。", "enum": [ "active", "disabled" ], "type": "string" }, "updated_at": { "description": "最后修改时间，UTC ISO 8601 日期。", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "ProductCreate": { "additionalProperties": false, "properties": { "description": { "description": "软件说明，可省略，最多 1000 字符。", "maxLength": 1000, "type": "string" }, "name": { "description": "软件的名称，1–120 字符。", "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "ProductList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ProductUpdate": { "additionalProperties": false, "properties": { "description": { "description": "产品的文字说明，可为空字符串。", "maxLength": 1000, "type": "string" }, "name": { "description": "供人识别的名称；名称长度限制见填写规则。", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "ProviderRefund": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "attempted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "attempts": { "minimum": 0, "type": "integer" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "last_error": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reserved": { "type": "boolean" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "created", "submitting", "pending", "unknown", "completed", "failed" ], "type": "string" }, "submitted_cents": { "minimum": 0, "type": "integer" }, "unapplied": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "PurchaseList": { "additionalProperties": false, "properties": { "active": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "公钥对象中表示当前签名密钥；策略预览中表示活跃设备或会话数量。" }, { "description": "公钥对象中表示当前签名密钥；策略预览中表示活跃设备或会话数量。", "type": "null" } ], "description": "当前生效的已购套餐合同；没有时为 null。" }, "active_devices": { "description": "该统计范围内按产品和设备去重的活跃设备数。", "type": "integer" }, "coverage_ends_at": { "anyOf": [ { "description": "连续已付款套餐的覆盖截止时间；没有时为 null。", "format": "date-time", "type": "string" }, { "description": "连续已付款套餐的覆盖截止时间；没有时为 null。", "type": "null" } ], "description": "连续已付款套餐的覆盖截止时间；没有时为 null。" }, "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "renewal_package": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "当前用于续费的最后一份已付款合同；没有时为 null。" }, { "description": "当前用于续费的最后一份已付款合同；没有时为 null。", "type": "null" } ], "description": "当前用于续费的最后一份已付款合同；没有时为 null。" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [], "type": "object" }, "RechargeInput": { "additionalProperties": false, "description": "关联 purchase_id 或 upgrade_id，不能同时提供。已确认付款记入钱包，并在报价仍有效时结算对应购买或升级。迟到的升级付款留在钱包中。", "properties": { "amount": { "description": "充值金额为小数，最多两位小数", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "purchase_id": { "format": "uuid", "type": [ "string", "null" ] }, "request_id": { "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "amount", "request_id" ], "type": "object" }, "RecoverOriginalRefund": { "additionalProperties": false, "properties": { "confirm_unpaid_manual": { "const": true, "type": "boolean" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "confirm_unpaid_manual" ], "type": "object" }, "RefundHistory": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundHistoryItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundHistoryItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "provider": { "enum": [ "paypal", "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": "string" }, "reason": { "type": "string" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "RefundInboxItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "cancellation_scope": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "pending_review": { "type": "boolean" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_totals": { "description": "JSON 编码的按币种划分的范围取消金额。", "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope": { "enum": [ "wallet", "service" ], "type": "string" }, "source": { "enum": [ "wallet_request", "support_case" ], "type": "string" }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "RefundInboxList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundInboxItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "summary": { "additionalProperties": false, "properties": { "pending_review": { "minimum": 0, "type": "integer" }, "service_pending_review": { "minimum": 0, "type": "integer" }, "wallet_pending_review": { "minimum": 0, "type": "integer" } }, "type": "object" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundInput": { "additionalProperties": false, "properties": { "amount": { "description": "以扣款币种填写的正数退款金额，不能超过剩余已扣款金额或可用且未消费的钱包余额。", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "RefundList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "RefundQuote": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "automatic_entitlement_cancellation": { "type": "boolean" }, "currency": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "requires_confirmation": { "type": "boolean" } }, "required": [], "type": "object" }, "RefundReview": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "amounts": { "items": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" } }, "required": [ "purchase_id", "amount" ], "type": "object" }, "type": "array" }, "approve": { "type": "boolean" }, "decision": { "maxLength": 3000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "Register": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "password": { "description": "12–128 个 UTF-8 字节，而非字符", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "必填，并须与密码完全一致", "type": "string", "writeOnly": true }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "tenant_name": { "maxLength": 120, "minLength": 1, "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" } }, "required": [ "email", "password", "password_confirmation", "name", "tenant_name" ], "type": "object" }, "Release": { "additionalProperties": false, "example": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "properties": { "channel": { "description": "版本渠道：stable 正式、preview 预览；省略默认 stable。", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "download_url": { "description": "下载地址；如提供须为 HTTPS，且同时提供 sha256。", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "notes": { "description": "版本发布说明。", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "published_at": { "description": "版本发布时间，UTC；省略时为服务器当前时间。", "format": "date-time", "type": "string" }, "sha256": { "description": "下载文件的 SHA-256，64 位小写十六进制；与签名算法分开。", "type": "string" }, "version": { "description": "策略中为修改版本号；产品版本为 major.minor.patch；离线协议中固定为 1。", "type": "string" } }, "required": [ "id", "product_id", "version", "channel", "notes", "download_url", "sha256", "published_at", "created_at" ], "type": "object" }, "ReleaseInput": { "additionalProperties": false, "properties": { "channel": { "description": "版本渠道：stable 正式、preview 预览；省略默认 stable。", "enum": [ "stable", "preview" ], "type": "string" }, "download_url": { "description": "下载地址；如提供须为 HTTPS，且同时提供 sha256。", "format": "uri", "maxLength": 2000, "type": "string" }, "notes": { "description": "版本发布说明。", "maxLength": 10000, "type": "string" }, "published_at": { "description": "版本发布时间，UTC；省略时为服务器当前时间。", "format": "date-time", "type": "string" }, "sha256": { "description": "下载文件的 SHA-256，64 位小写十六进制；与签名算法分开。", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "description": "策略中为修改版本号；产品版本为 major.minor.patch；离线协议中固定为 1。", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" } }, "required": [ "version" ], "type": "object" }, "ReleaseList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Release" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "Renew": { "additionalProperties": false, "properties": { "days": { "description": "增加的天数，1–36500；许可证续期和维护期续期分别作用于各自期限。", "maximum": 36500, "minimum": 1, "type": "integer" } }, "required": [ "days" ], "type": "object" }, "RenewalPlans": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "Renewed": { "additionalProperties": false, "example": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "properties": { "duration_days": { "description": "首次激活前续期会增加此值；已激活后续期保留原值，实际截止时间以 expires_at 为准。", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "format": "date-time", "type": "string" }, { "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。", "type": "null" } ], "description": "许可证最终到期时间。限期/试用未激活和永久授权均可能为 null，需结合 mode 和首次激活时间判断。Key 对象中为 Key 到期时间。" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, "required": [ "id", "expires_at", "duration_days" ], "type": "object" }, "ReservationResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "设备绑定或运行会话 UUID。保存后用于后续授权请求，不是许可证密钥。", "format": "uuid", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "当前心跳间隔，单位秒；计次不更新签名或心跳调度。", "type": "integer" }, "reservation": { "$ref": "#/components/schemas/FeatureReservation" } }, "required": [ "activation_id", "reservation" ], "type": "object" }, "Revenue": { "additionalProperties": false, "properties": { "invoices": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "month": { "type": "string" }, "paid_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "refunded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "type": "string" }, "offset": { "type": "integer" }, "paddle_totals": { "description": "服务购买和钱包充值的付款总额与累计退款，按原付款月份和币种分组；不表示银行结算。", "items": { "additionalProperties": false, "properties": { "currency": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" }, "paid_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "refunded_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "paid_users": { "type": "integer" }, "purchase_total": { "type": "integer" }, "purchases": { "items": { "additionalProperties": false, "properties": { "api_calls": { "type": "integer" }, "api_overage_cents": { "type": "integer" }, "base_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "overage_cents": { "type": "integer" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "type": "string" }, "source": { "enum": [ "purchase", "gift" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "pending", "active", "cancelled" ], "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "recharged_users": { "type": "integer" }, "registered_users": { "type": "integer" }, "sales": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "quantity": { "type": "integer" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "sold_subscriptions": { "type": "integer" }, "timezone": { "type": "string" }, "topup_total": { "type": "integer" }, "topups": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "credited_at": { "format": "date-time", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "description": "钱包充值的原支付提供方；退款仍与其绑定。", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "refunded_cents": { "type": "integer" }, "status": { "type": "string" }, "tenant_name": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "totals": { "items": { "additionalProperties": false, "properties": { "consumption_cents": { "type": "integer" }, "consumption_refund_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "paypal_refund_cents": { "type": "integer" }, "recharge_cents": { "type": "integer" }, "wallet_refund_cents": { "description": "PayPal、Paddle 和 Waffo 已执行的钱包退款或撤销；不包括临时退款预留。", "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "upgrade_total": { "description": "所选环境和报表期间内已应用升级数量，包括免费升级。与首次套餐销售分别统计。", "type": "integer" }, "upgrades": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "description": "按剩余时长折算后实际支付的金额，不是新套餐完整月费。", "type": "integer" }, "applied_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "description": "原套餐到期时间，升级不改变。", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "plan_name": { "description": "目标套餐名称。", "type": "string" }, "previous_plan_name": { "description": "本次升级前生效的套餐。", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "id", "email", "tenant_name", "plan_name", "previous_plan_name", "currency", "amount_cents", "applied_at", "ends_at" ], "type": "object" }, "type": "array" }, "waffo_totals": { "description": "服务购买和钱包充值的付款总额与累计退款，按原付款月份和币种分组；不表示银行结算。", "items": { "additionalProperties": false, "properties": { "currency": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "paid_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "refunded_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" } }, "required": [], "type": "object" }, "RuntimeAPIPeriod": { "additionalProperties": false, "properties": { "api_calls": { "description": "当前统计范围内成功且计量的运行 API 次数；不包含这里的管理请求。", "type": "integer" }, "api_hard_limit": { "description": "是否在用完 API 额度后拒绝继续调用。", "type": "boolean" }, "api_overage_cents": { "description": "本周期 API 超额消费，百分之一货币单位。", "type": "integer" }, "api_unit_micros": { "description": "每次超额运行 API 调用的价格，百万分之一货币单位。", "minimum": 0, "type": "integer" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "included_api_calls": { "description": "包含的成功运行 API 次数；null 表示无限，0 表示没有免费次数。", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "价格版本", "type": "string" } }, "required": [], "type": "object" }, "RuntimeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "上次成功激活返回的 data.activation_id。除首次 activate 外，验证、心跳、计次、解绑必须填写。", "format": "uuid", "type": "string" }, "app_version": { "description": "当前软件版本，格式为 major.minor.patch，如 1.0.0。有维护期或版本范围限制时必须填写，不能把版本冒充为旧版。", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "SDK 根据产品和本机系统、硬件身份计算的 64 位小写十六进制 SHA-256。不能任意填写固定值。", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "控制台显示的设备名称，最多 120 字符，不决定设备身份。", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK 自动生成的本机身份资料。策略要求硬件、拒绝虚拟机或启用硬件迁移时按策略提供。" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "本次消耗的功能标识。", "maxLength": 64, "type": "string" }, "identity_token": { "description": "一次性、带类型的 Ed25519 Launch 身份 JWT；不信任任何权益声明作为购买权限。", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "license_key": { "description": "完整客户授权码。lv_lic_ 为普通许可证密钥；lv_tmp_ 仅用于首次兑换激活；成功后 SDK 使用机器绑定的 lv_dev_ 凭证。不是厂商管理 API Key。", "pattern": "^(?:lv_(?:lic|tmp|dev)_[A-Za-z0-9_-]{43})?$", "type": "string", "writeOnly": true }, "product_id": { "description": "产品 UUID，必须与许可证所属产品一致。", "format": "uuid", "type": "string" }, "quantity": { "description": "本次业务申请的次数，整数 1–1000000000。", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "SDK 能力协商。当前绑定尚未保留票据时，请求仅限解绑的退出票据；已保留有效退出票据时省略，稳定状态的心跳因此不增加票据查询。", "type": "boolean" }, "reservation_id": { "description": "预留编号，确认或取消时传入此值。", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "可选预留有效秒数，30–3600；默认 900，周期重置时会提前结束。", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "浮动授权必填：每个运行实例新建一个 UUID，同一实例的后续请求沿用。绑定设备模式可省略。", "format": "uuid", "type": "string" } }, "required": [ "product_id", "license_key", "device_id" ], "type": "object" }, "RuntimePolicy": { "additionalProperties": false, "properties": { "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "联网时多久发送一次心跳，单位秒。0 关闭周期心跳，和允许离线时长分别设置。", "type": "integer" }, "offline_mode": { "description": "limited：有限离线；none：不允许离线；permanent：不另设离线时长上限，但仍受许可证有效期限制。", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "允许的离线秒数：limited 为 1–31536000，none/permanent 为 0。这不是心跳间隔。启用心跳时，新的有限离线策略必须满足 offline_seconds \u003e= 3 × heartbeat_seconds；浮动席位租约也必须至少覆盖三个心跳间隔。", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [ "heartbeat_seconds", "offline_mode", "offline_seconds" ], "type": "object" }, "RuntimeResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "设备绑定或运行会话 UUID。保存后用于后续授权请求，不是许可证密钥。", "format": "uuid", "type": "string" }, "deactivated": { "description": "解绑成功时为 true。该接口释放绑定或会话，不删除许可证、不重置有效期。", "type": "boolean" }, "device_key": { "description": "SDK 保存的本机设备凭证，不应写日志或分发给其他设备。", "pattern": "^lv_dev_[A-Za-z0-9_-]{43}$", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。" }, { "description": "周期心跳间隔，单位秒。0 关闭；启用时为 600–86400。省略时采用服务器默认值，与离线时长分别设置。", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "建议心跳间隔，单位秒。0 时顶层字段可能省略；签名中的 runtime_policy.heartbeat_seconds 才是完整策略值。", "type": "integer" }, "lease": { "$ref": "#/components/schemas/Lease", "description": "服务器签名的授权缓存。使用固定受信公钥验签、核对产品和设备后再接受。解绑及功能计次不返回此项。" }, "logout_ticket": { "$ref": "#/components/schemas/LogoutTicket", "description": "仅可解绑此精确绑定代次的能力凭据；不得写入运行时请求日志。" } }, "required": [ "activation_id" ], "type": "object" }, "SDKConfig": { "additionalProperties": false, "example": { "allow_http": false, "app_version": "", "base_url": "https://www.licentivo.com", "cache_path": "", "device_name": "My application", "license_key": "", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "allow_http": { "description": "是否允许 HTTP，仅用于本地开发。", "type": "boolean" }, "app_version": { "description": "当前软件的 major.minor.patch 版本号。", "type": "string" }, "base_url": { "description": "授权服务器根地址，通常为 HTTPS，不包含 /api/v1。", "type": "string" }, "cache_path": { "description": "本机授权缓存路径；空字符串让 SDK 选择当前用户私有目录。", "type": "string" }, "device_name": { "description": "便于识别设备的名称，不作为安全身份依据。", "type": "string" }, "license_key": { "description": "完整客户授权码，在软件激活时输入。产品初始化代码与示例下载不包含该密钥；离线申请使用 SDK 输出的对应凭证。", "type": "string" }, "product_id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "公钥 UUID 到 Base64URL 公钥的映射，用于固定信任的验签公钥。", "type": "object" } }, "required": [ "base_url", "product_id", "license_key", "app_version", "device_name", "trusted_keys", "cache_path", "allow_http" ], "type": "object" }, "SDKExampleInfo": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "can_configure": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "starts_at_first_activation": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleSetting": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "policy_id": { "description": "专用策略 UUID；初始设置前为空。", "type": "string" }, "product_id": { "description": "专用产品 UUID；初始设置前为空。", "type": "string" } }, "required": [ "available", "duration_days", "product_id", "policy_id" ], "type": "object" }, "SDKExampleSetup": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleTrial": { "additionalProperties": false, "properties": { "duration_days": { "const": 3, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "first_activated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "license_key": { "type": "string" }, "starts_at_first_activation": { "type": "boolean" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "SDKInitializer": { "additionalProperties": false, "example": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "language": { "description": "下载包的 SDK 语言标识。", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "source": { "description": "权益来源，例如 purchase 购买或 gift 赠送。", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "公钥 UUID 到 Base64URL 公钥的映射，用于固定信任的验签公钥。", "type": "object" } }, "required": [ "product_id", "trusted_keys", "language", "source" ], "type": "object" }, "ScheduledPlan": { "additionalProperties": false, "properties": { "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "type": "string" }, "effective_month": { "description": "安排生效的 UTC 月，YYYY-MM。", "type": "string" }, "plan": { "description": "计费方案的稳定标识，实际可选值来自公开套餐目录。", "type": "string" }, "sandbox": { "description": "测试环境", "type": "boolean" } }, "required": [], "type": "object" }, "ScopedRefundPreview": { "additionalProperties": false, "properties": { "affected_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "auto_renewal_disabled": { "type": "boolean" }, "auto_renewal_enabled": { "type": "boolean" }, "cancellation_at": { "const": "approval", "type": "string" }, "pending_purchase_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "pending_upgrade_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "remaining_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "request": { "$ref": "#/components/schemas/CustomerRefundInput" }, "scope": { "enum": [ "purchase", "service" ], "type": "string" }, "totals": { "items": { "$ref": "#/components/schemas/ScopedRefundTotal" }, "type": "array" } }, "required": [], "type": "object" }, "ScopedRefundPurchase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "maximum_cents": { "type": "integer" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "requires_review": { "type": "boolean" }, "source": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ScopedRefundTotal": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "held_cents": { "type": "integer" }, "manual_cents": { "type": "integer" } }, "required": [], "type": "object" }, "ServiceCompensation": { "additionalProperties": false, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "incident_id": { "description": "对应服务事件 UUID。", "format": "uuid", "type": "string" }, "intervals": { "description": "补偿涉及的时间区间，以 JSON 字符串返回。", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "type": "string" }, "purchase_id": { "description": "关联的套餐合同 UUID。", "format": "uuid", "type": "string" }, "seconds": { "description": "服务补偿增加的秒数。", "type": "integer" } }, "required": [ "id", "incident_id", "mode", "seconds", "purchase_id", "created_at" ], "type": "object" }, "ServiceCompensationList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/ServiceCompensation" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "ServiceIncident": { "additionalProperties": false, "properties": { "affected_tenants": { "description": "JSON 编码的工作空间 ID 数组；[] 表示全局。", "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "ServiceIncidentInput": { "additionalProperties": false, "properties": { "affected_tenants": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "body": { "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expected_version": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "maintenance", "incident" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "title": { "type": "string" } }, "required": [ "kind", "title", "body", "starts_at" ], "type": "object" }, "ServiceIncidentList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ServiceIncident" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SignedCapabilities": { "additionalProperties": false, "properties": { "app_version": { "description": "本次 Launch 授权操作的应用版本。", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "binding_version": { "description": "与授权会话关联、经过签名的设备绑定代次。", "minimum": 1, "type": "integer" }, "environment": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" }, "launch_connection_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "license_model": { "description": "本次 Launch 授权操作的许可证模式。", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "description": "本次 Launch 授权操作的维护期截止时间。", "type": "integer" }, "session_expires_at": { "description": "本次 Launch 授权操作的会话到期时间。", "maximum": 253402300799, "type": "integer" }, "session_id": { "description": "本次 Launch 授权操作的会话 ID。", "format": "uuid", "type": "string" }, "version_released_at": { "description": "本次 Launch 授权操作的版本发布时间。", "type": "integer" } }, "required": [ "license_model" ], "type": "object" }, "SigningKey": { "additionalProperties": false, "properties": { "active": { "description": "公钥对象中表示当前签名密钥；策略预览中表示活跃设备或会话数量。", "type": "boolean" }, "algorithm": { "const": "Ed25519", "description": "签名算法，当前为 Ed25519。", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "key_id": { "description": "产品签名公钥 UUID，用于找到对应的验签公钥。", "format": "uuid", "type": "string" }, "public_key": { "description": "Base64URL 编码的 Ed25519 公钥；不含私钥。", "type": "string" }, "retired_at": { "anyOf": [ { "description": "签名密钥停用时间；当前密钥为 null，旧公钥仍可验签。", "format": "date-time", "type": "string" }, { "description": "签名密钥停用时间；当前密钥为 null，旧公钥仍可验签。", "type": "null" } ], "description": "签名密钥停用时间；当前密钥为 null，旧公钥仍可验签。" } }, "required": [ "key_id", "public_key", "active" ], "type": "object" }, "StateResult": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "properties": { "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "Subscription": { "additionalProperties": false, "properties": { "current": { "$ref": "#/components/schemas/Period", "description": "当前 UTC 月的默认计费快照。" }, "next": { "anyOf": [ { "$ref": "#/components/schemas/PendingPlan", "description": "已安排的下月默认计费方案；没有时为 null。" }, { "description": "已安排的下月默认计费方案；没有时为 null。", "type": "null" } ], "description": "已安排的下月默认计费方案；没有时为 null。" }, "sandbox": { "description": "测试环境", "type": "boolean" } }, "required": [], "type": "object" }, "Summary": { "additionalProperties": false, "properties": { "active_licenses": { "description": "状态 active 且未到期的许可证数量，包含尚未首次激活的许可证。", "type": "integer" }, "licenses": { "description": "未归档许可证数量。", "type": "integer" }, "policies": { "description": "未归档策略数量。", "type": "integer" }, "products": { "description": "概览中为产品数量；用量中为各产品活跃设备的分组数组。", "type": "integer" } }, "required": [ "products", "policies", "licenses", "active_licenses" ], "type": "object" }, "SupportCase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "cancellation_preview": { "description": "JSON 编码的取消预览。", "type": "string" }, "cancellation_scope": { "type": "string" }, "change_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "decision": { "type": "string" }, "first_response_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "held_cents": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "incident_id": { "type": "string" }, "kind": { "type": "string" }, "manual_cents": { "type": "integer" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "refund_totals": { "description": "JSON 编码的分币种总额；绝不能将不同币种相加。", "type": "string" }, "request_id": { "type": "string" }, "response_due_at": { "format": "date-time", "type": "string" }, "review_due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope_ids": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "SupportCaseDetail": { "additionalProperties": false, "properties": { "case": { "$ref": "#/components/schemas/SupportCase" }, "messages": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "staff": { "type": "boolean" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "original_refund_receipts": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "intent_id": { "format": "uuid", "type": "string" }, "refund_id": { "type": "string" } }, "type": "object" }, "type": "array" }, "original_refunds": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" }, "refund_payments": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "provider_order_id": { "type": "string" }, "refunded_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "refund_provider": { "type": "string" }, "refund_unverified": { "type": "boolean" }, "refunds": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" } }, "required": [], "type": "object" }, "SupportCaseInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "kind": { "enum": [ "support", "privacy", "appeal" ], "type": "string" }, "request_id": { "maxLength": 80, "type": "string" }, "subject": { "maxLength": 200, "type": "string" } }, "required": [ "subject", "body", "request_id" ], "type": "object" }, "SupportCaseList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SupportCase" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SupportContact": { "additionalProperties": false, "properties": { "email": { "description": "公开支持邮箱及计费邮件的 Reply-To。为空时隐藏联系方式。不改变已有 SMTP From 地址，也不创建收件箱。", "maxLength": 254, "type": "string" } }, "required": [ "email" ], "type": "object" }, "SupportReadInput": { "additionalProperties": false, "properties": { "last_message_id": { "format": "uuid", "type": "string" } }, "required": [ "last_message_id" ], "type": "object" }, "SupportReply": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "", "reviewing", "awaiting_info", "resolved" ], "type": "string" } }, "required": [ "body" ], "type": "object" }, "SupportUnread": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "unread_messages": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "unread_cases": { "type": "integer" }, "unread_messages": { "type": "integer" }, "unread_notices": { "type": "integer" } }, "required": [], "type": "object" }, "SystemSettings": { "additionalProperties": false, "properties": { "database": { "$ref": "#/components/schemas/DatabaseStatus" }, "environment": { "type": "string" }, "mail": { "$ref": "#/components/schemas/MailSettings" }, "public_url": { "format": "uri", "type": "string" } }, "required": [ "mail", "database" ], "type": "object" }, "TLSCertificateInfo": { "additionalProperties": false, "properties": { "algorithm": { "type": "string" }, "chain_length": { "maximum": 10, "minimum": 1, "type": "integer" }, "domains": { "items": { "type": "string" }, "type": "array" }, "fingerprint_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "issuer": { "type": "string" }, "not_after": { "format": "date-time", "type": "string" }, "not_before": { "format": "date-time", "type": "string" }, "self_signed": { "type": "boolean" }, "serial_number": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "domains", "subject", "issuer", "not_before", "not_after", "fingerprint_sha256", "serial_number", "algorithm", "chain_length", "self_signed" ], "type": "object" }, "TLSCertificateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "PEM 叶证书，随后依序附上中间证书。必须匹配 public_url。仅本地开发允许自签名证书。", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "使用 GET /system/tls 返回的 version。更新时必填；并发替换返回 409。", "type": "string" }, "private_key_pem": { "description": "匹配且未加密的 PEM 密钥（PKCS#8、RSA 或 EC）。任何响应都绝不返回。", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem" ], "type": "object" }, "TLSCertificateResult": { "additionalProperties": false, "properties": { "certificate": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "certificate", "version", "updated_at" ], "type": "object" }, "TLSCertificateUpdateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "PEM 叶证书，随后依序附上中间证书。必须匹配 public_url。仅本地开发允许自签名证书。", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "使用 GET /system/tls 返回的 version。更新时必填；并发替换返回 409。", "type": "string" }, "private_key_pem": { "description": "匹配且未加密的 PEM 密钥（PKCS#8、RSA 或 EC）。任何响应都绝不返回。", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem", "expected_version" ], "type": "object" }, "TLSStatus": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "certificate": { "anyOf": [ { "$ref": "#/components/schemas/TLSCertificateInfo" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "http_redirect_address": { "type": "string" }, "public_url": { "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "version": { "type": "string" } }, "required": [ "enabled", "public_url", "address", "http_redirect_address", "certificate", "version", "updated_at" ], "type": "object" }, "TestMail": { "additionalProperties": false, "properties": { "to": { "format": "email", "type": "string" } }, "required": [ "to" ], "type": "object" }, "Token": { "additionalProperties": false, "properties": { "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" }, "TokenPassword": { "additionalProperties": false, "properties": { "password": { "description": "12–128 个 UTF-8 字节，而非字符", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "必填，并须与密码完全一致", "type": "string", "writeOnly": true }, "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token", "password", "password_confirmation" ], "type": "object" }, "TransferCode": { "additionalProperties": false, "properties": { "activation_code": { "pattern": "^lv_tmp_[A-Za-z0-9_-]{43}$", "type": "string" }, "activation_id": { "format": "uuid", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "license_id": { "format": "uuid", "type": "string" } }, "required": [ "activation_id", "activation_code", "expires_at", "license_id" ], "type": "object" }, "TranslationCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider_usage": { "additionalProperties": false, "properties": { "character_count": { "type": "integer" }, "character_limit": { "type": "integer" } }, "required": [ "character_count", "character_limit" ], "type": "object" } }, "required": [ "connected", "languages", "provider_usage" ], "type": "object" }, "TranslationLanguage": { "additionalProperties": false, "properties": { "lang": { "description": "DeepL v3 返回的 BCP 47 目标代码，例如 en-US 或 zh-Hant。", "type": "string" }, "name": { "type": "string" }, "usable_as_target": { "type": "boolean" } }, "required": [ "lang", "name", "usable_as_target" ], "type": "object" }, "TranslationOptions": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider": { "type": "string" } }, "required": [ "enabled", "languages", "provider" ], "type": "object" }, "TranslationSettings": { "additionalProperties": false, "properties": { "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "key_configured": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "local_usage": { "$ref": "#/components/schemas/TranslationUsage" }, "monthly_limit": { "description": "本地月度字符预算，独立于 DeepL 账号额度及账期。", "type": "integer" }, "requests_per_minute": { "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" }, "version": { "type": "string" } }, "required": [ "enabled", "tier", "key_configured", "monthly_limit", "requests_per_minute", "languages", "checked_at", "version", "local_usage" ], "type": "object" }, "TranslationSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "加密保存。为空时保留已保存密钥，除非 clear_key 为 true。改变密钥或档位后必须再次成功检查连接。", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_key": { "type": "boolean" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "monthly_limit": { "maximum": 1000000000, "minimum": 1, "type": "integer" }, "requests_per_minute": { "maximum": 60, "minimum": 1, "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" } }, "required": [ "enabled", "tier", "monthly_limit", "requests_per_minute", "expected_version" ], "type": "object" }, "TranslationUsage": { "additionalProperties": false, "properties": { "characters": { "description": "已成功计费字符数，加上结果未知请求的保守预留。缓存命中不增加用量。", "type": "integer" }, "month": { "description": "UTC 自然月 YYYY-MM。", "type": "string" } }, "required": [ "month", "characters" ], "type": "object" }, "Trial": { "additionalProperties": false, "properties": { "base_url": { "type": "string" }, "duration_days": { "const": 7, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "isolated": { "type": "boolean" }, "key": { "type": "string", "writeOnly": true }, "license_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" } }, "required": [ "product_id", "license_id", "key", "trusted_keys" ], "type": "object" }, "UpgradeList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/PlanUpgrade" }, "type": "array" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "UpgradePart": { "additionalProperties": false, "description": "针对当前或未来某一预付周期冻结的升级计算。change.amount_cents 是该周期差额；只有上层报价才收取合计金额。", "properties": { "change": { "$ref": "#/components/schemas/PlanUpgrade", "description": "该分项的升级价格及权益记录。" }, "ends_at": { "description": "套餐或周期结束时间，UTC；尚未生效时可能为 null。", "format": "date-time", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "source": { "description": "权益来源，例如 purchase 购买或 gift 赠送。", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "description": "套餐或周期开始时间，UTC。", "format": "date-time", "type": "string" } }, "required": [ "id", "source", "starts_at", "ends_at", "change" ], "type": "object" }, "UpgradeQuoteInput": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "type": "string" }, "request_id": { "maxLength": 80, "type": "string" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "Usage": { "additionalProperties": false, "properties": { "active_devices": { "description": "该统计范围内按产品和设备去重的活跃设备数。", "type": "integer" }, "api_calls": { "description": "当前统计范围内成功且计量的运行 API 次数；不包含这里的管理请求。", "type": "integer" }, "api_period": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeAPIPeriod", "description": "当前 UTC 月默认 API 额度快照；默认额度未启用时可能为 null。" }, { "description": "当前 UTC 月默认 API 额度快照；默认额度未启用时可能为 null。", "type": "null" } ], "description": "当前 UTC 月默认 API 额度快照；默认额度未启用时可能为 null。" }, "billable_devices": { "description": "未由预付套餐覆盖、进入默认月度计费的设备数。", "type": "integer" }, "estimated_total_cents": { "description": "默认月度设备账单预估，百分之一货币单位。", "type": "integer" }, "estimated_total_micros": { "description": "默认月度设备账单预估，百万分之一货币单位；不是所有套餐消费合计。", "type": "integer" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "operations": { "description": "按 activate、validate、heartbeat、deactivate 拆分的成功计量调用次数。", "items": { "additionalProperties": false, "properties": { "count": { "description": "当前分组的数量，或本次批量成功处理的条数。", "type": "integer" }, "operation": { "description": "操作名称；批量接口支持 create、renew、revoke、apply_policy；离线申请支持 activate、deactivate。", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "overage_devices": { "description": "超过所含额度的设备数量。", "type": "integer" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/Period", "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。" }, { "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。", "type": "null" } ], "description": "默认 UTC 月计费快照；计次规则中为 month/day/lifetime，用量记录中为实际周期键。" }, "products": { "description": "概览中为产品数量；用量中为各产品活跃设备的分组数组。", "items": { "additionalProperties": false, "properties": { "active_devices": { "description": "该统计范围内按产品和设备去重的活跃设备数。", "type": "integer" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "purchased": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "当前有效的滚动月套餐；没有时为 null。" }, { "description": "当前有效的滚动月套餐；没有时为 null。", "type": "null" } ], "description": "当前有效的滚动月套餐；没有时为 null。" }, "purchased_active_devices": { "description": "当前已购套餐周期内的活跃设备数。", "type": "integer" }, "sandbox": { "description": "测试环境", "type": "boolean" }, "timezone": { "description": "用量统计时区，固定 UTC。", "type": "string" }, "warning": { "description": "normal 正常、near_quota 接近额度、quota_reached 已达到默认设备额度。", "type": "string" } }, "required": [], "type": "object" }, "UsageDevice": { "additionalProperties": false, "properties": { "device_id": { "description": "产品范围内的设备指纹，通常是 64 位小写十六进制；由 SDK 从当前机器计算。", "type": "string" }, "first_seen_at": { "description": "该月首次记录此设备活动的 UTC 时间。", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "服务器最后一次收到该设备活动的 UTC 时间。", "format": "date-time", "type": "string" }, "month": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "type": "string" }, "product_id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "UsageDeviceList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/UsageDevice" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Verified": { "additionalProperties": false, "properties": { "verified": { "type": "boolean" } }, "required": [ "verified" ], "type": "object" }, "VersionedActivationReleaseInput": { "additionalProperties": false, "properties": { "expected_generation": { "description": "当前设备列表显示的绑定代次。Launch 账号绑定必填；过时版本绝不会释放较新的绑定。", "minimum": 1, "type": "integer" }, "operation_id": { "description": "用于重试恢复的稳定操作 UUID。Launch 账号绑定必填。", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "WaffoCheck": { "additionalProperties": false, "properties": { "connected": { "description": "开启", "type": "boolean" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "WaffoOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "原结账创建窗口的 UTC 截止时间。", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "经验证付款启用服务或记入钱包充值的 UTC 时间。purchase_id 和 upgrade_id 均为 null 时表示充值。" }, "checkout_expires_at": { "description": "原结账创建窗口的 UTC 截止时间。", "format": "date-time", "type": "string" }, "created_at": { "description": "原结账创建窗口的 UTC 截止时间。", "format": "date-time", "type": "string" }, "currency": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "原结账创建窗口的 UTC 截止时间。", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "后端确认 Waffo 交易完成的 UTC 时间。" }, "provider_order_id": { "anyOf": [ { "description": "以 MER_ 开头的商户标识。", "type": "string" }, { "type": "null" } ], "description": "从已验证 API 响应中恢复的原 ORD_ 标识。" }, "purchase_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的服务购买或续费，与 upgrade_id 互斥。" }, "refunded_cents": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" }, "request_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "status": { "description": "支付生命周期；已收款但需要经营者审核和退款时包括 paid_unapplied。", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的升级报价，与 purchase_id 互斥。" } }, "required": [ "id", "request_id", "mode", "provider_order_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "checkout_expires_at", "paid_at", "applied_at", "created_at" ], "type": "object" }, "WaffoOrderInput": { "additionalProperties": false, "description": "支付一份已冻结的购买或升级，或使用 amount 和 currency、且不提供服务 ID 来创建钱包充值。稳定的 request_id 返回原付款；不允许改变其意图、金额或币种。只有独立验证完成的付款才可记入钱包或启用服务。充值完成后返回钱包。重试只可在原结账创建窗口内复用原提供方幂等密钥。", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "仅钱包充值必填。显示用小数金额必须在配置限制内。服务订单拒绝客户端金额。", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "仅钱包充值必填，并且此提供方必须启用该币种。", "type": "string" }, "overage_accepted": { "description": "对已显示的收费超额用量进行单独明确授权。", "type": "boolean" }, "policy_version": { "description": "当前已发布的不可变条款版本。经营者发布条款后，任一支付环境中的受同意保护操作均要求提供。", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的服务购买或续费，与 upgrade_id 互斥。" }, "request_id": { "description": "调用方生成的稳定请求密钥。重放返回原结账。", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "明确接受，默认不得勾选。", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "本地服务付款标识。", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "已有待付款的升级报价，与 purchase_id 互斥。" } }, "required": [ "request_id" ], "type": "object" }, "WaffoOrderList": { "additionalProperties": false, "properties": { "items": { "description": "条目", "items": { "$ref": "#/components/schemas/WaffoOrder" }, "type": "array" }, "total": { "description": "以最小货币单位固定的完整服务价格；不允许钱包充值或混合支付。", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "WaffoOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "短期有效且带认证的结账 URL；付款、到期或渠道关闭后为空。绝不能记录日志或缓存。", "type": "string" }, "order": { "$ref": "#/components/schemas/WaffoOrder", "description": "订单" }, "return_url": { "description": "充值返回钱包控制台 URL，服务付款返回定价核对 URL。仅凭返回 URL 绝不能证明付款。", "format": "uri", "type": "string" } }, "required": [ "order", "approval_url", "return_url" ], "type": "object" }, "WaffoSettings": { "additionalProperties": false, "properties": { "currencies": { "description": "币种", "items": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "type": "array" }, "enabled": { "description": "开启", "type": "boolean" }, "maximum_cents": { "description": "钱包最高充值额，使用最小货币单位；默认 100000，且不能小于 minimum_cents。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "minimum_cents": { "description": "钱包最低充值额，使用最小货币单位；默认 100。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key_configured": { "description": "开启", "type": "boolean" }, "product_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "store_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "version": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "webhook_public_key": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "webhook_url": { "description": "Webhook 通知地址", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "private_key_configured", "webhook_public_key", "version", "webhook_url" ], "type": "object" }, "WaffoSettingsInput": { "additionalProperties": false, "properties": { "clear_private_key": { "description": "开启", "type": "boolean" }, "currencies": { "description": "币种", "items": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "type": "array" }, "enabled": { "description": "开启", "type": "boolean" }, "expected_version": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "maximum_cents": { "description": "钱包最高充值额，使用最小货币单位；默认 100000，且不能小于 minimum_cents。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "minimum_cents": { "description": "钱包最低充值额，使用最小货币单位；默认 100。", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key": { "description": "RSA 签名私钥。静态加密保存；为空时保留已保存密钥。", "maxLength": 8192, "type": "string", "writeOnly": true }, "product_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "store_id": { "description": "以 MER_ 开头的商户标识。", "type": "string" }, "webhook_public_key": { "description": "可选的官方 Webhook 公钥覆盖值。为空时使用所选环境的 SDK 公钥。", "maxLength": 8192, "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "expected_version" ], "type": "object" }, "WaffoWebhookEvent": { "description": "原始 Waffo 事件，使用 X-Waffo-Signature、所选环境公钥、商店和模式认证。付款与退款通过 API 独立验证。", "type": "object" }, "Wallet": { "additionalProperties": false, "properties": { "balance_cents": { "description": "钱包余额或该笔流水后的余额，百分之一货币单位。", "type": "integer" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "WalletEntry": { "additionalProperties": false, "properties": { "amount_cents": { "description": "本笔金额，百分之一货币单位；流水可为正（入账）或负（支出）。", "type": "integer" }, "balance_cents": { "description": "钱包余额或该笔流水后的余额，百分之一货币单位。", "type": "integer" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "currency": { "description": "三位大写货币代码，例如 USD；金额按此货币解释。", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "kind": { "description": "流水或通知的类别标识。", "type": "string" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "reference": { "description": "关联业务的标识，用于追踪来源。", "type": "string" } }, "required": [], "type": "object" }, "WalletEntryList": { "additionalProperties": false, "properties": { "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/WalletEntry" }, "type": "array" }, "limit": { "description": "每页条数，默认 25，范围 1–100。", "type": "integer" }, "offset": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "type": "integer" }, "total": { "description": "符合筛选条件的总记录数，不是当前页长度。", "type": "integer" } }, "required": [], "type": "object" }, "WalletRefundRequest": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 1, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "description": "仅管理员列表使用。", "type": "string" }, "decision": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "reason": { "type": "string" }, "refund_id": { "format": "uuid", "type": [ "string", "null" ] }, "refund_status": { "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "review_status": { "enum": [ "pending", "approved", "declined", "cancelled" ], "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending_review", "refund_pending", "refunded", "refund_failed", "declined", "cancelled" ], "type": "string" }, "tenant_name": { "description": "仅管理员列表使用。", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "mode", "currency", "amount_cents", "reason", "status", "review_status" ], "type": "object" }, "WalletRefundRequestInput": { "additionalProperties": false, "properties": { "amount": { "description": "正数金额，同时受订单未退款金额和当前未消费钱包余额限制。", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id", "mode" ], "type": "object" }, "WalletRefundRequestList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletRefundRequest" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "mode" ], "type": "object" }, "WalletRefundReview": { "additionalProperties": false, "properties": { "approve": { "type": "boolean" }, "decision": { "maxLength": 1000, "minLength": 1, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "WalletResult": { "additionalProperties": false, "properties": { "currencies": { "description": "当前环境允许的货币代码数组。", "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "description": "本次返回的记录数组；数组元素字段见 items[]。部分空集合可能返回 null，见类型。", "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" }, "maximum_cents": { "description": "最高充值金额，百分之一货币单位。", "type": "integer" }, "minimum_cents": { "description": "最低充值金额，百分之一货币单位。", "type": "integer" }, "mode": { "description": "授权期限类型：perpetual 永久、timed 限期、trial 试用；计费对象中为 sandbox 测试或 live 正式环境。", "enum": [ "sandbox", "live" ], "type": "string" }, "payment_channels": { "description": "可用支付渠道配置。只显示已启用、且匹配当前计费环境和购买币种的渠道。", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "description": "当前环境是否启用 PayPal 收款。", "type": "boolean" } }, "required": [], "type": "object" }, "WebhookAttempt": { "additionalProperties": false, "properties": { "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "delivery_id": { "description": "此尝试对应的投递任务 UUID。", "format": "uuid", "type": "string" }, "duration_ms": { "description": "本次投递耗时，单位毫秒。", "type": "integer" }, "error": { "description": "错误对象或一次投递的错误分类，见子字段或当前类型。", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "number": { "description": "该任务的累计尝试序号。", "type": "integer" }, "status_code": { "description": "本次收到的 HTTP 状态码；传输失败可能为 0。", "type": "integer" } }, "required": [ "id", "delivery_id", "number", "status_code", "error", "duration_ms", "created_at" ], "type": "object" }, "WebhookDelivery": { "additionalProperties": false, "properties": { "attempts": { "description": "任务累计尝试次数。", "type": "integer" }, "available_at": { "description": "任务最早可被执行的 UTC 时间。", "format": "date-time", "type": "string" }, "created_at": { "description": "资源创建时间；日期字符串使用 UTC，离线申请中为 Unix 秒。", "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "description": "投递成功时间；尚未成功时为 null。", "format": "date-time", "type": "string" }, { "description": "投递成功时间；尚未成功时为 null。", "type": "null" } ], "description": "投递成功时间；尚未成功时为 null。" }, "endpoint_id": { "description": "事件订阅端点 UUID。", "format": "uuid", "type": "string" }, "event_id": { "description": "原始事件 UUID；接收方据此去重。", "format": "uuid", "type": "string" }, "id": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" }, "last_error": { "description": "最近一次失败的错误分类；成功或未失败时可为空。", "type": "string" }, "last_status": { "description": "最近一次投递收到的 HTTP 状态码；未收到响应时可能为 0。", "type": "integer" }, "status": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "type": "string" } }, "required": [ "id", "endpoint_id", "event_id", "status", "attempts", "available_at", "last_status", "last_error", "delivered_at", "created_at" ], "type": "object" }, "WebhookEvent": { "description": "精确的已签名 PayPal 事件，通过 PayPal API 验证", "type": "object" }, "WebhookReceived": { "additionalProperties": false, "properties": { "ignored": { "type": "boolean" }, "received": { "type": "boolean" } }, "required": [], "type": "object" } }, "securitySchemes": { "closureExport": { "description": "受限的 15 分钟下载凭据，绝非控制台会话。生产环境使用 __Host-licentivo_closure_export，始终不超过原关闭截止时间。", "in": "cookie", "name": "licentivo_closure_export", "type": "apiKey" }, "customerSession": { "description": "生产环境使用 __Host-licenova_customer；买家身份独立于厂商会话。", "in": "cookie", "name": "licenova_customer", "type": "apiKey" }, "managementKey": { "bearerFormat": "lv_api_...", "scheme": "bearer", "type": "http" }, "session": { "description": "生产环境使用 __Host-licenova_session", "in": "cookie", "name": "licenova_session", "type": "apiKey" } } }, "info": { "description": "Licentivo 管理与授权 API。支持签名运行时授权、绑定设备与浮动许可证、当前激活设备额度、月度 API 用量、软件功能计次、Launch 账号会话、预付费套餐、赠送、钱包自动续费及完整覆盖期升级。PayPal、Paddle 和 Waffo 支持经验证的付款及原路退款。同时提供客户条款、审批范围内的取消、支持、补偿、数据导出和账号逻辑关闭。支付环境与币种相互隔离；私有凭据加密保存，绝不返回。", "title": "Licentivo API", "version": "0.12.0", "x-document-language": "zh-Hans" }, "openapi": "3.1.0", "paths": { "/api/v1/account/closure-export.zip": { "get": { "description": "每次请求及生成完成后，都重新检查凭据和原关闭截止时间。恢复备份不能重启窗口。", "operationId": "get__api_v1_account_closure_export_zip", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "closureExport": [] } ], "summary": "在关闭后的 30 天窗口内下载" } }, "/api/v1/account/closure-export/session": { "post": { "description": "要求已验证的原邮箱和密码，且已确认关闭仍处于恰好 30 天的窗口内。15 分钟 Cookie 不会超过原截止时间，受频率限制，不能授权普通 API 或控制台访问。", "operationId": "post__api_v1_account_closure_export_session", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosureExportLogin" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ClosureExportCredential" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "验证已关闭账号，以进行受限导出" } }, "/api/v1/account/data-export": { "get": { "description": "Owner 的下载包含工作空间业务 CSV。成员个人归档包含自己的资料、帖子和申请。不包含凭据秘密、哈希和签名私钥。", "operationId": "get__api_v1_account_data_export", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "下载自己的个人及获授权数据", "x-required-role": "session" } }, "/api/v1/account/deletions": { "get": { "description": "", "operationId": "get__api_v1_account_deletions", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosureList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取自己的逻辑关闭申请", "x-required-role": "session" }, "post": { "description": "Owner 关闭时必须选择工作空间；成员只能关闭自己的账号。确认后撤销会话和 API 密钥，但保留数据。确认后 30 天内允许导出。", "operationId": "post__api_v1_account_deletions", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosure" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "申请逻辑关闭账号或工作空间", "x-required-role": "session" } }, "/api/v1/account/deletions/{id}/cancel": { "post": { "description": "", "operationId": "post__api_v1_account_deletions__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "撤回尚未确认的关闭申请", "x-required-role": "session" } }, "/api/v1/account/legal-acceptances": { "get": { "description": "", "operationId": "get__api_v1_account_legal_acceptances", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LegalAcceptanceList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取自己的条款接受回执", "x-required-role": "session" } }, "/api/v1/account/profile": { "patch": { "description": "要求当前密码。新登录邮箱会收到有效期为 30 分钟的一次性验证链接。确认之前，当前已验证登录邮箱和访问权限保持不变。", "operationId": "patch__api_v1_account_profile", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCorrection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "修正自己的姓名或申请更换登录邮箱", "x-required-role": "session" } }, "/api/v1/activate": { "post": { "description": "使用 product_id + license_key + device_id 认证，不使用 Cookie、CSRF 或厂商管理密钥。除 activate 外均要求 activation_id。每次成功请求消耗一次 API 调用；幂等重放和失败不消耗。超额时原子扣减钱包，或返回 API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT。工作空间设备额度按当前激活数计算。释放可归还额度；浮动租约到期也归还额度，而普通设备离线后仍计入注册数。仅当额度月份内的计费峰值超出已付费容量时，才收取设备超额费用；释放不会退还已产生费用。API 用量独立计算。", "operationId": "post_api_v1_activate", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "运行时激活" } }, "/api/v1/activations": { "get": { "operationId": "get_api_v1_activations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "license_id", "schema": { "description": "许可证 UUID；它不是 lv_lic_ 开头的授权码。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "released" ], "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "搜索文本；实际搜索字段和长度上限见当前接口说明。", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActivationList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询激活列表", "x-management-reference": { "group": "devices" }, "x-required-scope": "read" } }, "/api/v1/activations/{id}/release": { "post": { "operationId": "post_api_v1_activations_by_id_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/VersionedActivationReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "released" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "释放激活", "x-management-reference": { "group": "devices" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/api-keys": { "get": { "operationId": "get_api_v1_api-keys", "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "allow_http": false, "created_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "prefix": "lv_api_AAAAAAA", "revoked": false, "scope": "read" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "查询 API 密钥列表", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "post": { "operationId": "post_api_v1_api-keys", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "仅使用登录 Cookie 的写操作需要；先 GET /api/v1/auth/csrf 取得 data.csrf_token，并保留返回的 Cookie。", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": false, "expires_days": 90, "name": "Order system", "scope": "write" }, "schema": { "$ref": "#/components/schemas/KeyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeySecret", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "创建 API Key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}": { "delete": { "operationId": "delete_api_v1_api-keys_by_id", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "仅使用登录 Cookie 的写操作需要；先 GET /api/v1/auth/csrf 取得 data.csrf_token，并保留返回的 Cookie。", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "吊销 API Key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "patch": { "description": "要求 Owner 会话和 CSRF 令牌。仅更新此有效密钥；轮换时保留该设置。不改变已有 Launch 连接或运行时授权。此设置不会为 Licentivo API 启用 HTTP。", "operationId": "patch_api_v1_api-keys_by_id", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "仅使用登录 Cookie 的写操作需要；先 GET /api/v1/auth/csrf 取得 data.csrf_token，并保留返回的 Cookie。", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": true }, "schema": { "$ref": "#/components/schemas/KeyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_http": false, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyUpdated", "description": "Response data for the completed operation." }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "更新 HTTP 站点接入权限", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}/rotate": { "post": { "operationId": "post_api_v1_api-keys_by_id_rotate", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "仅使用登录 Cookie 的写操作需要；先 GET /api/v1/auth/csrf 取得 data.csrf_token，并保留返回的 Cookie。", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyRotated", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "轮换 API Key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/audit-logs": { "get": { "operationId": "get_api_v1_audit-logs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "action": "license.create", "actor_id": "33333333-3333-4333-8333-333333333333", "actor_kind": "api_key", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "request_id": "55555555-5555-4555-8555-555555555555", "resource_id": "" } ], "limit": 25, "offset": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AuditList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询审计日志", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/auth/accept-invitation": { "post": { "operationId": "post_api_v1_auth_accept-invitation", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "接受邀请" } }, "/api/v1/auth/change-password": { "post": { "operationId": "post_api_v1_auth_change-password", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "撤销账号全部凭据并设置密码" } }, "/api/v1/auth/confirm-email-change": { "post": { "description": "验证加密的一次性挑战。只有成功确认后，才更换登录邮箱、标记其已验证，并撤销已有会话、API 密钥和认证链接。已过期、已替换或因密码变化失效的挑战不能更改账号。", "operationId": "post__api_v1_auth_confirm_email_change", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChangeConfirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "确认新登录邮箱" } }, "/api/v1/auth/csrf": { "get": { "operationId": "get_api_v1_auth_csrf", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "签发与会话绑定的 CSRF 令牌" } }, "/api/v1/auth/forgot-password": { "post": { "operationId": "post_api_v1_auth_forgot-password", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "忘记密码" } }, "/api/v1/auth/login": { "post": { "operationId": "post_api_v1_auth_login", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "登录" } }, "/api/v1/auth/logout": { "post": { "operationId": "post_api_v1_auth_logout", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "撤销当前会话" } }, "/api/v1/auth/me": { "get": { "operationId": "get_api_v1_auth_me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Me" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "当前 Cookie 账号" } }, "/api/v1/auth/register": { "post": { "description": "任一支付环境中，已发布条款均要求提供 policy_version 并明确接受。收费的服务超额用量还要求 overage_accepted。首次发布条款前，不记录对草稿的同意，各操作仍执行正常的注册、定价与支付检查。", "operationId": "post_api_v1_auth_register", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "注册" } }, "/api/v1/auth/resend-verification": { "post": { "operationId": "post_api_v1_auth_resend-verification", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "重新发送验证邮件" } }, "/api/v1/auth/reset-password": { "post": { "operationId": "post_api_v1_auth_reset-password", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "重置密码" } }, "/api/v1/auth/verify-email": { "post": { "operationId": "post_api_v1_auth_verify-email", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verified" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "验证邮箱" } }, "/api/v1/billing/auto-renewal": { "get": { "description": "仅限会话；PATCH 要求工作空间 Owner。默认关闭。启用时，当前环境和币种的余额必须足够续费一次，并使用审核过的最新已付费套餐、可选期限和价格版本。到期时只扣钱包资金，绝不扣 PayPal 或银行卡。每分钟工作进程和运行时变更在租户锁内处理到期续费。重复尝试只扣一次。余额不足时等待充值；价格、套餐或可用状态改变时暂停扣款，等待重新同意。关闭只取消未来自动扣款，不取消已付款覆盖期。", "operationId": "get_api_v1_billing_auto_renewal", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "next_renewal_at": null, "setting": { "amount_cents": 0, "currency": "USD", "enabled": true, "mode": "sandbox", "plan": "starter", "plan_name": "Starter", "policy_version": "", "price_version": "example-v1", "status": "disabled", "term_months": 1, "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewalResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取自动续费设置", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "仅限会话；PATCH 要求工作空间 Owner。默认关闭。启用时，当前环境和币种的余额必须足够续费一次，并使用审核过的最新已付费套餐、可选期限和价格版本。到期时只扣钱包资金，绝不扣 PayPal 或银行卡。每分钟工作进程和运行时变更在租户锁内处理到期续费。重复尝试只扣一次。余额不足时等待充值；价格、套餐或可用状态改变时暂停扣款，等待重新同意。关闭只取消未来自动扣款，不取消已付款覆盖期。任一支付环境中，已发布条款均要求提供 policy_version 并明确接受。收费的服务超额用量还要求 overage_accepted。首次发布条款前，不记录对草稿的同意，各操作仍执行正常的注册、定价与支付检查。", "operationId": "patch_api_v1_billing_auto_renewal", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRenewalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewal" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "启用或关闭经明确同意的钱包续费" } }, "/api/v1/billing/invoices": { "get": { "operationId": "get_api_v1_billing_invoices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "month", "schema": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InvoiceList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询账单列表", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}": { "get": { "operationId": "get_api_v1_billing_invoices_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取账单", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/export.csv": { "get": { "operationId": "get_api_v1_billing_invoices_by_id_export_csv", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "invoice_id,month,currency,status,plan,price_version,active_devices,included_devices,overage_devices,base_micros,unit_micros,total_micros,total_cents\n", "schema": { "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "导出账单", "x-csv-columns": [ "invoice_id", "month", "currency", "status", "plan", "price_version", "active_devices", "included_devices", "overage_devices", "base_micros", "unit_micros", "total_micros", "total_cents" ], "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/finalize": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_finalize", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "finalized" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "结算账单", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/invoices/{id}/pay": { "post": { "description": "发起新付款前，必须明确接受当前条款。已付款操作的重放保留原始回执。", "operationId": "post_api_v1_billing_invoices_by_id_pay", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "使用余额支付已确认的历史账单", "x-required-role": "owner" } }, "/api/v1/billing/invoices/{id}/void": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_void", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "void" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "作废账单", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs": { "get": { "operationId": "get_api_v1_billing_jobs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJobList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询计费任务列表", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_billing_jobs", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "month": "2026-09" }, "schema": { "$ref": "#/components/schemas/MonthInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJob", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "计费任务入队", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs/{id}/retry": { "post": { "operationId": "post_api_v1_billing_jobs_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "重试计费任务", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/notification-preferences": { "get": { "description": "仅限 Owner 会话，拒绝管理密钥。明确保存前，四种类型默认全部启用，语言为 zh。偏好属于当前用户和工作空间。复用认证邮件传输、发件人、加密持久化队列和重试。平台权限与收件人同意必须同时允许对应类型。投递时重新核对当前同意状态与事件状态。邮件选项不会授予或撤销钱包扣款同意。sandbox 邮件会标明环境。未付款的待处理购买或赠送不会创建通知。", "operationId": "get__api_v1_billing_notification_preferences", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreferencesResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取当前所有者的邮件同意设置", "x-required-role": "owner" }, "patch": { "description": "部分更新会话所有者的设置，不能指定其他用户。语言控制后续邮件，已有验证邮件和安全邮件保持独立。复用认证邮件传输、发件人、加密持久化队列和重试。平台权限与收件人同意必须同时允许对应类型。投递时重新核对当前同意状态与事件状态。邮件选项不会授予或撤销钱包扣款同意。sandbox 邮件会标明环境。未付款的待处理购买或赠送不会创建通知。", "operationId": "patch__api_v1_billing_notification_preferences", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationPreferenceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "保存当前所有者的邮件同意设置", "x-required-role": "owner" } }, "/api/v1/billing/overage-consent": { "post": { "description": "", "operationId": "post__api_v1_billing_overage_consent", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOverageConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "明确授权当前钱包超额使用", "x-required-role": "owner" } }, "/api/v1/billing/overage-settings": { "get": { "description": "仅限当前租户，只读成员可查看。客户超额偏好绝不会限制无限 API 额度。套餐为 null 表示默认额度不可用。", "operationId": "get__api_v1_billing_overage_settings", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_api_settings_enabled": false, "customer_device_settings_enabled": false, "plan": null, "preference": { "block_api_overage": false, "block_device_overage": false, "mode": "sandbox", "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OverageSettings", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取超额使用偏好", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "仅限 Owner 会话。每项提交的选择都要求对应管理员权限；未授权字段会使整个请求返回 403。运行时硬限制 = 管理员限制，或在相应权限已开放时客户选择的阻止偏好。不清除历史用量或费用。sandbox 与 live 的偏好相互独立。", "operationId": "patch__api_v1_billing_overage_settings", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OveragePreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "分别保存设备与 API 超额使用偏好" } }, "/api/v1/billing/paddle/orders": { "get": { "operationId": "get__api_v1_billing_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询 Paddle 服务付款和钱包充值", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_paddle_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "创建或恢复一笔 Paddle 服务付款", "x-licentivo-access": "owner" } }, "/api/v1/billing/paddle/orders/{id}": { "get": { "operationId": "get__api_v1_billing_paddle_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取所属结账交易和公开客户端令牌", "x-licentivo-access": "session" } }, "/api/v1/billing/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "验证付款并一次性交付购买的服务", "x-licentivo-access": "owner" } }, "/api/v1/billing/paypal/orders": { "get": { "operationId": "get_api_v1_billing_paypal_orders", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "approval_url": "", "capture_id": null, "created_at": "2026-10-18T00:00:00Z", "credited_at": null, "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "mode": "sandbox", "paypal_order_id": null, "purchase_id": null, "refunded_cents": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "creating", "upgrade_id": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrderList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询充值订单列表", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": "任一支付环境中，已发布条款均要求提供 policy_version 并明确接受。收费的服务超额用量还要求 overage_accepted。首次发布条款前，不记录对草稿的同意，各操作仍执行正常的注册、定价与支付检查。", "operationId": "post_api_v1_billing_paypal_orders", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechargeInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "幂等创建或恢复充值", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/capture": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_capture", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "一次性确认商户绑定资金", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/reconcile": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_reconcile", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "一次性确认商户绑定资金", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/refund-requests": { "post": { "description": "仅限 Cookie 会话，不接受管理 API 密钥。客户读取限定于自己的工作空间；写入要求已验证的工作空间 Owner，且不具有平台管理员权限。申请不会移动或预留资金。管理员批准时重新检查当前钱包和未退款的已扣款金额，再使用已有的幂等原路退款与预留流程。批准不会取消套餐。", "operationId": "post__api_v1_billing_paypal_orders__id__refund_requests", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundRequestInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" } }, "security": [ { "session": [] } ], "summary": "申请退还我未使用的充值余额", "x-required-role": "owner" } }, "/api/v1/billing/plans": { "get": { "operationId": "get_api_v1_billing_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "管理员维护的公开价格目录" } }, "/api/v1/billing/purchases": { "get": { "operationId": "get_api_v1_billing_purchases", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active": null, "active_devices": 0, "coverage_ends_at": null, "items": [ { "api_calls": 0, "api_hard_limit": false, "api_overage_cents": 0, "api_unit_micros": 0, "base_cents": 0, "cancelled_at": null, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "current_cycle_index": 0, "current_upgrade_id": "", "cycle_ends_at": "2026-10-18T00:00:00Z", "cycle_starts_at": "2026-10-18T00:00:00Z", "effective_included_devices": 0, "effective_plan": "", "effective_plan_name": "", "ends_at": null, "entitlement_cents": 0, "gift_batch_id": "", "gift_follows_current": false, "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "overage_cents": 0, "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_cents": 0, "renewal": false, "renewal_of": "", "request_id": "55555555-5555-4555-8555-555555555555", "service_credit_basis_cents": 0, "service_credit_basis_seconds": 0, "source": "purchase", "starts_at": null, "status": "pending", "term_months": 1, "total_api_calls": 0, "total_api_overage_cents": 0, "total_device_overage_cents": 0, "unit_micros": 0 } ], "mode": "sandbox", "renewal_package": null, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询套餐购买记录", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": "按所选套餐、币种、价格修订版和期限创建购买。立即尝试钱包结算；余额不足时返回 pending，不开始覆盖期。设置 renewal=true 可续费有效套餐。付款成功后，服务从已有覆盖期结束后开始；GET /billing/purchases 返回 coverage_ends_at。当前额度用量和软件许可证到期时间不变。重试复用 request_id，不会重复扣款。任一支付环境中，已发布条款均要求提供 policy_version 并明确接受。收费的服务超额用量还要求 overage_accepted。首次发布条款前，不记录对草稿的同意，各操作仍执行正常的注册、定价与支付检查。", "operationId": "post_api_v1_billing_purchases", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanPurchase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "购买套餐或预付续费", "x-required-role": "owner" } }, "/api/v1/billing/refund-requests": { "get": { "description": "仅限 Cookie 会话，不接受管理 API 密钥。客户读取限定于自己的工作空间；写入要求已验证的工作空间 Owner，且不具有平台管理员权限。申请不会移动或预留资金。管理员批准时重新检查当前钱包和未退款的已扣款金额，再使用已有的幂等原路退款与预留流程。批准不会取消套餐。", "operationId": "get__api_v1_billing_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" } }, "security": [ { "session": [] } ], "summary": "查询我的工作空间退款申请" } }, "/api/v1/billing/refund-requests/{id}/cancel": { "post": { "description": "仅限 Cookie 会话，不接受管理 API 密钥。客户读取限定于自己的工作空间；写入要求已验证的工作空间 Owner，且不具有平台管理员权限。申请不会移动或预留资金。管理员批准时重新检查当前钱包和未退款的已扣款金额，再使用已有的幂等原路退款与预留流程。批准不会取消套餐。", "operationId": "post__api_v1_billing_refund_requests__id__cancel", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" } }, "security": [ { "session": [] } ], "summary": "撤回我的待审核退款申请", "x-required-role": "owner" } }, "/api/v1/billing/renewal-plans": { "get": { "description": "仅按已完成购买和已应用升级确认所有权。为已有客户返回已启用的公开方案和隐藏的仅续费方案。待付款报价不能证明所有权。可在到期前或到期后使用 POST /billing/purchases 续费。", "operationId": "get__api_v1_billing_renewal_plans", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "api_hard_limit": false, "api_unit_micros": 0, "base_micros": 0, "currency": "USD", "description": "Desktop reporting software", "enabled": true, "hard_limit": false, "included_api_calls": null, "included_devices": 0, "name": "Report app", "plan": "starter", "price_version": "example-v1", "public": false, "renewal_only": false, "sort_order": 0, "terms": [], "unit_micros": 0, "updated_at": "2026-10-18T00:00:00Z" } ], "mode": "sandbox" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RenewalPlans", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询续费方案", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/subscription": { "get": { "operationId": "get_api_v1_billing_subscription", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "current": { "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "hard_limit": false, "included_devices": 0, "month": "2026-09", "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "unit_micros": 0 }, "next": null, "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Subscription", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "默认额度已禁用（DEFAULT_PLAN_DISABLED）" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取月度订阅", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_billing_subscription", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "currency": "USD", "plan": "starter", "price_version": "example-v1" }, "schema": { "$ref": "#/components/schemas/PlanChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "currency": "USD", "effective_month": "2026-11", "plan": "starter", "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScheduledPlan", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "安排月度套餐", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/upgrades": { "get": { "description": "", "operationId": "get__api_v1_billing_upgrades", "parameters": [ { "in": "query", "name": "limit", "schema": { "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "api_hard_limit": false, "api_unit_micros": 0, "applied_at": null, "base_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "cycle_seconds": 0, "ends_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "parent_id": "33333333-3333-4333-8333-333333333333", "parts": [], "plan": "starter", "plan_name": "Starter", "previous_base_cents": 0, "previous_plan_name": "", "previous_upgrade_id": "", "price_version": "example-v1", "purchase_id": "33333333-3333-4333-8333-333333333333", "remaining_seconds": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "pending", "unit_micros": 0 } ], "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UpgradeList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询套餐升级记录", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/upgrades/quote": { "post": { "description": "要求 Owner 会话。目标套餐必须使用相同币种，月费、设备额度和 API 额度均不能降低。保留原到期时间和已使用量。升级总是覆盖当前及所有未来预付和赠送的服务期。每期按其原权益价值抵扣，并按剩余秒数折算；尚未开始的服务期使用完整时长。赠送价值不能作为现金退款。付款通过一次原子钱包扣款完成，日期和已消耗额度保留。报价与付款之间发生续费、赠送或取消时，返回 UPGRADE_STATE_CONFLICT，使报价失效；关联的 PayPal 充值即使迟到，仍留作钱包余额。覆盖期发生变化时必须重新报价。", "operationId": "post__api_v1_billing_upgrades_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "预览按剩余时长折算的套餐升级，不扣减钱包" } }, "/api/v1/billing/upgrades/{id}/pay": { "post": { "description": "余额不足时返回 pending，不改变套餐。一次扣款后返回 applied。当前有效套餐已变或报价到期时返回 409。升级总是覆盖当前及所有未来预付和赠送的服务期。每期按其原权益价值抵扣，并按剩余秒数折算；尚未开始的服务期使用完整时长。赠送价值不能作为现金退款。付款通过一次原子钱包扣款完成，日期和已消耗额度保留。报价与付款之间发生续费、赠送或取消时，返回 UPGRADE_STATE_CONFLICT，使报价失效；关联的 PayPal 充值即使迟到，仍留作钱包余额。覆盖期发生变化时必须重新报价。发起新付款前必须明确接受当前条款；已付款操作的重放保留原始回执。", "operationId": "post__api_v1_billing_upgrades__id__pay", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "一次性确认并支付有效的升级报价" } }, "/api/v1/billing/waffo/orders": { "get": { "operationId": "get__api_v1_billing_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询 Waffo 服务付款和钱包充值", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_waffo_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "创建或恢复一笔 Waffo 服务付款", "x-licentivo-access": "owner" } }, "/api/v1/billing/waffo/orders/{id}": { "get": { "operationId": "get__api_v1_billing_waffo_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取自己工作空间的 Waffo 结账信息", "x-licentivo-access": "session" } }, "/api/v1/billing/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "验证付款并核对服务和退款", "x-licentivo-access": "owner" } }, "/api/v1/billing/wallet": { "get": { "operationId": "get_api_v1_billing_wallet", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "currencies": [], "items": [ { "balance_cents": 0, "currency": "USD", "mode": "sandbox" } ], "maximum_cents": 0, "minimum_cents": 0, "mode": "sandbox", "payment_channels": [], "paypal_enabled": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取钱包余额", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/wallet/entries": { "get": { "operationId": "get_api_v1_billing_wallet_entries", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "balance_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "kind": "", "mode": "sandbox", "reference": "" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletEntryList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询钱包流水", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/consume": { "post": { "description": "通过许可证认证的运行时操作，不使用厂商 Cookie 或 API Key。功能计次要求稳定的 Idempotency-Key；consume 不扣减平台 API 额度。", "operationId": "post_api_v1_consume", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ConsumptionResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "/consume" } }, "/api/v1/consume/cancel": { "post": { "description": "业务操作前预留，成功后才确认扣次，失败时取消。重试保持同一任务标识和请求体。确认请求超时意味着结果不确定：应重试确认，绝不取消或重复已完成的业务。已结束预留返回当前状态，不扣减平台 API 额度。完成时发出 license.consume；临时预留不产生消耗事件。", "operationId": "post_api_v1_consume_cancel", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "功能次数：取消" } }, "/api/v1/consume/commit": { "post": { "description": "业务操作前预留，成功后才确认扣次，失败时取消。重试保持同一任务标识和请求体。确认请求超时意味着结果不确定：应重试确认，绝不取消或重复已完成的业务。已结束预留返回当前状态，不扣减平台 API 额度。完成时发出 license.consume；临时预留不产生消耗事件。", "operationId": "post_api_v1_consume_commit", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "功能次数：确认" } }, "/api/v1/consume/reserve": { "post": { "description": "业务操作前预留，成功后才确认扣次，失败时取消。重试保持同一任务标识和请求体。确认请求超时意味着结果不确定：应重试确认，绝不取消或重复已完成的业务。已结束预留返回当前状态，不扣减平台 API 额度。完成时发出 license.consume；临时预留不产生消耗事件。", "operationId": "post_api_v1_consume_reserve", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "功能次数：预留" } }, "/api/v1/customer/activations/{id}/release": { "post": { "operationId": "post_api_v1_customer_activations_by_id_release", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerReleaseResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/activations/{id}/release" } }, "/api/v1/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_customer_cases", "parameters": [ { "description": "在统计和分页之前排除一种申请类型。使用 refund 可将退款申请排除在支持列表之外；访问仍限定于当前会话范围。", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "将退款申请限制为钱包充值或服务取消。", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询客户申请列表", "x-required-role": "session" }, "post": { "description": "稳定的 request_id 限定于工作空间；内容改变后不能复用。", "operationId": "post__api_v1_customer_cases", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "创建支持、隐私或申诉申请", "x-required-role": "session" } }, "/api/v1/customer/cases/unread": { "get": { "description": "排除退款聊天。客户只看到获授权的工作空间工单，成员只看到自己的工单。每位管理员拥有独立的已读水位。", "operationId": "get__api_v1_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取个人工单及通知未读数", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取申请及回复", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/messages": { "post": { "description": "退款申请拒绝回复，返回 REFUND_REVIEW_WORKFLOW；管理员直接批准或拒绝。普通支持工单保留回复功能。已审核的关闭申请保留其隐私工作流状态。", "operationId": "post__api_v1_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "回复支持工单", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/read": { "post": { "description": "只将最后一条已显示消息及之前的内容标为已读。后续到达的消息保持未读，迟到确认不能倒退已读水位。", "operationId": "post__api_v1_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "确认已显示的工单消息", "x-required-role": "session" } }, "/api/v1/customer/compensations": { "get": { "description": "", "operationId": "get__api_v1_customer_compensations", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "incident_id": "33333333-3333-4333-8333-333333333333", "intervals": "", "mode": "timed", "purchase_id": "33333333-3333-4333-8333-333333333333", "seconds": 0 } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceCompensationList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询服务补偿列表", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/licenses": { "get": { "operationId": "get_api_v1_customer_licenses", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerLicenses" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "customerSession": [] } ], "summary": "关联买家的许可证" } }, "/api/v1/customer/login": { "post": { "operationId": "post_api_v1_customer_login", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "/customer/login" } }, "/api/v1/customer/logout": { "post": { "operationId": "post_api_v1_customer_logout", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/logout" } }, "/api/v1/customer/notices": { "get": { "description": "", "operationId": "get__api_v1_customer_notices", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "body": "", "created_at": "2026-10-18T00:00:00Z", "effective_at": null, "emailed_at": null, "id": "33333333-3333-4333-8333-333333333333", "kind": "", "read_at": null, "reference": "", "title": "" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceNoticeList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询服务通知列表", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/notices/{id}/read": { "post": { "description": "", "operationId": "post__api_v1_customer_notices__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "将自己的通知标为已读", "x-required-role": "session" } }, "/api/v1/customer/offline/respond": { "post": { "operationId": "post_api_v1_customer_offline_respond", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/offline/respond" } }, "/api/v1/customer/refunds": { "post": { "description": "明确范围时，要求确认并提交返回的 quote_hash 和 quoted_at。管理员批准前服务保持有效。状态改变或报价过期时必须重新预览；相冲突的待处理申请会被拒绝。未指定范围的申请可在明确确认后立即执行符合条件的取消。order_id 也可选择状态为 paid_unapplied 的 Waffo/Paddle 付款，并使用 reason=failed_delivery；不会冻结从未入账的钱包余额。", "operationId": "post__api_v1_customer_refunds", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "提交退款申请以供直接审核", "x-required-role": "owner" } }, "/api/v1/customer/refunds/quote": { "post": { "description": "明确指定购买或服务范围后，返回有界快照哈希、受影响购买、分币种退款估算和剩余日期。提交申请不终止服务。赠送没有现金价值；付费升级仍可经审核退款。", "operationId": "post__api_v1_customer_refunds_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerRefundQuote" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "预览取消范围、退款及剩余服务", "x-required-role": "owner" } }, "/api/v1/customer/refunds/{id}/cancel": { "post": { "operationId": "post__api_v1_customer_refunds__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelCustomerRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" } }, "security": [ { "session": [] } ], "summary": "撤回我尚未审核的剩余退款申请", "x-required-role": "owner" } }, "/api/v1/customer/verify": { "post": { "operationId": "post_api_v1_customer_verify", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerSession" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "/customer/verify" } }, "/api/v1/deactivate": { "post": { "description": "使用 product_id + license_key + device_id 认证，不使用 Cookie、CSRF 或厂商管理密钥。除 activate 外均要求 activation_id。每次成功请求消耗一次 API 调用；幂等重放和失败不消耗。超额时原子扣减钱包，或返回 API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT。工作空间设备额度按当前激活数计算。释放可归还额度；浮动租约到期也归还额度，而普通设备离线后仍计入注册数。仅当额度月份内的计费峰值超出已付费容量时，才收取设备超额费用；释放不会退还已产生费用。API 用量独立计算。", "operationId": "post_api_v1_deactivate", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "运行时解绑" } }, "/api/v1/demo/trial": { "post": { "operationId": "post_api_v1_demo_trial", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Trial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "每位所有者创建一个隔离的七天 SDK 试用", "x-required-role": "owner" } }, "/api/v1/examples/sdk": { "get": { "operationId": "get_api_v1_examples_sdk", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "公开 SDK 示例可用状态" } }, "/api/v1/examples/sdk/download/{name}": { "get": { "operationId": "get_api_v1_examples_sdk_download_{name}", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "description": "语言加 .zip，例如 csharp.zip", "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "下载已在代码中填写公开产品设置的源码" } }, "/api/v1/examples/sdk/trial": { "post": { "description": "要求浏览器 CSRF 和 HttpOnly 访客 Cookie。每位访客获得独立许可证，三天从首次激活开始。重复领取不会延长到期时间。开放 export，不开放 pro。", "operationId": "post_api_v1_examples_sdk_trial", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleTrial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "领取或恢复此访客独立的三天试用" } }, "/api/v1/forum/images": { "post": { "operationId": "post__api_v1_forum_images", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "image": { "description": "PNG、JPEG 或 GIF；最大 5 MB、4096 × 4096、1600 万像素。GIF 存为静态 PNG。附加到已发布帖子之前保持私有。", "format": "binary", "type": "string" } }, "required": [ "image" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumImage" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "上传私有草稿图片", "tags": [ "Community" ] } }, "/api/v1/forum/replies/{id}": { "delete": { "operationId": "delete__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "删除回复，限作者或平台管理员", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "编辑自己的回复", "tags": [ "Community" ] } }, "/api/v1/forum/topics": { "get": { "operationId": "get__api_v1_forum_topics", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "language", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [], "summary": "查询公开讨论，置顶优先", "tags": [ "Community" ] }, "post": { "operationId": "post__api_v1_forum_topics", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "创建讨论，任意已验证的租户成员可用", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}": { "delete": { "operationId": "delete__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "删除讨论，限作者或平台管理员", "tags": [ "Community" ] }, "get": { "operationId": "get__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [], "summary": "读取公开讨论及回复", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "编辑自己的讨论", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/moderation": { "post": { "operationId": "post__api_v1_forum_topics__id__moderation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumModerationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "置顶、取消置顶、隐藏或锁定讨论，限平台管理员", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/replies": { "post": { "operationId": "post__api_v1_forum_topics__id__replies", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "错误码与请求 ID；不暴露账号详情" } }, "security": [ { "session": [] } ], "summary": "回复讨论", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/translate": { "post": { "description": "匿名访客可携带 CSRF 令牌使用此接口。只接受已发布并保存的论坛文本，绝不接受任意提交的文本。按内容和目标语言缓存译文。隐藏主题或回复返回 404；并发翻译可能返回 TRANSLATION_PENDING。原文保留。", "operationId": "post__api_v1_forum_topics__id__translate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTranslationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTranslationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [], "summary": "翻译已发布的主题或回复" } }, "/api/v1/forum/translation": { "get": { "description": "", "operationId": "get__api_v1_forum_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationOptions" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [], "summary": "获取公开可用的翻译目标语言" } }, "/api/v1/heartbeat": { "post": { "description": "使用 product_id + license_key + device_id 认证，不使用 Cookie、CSRF 或厂商管理密钥。除 activate 外均要求 activation_id。每次成功请求消耗一次 API 调用；幂等重放和失败不消耗。超额时原子扣减钱包，或返回 API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT。验证和心跳重试回执在 3600 秒后到期。原授权仍有效时，此窗口内相匹配的请求会重放原结果，不再次扣费。窗口结束后应使用新密钥；已使用过的旧密钥可能按新请求处理。激活、解绑和功能计次回执持续保存。工作空间设备额度按当前激活数计算。释放可归还额度；浮动租约到期也归还额度，而普通设备离线后仍计入注册数。仅当额度月份内的计费峰值超出已付费容量时，才收取设备超额费用；释放不会退还已产生费用。API 用量独立计算。", "operationId": "post_api_v1_heartbeat", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "运行时心跳" } }, "/api/v1/launch/connections": { "get": { "description": "查询 Launch 信任连接。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_get__api_v1_launch_connections", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "本次操作结果。", "properties": { "items": { "description": "请求范围内相匹配的记录。", "items": { "$ref": "#/components/schemas/LaunchConnection" }, "type": "array" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "查询 Launch 信任连接", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" }, "post": { "description": "注册 Launch 签发者和商业环境。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_post__api_v1_launch_connections", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "注册 Launch 签发者和商业环境", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}": { "put": { "description": "签发者、受众和环境不可变。必须提供完整的受信公钥集合。", "operationId": "launch_put__api_v1_launch_connections_id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "轮换 Launch 密钥或更新运行时限制", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/devices/{activation}/release": { "post": { "description": "Licentivo 预留 30 天自助解绑额度、记录操作，并负责重试和人工审核。工作进程在同一事务锁下比较绑定版本并撤销会话和凭据。旧 Launch 登录会话不能在被撤销的设备上再次交换身份断言。", "operationId": "launch_post__api_v1_launch_connections_id_devices_activation_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "activation", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchDeviceReleaseInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "请求带版本的远程账号设备解绑", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/entitlements/{entitlement}/devices": { "get": { "description": "读取账号设备、权威解绑额度和操作。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_get__api_v1_launch_connections_id_entitlements_entitlement_devices", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "entitlement", "required": true, "schema": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "account_ref", "required": true, "schema": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "environment", "required": true, "schema": { "description": "商业环境，同时固定在连接和签名授权中。", "enum": [ "live", "sandbox" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "本次操作结果。", "properties": { "can_release": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" }, "items": { "description": "请求范围内相匹配的记录。", "items": { "additionalProperties": false, "properties": { "device_name": { "description": "供人阅读的设备名称。", "type": "string" }, "generation": { "description": "当前设备绑定代次。", "type": "integer" }, "id": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "记录创建时间，使用 UTC。", "format": "date-time", "type": "string" }, "status": { "description": "由服务端管理的当前生命周期或处理状态。", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "operations": { "description": "由服务端管理的设备解绑操作历史。", "items": { "$ref": "#/components/schemas/DeviceReleaseOperation" }, "type": "array" }, "remaining": { "description": "由 Licentivo 计算的最近 30 天内剩余自助解绑次数。", "type": "integer" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "读取账号设备、权威解绑额度和操作", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events": { "post": { "description": "确认接收前先持久化。同一 ID 对应不同请求体时冲突。工作进程在事务中应用绝对有效期和单调递增的聚合版本，忽略旧版本；失败最多重试 12 次，再转人工审核。对于已有权益，退款、暂停和到期不受套餐映射、策略版本、有效期模式或设备占用影响，均会撤销访问，同时保留所有权和版本检查。套餐降级会一起应用新功能、计次规则和有效设备上限，保留最早的绑定，并撤销超额设备会话和凭据，不消耗自助解绑额度。续费、套餐变更和策略保存保留独立的人工功能与设备上限。明确的 entitlement.downgraded 快照保留有效商业状态，但若应用失败，会持久阻止旧权益。能够证明发生限制收缩的已有 active 快照也获得同样保护。只有已应用且版本达到或超过待处理限制版本的快照，才清除此阻挡。幂等运行时重试保留操作去重，同时刷新变化后的授权和购买截止时间。应轮询事件，再宣布授权就绪。", "operationId": "launch_post__api_v1_launch_connections_id_events", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "launch_product_id": "11111111-1111-4111-8111-111111111111", "plan_ref": "plan_ref_example", "type": "entitlement.created", "valid_from": "2026-10-24T00:00:00Z", "version": 1 }, "schema": { "$ref": "#/components/schemas/LaunchCommerceEvent" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "接收完整的 Launch 商业快照", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/events/{event}": { "get": { "description": "读取 Launch 商业事件结果。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_get__api_v1_launch_connections_id_events_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "读取 Launch 商业事件结果", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events/{event}/retry": { "post": { "description": "重试未应用的 Launch 事件。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_post__api_v1_launch_connections_id_events_event_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "本次操作结果。", "properties": { "queued": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "重试未应用的 Launch 事件", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/plans/{plan}": { "put": { "description": "将 Launch 套餐版本映射到授权策略。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_put__api_v1_launch_connections_id_plans_plan_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "plan", "required": true, "schema": { "description": "区分大小写且不可变的购买权益引用。", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "launch_product_id": "11111111-1111-4111-8111-111111111111", "policy_id": "11111111-1111-4111-8111-111111111111", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchPlanMappingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "本次操作结果。", "properties": { "saved": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "将 Launch 套餐版本映射到授权策略", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations": { "post": { "description": "同步原子撤销：HTTP 200 表示会话、凭据、匹配的设备绑定及持久回执均已提交。连接决定环境；可选的非空 environment 必须与其一致。省略和明确填写相匹配的值，在幂等判断上等价。重试及并发重试须复用 event_id 和相同的归一化请求体；不同请求体产生冲突。成功重放返回原始计数，不撤销较新的登录。未知账号或 sid 仍成功，影响行数为零，并保留拒绝登录标记。账号范围撤销记录服务端接收时的认证截止时间。保留购买权益有效期和许可证期限。已禁用连接仍接受撤销。", "operationId": "launch_post__api_v1_launch_connections_id_session_revocations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_456", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "scope": "session", "sid": "login_123" }, "schema": { "$ref": "#/components/schemas/LaunchSessionRevocationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "404": { "description": "此租户中不存在该连接" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "415": { "description": "使用 Content-Type: application/json" }, "500": { "description": "数据库失败或结果未知；查询或重试原事件，不改变其 ID 或请求体" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "撤销一次 Launch 登录或账号全部授权会话", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations/{event}": { "get": { "description": "返回此租户和连接的原持久回执。HTTP 404 表示当前看不到已提交结果；应使用相同 event_id 和请求体重试原 POST。不需要异步工作进程。", "operationId": "launch_get__api_v1_launch_connections_id_session_revocations_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "404": { "description": "此租户和连接中不存在已提交结果" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "500": { "description": "数据库失败或结果未知；查询或重试原事件，不改变其 ID 或请求体" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "查询已提交的 Launch 会话撤销结果", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}": { "get": { "description": "读取远程解绑进度。决策、重试和范围检查由 Licentivo 执行。", "operationId": "launch_get__api_v1_launch_device_operations_operation_", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "读取远程解绑进度", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}/retry": { "post": { "description": "manual_review 操作要求所有者提供 approve=true。批准绝不会绕过原绑定版本。", "operationId": "launch_post__api_v1_launch_device_operations_operation_retry", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": { "approve": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "本次操作结果。", "properties": { "queued": { "description": "此信任连接是否可以授权新的运行时使用。", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "重试或明确批准经审核的解绑", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/exchange": { "post": { "description": "必须提供 Idempotency-Key。JWT 头要求 alg=Ed25519、typ=licentivo-launch-identity+jwt 和固定受信的 kid；必须精确提供 iss/aud/environment，以及 sub、sid、jti、iat、nbf、exp、auth_time、session_exp、launch_product_id、product_id 和 entitlement_ref。断言寿命最多 120 秒。重放只能用相同请求和幂等密钥恢复同一有效设备会话。购买信息只从 Licentivo 读取。", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "本次 Launch 授权操作的 Idempotency-Key。", "maxLength": 80, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "environment": "live", "identity_token": "identity_token_example", "launch_connection_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchExchangeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [], "summary": "交换 Launch 账号身份以获取设备授权", "tags": [ "Launch account licensing" ] } }, "/api/v1/legal/policy": { "get": { "description": "返回全部 13 种受支持语言的固定服务、退款和隐私文档。未确认的可选经营主体信息不会包含在内。已发布版本要求明确接受；首次发布前维持已有流程。", "operationId": "get__api_v1_legal_policy", "parameters": [ { "in": "query", "name": "version", "schema": { "type": "string" } }, { "in": "query", "name": "locale", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "读取不可变的法律条款版本" } }, "/api/v1/licenses": { "get": { "operationId": "get_api_v1_licenses", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "搜索文本；实际搜索字段和长度上限见当前接口说明。", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询许可证列表", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "post": { "description": "要求 Owner 会话，或由有效 Owner 持有的写入密钥。不自动执行 Idempotency-Key 重试。", "operationId": "post_api_v1_licenses", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LicenseCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseSecret", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "签发许可证", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "timed", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "perpetual", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": null, "policy_id": "22222222-2222-4222-8222-222222222223", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": null, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/batch": { "post": { "description": "应用策略绝不改变许可证模式或总有效期。创建定期或试用许可证时，必须从单项条目或公共批量字段明确提供有效时长。Launch 管理的许可证拒绝独立的单个或批量续费，返回 HTTP 409 LAUNCH_VALIDITY_MANAGED；应在 Launch 中续费购买并同步绝对有效期。混合续费批次将整体回滚。", "operationId": "post_api_v1_licenses_batch", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/BatchInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "批量处理许可证", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "create", "request": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "renew", "request": { "days": 30, "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "renew" } ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "revoke", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "revoke" } ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "apply_policy", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "apply_policy", "policy_id": "22222222-2222-4222-8222-222222222222", "preview_token": "REPLACE_WITH_THE_UNEXPIRED_PREVIEW_TOKEN", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "apply_policy" } ], "operation": "apply_policy", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/export.csv": { "get": { "operationId": "get_api_v1_licenses_export_csv", "parameters": [ { "in": "query", "name": "product_id", "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "搜索文本；实际搜索字段和长度上限见当前接口说明。", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "当前资源状态；具体可选值见本字段的枚举和接口说明。", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "id,product_id,key_prefix,customer,mode,status,max_devices,expires_at\n", "schema": { "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "413": { "content": { "application/json": { "example": { "error": { "code": "EXPORT_TOO_LARGE", "message": "Filter the export to at most 5000 records" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "筛选结果最多 5000 条" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "导出许可证", "x-csv-columns": [ "id", "product_id", "key_prefix", "customer", "mode", "status", "max_devices", "expires_at" ], "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/policy-preview": { "post": { "description": "应用策略绝不改变许可证模式或总有效期。创建定期或试用许可证时，必须从单项条目或公共批量字段明确提供有效时长。", "operationId": "post_api_v1_licenses_policy-preview", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "policy_id": "22222222-2222-4222-8222-222222222222" }, "schema": { "$ref": "#/components/schemas/PreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "changes": [], "expires_in": 600, "note": "", "policy_version": 1, "preview_token": "" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyPreview", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "预览策略应用结果", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}": { "delete": { "operationId": "delete_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "归档许可证", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/License", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取许可证", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "status": "suspended" }, "schema": { "$ref": "#/components/schemas/LicenseUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "更新许可证", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/capabilities": { "get": { "operationId": "get_api_v1_licenses_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilityResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取许可证扩展能力", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/{id}/customer": { "patch": { "operationId": "patch_api_v1_licenses_by_id_customer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "buyer@example.com", "name": "Sample customer" }, "schema": { "$ref": "#/components/schemas/CustomerAssignment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "分配客户", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/maintenance/renew": { "post": { "operationId": "post_api_v1_licenses_by_id_maintenance_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "续延维护期", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/renew": { "post": { "description": "首次激活前，续费增加 duration_days；激活后，从当前时间与 expires_at 中较晚的时间开始延长，已过期许可证不会损失购买的延长时长。Launch 管理的许可证拒绝独立的单个或批量续费，返回 HTTP 409 LAUNCH_VALIDITY_MANAGED；应在 Launch 中续费购买并同步绝对有效期。混合续费批次将整体回滚。", "operationId": "post_api_v1_licenses_by_id_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Renewed", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "续期许可证", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "before_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "after_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 30, "expires_at": "2026-12-17T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/reveal-key": { "post": { "description": "Requires an active Owner browser session and CSRF token. Management API keys and read-only members are forbidden. Keys are encrypted at rest and each view is audited without recording the secret. Ordinary lists, details and CSV exports contain only the prefix. Older encrypted batch/onboarding receipts are recovered during migration. Older hash-only issuances return LICENSE_KEY_UNAVAILABLE (409); Launch account licenses return LICENSE_KEY_NOT_APPLICABLE (409). Viewing does not rotate the key or change validity, devices or usage.", "operationId": "post_api_v1_licenses_by_id_reveal-key", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseKeyReveal" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "View the original license key", "x-required-role": "owner" } }, "/api/v1/licenses/{id}/revoke": { "post": { "operationId": "post_api_v1_licenses_by_id_revoke", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "吊销许可证", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/members": { "get": { "operationId": "get_api_v1_members", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MemberList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "GET /members", "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_members", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invited" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "POST /members", "x-required-role": "owner" } }, "/api/v1/members/{id}": { "patch": { "operationId": "patch_api_v1_members_by_id", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "PATCH /members/{id}", "x-required-role": "owner" } }, "/api/v1/offline/respond": { "post": { "operationId": "post_api_v1_offline_respond", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "签发离线响应", "x-management-reference": { "group": "integration" }, "x-request-variants": [ { "name": "activate", "request": { "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "activate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "activate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "device_key": "lv_dev_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "heartbeat_seconds": 600, "lease": { "key_id": "66666666-6666-4666-8666-666666666666", "payload": "BASE64URL_ENCODED_SIGNED_CLAIMS", "signature": "BASE64URL_ED25519_SIGNATURE", "version": 1 } }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "deactivate", "request": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/onboarding": { "post": { "operationId": "post_api_v1_onboarding", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 7, "mode": "trial", "name": "Report app", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/OnboardingInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OnboardingResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "创建接入资源", "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/payments/paddle/webhook": { "post": { "operationId": "post__api_v1_payments_paddle_webhook", "parameters": [ { "in": "header", "name": "Paddle-Signature", "required": true, "schema": { "description": "供人识别的名称；名称长度限制见填写规则。", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "验证 Paddle 签名，核对已完成付款或调整", "x-licentivo-access": "public" } }, "/api/v1/payments/paypal/webhook": { "post": { "operationId": "post_api_v1_payments_paypal_webhook", "parameters": [ { "in": "header", "name": "Paypal-Auth-Algo", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Cert-Url", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Sig", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Time", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "经验证的扣款、退款或撤销通知" } }, "/api/v1/payments/waffo/webhook": { "post": { "operationId": "post__api_v1_payments_waffo_webhook", "parameters": [ { "in": "header", "name": "X-Waffo-Signature", "required": true, "schema": { "description": "以 MER_ 开头的商户标识。", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "验证 Waffo 签名并核对付款或退款", "x-licentivo-access": "public" } }, "/api/v1/policies": { "get": { "operationId": "get_api_v1_policies", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询策略列表", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "post": { "description": "要求 Owner 会话，或由有效 Owner 持有的写入密钥。不自动执行 Idempotency-Key 重试。", "operationId": "post_api_v1_policies", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "features": [ "export" ], "heartbeat_seconds": 600, "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/PolicyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "新授权策略", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}": { "delete": { "operationId": "delete_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "归档策略", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Policy", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取策略", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "原子更新策略及所有关联且未吊销的许可证快照。保留已有许可证期限、已确认用量和独立维护期延长。返回 synced_licenses。出现 ACTIVE_DEVICES_CONFLICT 时，整次保存回滚。", "operationId": "patch_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "max_devices": 2 }, "schema": { "$ref": "#/components/schemas/PolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "更新基础策略", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}/capabilities": { "get": { "operationId": "get_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_vm": true, "device_match": "system", "license_model": "node_locked", "maintenance_days": 0, "max_version": "", "meter_rules": [], "min_version": "", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "require_hardware": false, "self_release_limit": 3, "session_seconds": 7200, "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyCapabilities", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取策略扩展能力", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "使用当前 policy_version。原子更新策略及所有关联且未吊销的许可证快照，同时保留已签发期限、已确认用量和独立维护期延长。返回 synced_licenses。出现 POLICY_CHANGED 或 ACTIVE_DEVICES_CONFLICT 时，整次保存回滚。", "operationId": "patch_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "license_model": "node_locked", "meter_rules": [ { "allow_overage": false, "feature": "export", "limit": 500, "max_overage": 0, "period": "month" } ], "policy_version": 1 }, "schema": { "$ref": "#/components/schemas/PolicyCapabilitiesInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "更新策略扩展能力", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products": { "get": { "operationId": "get_api_v1_products", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "description": "搜索文本；实际搜索字段和长度上限见当前接口说明。", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProductList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询产品列表", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "post": { "description": "要求 Owner 会话，或由有效 Owner 持有的写入密钥。不自动执行 Idempotency-Key 重试。", "operationId": "post_api_v1_products", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "description": "Desktop reporting software", "name": "Report app" }, "schema": { "$ref": "#/components/schemas/ProductCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "新建产品", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}": { "delete": { "operationId": "delete_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "归档产品", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Product", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "读取产品", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Report app Pro", "status": "active" }, "schema": { "$ref": "#/components/schemas/ProductUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "更新产品", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/public-keys": { "get": { "operationId": "get_api_v1_products_by_id_public-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyBundle" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "产品固定受信公钥包" } }, "/api/v1/products/{id}/releases": { "get": { "operationId": "get_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReleaseList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询版本列表", "x-management-reference": { "group": "releases" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "channel": "stable", "notes": "Initial release", "version": "1.0.0" }, "schema": { "$ref": "#/components/schemas/ReleaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Release", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "发布版本", "x-management-reference": { "group": "releases" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-bundle": { "post": { "operationId": "post_api_v1_products_by_id_sdk-bundle", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "language": "go" }, "schema": { "$ref": "#/components/schemas/BundleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "下载产品示例源码", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-initializer": { "get": { "operationId": "get_api_v1_products_by_id_sdk-initializer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "language", "schema": { "default": "go", "description": "下载包的 SDK 语言标识。", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKInitializer", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "复制产品初始化代码", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys": { "get": { "operationId": "get_api_v1_products_by_id_signing-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "keys": [], "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ManagementKeyBundle", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询签名密钥列表", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys/rotate": { "post": { "operationId": "post_api_v1_products_by_id_signing-keys_rotate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "active": true, "algorithm": "Ed25519", "created_at": "2026-10-18T00:00:00Z", "key_id": "66666666-6666-4666-8666-666666666666", "public_key": "", "retired_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SigningKey", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "轮换签名密钥", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/releases/eligible": { "post": { "description": "通过许可证认证的运行时操作，不使用厂商 Cookie 或 API Key。功能计次要求稳定的 Idempotency-Key；consume 不扣减平台 API 额度。", "operationId": "post_api_v1_releases_eligible", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EligibleReleases" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "/releases/eligible" } }, "/api/v1/service/status": { "get": { "description": "只有全局通知公开；不会暴露定向工作空间 ID。", "operationId": "get__api_v1_service_status", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "读取公开维护与故障信息" } }, "/api/v1/sessions/logout": { "post": { "description": "不使用浏览器 Cookie 或 CSRF 令牌。重复操作重放原结果，不释放较新的绑定。stale 状态表示过时撤销已成功完成。SDK 在提交此请求前拒绝本地使用，并清除运行时凭据。", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111", "release_token": "lv_out_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "schema": { "$ref": "#/components/schemas/LogoutTicket" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "本次操作结果。" }, "request_id": { "description": "HTTP 请求关联标识。", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "已接收的结果" }, "400": { "description": "输入无效" }, "401": { "description": "认证或身份断言被拒绝" }, "403": { "description": "权益、凭据、环境或登录已撤销" }, "409": { "description": "幂等、策略、审核或绑定版本冲突" }, "503": { "description": "临时失败；重试原操作" } }, "security": [], "summary": "使用仅限解绑的票据撤销一个带版本的设备绑定", "tags": [ "Launch account licensing" ] } }, "/api/v1/summary": { "get": { "operationId": "get_api_v1_summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_licenses": 0, "licenses": 0, "policies": 0, "products": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Summary", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "工作空间统计", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/support/contact": { "get": { "description": "只返回已配置的联系邮箱；为空时隐藏。不发送邮件。", "operationId": "get__api_v1_support_contact", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportContact" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [], "summary": "读取公开支持邮箱" } }, "/api/v1/system/billing-notifications": { "get": { "description": "复用认证邮件传输、发件人、加密持久化队列和重试。平台权限与收件人同意必须同时允许对应类型。投递时重新核对当前同意状态与事件状态。邮件选项不会授予或撤销钱包扣款同意。sandbox 邮件会标明环境。未付款的待处理购买或赠送不会创建通知。", "operationId": "get__api_v1_system_billing_notifications", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取平台计费邮件规则", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "部分更新，明确为 false 的值也会保存。复用认证邮件传输、发件人、加密持久化队列和重试。平台权限与收件人同意必须同时允许对应类型。投递时重新核对当前同意状态与事件状态。邮件选项不会授予或撤销钱包扣款同意。sandbox 邮件会标明环境。未付款的待处理购买或赠送不会创建通知。", "operationId": "patch__api_v1_system_billing_notifications", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "配置计费邮件规则和公开支持联系方式", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/preview": { "get": { "description": "使用已保存的平台设置和 sandbox 示例数据。不创建购买或邮件任务。", "operationId": "get__api_v1_system_billing_notifications_preview", "parameters": [ { "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" } }, { "in": "query", "name": "locale", "schema": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingEmailPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "预览计费邮件但不发送", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/test": { "post": { "description": "明确测试使用 sandbox 示例数据，添加 [TEST]，并遵循已有邮件配置。即使对应客户通知类型已关闭，也可以测试模板。不执行付款或续费。", "operationId": "post__api_v1_system_billing_notifications_test", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailTestInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "将明确请求的计费测试邮件入队", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/check-mail": { "post": { "description": "仅检查已保存的服务。API 提供方检查只执行只读请求，绝不发送邮件。仅具发送权限的密钥可能返回 check_status=limited 和 ok=false；这不能证明凭据有效或投递成功。测试发送必须明确请求测试邮件。", "operationId": "post_api_v1_system_check-mail", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailConnection" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "MAIL_PROVIDER_AUTH_FAILED、MAIL_PROVIDER_RATE_LIMITED 或 MAIL_PROVIDER_UNAVAILABLE。测试邮件异步投递；投递错误出现在任务结果中，而非最初的 HTTP 202 响应中。" } }, "security": [ { "session": [] } ], "summary": "POST /system/check-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases", "parameters": [ { "description": "在统计和分页之前排除一种申请类型。使用 refund 可将退款申请排除在支持列表之外；访问仍限定于当前会话范围。", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "将退款申请限制为钱包充值或服务取消。", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询客户申请列表", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/unread": { "get": { "description": "排除退款聊天。客户只看到获授权的工作空间工单，成员只看到自己的工单。每位管理员拥有独立的已读水位。", "operationId": "get__api_v1_system_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取个人工单及通知未读数", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取申请及回复", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/deletion-review": { "post": { "description": "要求确认财务责任。立即撤销普通访问；客户导出在恰好 30 天时结束，全部业务记录仍保留，供获授权管理员导出。", "operationId": "post__api_v1_system_customer_cases__id__deletion_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "确认或拒绝逻辑关闭账号", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/manual-refund": { "post": { "description": "要求客户同意及已完成付款的证据。这里只记录结算，不会发送银行转账。重复确认不能重复扣款。原 Waffo/Paddle 付款（包括服务付款）拒绝这种仅声明的路径，返回 ORIGINAL_REFUND_REQUIRED。", "operationId": "post__api_v1_system_customer_cases__id__manual_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "记录实际完成的替代退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/messages": { "post": { "description": "退款申请拒绝回复，返回 REFUND_REVIEW_WORKFLOW；管理员直接批准或拒绝。普通支持工单保留回复功能。已审核的关闭申请保留其隐私工作流状态。", "operationId": "post__api_v1_system_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "回复支持工单", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/read": { "post": { "description": "只将最后一条已显示消息及之前的内容标为已读。后续到达的消息保持未读，迟到确认不能倒退已读水位。", "operationId": "post__api_v1_system_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "确认已显示的工单消息", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/recover-original-refund": { "post": { "description": "要求管理员明确确认实际并未进行替代转账。保留原始证据，并使用补偿流水。只向原付款申请剩余金额。", "operationId": "post__api_v1_system_customer_cases__id__recover_original_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoverOriginalRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" } }, "security": [ { "session": [] } ], "summary": "修正未付款的人工声明，并申请原路退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-quote": { "post": { "description": "重新预览范围、金额和排期。服务范围发生变化时，必须由客户重新申请；管理员可以直接拒绝旧申请。", "operationId": "post__api_v1_system_customer_cases__id__refund_quote", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRefundPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScopedRefundPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "批准前预览待处理的范围申请", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-review": { "post": { "description": "按目标工作空间串行处理。批准时预留可用钱包资金，使用稳定的提供方请求 ID 分配原路退款，并保留需要约定替代方式的余额。Waffo/Paddle 审批会创建持久化的原提供方退款意图，并发送商户退款 API 请求。不能通过人工声明完成这些退款。processing/pending 审批状态不代表资金已结算。", "operationId": "post__api_v1_system_customer_cases__id__refund_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "批准或拒绝客户退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/legal/policy": { "get": { "description": "", "operationId": "get__api_v1_system_legal_policy", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取经营主体资料和待发布条款版本", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "发布前必须确认经营主体法定名称，并提供有效联系邮箱。其他资料可选，未确认项目不会出现在公开文档中。替换已发布版本时，至少经过 30 天的控制台通知和成功发出的邮件通知期，期间保留旧版本。", "operationId": "patch__api_v1_system_legal_policy", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePolicyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "发布或安排服务条款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs": { "get": { "description": "仅限平台管理员会话。返回最新 50 封邮件，含类型、环境、收件人、尝试次数、状态和取消原因。已投递或取消的邮件内容会被清除。SMTP 接收不表示到达收件箱或已阅读。", "operationId": "get_api_v1_system_mail-jobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailJobList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "GET /system/mail-jobs", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs/{id}/retry": { "post": { "description": "重置尝试次数，将同一封失败邮件重新入队。已投递、已取消、运行中和待处理任务返回 MAIL_JOB_NOT_RETRYABLE。计费邮件在再次投递前重新核对当前同意状态和事件状态。SMTP 错误绝不会撤销已提交的付款。", "operationId": "post__api_v1_system_mail_jobs__id__retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "使用保留的加密内容重试失败邮件", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/operations": { "get": { "description": "仅限平台管理员会话。只追加的应用日志，包含执行者、对象、原因和明确变更。", "operationId": "get__api_v1_system_operations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "action", "schema": { "maxLength": 80, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOperationList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询客户管理操作记录" } }, "/api/v1/system/overview": { "get": { "description": "仅限平台管理员会话。套餐指标使用当前配置的支付环境。新用户统计最近 30 天，到期统计未来 7 天。", "operationId": "get__api_v1_system_overview", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOverview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取平台客户与套餐统计" } }, "/api/v1/system/paddle": { "get": { "operationId": "get__api_v1_system_paddle", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取 Paddle 配置，不包含私有密钥", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_paddle", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "加密保存 Paddle Billing 凭据", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/check": { "post": { "operationId": "post__api_v1_system_paddle_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleCheck" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "验证 Paddle 凭据和有效产品", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders": { "get": { "operationId": "get__api_v1_system_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询 Paddle 服务付款和钱包充值", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "核对或恢复原交易，不创建扣款", "x-licentivo-access": "platform" } }, "/api/v1/system/payment-channels": { "get": { "operationId": "get__api_v1_system_payment_channels", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询可独立配置的支付渠道", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_payment_channels", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChannelInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "通过乐观并发控制原子启用或禁用渠道", "x-licentivo-access": "platform" } }, "/api/v1/system/paypal": { "get": { "operationId": "get_api_v1_system_paypal", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "PayPal", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_paypal", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "PayPal", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/check": { "post": { "operationId": "post_api_v1_system_paypal_check", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "检查 PayPal", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/orders/{id}/refund": { "post": { "description": "仅限平台管理员会话。联系 PayPal 前先预留可用且未消费的钱包余额。pending 表示结果尚未确认，应对同一请求进行核对。不会自动取消套餐。", "operationId": "post__api_v1_system_paypal_orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "将未使用的钱包资金退回原 PayPal 支付方式" } }, "/api/v1/system/paypal/refund-requests": { "get": { "description": "仅限 Cookie 会话，不接受管理 API 密钥。客户读取限定于自己的工作空间；写入要求已验证的工作空间 Owner，且不具有平台管理员权限。申请不会移动或预留资金。管理员批准时重新检查当前钱包和未退款的已扣款金额，再使用已有的幂等原路退款与预留流程。批准不会取消套餐。", "operationId": "get__api_v1_system_paypal_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" } }, "security": [ { "session": [] } ], "summary": "查询待审核客户退款申请", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refund-requests/{id}/review": { "post": { "description": "仅限 Cookie 会话，不接受管理 API 密钥。客户读取限定于自己的工作空间；写入要求已验证的工作空间 Owner，且不具有平台管理员权限。申请不会移动或预留资金。管理员批准时重新检查当前钱包和未退款的已扣款金额，再使用已有的幂等原路退款与预留流程。批准不会取消套餐。", "operationId": "post__api_v1_system_paypal_refund_requests__id__review", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、认证、所有权、审核冲突或余额错误" } }, "security": [ { "session": [] } ], "summary": "批准或拒绝客户退款申请", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refunds": { "get": { "description": "仅限平台管理员会话。", "operationId": "get__api_v1_system_paypal_refunds", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "查询所选支付环境的退款申请" } }, "/api/v1/system/paypal/refunds/{id}/reconcile": { "post": { "description": "仅限平台管理员会话。尚未收到退款 ID 时，重试同一 PayPal-Request-Id；否则查询已有的提供方退款。", "operationId": "post__api_v1_system_paypal_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "核对同一退款，不创建新的扣款标识" } }, "/api/v1/system/plan-gifts": { "get": { "description": "仅限平台管理员会话。指定收件人代表去重后的工作空间。搜索匹配收件人邮箱、工作空间或套餐名称。", "operationId": "get__api_v1_system_plan_gifts", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询赠送历史" }, "post": { "description": "仅限平台管理员会话，批次原子执行。提供预览返回的 fingerprint 和稳定的 request_id；相同重放返回同一批次。档位或排期改变后必须重新预览。赠送实际付款为零，不能转为现金退款；升级时仍正常抵扣其记录的权益价值。只有尚未开始的新当前档位赠送会随后续升级调整，不额外收费，并保留原日期。历史赠送不重新对齐；月度额度及超额规则正常适用。混合批次使用 current/--- 元数据；每项实际档位和币种应查看由购买记录支撑的赠送明细。", "operationId": "post__api_v1_system_plan_gifts", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "确认已审核的当前档位赠送" } }, "/api/v1/system/plan-gifts/preview": { "post": { "description": "仅限平台管理员会话。接受 1–100 个不同且有效的客户用户 ID。同一工作空间的用户只获得一份合约。每项继承该客户当前生效的套餐，或所选环境中最近到期的套餐。混合档位批次逐项返回实际套餐和权益价值。省略 plan/currency/price_version；可选的显式值必须与每位客户已有套餐匹配。不能通过此接口给没有套餐的客户发放其他档位。after_current 追加到所有付费和赠送覆盖期之后；immediate 拒绝权益重叠。不写入数据或扣款。", "operationId": "post__api_v1_system_plan_gifts_preview", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "预览当前档位套餐赠送" } }, "/api/v1/system/plan-gifts/{id}/cancel": { "post": { "description": "仅限平台管理员会话。可安全重复取消。停止此合约，但不删除历史、不退还超额费用、不移动其他已排期合约。", "operationId": "post__api_v1_system_plan_gifts__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftCancellation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "取消有效或已排期的赠送" } }, "/api/v1/system/plans": { "get": { "operationId": "get_api_v1_system_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AdminPlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "套餐目录", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_system_plans", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Price" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "套餐目录", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/plans/customer-controls": { "patch": { "description": "仅限平台管理员会话。两个开关默认均为 false。可提交 device_enabled、api_enabled 或两者；省略的开关保持当前状态。关闭某个开关时，隐藏对应客户设置，并只忽略该项已保存偏好，直到重新启用。标为无限的 API 额度仍保持无限。", "operationId": "patch__api_v1_system_plans_customer_controls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerControlsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerControlsResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "分别允许客户设置设备或 API 超额偏好" } }, "/api/v1/system/plans/default": { "patch": { "operationId": "patch_api_v1_system_plans_default", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefaultPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DefaultPlan" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "默认套餐", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention": { "get": { "description": "", "operationId": "get__api_v1_system_privacy_retention", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取归档和保留执行记录", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention/run": { "post": { "description": "只做逻辑归档，保留客户和业务数据行。轮换超过 90 天的已认证托管 .lvb 备份，以及超过六个自然月的应用自有安全日志。执行通过数据库锁串行化。", "operationId": "post__api_v1_system_privacy_retention_run", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "处理已到期的归档与保留任务", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/provider-refunds/{id}/reconcile": { "post": { "description": "通过提供方或业务引用查询已有请求。只有此前从未提交过的持久化意图可以首次发送；重复或结果未知的提交绝不再次发送。完成退款必须取得独立验证的原提供方回执。", "operationId": "post__api_v1_system_provider_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProviderRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" } }, "security": [ { "session": [] } ], "summary": "核对已有的原渠道退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refund-requests": { "get": { "description": "只读的平台管理员会话。合并钱包退款申请及提供方钱包或服务取消申请。按环境统计的待审核数独立于分页和范围筛选。读取绝不会批准、冻结或退还资金；应使用各来源已有的审核接口。", "operationId": "get_system_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "review", "schema": { "enum": [ "pending", "all" ], "type": "string" } }, { "in": "query", "name": "scope", "schema": { "enum": [ "wallet", "service" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundInboxList" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "按环境限定的申请及待审核数量" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、会话或权限错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、会话或权限错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、会话或权限错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、会话或权限错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、会话或权限错误" } }, "security": [ { "session": [] } ], "summary": "统一客户退款审核队列", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refunds": { "get": { "operationId": "get__api_v1_system_refunds", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundHistory" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" } }, "security": [ { "session": [] } ], "summary": "查询 PayPal、Waffo 和 Paddle 退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/revenue": { "get": { "operationId": "get_api_v1_system_revenue", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "month", "schema": { "description": "all 或 UTC YYYY-MM", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Revenue" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "收入", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/sdk-example": { "post": { "description": "仅限平台管理员 Owner 会话，要求 CSRF，不接受 API 密钥。复用专用产品和策略，不续延现有试用。", "operationId": "post_api_v1_system_sdk-example", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKExampleSetup" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleSetting" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "准备或启用管理员专用的公开 SDK 示例产品", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/service/incidents": { "get": { "description": "", "operationId": "get__api_v1_system_service_incidents", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取全部服务通知", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "description": "非紧急维护至少提前 24 小时通知。连续已核实故障超过 24 小时时，补偿实际受影响的付费时长；重叠区间不重复补偿。超过七天时，可符合未使用服务退款条件。", "operationId": "post__api_v1_system_service_incidents", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIncidentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncident" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "发布维护或解决故障", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/settings": { "get": { "operationId": "get_api_v1_system_settings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SystemSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "GET /system/settings", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_settings", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "PATCH /system/settings", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/test-mail": { "post": { "description": "使用已保存的投递服务，明确向指定收件人发送一封真实测试邮件并加入队列。HTTP 202 只确认队列接收，不表示邮件到达收件箱。应跟踪任务状态，并检查提供方控制台和收件箱中的投递情况。", "operationId": "post_api_v1_system_test-mail", "parameters": [ { "description": "Cookie 和公共认证写入必须提供；仅支持的 Bearer 资源写入可豁免", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestMail" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] } ], "summary": "POST /system/test-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/tls": { "get": { "description": "仅限平台管理员浏览器会话；拒绝管理 API 密钥和租户所有者。反映本进程实际使用的证书，不暴露证书 PEM 或私钥。", "operationId": "get__api_v1_system_tls", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功；只返回公开证书元数据。" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" } }, "security": [ { "session": [] } ], "summary": "读取当前 HTTPS 证书" }, "patch": { "description": "仅限平台管理员浏览器会话；拒绝管理 API 密钥和租户所有者。在 MySQL 中验证并加密保存证书和密钥、记录审计事件，再替换当前证书。新 TLS 握手立即使用新证书，已有连接正常继续。重启时优先采用数据库证书，而非引导文件。", "operationId": "patch__api_v1_system_tls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateUpdateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功；只返回公开证书元数据。" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" } }, "security": [ { "session": [] } ], "summary": "立即更换 HTTPS 证书" } }, "/api/v1/system/tls/check": { "post": { "description": "仅限平台管理员浏览器会话；拒绝管理 API 密钥和租户所有者。检查格式、密钥强度、密钥匹配、主机名、有效期和信任链。必须启用直接 HTTPS。当前证书不变。", "operationId": "post__api_v1_system_tls_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功；只返回公开证书元数据。" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code。TLS_KEY_MISMATCH、TLS_DOMAIN_MISMATCH、TLS_EXPIRED、TLS_CHAIN_UNTRUSTED 和 TLS_SETTINGS_CONFLICT 均保留原证书。" } }, "security": [ { "session": [] } ], "summary": "验证证书和私钥但不保存" } }, "/api/v1/system/translation": { "get": { "description": "仅限平台管理员会话。", "operationId": "get__api_v1_system_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "读取 DeepL 设置，不暴露 API 密钥" }, "patch": { "description": "仅限平台管理员会话。使用最近一次 GET 返回的 expected_version。绝不返回密钥。", "operationId": "patch__api_v1_system_translation", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "加密保存 DeepL 设置" } }, "/api/v1/system/translation/check": { "post": { "description": "只调用 DeepL 语言与用量接口，不发送论坛内容。", "operationId": "post__api_v1_system_translation_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "查看 error.code 和 error.message；request_id 用于定位请求。" } }, "security": [ { "session": [] } ], "summary": "验证已保存的 API 密钥，读取支持的语言和用量" } }, "/api/v1/system/users": { "get": { "description": "仅限平台管理员会话。包括未验证账号和团队成员，绝不返回哈希或认证令牌。", "operationId": "get__api_v1_system_users", "parameters": [ { "description": "邮箱、姓名或工作空间的部分匹配，不区分大小写；通配字符会被转义。", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询所有注册用户" } }, "/api/v1/system/users/export.csv": { "get": { "description": "仅限平台管理员会话。最多 10000 条匹配记录，使用 UTF-8 BOM，并转义电子表格公式。不包含凭据。", "operationId": "get__api_v1_system_users_export_csv", "parameters": [ { "description": "邮箱、姓名或工作空间的部分匹配，不区分大小写；通配字符会被转义。", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "CSV 附件" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "将筛选后的注册用户导出为 CSV" } }, "/api/v1/system/users/{id}": { "get": { "description": "仅限平台管理员会话。工作空间余额、最近 20 份合约及 PayPal 累计付款和退款金额按币种与环境分别统计。", "operationId": "get__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取客户和工作空间详情" }, "patch": { "description": "仅限平台管理员会话。要求操作原因和乐观版本号。禁用时撤销已有会话、密钥和登录链接；恢复账号不会恢复密钥。平台管理员账号受到保护。", "operationId": "patch__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "更新客户状态或私有管理员备注" } }, "/api/v1/system/users/{id}/data-export": { "post": { "description": "账号关闭且客户导出期限结束后可用。要求管理员密码、范围和可审计的操作原因。不清除任何业务记录。", "operationId": "post__api_v1_system_users__id__data_export", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDataExportInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "导出保留的客户记录", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/users/{id}/revoke-credentials": { "post": { "description": "仅限平台管理员会话。不会禁用账号，客户可以重新登录。不能在此撤销管理员凭据。", "operationId": "post__api_v1_system_users__id__revoke_credentials", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformRevocation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "撤销客户已有会话和 API 密钥" } }, "/api/v1/system/waffo": { "get": { "operationId": "get__api_v1_system_waffo", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "读取 Waffo 设置，不包含签名密钥", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_waffo", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "加密保存 Waffo 凭据", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/check": { "post": { "operationId": "post__api_v1_system_waffo_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoCheck" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "验证 Waffo 凭据和有效的一次性产品", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders": { "get": { "operationId": "get__api_v1_system_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "查询 Waffo 服务付款和钱包充值", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "本地服务付款标识。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "恢复并核对原 Waffo 付款", "x-licentivo-access": "platform" } }, "/api/v1/system/workspaces/{id}/status": { "patch": { "description": "仅限平台管理员会话。暂停会阻止登录、管理 API 和在线授权，并撤销凭据。合约到期时间继续计算。平台工作空间受到保护；签名离线缓存仍受已有到期时间约束。", "operationId": "patch__api_v1_system_workspaces__id__status", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformWorkspaceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformWorkspaceStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "检查 error.code 和 error.message。" } }, "security": [ { "session": [] } ], "summary": "暂停或恢复整个客户工作空间" } }, "/api/v1/system/{provider}/orders/{id}/refund": { "post": { "description": "要求平台管理员会话。已付款服务应改用取消流程。未应用付款直接退款，不产生钱包变动。稳定的 request_id 在调用网关前持久化退款意图；结果未知时查询，绝不盲目重新提交。", "operationId": "post__api_v1_system__provider__orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "waffo", "paddle" ], "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginalRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OriginalRefundResult" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "校验、所有权、环境、退款状态或提供方错误" } }, "security": [ { "session": [] } ], "summary": "为未使用余额或未应用付款发起原渠道退款", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/usage": { "get": { "description": "当前月份报告活跃设备注册数，历史月份报告记录的设备使用历史。已购买套餐的 API 额度按各自额度月份计算。设备释放后仍保留历史记录。当前占用量与计费峰值是不同指标。", "operationId": "get_api_v1_usage", "parameters": [ { "description": "UTC 自然月；默认当前月份", "in": "query", "name": "month", "schema": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "api_calls": 0, "api_period": null, "billable_devices": 0, "estimated_total_cents": 0, "estimated_total_micros": 0, "month": "2026-09", "operations": [], "overage_devices": 0, "period": null, "products": [], "purchased": null, "purchased_active_devices": 0, "sandbox": false, "timezone": "UTC", "warning": "normal" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Usage", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "默认额度已禁用（DEFAULT_PLAN_DISABLED）" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Current device occupancy, historical device use and metered API usage", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/devices": { "get": { "description": "所选 UTC 月份的设备使用记录，设备释放后仍保留。这是活动历史，不是当前在线设备列表。查询当前占用量请使用 GET /api/v1/usage。", "operationId": "get_api_v1_usage_devices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "description": "UTC 自然月；默认当前月份", "in": "query", "name": "month", "schema": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "所属产品的 UUID，必须属于当前工作空间。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "first_seen_at": "2026-09-01T00:00:00Z", "last_seen_at": "2026-09-30T00:00:00Z", "month": "2026-09", "product_id": "11111111-1111-4111-8111-111111111111" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UsageDeviceList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询用量设备列表", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/export.csv": { "get": { "description": "所选 UTC 月份的设备使用记录，设备释放后仍保留。这是活动历史，不是当前在线设备列表。查询当前占用量请使用 GET /api/v1/usage。", "operationId": "get_api_v1_usage_export_csv", "parameters": [ { "description": "UTC 自然月；默认当前月份", "in": "query", "name": "month", "schema": { "description": "UTC 月份，YYYY-MM；省略查询参数时使用当前 UTC 月，创建计费任务时必须是已结束月份。", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "month,product_id,device_id,first_seen_utc,last_seen_utc\n", "schema": { "type": "string" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "导出用量", "x-csv-columns": [ "month", "product_id", "device_id", "first_seen_utc", "last_seen_utc" ], "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/validate": { "post": { "description": "使用 product_id + license_key + device_id 认证，不使用 Cookie、CSRF 或厂商管理密钥。除 activate 外均要求 activation_id。每次成功请求消耗一次 API 调用；幂等重放和失败不消耗。超额时原子扣减钱包，或返回 API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT。验证和心跳重试回执在 3600 秒后到期。原授权仍有效时，此窗口内相匹配的请求会重放原结果，不再次扣费。窗口结束后应使用新密钥；已使用过的旧密钥可能按新请求处理。激活、解绑和功能计次回执持续保存。工作空间设备额度按当前激活数计算。释放可归还额度；浮动租约到期也归还额度，而普通设备离线后仍计入注册数。仅当额度月份内的计费峰值超出已付费容量时，才收取设备超额费用；释放不会退还已产生费用。API 用量独立计算。", "operationId": "post_api_v1_validate", "parameters": [ { "description": "每次操作生成新密钥；重试保持同一密钥和请求体。最多 80 个字符，不能包含空白。验证和心跳可不提供。", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "运行时验证" } }, "/api/v1/webhook-deliveries/{id}/attempts": { "get": { "operationId": "get_api_v1_webhook-deliveries_by_id_attempts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AttemptList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询投递尝试列表", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/api/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_api_v1_webhook-deliveries_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "重试 Webhook 投递", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks": { "get": { "operationId": "get_api_v1_webhooks", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "event_types": [], "items": [ { "created_at": "2026-10-18T00:00:00Z", "enabled": true, "events": [], "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "updated_at": "2026-10-18T00:00:00Z", "url": "https://merchant.example.com/license-events" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询 Webhook 列表", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_webhooks", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "enabled": true, "events": [ "license.created", "license.renewed" ], "name": "Order system", "url": "https://merchant.example.com/license-events" }, "schema": { "$ref": "#/components/schemas/LicensingWebhookInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "secret": "whsec_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookSecret", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "保存 Webhook", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "get_api_v1_webhooks_by_id_deliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "当前资源的唯一 UUID；路径中的 {id} 使用相应资源的 ID。", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "每页条数，默认 25，范围 1–100。", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "跳过的记录数，默认 0，范围 0–100000；下一页用 offset + limit。", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null, "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeliveryList", "description": "本次成功操作的业务结果；失败响应改为 error。" }, "request_id": { "description": "响应顶层为本次 HTTP 请求的追踪 UUID；在批量和接入请求正文中为调用方生成的业务去重 UUID。两者用途不同。", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "查询 Webhook 投递列表", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/healthz": { "get": { "operationId": "get_healthz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" } }, "security": [], "summary": "进程存活检查" } }, "/readyz": { "get": { "operationId": "get_readyz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "成功" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参见 docs/error-codes.md；适用范围取决于具体接口" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "数据库就绪检查" } } }, "servers": [ { "url": "https://www.licentivo.com" } ] }