{ "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、一個換行和 payload 解碼后的原始 JSON 位元組；不能重新序列化 JSON。簽章解碼后為 64 位元組。", "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-Hant" }, "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" } ] }