{ "components": { "schemas": { "Checkout": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "properties": { "checkout_url": { "format": "uri", "type": "string" }, "fulfillment": { "type": "string" } }, "required": [ "fulfillment" ], "type": "object" } ] }, "Credential": { "properties": { "license_key": { "description": "僅供官方 SDK 使用；絕不能通過檢查此值自行授權訪問。", "type": "string", "x-sensitive": true }, "product_id": { "format": "uuid", "type": "string" }, "valid_until": { "format": "date-time", "type": [ "string", "null" ] }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "product_id", "license_key", "valid_until", "version" ], "type": "object" }, "EntitlementStatus": { "properties": { "account_url": { "format": "uri", "type": "string" }, "code": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "max_retry_attempts": { "minimum": 0, "type": "integer" }, "message": { "type": "string" }, "next_action": { "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "retry_after_seconds": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "ready", "pending", "expired", "suspended", "not_purchased" ], "type": "string" }, "synchronized": { "type": "boolean" }, "valid_from": { "format": "date-time", "type": [ "string", "null" ] }, "valid_until": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "product_id", "environment", "status", "code", "message", "next_action", "account_url", "synchronized", "retry_after_seconds", "max_retry_attempts" ], "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "error", "request_id" ], "type": "object" }, "ExternalCapabilities": { "additionalProperties": false, "properties": { "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "delivery_types": { "items": { "enum": [ "license_key", "activation_url", "instructions" ], "type": "string" }, "minItems": 1, "type": "array" }, "devices": { "const": false, "type": "boolean" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "identity_exchange": { "const": false, "type": "boolean" }, "protocol": { "const": "launch-external-licensing-v1", "type": "string" }, "purchase_types": { "items": { "enum": [ "perpetual", "fixed_term" ], "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "protocol", "connection_ref", "environment", "purchase_types", "delivery_types" ], "type": "object" }, "ExternalCapabilitiesResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ExternalCapabilities" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "ExternalConnection": { "additionalProperties": false, "properties": { "activation_origins": { "items": { "format": "uri", "type": "string" }, "type": "array" }, "allow_local_http": { "type": "boolean" }, "allow_private_network": { "type": "boolean" }, "base_url": { "format": "uri", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/ExternalCapabilities" }, "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "credential_stored": { "type": "boolean" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "id": { "format": "uuid", "type": "string" }, "key_id": { "type": "string" }, "last_check_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provider": { "const": "custom_http", "type": "string" } }, "required": [ "id", "provider", "name", "base_url", "environment", "connection_ref", "key_id", "credential_stored", "allow_private_network", "allow_local_http", "activation_origins", "capabilities", "last_checked_at", "last_check_error" ], "type": "object" }, "ExternalConnectionInput": { "additionalProperties": false, "properties": { "activation_origins": { "items": { "format": "uri", "type": "string" }, "type": "array" }, "allow_local_http": { "default": false, "description": "只允許 sandbox 回環 HTTP。", "type": "boolean" }, "allow_private_network": { "default": false, "type": "boolean" }, "base_url": { "format": "uri", "maxLength": 512, "type": "string" }, "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "key_id": { "maxLength": 64, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "provider": { "const": "custom_http", "type": "string" }, "signing_key": { "description": "32-128 個隨機位元組的標準 Base64 編碼；創建時必填，編輯時為空可保留已有密鑰。", "maxLength": 180, "type": "string", "writeOnly": true } }, "required": [ "provider", "name", "base_url", "environment", "connection_ref", "key_id" ], "type": "object" }, "ExternalConnectionResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ExternalConnection" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "ExternalDelivery": { "additionalProperties": false, "properties": { "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/ExternalDeliveryValue" }, { "type": "null" } ] }, "entitlement_ref": { "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "status": { "enum": [ "pending", "ready", "unavailable" ], "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "connection_ref", "environment", "entitlement_ref", "version", "status", "delivery" ], "type": "object" }, "ExternalDeliveryResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ExternalDelivery" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "ExternalDeliveryValue": { "additionalProperties": false, "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "license_key", "activation_url", "instructions" ], "type": "string" }, "value": { "description": "敏感內容，最多 4096 個 UTF-8 位元組。絕不能寫入日誌。啟用 URL 必須使用已設定的 HTTPS 來源位址。", "maxLength": 4096, "type": "string" } }, "required": [ "type", "value", "expires_at" ], "type": "object" }, "ExternalError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "ExternalMapping": { "additionalProperties": false, "properties": { "connection_id": { "format": "uuid", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "product_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "version_id": { "format": "uuid", "type": "string" } }, "required": [ "version_id", "environment", "connection_id", "product_ref", "plan_ref" ], "type": "object" }, "ExternalMappingInput": { "additionalProperties": false, "properties": { "plan_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "product_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "version_id": { "format": "uuid", "type": "string" } }, "required": [ "version_id", "product_ref", "plan_ref" ], "type": "object" }, "ExternalReceipt": { "additionalProperties": false, "properties": { "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "entitlement_ref": { "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "error_code": { "anyOf": [ { "maxLength": 96, "type": "string" }, { "type": "null" } ] }, "event_id": { "format": "uuid", "type": "string" }, "payload_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "status": { "enum": [ "pending", "applied", "rejected", "manual_review" ], "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "event_id", "connection_ref", "environment", "entitlement_ref", "version", "payload_sha256", "status", "error_code" ], "type": "object" }, "ExternalReceiptResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ExternalReceipt" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "ExternalSnapshot": { "additionalProperties": false, "properties": { "account_ref": { "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "change_reason": { "enum": [ "purchase", "renewal", "upgrade", "refund", "reversal", "suspension", "resumption", "expiry", "reconciliation" ], "type": "string" }, "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "desired_state": { "enum": [ "active", "suspended", "expired", "revoked" ], "type": "string" }, "entitlement_ref": { "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "event_id": { "format": "uuid", "type": "string" }, "launch_plan_version_id": { "format": "uuid", "type": "string" }, "launch_product_id": { "format": "uuid", "type": "string" }, "plan_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "product_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "schema": { "const": "launch-external-licensing-v1", "type": "string" }, "type": { "const": "entitlement.snapshot", "type": "string" }, "valid_from": { "format": "date-time", "type": "string" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "schema", "event_id", "connection_ref", "environment", "type", "change_reason", "account_ref", "entitlement_ref", "launch_product_id", "launch_plan_version_id", "product_ref", "plan_ref", "version", "desired_state", "valid_from", "valid_until" ], "type": "object" }, "HealthResponse": { "properties": { "data": { "properties": { "status": { "const": "ok" } }, "required": [ "status" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" }, "IntegrationBundle": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "checks": { "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" } }, "required": [ "code", "status", "message" ], "type": "object" }, "type": "array" }, "config": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "launch_product_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "const": "" } ], "description": "僅檢查失敗且無法解析映射時為空。" }, "merchant_origin": { "format": "uri", "type": "string" }, "schema_version": { "const": 1, "type": "integer" } }, "required": [ "schema_version", "merchant_origin", "launch_product_id", "licentivo_product_id", "environment" ], "type": "object" }, "example_path": { "type": "string" }, "language": { "enum": [ "go", "python", "csharp", "java", "javascript", "rust", "ruby", "c", "cpp", "web" ], "type": "string" }, "product_config": { "$ref": "#/components/schemas/PublicProductConfig" }, "ready": { "type": "boolean" } }, "required": [ "ready", "config", "checks", "language", "example_path", "checked_at" ], "type": "object" }, "LaunchIdentity": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "identity_token": { "description": "短期身份斷言，最多 120 秒；絕不是運行時授權。", "type": "string" }, "launch_connection_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "token_type": { "type": "string" } }, "required": [ "identity_token", "token_type", "product_id", "licentivo_product_id", "launch_connection_id", "environment", "audience", "expires_at" ], "type": "object" }, "LicensingConnections": { "additionalProperties": false, "properties": { "bindings": { "items": { "$ref": "#/components/schemas/ProductLicensingBinding" }, "type": "array" }, "connections": { "items": { "$ref": "#/components/schemas/ExternalConnection" }, "type": "array" }, "default_provider": { "description": "全部產品和兩個環境共用的唯一當前授權提供方。", "enum": [ "licentivo", "custom_http" ], "type": "string" }, "mappings": { "items": { "$ref": "#/components/schemas/ExternalMapping" }, "type": "array" } }, "required": [ "connections", "bindings", "mappings", "default_provider" ], "type": "object" }, "LicensingConnectionsResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingConnections" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "LicensingProviderInput": { "additionalProperties": false, "properties": { "provider": { "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "provider" ], "type": "object" }, "LicensingSaved": { "additionalProperties": false, "properties": { "saved": { "const": true, "type": "boolean" } }, "required": [ "saved" ], "type": "object" }, "LicensingSavedResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingSaved" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "LicentivoConnectionInput": { "additionalProperties": false, "properties": { "api_key": { "description": "首次連接必填；省略或留空可保留服務端已保存密鑰。", "type": "string", "writeOnly": true }, "webhook_secret": { "description": "可選的 32–256 位元組秘密。省略或留空可保留已保存的秘密。", "type": "string", "writeOnly": true } }, "type": "object" }, "Order": { "properties": { "action": { "type": "string" }, "amount_minor": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "id": { "format": "uuid", "type": "string" }, "paid_at": { "format": "date-time", "type": [ "string", "null" ] }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer" }, "plan_version_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "product_name": { "type": "string" }, "product_slug": { "type": "string" }, "purchase_periods": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "product_id", "product_name", "product_slug", "plan_version_id", "plan_name", "plan_version", "action", "status", "currency", "amount_minor", "purchase_periods", "created_at", "paid_at", "environment" ], "type": "object" }, "ProductLicensingBinding": { "additionalProperties": false, "properties": { "connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "product_id", "environment", "provider", "connection_id" ], "type": "object" }, "ProductLicensingInput": { "additionalProperties": false, "properties": { "connection_id": { "description": "外部連接 UUID；custom_http 時必填。", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "mappings": { "items": { "$ref": "#/components/schemas/ExternalMappingInput" }, "type": "array" }, "provider": { "description": "必須與實例全局當前授權提供方一致。先使用 PUT /api/v1/admin/licensing/provider 配置。", "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "provider", "environment" ], "type": "object" }, "PublicLaunchConfig": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "launch_product_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "format": "uuid", "type": "string" }, "merchant_origin": { "format": "uri", "type": "string" }, "schema_version": { "const": 1, "type": "integer" } }, "required": [ "schema_version", "merchant_origin", "launch_product_id", "licentivo_product_id", "environment" ], "type": "object" }, "PublicProductConfig": { "additionalProperties": false, "description": "經過凈化的公開配置。簽名密鑰來源必須由商戶驗證。", "properties": { "app_version": { "type": "string" }, "base_url": { "format": "uri", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "maxProperties": 32, "minProperties": 1, "propertyNames": { "description": "密鑰標識長度為 1–128 個 UTF-8 位元組。", "minLength": 1, "type": "string", "x-maxBytes": 128 }, "type": "object" } }, "required": [ "product_id", "trusted_keys", "base_url" ], "type": "object" }, "PublicProductImport": { "additionalProperties": false, "description": "Launch 公開產品配置，由官方產品 ID 和簽名公鑰填充。兼容舊 JSON 中空的 license_key/cache_path 和 false 的 allow_http，并將這些字段移除。拒絕已填充的秘密和未知字段。", "properties": { "allow_http": { "const": false }, "app_version": { "description": "最多 80 個 UTF-8 位元組。", "type": "string", "x-maxBytes": 80 }, "base_url": { "format": "uri", "type": "string" }, "cache_path": { "const": "" }, "device_name": { "maxLength": 128, "type": "string" }, "license_key": { "const": "" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "maxProperties": 32, "minProperties": 1, "propertyNames": { "description": "密鑰標識長度為 1–128 個 UTF-8 位元組。", "minLength": 1, "type": "string", "x-maxBytes": 128 }, "type": "object" } }, "required": [ "product_id", "trusted_keys" ], "type": "object" }, "ReadinessResponse": { "properties": { "data": { "properties": { "code": { "enum": [ "DATABASE_NOT_CONFIGURED", "DATABASE_UNAVAILABLE", "DATABASE_SCHEMA_NOT_READY" ] }, "status": { "enum": [ "ready", "not_ready" ] } }, "required": [ "status" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" }, "RequestID": { "description": "同時返回于 X-Request-ID 響應頭", "pattern": "^[a-f0-9]{32}$", "type": "string" }, "SessionGrant": { "properties": { "access_token": { "description": "僅桌面登錄返回。必須當作秘密，絕不能放入 URL 或日志。", "type": "string", "x-sensitive": true }, "expires_at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "website", "desktop" ], "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user", "kind", "expires_at" ], "type": "object" }, "SessionView": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "current": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "website", "desktop" ], "type": "string" } }, "required": [ "id", "kind", "created_at", "expires_at", "current" ], "type": "object" }, "User": { "properties": { "email": { "format": "email", "type": "string" }, "full_access": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "password_change_required": { "type": "boolean" }, "role": { "enum": [ "customer", "admin", "operations", "support" ], "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "email", "verified", "role", "full_access", "password_change_required" ], "type": "object" } }, "securitySchemes": { "desktopBearer": { "description": "通過 auth/login 并設置 kind=desktop 取得的不透明桌面會話。", "scheme": "bearer", "type": "http" }, "websiteCookie": { "description": "瀏覽器會話。變更還要求匹配的 Origin 及來自 launch_csrf 的 X-CSRF-Token。", "in": "cookie", "name": "launch_session", "type": "apiKey" } } }, "info": { "description": "系統、帳號、桌面授權、接入向導和基礎購買 API。這不是完整的員工管理或支付 Webhook API。運行時訪問仍必須通過官方 Licentivo SDK。僅商戶啟用郵箱驗證時才要求驗證。同時記錄自定義授權連接和客戶交付。外部接收端接口另見 external-licensing-openapi.json。", "license": { "identifier": "MIT", "name": "MIT" }, "title": "Licentivo Launch 集成 API", "version": "0.3.4-beta", "x-document-language": "zh-Hant" }, "openapi": "3.1.0", "paths": { "/api/v1/admin/connections/licentivo": { "post": { "operationId": "configureLicentivoConnection", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicentivoConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": true, "description": "連接標識、已驗證能力和目錄。絕不返回已保存的秘密。", "type": "object" }, "request_id": { "type": "string" } }, "required": [ "data" ], "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "websiteCookie": [] } ], "summary": "驗證并保存服務端 Licentivo 管理連接", "tags": [ "Licentivo connection" ] } }, "/api/v1/admin/identity-notifications/{id}/retry": { "post": { "operationId": "retryIdentityNotification", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 2, "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "原通知已安排重試" }, "403": { "description": "需要管理員權限" }, "409": { "description": "通知已完成或正在處理" } }, "security": [ { "websiteCookie": [] } ], "summary": "重試帳號安全撤銷通知（管理員）" } }, "/api/v1/admin/integration/check": { "post": { "description": "要求 admin 角色。網站調用方必須提供 Origin 和 X-CSRF-Token。ready=false 表示配置不完整，不返回秘密字段。配置不完整的報告中，licentivo_product_id 可為空。", "operationId": "checkApplicationIntegration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "language": { "enum": [ "go", "python", "csharp", "java", "javascript", "rust", "ruby", "c", "cpp", "web" ], "type": "string" }, "product_id": { "format": "uuid", "type": "string" } }, "required": [ "product_id", "environment", "language" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/IntegrationBundle" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "自動讀取所選軟體映射及簽名公鑰，直接初始化 SDK", "tags": [ "Application integration" ] } }, "/api/v1/admin/integration/context": { "get": { "description": "要求 admin 角色。網站調用方必須提供 Origin 和 X-CSRF-Token。ready=false 表示配置不完整，不返回秘密字段。配置不完整的報告中，licentivo_product_id 可為空。", "operationId": "getIntegrationContext", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": false, "properties": { "licensing_origin": { "type": "string" }, "merchant_origin": { "type": "string" } }, "required": [ "merchant_origin", "licensing_origin" ], "type": "object" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "公開部署上下文，不包含私有啟動設置" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "字段、產品 ID 或環境無效。" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "讀取配置的商戶來源與固定授權來源", "tags": [ "Application integration" ] } }, "/api/v1/admin/licensing/connections": { "get": { "operationId": "listLicensingChoices", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingConnectionsResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "查詢外部連接、產品綁定和映射；Licentivo 設置保留已有 API", "tags": [ "Custom licensing" ] }, "post": { "operationId": "createExternalLicensingConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "驗證并保存自定義 HTTP 授權連接", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/connections/{id}": { "put": { "operationId": "updateExternalLicensingConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "編輯元資料或簽名密鑰；目標地址、環境和網路策略不可變", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/connections/{id}/check": { "post": { "operationId": "checkExternalLicensingConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "刷新能力；200 響應中的 last_check_error 用于區分檢查失敗", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/provider": { "put": { "operationId": "selectLicensingProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingProviderInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingSavedResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "為整個實例啟用一個授權提供方；已有其他提供方訂單時，切換要求先遷移", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/products/{id}/licensing": { "put": { "operationId": "configureProductLicensing", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductLicensingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingSavedResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "使用當前授權提供方，為某一環境配置產品連接和套餐映射", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/refunds/{id}/reconcile": { "post": { "description": "管理員核對原退款，驗證渠道回執的原交易、金額和幣種后恢復同一操作。無回執時僅在 Stripe/PayPal 原審批時間的 23 小時內重試原冪等請求；超過期限需提供原渠道退款編號。操作記入審計，不創建新的退款操作編號。", "operationId": "reconcileRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "external_refund_id": { "maxLength": 128, "type": "string" }, "reason": { "maxLength": 500, "minLength": 2, "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "原任務已恢復排隊" }, "403": { "description": "需要管理員權限和有效 CSRF 憑據" }, "409": { "description": "狀態沖突、回執不匹配或需要原渠道退款編號" }, "503": { "description": "原渠道查詢暫不可用" } }, "security": [ { "websiteCookie": [] } ], "summary": "核對并恢復原退款任務" } }, "/api/v1/auth/complete-email": { "post": { "operationId": "completeAccountEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "password": { "type": "string", "writeOnly": true }, "token": { "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [], "summary": "完成一次性郵件憑據操作", "tags": [ "Application integration" ] } }, "/api/v1/auth/email": { "post": { "operationId": "requestAccountEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "kind": { "enum": [ "verify", "reset" ], "type": "string" } }, "required": [ "email", "kind" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [], "summary": "申請驗證或密碼恢復郵件", "tags": [ "Application integration" ] } }, "/api/v1/auth/identity-keys": { "get": { "operationId": "launchIdentityPublicKeys", "responses": { "200": { "description": "Ed25519 公鑰，絕不包含私有簽名材料" } }, "summary": "Launch 帳號身份的固定受信公開簽名密鑰" } }, "/api/v1/auth/login": { "post": { "description": "應用應設置 kind=desktop，并省略瀏覽器 Origin 請求頭。網站登錄設置 Cookie，且不返回 access_token。", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "kind": { "default": "website", "enum": [ "desktop", "website" ], "type": "string" }, "password": { "type": "string", "writeOnly": true } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SessionGrant" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [], "summary": "登錄網站或桌面應用", "tags": [ "Application integration" ] } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "撤銷當前會話；SDK 關閉、本地清理和設備釋放仍是不同操作", "tags": [ "Application integration" ] } }, "/api/v1/auth/register": { "post": { "operationId": "registerCustomer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "password": { "description": "12–128 個 UTF-8 位元組；服務端計算位元組數，而非 Unicode 字符數。", "type": "string", "writeOnly": true, "x-maxBytes": 128, "x-minBytes": 12 } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [], "summary": "注冊客戶；是否驗證遵循商戶郵件設置", "tags": [ "Application integration" ] } }, "/api/v1/licensing/documentation": { "get": { "operationId": "readExternalLicensingGuide", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "公開文件" } }, "security": [], "summary": "公開外部授權文件" } }, "/api/v1/licensing/protocol": { "get": { "operationId": "readExternalLicensingProtocol", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "公開文件" } }, "security": [], "summary": "公開外部授權文件" } }, "/api/v1/me": { "get": { "operationId": "currentUser", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "session_id": { "format": "uuid", "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user", "session_id" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "讀取已認證帳號", "tags": [ "Application integration" ] } }, "/api/v1/me/orders": { "get": { "operationId": "listOrders", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "查詢當前客戶的訂單列表", "tags": [ "Application integration" ] } }, "/api/v1/me/products/{id}/delivery": { "get": { "operationId": "readOwnedExternalDelivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "environment", "required": true, "schema": { "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalDeliveryResponse" } } }, "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": "要求管理員、CSRF 無效或范圍被禁止" }, "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": "觸發頻率限制" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "存儲或外部服務不可用" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "讀取當前所屬外部交付，絕不作為運行時授權決定", "tags": [ "Custom licensing" ] } }, "/api/v1/me/sessions": { "get": { "operationId": "listSessions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionView" }, "type": "array" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "查詢有效帳號會話列表", "tags": [ "Application integration" ] } }, "/api/v1/me/sessions/{id}": { "delete": { "operationId": "revokeSession", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "撤銷所屬會話", "tags": [ "Application integration" ] } }, "/api/v1/orders": { "post": { "description": "價格由服務端計算。續費和升級要求服務端簽發的報價。應完成托管結賬；重定向返回不證明付款成功。", "operationId": "createCheckout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "purchase", "renew", "upgrade" ], "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "idempotency_key": { "description": "穩定操作標識，16–80 個 UTF-8 位元組。同一操作的重試復用相同密鑰。", "type": "string", "x-maxBytes": 80, "x-minBytes": 16 }, "plan_version_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "stripe", "paypal", "waffo", "paddle" ], "type": "string" }, "purchase_periods": { "minimum": 1, "type": "integer" }, "quote_token": { "type": "string", "writeOnly": true } }, "required": [ "product_id", "plan_version_id", "environment", "provider", "idempotency_key" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "使用穩定冪等密鑰創建或恢復所屬結賬", "tags": [ "Application integration" ] } }, "/api/v1/orders/{id}": { "get": { "operationId": "getOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "讀取所屬訂單及交付進度", "tags": [ "Application integration" ] } }, "/api/v1/orders/{id}/reconcile": { "post": { "operationId": "reconcileOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "向支付提供方查詢所屬訂單", "tags": [ "Application integration" ] } }, "/api/v1/software/products/{id}/credential": { "post": { "deprecated": true, "description": "瀏覽器會話不能取得許可證密鑰，不接受客戶端指定用戶 ID。403 ENTITLEMENT_PENDING 包含 Retry-After: 3，重試必須有界。EXPIRED/SUSPENDED 要求用戶處理。404 ENTITLEMENT_NOT_PURCHASED 表示沒有所屬權益。", "operationId": "softwareCredential", "parameters": [ { "description": "Launch 產品 ID，不是 Licentivo 產品 ID。", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "environment" ], "type": "object" } } }, "required": true }, "responses": { "410": { "description": "LICENSE_CREDENTIAL_REMOVED；不返回許可證密鑰" } }, "security": [ { "desktopBearer": [] } ], "summary": "已移除：帳號 SDK 必須使用身份交換", "tags": [ "Application integration" ] } }, "/api/v1/software/products/{id}/identity": { "post": { "operationId": "exchangeAccountIdentity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "environment" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/LaunchIdentity" } }, "type": "object" } } }, "description": "僅身份上下文。授權由 Licentivo 決定。" }, "401": { "description": "帳號會話被拒絕" }, "503": { "description": "身份連接不可用" } }, "security": [ { "desktopBearer": [] } ], "summary": "取得供官方 SDK 使用的短期帳號身份斷言" } }, "/api/v1/software/products/{id}/status": { "get": { "description": "這是購買和同步資訊，不是運行時授權。", "operationId": "softwareStatus", "parameters": [ { "description": "Launch 產品 ID，不是 Licentivo 產品 ID。", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "environment", "required": false, "schema": { "default": "live", "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EntitlementStatus" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "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": "登錄時為 LOGIN_FAILED；會話過期或已撤銷時為 AUTH_REQUIRED。清除被拒絕的會話，收到明確拒絕后絕不能離線回退。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "禁止訪問、要求郵箱驗證、要求修改初始密碼或明確拒絕權益。" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED；不得緊密循環重試。", "headers": { "Retry-After": { "description": "再次嘗試前應等待的秒數。必須遵循此值，并限制總重試次數。", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "臨時服務或資料庫故障。只有有效的官方 SDK 簽名授權才允許離線訪問。" } }, "security": [ { "desktopBearer": [] } ], "summary": "讀取已認證客戶與所請求產品的可處理狀態", "tags": [ "Application integration" ] } }, "/api/v1/system/status": { "get": { "operationId": "getSystemStatus", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "implemented": { "items": { "type": "string" }, "type": "array" }, "phase": { "const": "local-development" }, "product": { "const": "Licentivo Launch" }, "sales_enabled": { "const": false }, "version": { "type": "string" } }, "required": [ "product", "version", "phase", "sales_enabled", "implemented" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "當前開發階段和實現范圍" } }, "summary": "公開版本和實現范圍，不包含配置或憑據" } }, "/healthz": { "get": { "operationId": "getLiveness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "HTTP 進程正在運行" } }, "summary": "進程存活狀態，獨立于資料庫就緒狀態" } }, "/readyz": { "get": { "operationId": "getReadiness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "資料庫已就緒，但這不能證明付款或授權驗收通過" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "資料庫未配置、不可用或缺少必需資料表" } }, "summary": "檢查 MySQL 連接和必需的 GORM 資料表" } } }, "servers": [ { "description": "替換為你的商戶來源；HTTP 只允許用于回環地址的 sandbox 開發。", "url": "https://shop.example.com" } ] }