Open API

Open API

项	值
平台	api.sjtu.edu.cn
认证	OAuth 2.0（Authorization Code / Client Credentials 等）+ scope
数据方向	读 + 写，按 scope 和接口
难度	高（需要单位/教职工申请 clientId）
最后验证	2026-10-25
证据等级	B（官方文档；未逐接口实测）

Open API 是交大官方开放平台，覆盖身份、组织、教学、邮件、文件、通知、校园卡、财务、日历、条码和电子签章等能力。正式应用优先使用这一层；个人开发者最常卡在 clientId 申请。

要点

• Base URL：https://api.sjtu.edu.cn/v1
• 认证：OAuth 2.0，使用 Authorization: Bearer <access_token>；也支持查询参数或请求体中的 access_token。
• 可获取：取决于 scope 和接口，包括 Profile、Enterprise、Education、Task、Mail、File、Notification、Finance、Card、Unicode、Barcode、Calendar、Signature。
• 注意：没有 clientId 就无法调用；部分接口文档已列出但尚未实现（考试、GPA）；分页和错误结构与常规 REST 不同。

---

1. 认证

Token

GET /v1/me/profile HTTP/1.1
Host: api.sjtu.edu.cn
Authorization: Bearer <access_token>

也支持：

GET /v1/me/profile?access_token=<token>

官方说 query/body 用 access_token，header 用 Authorization: Bearer。[官方]

授权方式

• Authorization Code：用户登录授权，适合读本人数据。
• Client Credentials：应用身份，适合与用户无关的数据；只有接口明确支持时才用。
• Resource Owner Password：官方仍列，但不推荐；不要把用户密码交给应用。

scope

Open API 的 scope 与 jAccount OAuth 共用一套注册表（见 jAccount 与校园会话）。常见：

scope	用途
basic / essential / profile	身份、姓名、学工号、院系、联系方式
lessons	课程信息、教学班
classes	课表
exams / scores	考试/成绩（注意「尚未实现」）
read_mails / send_mail	邮件
tasks	待办、流程
card_info / card_transactions	校园卡
notifications	通知
calendar	日程

申请时按接口页面的标签勾选；不要一次申请全部。

---

2. API 分组

组	主要能力	典型 scope	备注
Profile	本人资料、身份、组织、头像	basic/essential/profile/privacy	字段随 scope 变化
Enterprise	组织、岗位、权限、校历	岗位/权限相关	高权限项需审批
Education	教学班、学生课表、考试、绩点	lessons/classes/exams/scores	考试/GPA 文档标注「尚未实现」
Task	InfoPlus 流程、第三方任务更新	tasks	与 InfoPlus 有演进关系
Mail	邮件读取、发送、状态	read_mails/send_mail	也可走 IMAP/SMTP
File	上传、下载、元数据、缩略图、WPS 链接	storage 等	适合附件层
Notification	发通知、查状态、改状态	send_notification 等	短信/邮件/交我办渠道需单独准入
Finance	财务预约、查询、撤销、完成标记	业务权限	业务级，个人通常拿不到
Campus Card	卡信息、交易、充值/卡务	card_info/card_transactions/write_card_info	写操作高风险
Unicode	思源码校验、身份码、支付码	unicode	支付码是临时凭据
Barcode	条码/二维码图像	部分无需认证	辅助能力
Calendar	校园日程创建/删除	calendar	偏教职工/线下申请
Signature	PDF 电子签章	signature	高权限，默认禁用

代表端点

只列官方页面明确写出的代表端点；完整列表以官方接口列表为准。

组	Method	Path	认证/scope	说明
Profile	GET	/v1/me/profile	用户 Token；basic/essential/profile/privacy	本人资料；字段随 scope 变
Enterprise	GET	/v1/enterprise/user/positions	用户 Token	本人岗位/身份（post、dept 三元组）
Enterprise	GET	/v1/enterprise/user/rights	用户/客户端 Token	本人在应用中的权限；account 可选
Enterprise	GET	/v1/enterprise/organizes	无需令牌	学校组织机构树，约 932 个节点
Enterprise	GET	/v1/enterprise/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD	无需令牌	校历：工作日/节假日/周末/寒假/暑假
Enterprise	GET	/v1/enterprise/position/{dept:post:biz}/users	客户端 basic	按部门/岗位/业务查用户；不能查身份岗
Enterprise	PUT/DELETE	/v1/enterprise/position/{dept:post}/users?code={account}	授权码 profile	给岗位加/删用户；需要有管理权限
Education	GET	/v1/lesson/{code|bsid}	授权码 lessons	教学班信息 + 排课
Education	GET	/v1/me/lessons[/{term}]	授权码 lessons	本人学期课程；term 如 2026-2027-1
Mail	GET	/v1/mails/{unread|read}?pageToken=	授权码 read_mails	最多 100 条/页；pageToken 翻页
Mail	PUT	/v1/mail	授权码 send_mail	发邮件；body 含 to/name/contentType/content
Mail	POST	/v1/mail/{mailId}	授权码 send_mail	只改 status（read/unread）

---

3. 通用请求与响应

请求

• RESTful；动词 GET/PUT/POST/DELETE。
• Content-Type 默认 application/json。
• URL 和参数大小写敏感。
• 命名用 camelCase（access_token 除外）。
• 时间类型用 Unix 秒。
• 对象 id 用 GUID；kind 标识对象类型；uri 是 Web 地址。

响应

{
  "errno": 0,
  "error": "success",
  "total": 0,
  "nextToken": "3A4bz-e",
  "entities": [{ "id": "...", "kind": "canvas.profile" }]
}

• errno: 0 成功；非 0 是业务错误。
• entities 是数组；单条也在 entities[0]。
• total 是总数；分页时用。
• nextToken 是下一页 token。

分页

• limit：每页条数，默认 100。
• start：起始索引；和 pageToken 二选一，同时给时忽略 pageToken。
• pageToken：上一页返回的 nextToken。
• 没有 nextToken 就是最后一页。

curl 'https://api.sjtu.edu.cn/v1/me/circles?pageToken=3A4bz-e&limit=5' \
  -H "Authorization: Bearer $TOKEN"

错误

HTTP	含义	处理
400	参数错误	修参数
403	鉴权失败/scope 不足	看 body errno；不要重试
404	URL/资源不存在	检查路径
405	方法不允许	检查 method
500/503	服务端错误	重试一次

403 常见 body：

{ "errno": 10002, "error": "认证失败", "total": 0 }

错误码：10002 认证失败、10007 令牌过期、10010 scope 失败。[官方]

---

4. Education：文档写了但没实现

官方 Education 页面明确标注：

• GET /v1/me/examinations[/{term}]：此 API 尚未实现。
• GET /v1/gpa：此 API 尚未实现。

能用的主要是：

• GET /v1/lesson/{code|bsid}：教学班信息（课程、教师、院系、学分、排课）。
• GET /v1/me/lessons[/{term}]：本人学期课程。

lessons 的排课字段是 week（0–17）、day（0–6，0=周一）、period（0–17，0=第一节）、last、start/finish（Unix 秒，校历不完整时可能没有）。[官方]

Warning

不要因为 scope 名叫 exams/scores 就假设接口可用。文档本身写了「尚未实现」；调用前先确认当前实现状态。

---

5. 申请

1. 登录 my.sjtu.edu.cn 或交我办。
2. 服务大厅 → 信息服务 → 其他 → jAccount 接口申请。
3. 填应用名称、用途、部署地址、回调地址、需要的 scope。
4. 部门领导审批 → 网络信息中心处理（约 3 个工作日）。
5. 拿到 appId（如 japortal000000）和 48 字符 appSecret。
6. 增加 scope：发邮件给 gwang@sjtu.edu.cn，附 appId 和新增 scope 代码。[官方]

服务对象写的是部门、教职工。学生个人通常拿不到；需要老师/实验室/社团/院系挂靠。

---

6. 常见问题

1. 没有 clientId 就无从开始：先确认你能不能拿到，再设计功能。
2. scope 需要逐项确认：每个接口支持的授权方式不同；有的只支持 Authorization Code，有的支持 Client Credentials。
3. 文档列出不等于已经实现：考试、GPA 明确标注「尚未实现」。
4. 错误信息在 errno 中：HTTP 200 也可能是业务错误。
5. 分页使用 limit、start 或 pageToken：没有 page 参数。
6. 时间戳单位为秒：不使用毫秒。
7. URL/参数大小写敏感：access_token、pageToken 别写错。
8. /v1/profile/{account} 不对外开放：只能读本人。
9. Token 放 query 会进日志：优先 Authorization 头。
10. clientSecret 不进前端：授权码换 Token 在后端做。

---

7. 最小示例

# 1. 用授权码换 Token（后端）
curl -X POST 'https://jaccount.sjtu.edu.cn/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "redirect_uri=$REDIRECT_URI" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

# 2. 读本人 Profile
curl 'https://api.sjtu.edu.cn/v1/me/profile' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. 读本人课表
curl 'https://api.sjtu.edu.cn/v1/me/lessons/2026-2027-1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

---

8. 证据与来源

• 总体设计、请求/响应、分页、错误码：[官方 2026-10-25，developer.sjtu.edu.cn/api/overview.html]
• OAuth/scope：[官方] developer.sjtu.edu.cn/auth/oauth.html
• Profile 字段/scope：[官方] developer.sjtu.edu.cn/api/profile.html
• Education 端点与「尚未实现」：[官方] developer.sjtu.edu.cn/api/education.html
• Enterprise 代表端点（positions/rights/organizes/calendar/position users）：[官方 2026-10-25，developer.sjtu.edu.cn/api/enterprise.html]
• Mail 代表端点（mails/mail/status）：[官方 2026-10-25，developer.sjtu.edu.cn/api/mail.html]
• 申请流程/服务对象：[官方] net.sjtu.edu.cn/wlfw/jAccountjk.htm

变更记录

• 2026-10-25：首版。补分页、错误码、Education 未实现项、申请现实。