云盘管家API DOCUMENTATION
生产可用 · HTTPS · 租户隔离

云盘管家 API v1

用一套受控接口读取自己的夸克、百度和迅雷网盘账号，搜索文件索引，并从外部分享链接中精确转存一个文件或指定项目。

5 分钟接入 OpenAPI JSON
基础地址 https://wp.ypsoso.com/api/v1 认证方式 Authorization: Bearer wpk_... 数据范围 仅当前密钥所属用户
密钥只能放在服务端。 不要写入浏览器、小程序、桌面安装包、Git 仓库、URL 或日志。明文只显示一次。
01

快速调用

在“账户设置 → API 访问”创建最小权限密钥，再通过环境变量使用。

终端读取当前身份
export WP_API_KEY='wpk_...'

curl --fail-with-body \
  --url 'https://wp.ypsoso.com/api/v1/me' \
  --header "Authorization: Bearer ${WP_API_KEY}" \
  --header 'Accept: application/json'
1. 创建密钥

设置名称、有效期和 Scope；明文立刻保存。

2. 读取账号

调用 GET /accounts 取得自己的 accountId。

3. 解析并转存

先 probe，明确 selectedIds，再提交幂等转存。

02

认证与安全边界

所有鉴权都在服务端执行，客户端不能通过传参扩大数据范围。

摘要存储

API 密钥只保存 SHA-256 摘要，无法从数据库恢复明文。

租户隔离

accountId、taskId、probeId 都校验 owner；管理员密钥也不能操作其他用户。

到期与撤销

密钥到期、撤销、用户停用或套餐失效后立即拒绝认证。

危险操作隔离

删除账号、批量删除、备份导出等高风险页面接口不接受 API 密钥。

03

权限与限流

按业务选择最少的 Scope；额度按密钥和来源 IP 分开计算。

Scope允许能力稳定接口
accounts:read查看自己的网盘账号GET /accounts
files:read浏览、索引搜索、解析链接GET /files、/search；POST /share-links/probe
transfer:write提交精确转存POST /transfers
tasks:read查询自己的任务GET /tasks/{id}
files:write预留文件写入能力以 OpenAPI 发布版本为准
shares:write预留分享写入能力以 OpenAPI 发布版本为准
默认额度：VIP 60 次/分钟，SVIP 300 次/分钟。最终值以 GET /me 返回为准。
04

稳定接口

v1 路径保持兼容；新增响应字段时，调用方应当忽略未知字段。

GET

/me

无需额外 Scope

返回当前密钥所属用户、角色、有效权限、套餐与限流配置。

{
  "id": 12,
  "username": "example",
  "role": "user",
  "authentication": "api_key",
  "scopes": ["accounts:read", "files:read"],
  "plan": { "code": "basic", "name": "VIP", "apiRateLimit": 60 }
}
GET

/accounts

accounts:read

列出密钥所属用户自己的网盘账号。平台值为 quark、baidu 或 xunlei。

{
  "accounts": [{
    "id": 3,
    "platform": "baidu",
    "accountName": "示例账号",
    "status": "valid",
    "capacityText": "28.7 GB / 5.00 TB",
    "usedPercent": 0.6,
    "rootFileCount": 6
  }]
}
GET

/files

files:read

accountId 必填；dir 是目录 ID 或路径；refresh=true 会跳过缓存，应谨慎使用。

GET /api/v1/files?accountId=3&dir=%2F%E8%B5%84%E6%96%99

{
  "current": { "id": "/资料", "path": "/资料" },
  "rows": [
    { "id": "123", "name": "子目录", "isDir": true, "size": 0 }
  ],
  "cache": { "state": "fresh", "revalidating": false }
}
POST

/share-links/probe

files:read

解析分享链接并返回 20 分钟有效的 probeId。可以从多层目录中只选择一个文件。

{
  "accountId": 3,
  "url": "https://pan.baidu.com/s/example",
  "code": "1234"
}

{
  "probeId": "261466df-2065-4862-9983-0d55c30f976f",
  "platform": "baidu",
  "count": 3,
  "rows": [{ "id": "file-id", "name": "单个文件.mp4", "isDir": false }]
}
POST

/transfers

transfer:write

只转存 selectedIds 中明确选择的项目。必须提供至少 8 位的 Idempotency-Key，相同响应保存 24 小时。

POST /api/v1/transfers
Idempotency-Key: 019fa7b1-c8a4-7c81-b972-2bf37e72a56b

{
  "accountId": 3,
  "probeId": "261466df-2065-4862-9983-0d55c30f976f",
  "selectedIds": ["file-id"],
  "destination": "/我的资源",
  "conflictStrategy": "rename",
  "rightsConfirmed": true
}
权利确认：rightsConfirmed 必须为 true，表示调用方已获得保存和使用所选内容的权利。
GET

/tasks/{taskId}

tasks:read

查询任务状态。常见状态为 waiting、running、paused、completed、failed、cancelled。

{
  "task": {
    "id": "7e815e58-2f75-4c07-813b-adcf18727525",
    "type": "transfer",
    "status": "completed",
    "progress": 100,
    "request": { "destination": "/我的资源", "selectedCount": 1 },
    "error": ""
  }
}
05

签名回调

任务完成或失败后，系统向公网 HTTPS 地址发送 HMAC-SHA256 签名事件。

1保留原始请求体

验签前不要重新序列化 JSON。

2检查 5 分钟时间窗

拒绝过旧时间戳，降低重放风险。

3常量时间验签

比较 sha256= + HMAC 十六进制。

4事件去重

按事件 ID 或 X-WP-Delivery 保存至少 24 小时。

const expected = `sha256=${createHmac('sha256', secret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex')}`;

const valid = expected.length === signature.length
  && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

请求头：X-WP-Event-Timestamp、X-WP-Signature、X-WP-Delivery。当前投递超时 12 秒；非 2xx 记为失败。

06

错误与重试

只对明确可重试的错误使用指数退避，避免放大网盘限流。

状态处理方式
400修正参数、目录、确认项或幂等密钥，不自动重试。
401立即停止，检查密钥或重新授权网盘账号。
403检查套餐、Scope 和接口白名单，不自动重试。
404资源不存在或不属于当前用户，不自动重试。
409按错误码处理幂等或任务状态冲突。
429读取 X-RateLimit-Reset，加入随机抖动后重试。
502 / 503仅当 retryable=true 时指数退避，设置最大重试次数。
07

上线检查清单

完成以下项目后再接入正式业务。

  • 使用独立、最小权限、90–180 天有效的生产密钥。
  • 密钥只存服务器环境变量或专用 Secret Manager。
  • 生产与测试使用不同 API 密钥和回调密钥。
  • 为所有写入生成 UUID 幂等键，并持久化业务操作与幂等键映射。
  • 对 401 告警，对 429 和可重试 5xx 做有上限的指数退避。
  • 回调校验时间戳、原始请求体签名和事件去重。
  • 轮换时先双密钥灰度，确认新密钥稳定后撤销旧密钥。
  • 定期检查最后使用时间和来源 IP，异常时立即撤销。