{ "openapi": "3.0.3", "info": { "title": "夸克短链开放 API", "version": "1.0.0", "description": "与原生 RuoYi 账号、RBAC 和数据归属共用。先在后台的 API 密钥中创建有范围和有效期的密钥。API文档公开，业务调用须鉴权；不提供匿名发布或审核绕过接口。" }, "servers": [ { "url": "/openapi/v1" } ], "security": [ { "ApiKey": [] } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "psk_ID.SECRET", "description": "通过原生后台生成，明文仅显示一次。不要使用Cookie或AI供应商密钥。" } }, "schemas": { "Link": { "type": "object", "required": [ "title", "target", "enabled" ], "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{4,32}$", "description": "POST可省略自动生成；PUT必填且保持不变" }, "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "target": { "type": "string", "format": "uri", "example": "https://pan.quark.cn/s/2495e46017e5" }, "enabled": { "type": "boolean", "description": "启停；请求应显式提供" }, "ownerId": { "type": "integer", "readOnly": true }, "origin": { "type": "string", "readOnly": true }, "created": { "type": "string", "readOnly": true }, "updated": { "type": "string", "readOnly": true } } }, "Job": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "checking", "saving", "moderating", "sharing", "replacing", "replacement_error", "expired", "ready", "fallback", "error", "audit_error", "blocked", "disabled" ] }, "message": { "type": "string" }, "reviewDueAt": { "type": "string", "format": "date-time", "description": "新外部自动分享就绪满5分钟后的审核开始时间" }, "review": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "enum": [ "safe", "manual_review", "blocked", "error" ] }, "risk_score": { "type": "number", "nullable": true }, "description": { "type": "string" }, "resource_type": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } } } }, "created": { "type": "string" }, "updated": { "type": "string" }, "sourceFacts": { "type": "object", "description": "原分享可访问/时间/受限参考；不代表官方合规认证", "additionalProperties": true }, "stageDurationsMs": { "type": "object", "description": "已结束阶段的累计毫秒数", "additionalProperties": { "type": "integer" } } } }, "Error": { "type": "object", "required": [ "code", "msg" ], "properties": { "code": { "type": "integer" }, "msg": { "type": "string" } } } } }, "paths": { "/links": { "get": { "summary": "列出有权访问的短链", "operationId": "get__links", "description": "所需权限：pan:link:list。返回完整数组，无分页；普通账号仅自己的记录，超级管理员所有记录。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "手动创建短链", "operationId": "post__links", "description": "所需权限：pan:link:add。这是调用方明确管理的手动目标，不执行转存/AI审核。他人资源的自动处理请用POST /resolve-jobs。code省略时服务端生成；指定code可防止重复创建（冲突返回409）。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "$ref": "#/components/schemas/Link" } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } } }, "put": { "summary": "完整更新短链/替换目标/启停", "operationId": "put__links", "description": "所需权限：pan:link:edit。保持code不变，提供完整title/description/target/enabled；不是PATCH。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "$ref": "#/components/schemas/Link" } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "title", "target", "enabled" ], "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{4,32}$", "description": "POST可省略自动生成；PUT必填且保持不变" }, "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "target": { "type": "string", "format": "uri", "example": "https://pan.quark.cn/s/2495e46017e5" }, "enabled": { "type": "boolean", "description": "启停；请求应显式提供" }, "ownerId": { "type": "integer", "readOnly": true }, "origin": { "type": "string", "readOnly": true }, "created": { "type": "string", "readOnly": true }, "updated": { "type": "string", "readOnly": true } } } } } } } }, "/links/{code}": { "get": { "summary": "读取一条短链", "operationId": "get__links_code", "description": "所需权限：pan:link:list。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "$ref": "#/components/schemas/Link" } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "删除短链", "operationId": "delete__links_code", "description": "所需权限：pan:link:remove。保留访问统计和自动任务停用标记，避免访问后重新自动生成。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "nullable": true } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/resolve-jobs": { "post": { "summary": "提交自动准备任务", "operationId": "post__resolve-jobs", "description": "所需权限：pan:link:add。仅超级管理员ID1；同码去重。已手动绑定的短码直接返回当前状态，可能没有任务记录。文件先转存到专属文件夹并立即分享，分享就绪5分钟后审核；未通过或异常时复制公共300MB占位ZIP并在同一夸克直链中替换原文件。", "responses": { "200": { "description": "成功。任务提交不等于完成，需查询任务状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "state": { "type": "string" }, "shortUrl": { "type": "string" } } } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://pan.quark.cn/s/2495e46017e5", "description": "12位分享码，可附?pwd=提取码" } } } } } } }, "get": { "summary": "读取自动准备记录", "operationId": "get__resolve-jobs", "description": "所需权限：pan:link:list。仅超级管理员可查看全部自动任务；普通账号返回空数组。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/resolve-jobs/{code}": { "get": { "summary": "读取任务及审核结果", "operationId": "get__resolve-jobs_code", "description": "所需权限：pan:link:list。仅超级管理员ID1；建议2–5秒轮询，终态立即停止。没有任务返回404。", "responses": { "200": { "description": "成功。任务提交不等于完成，需查询任务状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "$ref": "#/components/schemas/Job" } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/resolve-jobs/{code}/retry": { "post": { "summary": "重试审核异常", "operationId": "post__resolve-jobs_code_retry", "description": "所需权限：pan:link:edit。仅超级管理员ID1，且仅用于旧流程audit_error任务；新后审任务失败时自动替换，不通过本接口放行。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "nullable": true } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/stats": { "get": { "summary": "读取访问统计", "operationId": "get__stats", "description": "所需权限：pan:stats:list。total包含views、opens、pc、mobile、unique；只返回当前账号有权访问的数据，不涉及收入。 返回全部链接汇总 links、标题 titles、逐链接逐完整转入URL的 entries（code/title/source/referrer/views/opens/unique/pc/mobile）。历史数据可能只有 source，浏览器未提供的URL不补造。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "object", "additionalProperties": true }, "links": { "type": "object", "additionalProperties": true }, "sources": { "type": "object", "additionalProperties": true }, "daily": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "UTC日期，含当日；可省略" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "UTC日期，含当日；可省略" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选，筛选某条短链接" } ] } }, "/export": { "get": { "summary": "导出访问CSV", "operationId": "get__export", "description": "所需权限：pan:stats:export。当前账号的数据范围；日期错误返回JSON。", "responses": { "200": { "description": "UTF-8带BOM的CSV", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效、过期或账号不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "不存在或不属于当前账号", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "短码冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流，等待后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "保存失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "UTC日期，含当日；可省略" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "UTC日期，含当日；可省略" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选，筛选某条短链接" } ] } } } }