# Unicode APIs
本组API提供思源码的相关支持,除校验接口外,其余接口仅对交我办开放。
- 使用本组API前请先阅读概述,使用前的准备工作请参考此处,令牌的获取参考此处,构造请求请参考此处,返回数据请参考此处,除非特殊注明,所有开放式API有着通用的返回结构。
- 每个API的授权方式、授权范围和是否API SDK支持请查看以下每个API详细的表述。
# 思源码校验
# 功能介绍
用于校验、解码思源码/多码合一二维码,一般为门禁系统使用
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
qrCode | String | 待校验的二维码内容 | 思源码内容包含不能在url上传递的字符,传递前必需进行url encode |
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- 校验结果 Structure
{
"type": {string}, // 输入的二维码类型: SJTU - 思源码; SJTUGREEN - 多码合一; UNKNOWN - 不支持的未知类型。
"account": {string}, // 码所属用户的账号,jAccount。
"identities": [{ // 码所属用户的身份信息。用户的所有关联身份,可能多条,不考虑有效期。
"code": {string}, // 身份Id(学工号)
"userType": {string} // 身份类型。参考Profile API中的身份类型定义。
"organize": { // 身份所在机构
"id": {string}, // 机构代码
"name": {string} // 机构名称
},
"topOrganize": { // 身份所在机构的顶级机构
"id": {string}, // 顶级机构代码
"name": {string} // 顶级机构名称
},
"expireDate": {string}, // 身份过期日期。yyyy-mm-dd格式
"status": {string}, // 教职工身份取值: 正常、退休、离职、过期、其他;学生身份取值: 正常、离校、过期;其他身份取值: 正常、过期
"default" {boolean} // 是否默认身份。true: 该身份是账号当前的默认身份
}],
"createTime": {long}, // 码的签发时间,unix时间戳,单位秒。
"expired": {boolean}, // 码是否已过期。调用方应该仅在expired为false时接受解码结果,但即使expired为false,调用方也可以根据createTime决定自己的过期政策。
"extensions": { // 码的扩展属性。扩展属性具体作用由特定的调用方解释
"reserved": {string}, // 保留属性,调用方无需关注
"color": {string} // 防疫控制标识:G - 绿色; Y - 黄色; R - 红色
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
注:校验接口使用通用结构中的errno、error返回校验失败的情况,包括:二维码不能识别、签名错误等。 在签名正确的情况下,由于签发时间导致的过期属于校验通过,但是如果过期时间过长(大于30分钟),返回的解码信息将仅包含码的明文中已包含的用户信息,对于思源码是account,对于多码合一则是身份Id(学工号)。
# 请求示例:请求校验思源码/多码合一
GET /v1/unicode?access_token={访问令牌}&qrCode=SJTU5061A03852gwang%7CMC0CFG7Z8%2FGTkzcKEIHnU7M1yXWnFnHCAhUA8tGxP0Rb7SXV9SBzWB9eirBEpjc%3D HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 不能识别码类型
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":-3,
"error":"无法识别的二维码",
"entities":[{
"type": "UNKNOWN"
}]
}
2
3
4
5
6
7
8
9
10
# 响应示例: 思源码签名不正确
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":-3,
"error":"思源码签名校验错误",
"entities":[{
"type": "SJTU"
}]
}
2
3
4
5
6
7
8
9
10
# 响应示例: 多码合一签名不正确
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":-3,
"error":"多码合一签名校验错误",
"entities":[{
"type": "SJTUGREEN"
}]
}
2
3
4
5
6
7
8
9
10
# 响应示例: 思源码校验通过但过期
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno": 0,
"entities":[{
"type": "SJTU",
"account": "gwang",
"createTime": 1658480452,
"expired": true
}]
}
2
3
4
5
6
7
8
9
10
11
12
# 响应示例: 多码合一校验通过但过期
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno": 0,
"entities":[{
"type": "SJTUGREEN",
"identities": [{
"code": "60803"
}],
"createTime": 1658480452,
"expired": true
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
# 响应示例: 校验通过未过期
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno": 0,
"entities":[{
"type": "SJTU",
"account": "gwang",
"identites": [{
"code": "60803",
"userType": "faculty",
"default": true
}]
"createTime": 1658480452,
"expired": false,
"extensions": {
"reserved": "0",
"color": "G"
}
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 开通思源码
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
identityOnly | boolean | 仅开通身份码 | 该参数为true时,开通无支付功能的思源码;为false或未指定时,开通全功能思源码,但用户必须已有校园卡或V卡 |
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
此接口无额外响应数据
# 请求示例: 开通全功能思源码
POST /v1/unicode?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 请求示例: 开通无支付功能思源码
POST /v1/unicode?identityOnly=true&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 开通成功
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success"
}
2
3
4
5
6
7
# 响应示例: 开通失败
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":-3,
"error":"用户无校园卡/V卡"
}
2
3
4
5
6
7
# 获取身份码、获取思源码开通状态
# 功能介绍
获取用户思源码开通状态、获取身份码。对于获取思源码开通状态的需求,使用授权码(Authorization Code)方式获取scope为card_info的令牌来访问。获取身份码仅对交我办App开放。
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
checkSupplier | boolean | 检查支付供应商 | 该参数为true时,返回支持的支付供应商,用于判断是否可以开通支付。 |
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- 身份码 Structure
{
"status": {int}, // -1: 未开通思源码;0: 已开通思源码(含支付);1: 已开通思源码(不含支付)
/***** 以下属性仅在提供了unicode授权令牌时返回,使用card_info授权令牌时,仅返回status属性 *****/
"suppliers":[{string}], // 校园卡(synjones)、V卡(weixiao)开通情况, 仅在指定了checkSupplier时返回
//以下属性仅在未指定 checkUpgrade 和 checkSupplier,但已经开通思源码时返回
"code": {string}, // 身份码
"ec": {string}, // 思源码显示使用的二维码纠错率,可能值:L、M、Q、H
"showIcon": {boolean}, // 思源码中是否显示图标
"backgroundColor": {string}, // 展码界面总体背景色,如"016AED"
"icon": {string}, // 标题栏图标。可为空,为空时不显示图标。
"message": {string}, // 标题栏显示的文字,如"尚未进行健康申报"。可为空,为空时不显示
"messageColor": {string}, // message和icon的显示颜色,如"000000"
"messageBackground": {string},// 标题栏背景颜色。
"slowIcon": {string}, // 身份码获取缓慢时的标题栏提示图标。缓存使用
"slowMessage": {string}, // 身份码获取缓慢时的标题栏提示的文字。缓存使用,为空时表示不用提示缓慢状态
"slowMessageColor": {string}, // slowMessage和slowIcon的显示颜色。
"slowMessageBackground": {string},// 身份码获取缓慢时的标题栏提示背景颜色。
"action": {string}, // 标题栏显示的操作按钮文字,如"去申报"。可为空,为空时不显示
"actionColor": {string}, // action的显示颜色,如"000000"
"actionUrl": {string} // 标题栏点击时开打的Url。可为空,为空时标题栏不响应点击操作
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
注:icon、message、action都为空时,不显示标题栏
# 请求示例: 查询是否可以开通支付
GET /v1/unicode/identity?checkSupplier=true&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 思源码当前未开通,但可以开通支付
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": -1,
"suppliers": ["weixiao"]
}]
}
2
3
4
5
6
7
8
9
10
11
# 响应示例: 思源码当前未开通,且不能开通支付
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": -1,
"suppliers": []
}]
}
2
3
4
5
6
7
8
9
10
11
# 响应示例: 思源码当前已开通,未开通支付,但可以开通支付
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 1,
"suppliers": ["weixiao"]
}]
}
2
3
4
5
6
7
8
9
10
11
# 响应示例: 思源码当前已开通,未开通支付,且不可以开通支付
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 1,
"suppliers": []
}]
}
2
3
4
5
6
7
8
9
10
11
# 请求示例: 获取身份码
GET /v1/unicode/identity&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 未开通思源码
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": -1
}]
}
2
3
4
5
6
7
8
9
10
# 响应示例: 思源码已开通,但未开通支付,存在额外操作
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 1,
"code": "SJTU5061A03852gwang|MC0CFG7Z8/GTkzcKEIHnU7M1yXWnFnHCAhUA8tGxP0Rb7SXV9SBzWB9eirBEpjc=",
"backgroundColor": "016AED",
"icon": "warn",
"message": "尚未进行健康申报",
"messageColor": "000000",
"action": "去申报",
"actionColor": "000000",
"actionUrl": "https://pass.sjtu.edu.cn/.........."
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 响应示例: 思源码已开通,含支付,不存在额外操作
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 0,
"code": "SJTU5061A03852gwang|MC0CFG7Z8/GTkzcKEIHnU7M1yXWnFnHCAhUA8tGxP0Rb7SXV9SBzWB9eirBEpjc=",
"color": "00000FF"
}]
}
2
3
4
5
6
7
8
9
10
11
12
# 获取运营位信息
# 请求参数
该接口除了访问令牌,无其他参数
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- 运营位信息 Structure
{
"status": {int}, // 0: 成功
"message": {string}, // 运营位显示的文字。当运营位背景图片不存在时提供
"messageColor": {string}, // 运营位文字的显示颜色,如"000000"。当运营位背景图片不存在时提供
"messageBackground": {string},// 运营位背景图片。可为空,为空时显示运营文字
"actionUrl": {string} // 运营位点击时开打的Url。可为空,为空时运营位不响应点击操作
}
2
3
4
5
6
7
# 请求示例:查询运营位信息
GET /v1/unicode/identity/advertising?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 无运营信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[]
}
2
3
4
5
6
7
8
# 响应示例: 获取到运营信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status":0,
"messageBackground":"https://api.sjtu.edu.cn/v1/file/xxxxxxxxxxxx",
"actionUrl":"https://net.sjtu.edu.cn"
}]
}
2
3
4
5
6
7
8
9
10
11
12
# 获取支付码
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
supplier | string | 支付供应商 | boc: 中国银行, weixiao: V卡, wallet: 钱包 |
userCode | string | 用户学工号 | 必须和access_token所属用户具有关联性 |
offline | boolean | 是否同时获取离线码 | 如果支付供应商支持,同时获取离线码 |
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- 支付码 Structure
{
"status": {int}, // -1: 思源码未开通, 0: 正常, 1: 未开通思源码支付, 2: 开通但暂时不能展码, 3: 开通但获取异常, 4:开通但当前禁止消费
"code": {string}, // 支付码,仅在status为0时提供
"offlineCodes": [{string}], // 离线支付码,仅在指定了offline=true,且支付供应商支持时返回
"offlineCodesExp": {int}, // 离线支付码有效期。unix时间戳,单位秒
"balance": {float}, // 钱包余额,单位元。仅查询钱包渠道时返回
"message": {string}, // "未开通" 或者不能展码的原因
"newMessage": {string}, // 同message,供新版交我办使用
"action": {string}, // 打开actionUrl链接的按钮建议的提示文字(如果UI设计显示该按钮的话)
"actionUrl": {string} // 处理不能展码需要打开的链接
}
2
3
4
5
6
7
8
9
10
11
# 请求示例
GET /v1/unicode/pay?supplier=boc&userCode=12345&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例: 正常返回
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 0,
"code": FnHCAhUA8tGxP0Rb7SXV9SBzWB9eirBEpFnHCAhUA8tGxPFnHCAhUA8tGxPasdd22Hjc="
}]
}
2
3
4
5
6
7
8
9
10
11
# 响应示例: 不支持支付码
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 1
}]
}
2
3
4
5
6
7
8
9
10
# 响应示例: 思源码开通,但中行未开通支付,返回开通链接(http)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 2,
"message": "尚未绑定银行卡",
"action": "立即绑定",
"actionUrl": "https://e.boc.cn/ezcs-qrcode"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
# 响应示例: 思源码开通,但V卡未开通,返回开通链接(小程序)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"entities":[{
"status": 2,
"message": "尚未开通V卡",
"action": "立即开通",
"actionUrl": "miniProgram://gh_c16ce1eeeb10"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
# 响应示例: 思源码开通,但V卡未签约,返回签约链接(小程序)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"total":0,
"entities":[{
"status": 2,
"message": "微信支付未签约",
"action": "立即签约",
"actionUrl": "miniProgram://gh_c16ce1eeeb10/pages/sign_package/pages/openSign/openSign?token=xxxxxx"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
# 获取支付码对接参数
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
userCode | string | 用户学工号 | 必须和access_token所属用户具有关联性 |
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- 思源码支付码对接参数 Structure
{
"synjones": { // 校园卡的对接参数
"available": {string}, // 是否启用 true/false
"name": {string}, // 支付渠道名称
"index":{integer}, // 支付渠道排序号
"appId": {string}, // 开发者appId
"serverUrl": {string}, // 服务器地址
"socketUrl": {string}, // websocket地址用于监听联机码支付状态
"userToken": {string} // 用户令牌
},
"boc": { // 中行对接参数
"available": {string}, // 是否启用 true/false
"name": {string}, // 支付渠道名称
"index":{integer}, // 支付渠道排序号
"cardManageUrl":{string}// 卡管理入口地址
},
"weixiao": { // V卡对接参数
"available": {string}, // 是否启用 true/false
"name": {string}, // 支付渠道名称
"index":{integer}, // 支付渠道排序号
},
"wallet": { // 钱包对接参数
"available": {string}, // 是否启用 true/false
"name": {string}, // 支付渠道名称
"index":{integer}, // 支付渠道排序号
"balance": {float}, // 钱包余额,单位元。
"transfer":{boolean} // 是否允许校园卡向钱包充值。
"*": { // 全局参数
"orderStatus": [ // 可筛选的交易记录状态
"待扣费",
"已完成",
"待补缴",
"已退费",
"已关单"
],
"orderChannels": [ // 可筛选的支付渠道名称
"思源码钱包",
"微信支付",
"中国银行"
]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# 请求示例
GET /v1/unicode/parameters?supplier=synjones&supplier=boc&supplier=weixiao&supplier=wallet&userCode=12345&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno":0,
"error":"success",
"total":0,
"entities":[{
"synjones": {
"availiable": "true",
"name": "校园卡",
"appId": "sdk_app_id",
"serverUrl": "https://ecard.sjtu.edu.cn",
"socketUrl": "wss://ecard.sjtu.edu.cn",
"userToken": "eyJ0eXAiOiJKc29uV2ViVG9rZW4iLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJpc3N1c2VyIiwiYXVkIjoiYXVkaWVuY2UiLCJzbm8iOiIyMzE4NyIsIm5hbWUiOiLmnY7mmZPmnbAiLCJpZCI6MjQwLCJsb2dpbkZyb20iOiJlcSIsInV1aWQiOiI3MGEwMGNiNDk3YmI4MTY1MDEwMGYwMDI1YTU1OWVlOSIsImFjY291bnQiOiIyMzE4NyIsImV4cCI6MTYzNzY5MzUwMCwibmJmIjoxNjM3NjM0NTYxfQ.A2cAEO6i0FIpjR4492v4MXWS0K8feOsw8fqvqE7Nbb8"
},
"boc": {
"availiable": "false",
"name": "中国银行",
"cardManageUrl": "https://101.231.206.171/ezcs-qrcode";
},
"weixiao": {
"availiable": "true",
"name": "微信"
},
"wallet": {
"availiable": "true",
"name": "钱包",
"balance": 0
}
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 查询交易记录
- GET https://api.sjtu.edu.cn/v1/unicode/transactions 授权码 card_transactions
# 功能介绍
查询思源码(含V卡小程序)相关的交易记录,使用授权码(Authorization Code)方式获取scope为card_transactions的令牌即可访问。
# 请求参数
参数名 | 类型 | 描述 | 备注 |
---|---|---|---|
beginDate | long | 查询起始时间 | unix时间戳(单位秒),不指定时表示不限制起始时间。 |
endDate | long | 查询结束时间 | unix时间戳(单位秒),不指定时表示不限制结束时间。 |
start | int | 起始序号 | 分页参数,指定返回数据的起始序号,从0开始。如果指定了大于0的值,必须同时指定limit,并且为limit的整数倍 |
limit | int | 分页大小 | 分页参数,指定返回数据的条数,0-100,0表示不分页。不分页时必须指定beginDate |
status | string | 交易状态 | 指定此参数时仅返回指定状态的交易记录 |
channel | string | 支付渠道 | 指定此参数时仅返回指定渠道的交易记录 |
注: beginDate和endDate所指时间为交易发生时间。
# 响应参数
所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。
- Transaction 交易记录 Structure
{
"orderNo":{string}, // 交易单号。
"orderTime":{long}, // 交易发生时间,unix时间戳,秒。
"payTime":{long}, // 交易扣费时间,unix时间戳,秒。该笔交易已完成扣费时提供。
"refundTime":{long}, // 交易退费时间,unix时间戳,秒。该笔交易已退费时提供。
"merchantNo":{string}, // 商户号。
"merchant":{string}, // 商户名称。
"deviceNo":{string}, // 交易设备号。
"amount":{double}, // 交易金额,单位元。
"origAmount":{double}, // 交易原价金额。仅在交易金额和原价存在差价时提供。
"origName":{string}, // 交易原价显示名称。仅在交易金额和原价存在差价时提供。
"diffAmount":{double}, // 交易差价金额。仅在交易金额和原价存在差价时提供。
"diffName":{string}, // 交易差价显示名称。仅在交易金额和原价存在差价时提供。
"status":{string}, // 交易状态。可能值:待扣费、已完成、待补缴、已退费、已关单。
"channel":{string} // 支付渠道。
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 请求示例
GET /v1/unicode/transactions?access_token=token&start=0&limit=20 HTTP/1.1
Host: api.sjtu.edu.cn
2
# 响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"errno": 0,
"error": "success",
"total": 0,
"entities":
[
{
"orderTime": 1683863228,
"payTime": 1683863232,
"merchant": "广式烧腊饭",
"amount": -16.00,
"status": "已完成",
"channel": "微信支付"
},
{
"orderTime": 1683776458,
"payTime": 1683776460,
"merchant": "大众餐厅",
"amount": -0.02,
"status": "已完成",
"channel": "思源码钱包"
},
{
"orderTime": 1683776458,
"payTime": 1683776463,
"merchant": "大众餐厅",
"amount": -12.64,
"status": "已完成",
"channel": "微信支付"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35