{ "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-Hans" }, "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" } ] }