上海交通大学开发者平台

# Unicode APIs

本组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 - 红色
    }
}
1
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
1
2

# 响应示例: 不能识别码类型

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":-3,
    "error":"无法识别的二维码",
    "entities":[{
        "type": "UNKNOWN"
    }]
}
1
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"
    }]
}
1
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"
    }]
}
1
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
    }]
}
1
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
    }]
}
1
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"
        }
    }]
}
1
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
1
2

# 请求示例: 开通无支付功能思源码

POST /v1/unicode?identityOnly=true&access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例: 开通成功

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success"
}
1
2
3
4
5
6
7

# 响应示例: 开通失败

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":-3,
    "error":"用户无校园卡/V卡"
}
1
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。可为空，为空时标题栏不响应点击操作
}
1
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
1
2

# 响应示例: 思源码当前未开通，但可以开通支付

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "entities":[{
        "status": -1,
        "suppliers": ["weixiao"]
    }]
}
1
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": []
    }]
}
1
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"]
    }]
}
1
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": []
    }]
}
1
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
1
2

# 响应示例: 未开通思源码

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "entities":[{
         "status": -1
    }]
}
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/.........."
    }]
}
1
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"
    }]
}
1
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。可为空，为空时运营位不响应点击操作
}
1
2
3
4
5
6
7

# 请求示例：查询运营位信息

GET /v1/unicode/identity/advertising?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例: 无运营信息

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "entities":[]
}
1
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"
    }]
}
1
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}       // 处理不能展码需要打开的链接
}
1
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
1
2

# 响应示例: 正常返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "entities":[{
        "status": 0,
        "code": FnHCAhUA8tGxP0Rb7SXV9SBzWB9eirBEpFnHCAhUA8tGxPFnHCAhUA8tGxPasdd22Hjc="
    }]
}
1
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
    }]
}
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"
    }]
}
1
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"
    }]
}
1
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"
    }]
}
1
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": [      // 可筛选的支付渠道名称
        "思源码钱包",
        "微信支付",
        "中国银行"
      ]
    }
}
1
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
1
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
        }
    }]
}
1
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

# 查询交易记录

# 功能介绍

查询思源码（含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}           // 支付渠道。
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 请求示例


示例 请求最近20条交易记录
GET /v1/unicode/transactions?access_token=token&start=0&limit=20 HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 请求最近20条交易记录
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": "微信支付"
        }
    ]
}
1
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

← Barcode APIs →