API 总览

Notanote 第三方 API 目前提供以下接口。所有接口的通用约定（请求格式、响应格式、错误处理等）请参阅 API 约定与规范。

接口列表

WebAuth 鉴权

接口	说明	调用方
POST /webauth/get-session	换取临时授权会话	你的服务端

详细说明见 鉴权机制。

第三方存档

接口	说明	调用方
POST /third-party/save/get	获取存档元信息	你的服务端
POST /third-party/save/pull	拉取存档下载链接	你的服务端

详细说明见 第三方存档读取。

用户资料

接口	说明	调用方
POST /third-party/user/profile	获取用户公开资料	任意客户端/服务端

详细说明见 用户资料查询。

快速导航

• 约定与规范 — 请求/响应格式、Identifier 规则、错误处理

• 鉴权机制 — WebAuth 网页授权完整流程

• 第三方存档 — 存档查询与下载接口

• 用户资料 — 用户公开资料查询

• 模块：业务模块名（如 webauth、third-party）

• 操作：具体接口名（如 get-session、save/pull）

• 状态：succeed 或 failed

• 原因：仅在失败时出现，描述失败原因

示例：

Identifier	含义
nano.api.v2.webauth.get-session.succeed	WebAuth 模块 get-session 操作成功
nano.api.v2.webauth.get-session.failed.TIDVerifyFailed	WebAuth 模块 get-session 失败，原因是 TID 校验不通过
nano.api.v2.webauth.authorize.failed.invalidSession	WebAuth 模块 authorize 失败，原因是会话无效

判断结果以 Identifier 为准

调用方应以 Identifier 为准判断结果，不要依赖 HTTP 状态码。除网络异常外，Notanote 接口始终返回 HTTP 200。

常见 Identifier 前缀

前缀	模块	说明
nano.api.v2.webauth.*	网页授权	换取会话、玩家授权等流程
nano.api.v2.third-party.*	第三方接口	存档查询、存档下载等业务接口
nano.api.v2.third-party.user.*	用户资料	用户公开资料查询
nano.api.v2.global.*	全局错误	跨模块的通用错误（如模块未启用）

通用错误码及处理建议见 约定与规范，各接口的错误码见对应接口文档。

调用最佳实践

1. 以 Identifier 判断业务结果

不要依赖 HTTP 状态码做业务判断。正确的判断流程：

const data = await fetch(apiUrl, { ... }).then(r => r.json());

if (data.Status === true) {
  // 业务成功，使用 data.Response.Data
} else {
  // 业务失败，根据 Identifier 处理
  const identifier = data.Response.Identifier;
  switch (identifier) {
    case 'nano.api.v2.webauth.get-session.failed.TIDVerifyFailed':
      // 凭证错误
      break;
    case 'nano.api.v2.webauth.get-session.failed.serverError':
      // 服务端故障，可重试
      break;
    // ...
  }
}

2. 网络异常与业务异常分开处理

• 网络异常：fetch 抛出的 Error、HTTP 非 200 响应、连接超时等
• 业务异常：Status: false 的响应，由 Identifier 描述原因

try {
  const res = await fetch(...);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  if (!data.Status) {
    // 业务异常
    throw new Error(`业务错误: ${data.Response.Identifier}`);
  }
  // 成功
} catch (err) {
  // 网络异常或业务异常
  console.error(err.message);
}

3. 重试策略

• serverError 类错误通常为服务端临时故障，可间隔重试
• invalidSession 类错误表示会话过期，需要重新发起流程，不要重试
• TIDVerifyFailed 等参数错误不会因重试而成功，不要重试