Notanote 开放平台

外观

API 约定与规范 ​

本页描述 Notanote API 的通用约定，包括接口基础信息、请求格式、响应格式和标识符（Identifier）命名规则。所有第三方接口均遵循本规范。

基础信息 ​

项目说明
接口域名https://api.notanote.cn
协议HTTPS（不兼容 HTTP）
请求方法POST
数据格式JSON
字符编码UTF-8

请求规范 ​

Method ​

全部接口使用 POST 方法，我们拒绝使用 RESTful API 接口规范，即使是只读查询接口也统一走 POST，不接受 PUT、DELETE 等其他非常规方法。

Headers ​

Content-Type: application/json

如果你的请求体中包含中文或特殊字符，请确保 Content-Type 同时声明字符编码：

Content-Type: application/json; charset=utf-8

请求体 ​

所有参数通过 URL query 或 form-data 请求，不使用 JSON Body。请求体必须是一个合法的 Form 对象。

请求示例：

http
POST /webauth/get-session HTTP/1.1
Host: api.notanote.cn
Content-Type: application/json

tid: 1001
secretkey: your-secret-key
scope: access_token

响应规范 ​

成功响应 ​

json
{
  "Status": true,
  "Response": {
    "Identifier": "nano.api.v2.模块.操作.succeed",
    "Data": { }
  }
}
字段类型说明
Statusbooleantrue 表示业务处理成功
Identifierstring字符串标识，描述「哪个模块的哪个操作成功了」
Dataobject业务数据，结构因接口而异。无数据时可能为空对象 {}

失败响应 ​

json
{
  "Status": false,
  "Response": {
    "Identifier": "nano.api.v2.模块.操作.failed.原因"
  }
}

失败时 Status 为 false，Identifier 末尾包含失败原因。不会附带 Data 字段。

示例：

json
{
  "Status": false,
  "Response": {
    "Identifier": "nano.api.v2.webauth.get-session.failed.TIDVerifyFailed"
  }
}

Identifier 命名规则 ​

nano.api.v2.{模块}.{操作}.{状态}.{原因}
段位说明示例
v2API 版本号v2
模块业务模块，如 webauth、third-partywebauth
操作具体接口操作，如 get-session、save.pullget-session
状态succeed 或 failedfailed
原因仅失败时出现，描述具体失败原因TIDVerifyFailed

全局错误 ​

跨模块的通用错误，所有接口均可能返回。

Identifier说明处理建议
nano.api.v2.global.nodeIsUnavailable功能模块未启用联系 contact@notanote.cn 解决

错误处理建议 ​

1. 以 Identifier 为准 ​

不要依赖 HTTP 状态码做业务判断。Notanote 接口除网络异常外始终返回 HTTP 200，所有业务结果都通过 Status 字段和 Identifier 字段表达。

js
const data = await fetch(url, options).then(r => r.json());

if (data.Status === true) {
  // 业务成功
} else {
  // 业务失败，根据 Identifier 处理
  const identifier = data.Response?.Identifier ?? 'unknown';
  // ...
}

2. serverError 类错误 ​

serverError 通常为服务端临时故障：

  • 可间隔 1-3 秒后重试
  • 重试 3 次仍失败，应中断流程并向用户提示

3. 错误码查阅 ​

各接口的具体错误码已随接口文档列出，请参阅对应的 API 参考页面：