上海交通大学开发者平台

# Card APIs

本组API用于校园卡信息的查询、设置。

# 获取校园卡信息

# 功能介绍

用于获取用户校园卡信息，使用授权码（Authorization Code）方式获取scope为card_info的令牌即可访问。 注意: 一个用户可能存在多张校园卡，其他接口可以通过此接口返回的校园卡信息中的cardNo来确定唯一的校园卡。

# 请求参数

除了access_token无其他参数

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

  • Card Info 校园卡信息 Structure
{
    "user":{canvas.profile},       // 只含name,code,organize.name, userType
    "cardNo":{string},             // 校园卡账号
    "cardId":{string},             // 校园卡物理卡号，hex string
    "bankNo":{string},             // 银行卡号
    "expireDate":{string},         // 校园卡有效期，yyyyMMdd
    "cardBalance":{double},        // 校园卡余额,单位元
    "transBalance":{double},       // 当前过渡余额, 单位元
    "lost":{boolean},			   // 挂失状态 false正常 true已挂失
    "frozen":{boolean}             // 冻结状态 false正常 true已冻结
}
1
2
3
4
5
6
7
8
9
10
11

# 请求示例

GET /v1/me/card?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":[{
        "user":{
            "name":"张三",
            "code":"gh1234",
            "organize":{
                "name":"网络信息中心"
            },
            "timeZone":0
        },
        "cardNo":"12345",
        "cardId":"12345678",
        "bankNo":"",
        "expireDate", "20600101",
        "cardBalance":10.34,
        "transBalance":0,
        "lost":false,
        "frozen":false
    }]
}
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

# 校园卡开户

# 功能介绍

用于创建校园卡账户，使用授权码（Authorization Code）方式获取scope为manage_card的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
userCode string 创建校园卡账户的学工号 校园卡和用户的学工号关联，因此必须指定需要创建校园卡账户的学工号
cardType string 创建的校园卡类型 当前支持的值为: 800 - 正式卡，801 - 临时卡
expireDate string 校园卡账户的失效日期。以yyyyMMdd格式指定
free boolean 是否免收开户管理费 true - 免收开户管理费，false - 根据一卡通系统设置确定是否收取管理费
openAmount float 开户金额。单位元。 调用方需自行保障传入的金额对应的资金已转入一卡通专户。

# 响应参数

返回数据和获取校园卡信息接口返回一致，但仅保障其中的校园卡账号(cardNo)属性。

# 请求示例

PUT /v1/me/card?access_token=token&userCode=CS0021&cardType=800&expireDate=20301231&openAmount=0 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":[{
        "user":{
            "name":"测试",
            "code":"CS0021"
        },
        "cardNo":"1003"
        "lost":false,
        "frozen":false
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 查询校园卡身份信息

# 功能介绍

用于查询校园卡身份信息，确定指定学工号在一卡通系统中是否存在，使用授权码（Authorization Code）方式获取scope为manage_card或者card_info的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
userCode string 指定学工号 校园卡和用户的学工号关联，因此必须指定需要查询的学工号

# 响应参数

返回数据和获取校园卡信息接口返回一致，但仅保障其中的用户(user)属性。

# 请求示例

GET /v1/me/card/user?access_token=token&userCode=CS0021 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":[{
        "user":{
            "name":"测试",
            "code":"CS0021"
        }
    }]
}
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,
    "error":"success",
    "total":0,
    "entities":[]
}
1
2
3
4
5
6
7
8
9

# 获取交易记录信息

# 功能介绍

用于获取用户校园卡交易记录，使用授权码（Authorization Code）方式获取scope为card_transactions的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号 2021-07-16新增。为保持兼容，允许不提供，但若用户有多张校园卡，随机确定实际查询的校园卡
beginDate long 查询起始时间 unix时间戳 1970年1月1日以来的毫秒数。2021-10-20调整为可选参数，未提供时使用1970年1月1日。
endDate long 查询结束时间 unix时间戳 1970年1月1日以来的毫秒数。可选，未提供时默认为当日
orderBy string 排序方式 2022-07-19新增。指定返回交易记录的排序方式，支持: dateTime - 按消费时间排序；dateTimeAccount - 按入账时间排序。默认为按消费时间排序
start int 起始序号 2021-10-20新增。分页参数，指定返回数据的起始序号，从0开始。如果指定了大于0的值，必须同时指定limit，并且为limit的整数倍
limit int 分页大小 2021-10-20新增。分页参数，指定返回数据的条数，0-100，0表示不分页。不分页时必须指定beginDate

注: beginDate和endDate所指时间和orderBy一致。如果orderBy指定了按消费时间排序，beginDate、endDate指交易记录的消费时间。如果orderBy指定了按入账时间排序，beginDate、endDate指交易记录的入账时间。

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

响应数据的total为指定时间范围内（如未指定即为全部）的总数据条数。

  • Card Transaction 消费信息 Structure
{
    "dateTime":{long},          // 消费时间
    "dateTimAccount": {long},   // 入账时间（仅在指定使用入账时间排序时返回）
    "system":{string},          // 消费目标系统（eg：闵行第二餐厅）
    "merchantNo":{string},      // 商户号
    "merchant":{string},        // 商户名称
    "description":{string},     // 交易名称（eg：持卡人消费）
    "amount":{double},          // 交易金额，单位元
    "cardBalance":{double},     // 交易后卡余额，单位元                               
}
1
2
3
4
5
6
7
8
9
10

# 请求示例


示例 请求2020-09-01以来的消费记录
GET /v1/me/card/transactions?access_token=token&cardNo=12345&beginDate=1598889600000 HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 请求2020-09-01以来的消费记录返回数据
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "total":1,
    "entities":[{
        "dateTime":1599017902000,
        "system":"新闵行第二食堂",
        "merchant":"大众餐厅",
        "description":"持卡人消费",
        "amount":-10.66,
        "cardBalance":86.06
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 设置卡信息和状态

# 功能介绍

设置校园卡挂失/解挂状态、设置新查询密码，使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号 2021-07-16新增。为保持兼容，允许不提供，但若用户有多张校园卡，随机确定实际操作的校园卡
queryPassword string 校园卡查询密码 设置挂失/解挂状态和修改查询密码时必须提供
lost boolean 挂失/解挂校园卡，挂失为true，解挂为false 挂失/解挂功能参数。
newPassword string 新查询密码 修改查询密码功能参数。

# 响应参数

只有errno,error,total字段，无其他信息。从errno字段可知是否设置成功。

# 请求示例


示例 挂失
POST /v1/me/card?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

lost=true&cardNo=12345&queryPassword=userpassword
1
2
3
4
5

# 响应示例


示例 挂失成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

# 获取校园卡照片

# 功能介绍

获取校园卡的照片数据。使用授权码（Authorization Code）方式获取scope为privacy的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
userCode string 学工号 此参数如果提供则忽略cardNo参数，且必须和令牌所属账户关联。userCode和cardNo不能同时缺失
cardNo string 校园卡账号 此参数确定校园卡，仅在未提供userCode时使用。userCode和cardNo不能同时缺失
urlOnly boolean 仅获取照片的下载地址 此参数指定为true时，不再返回照片的图像数据(format和photo)，推荐使用

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

  • 校园卡照片信息 Structure
{
    "cardNo": {string},             // 校园卡账号，如果查询参数提供了userCode，不返回此项信息
    "userId": {string},             // 学工号
    "url":    {string},             // 照片下载地址
    "format": {string},             // 照片的格式
    "photo":  {string}              // 照片图像数据，base64编码
}
1
2
3
4
5
6
7

# 请求示例


示例 获取校园卡照片请求
GET /v1/me/card/photo?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

cardNo=12345
1
2
3
4
5

# 响应示例


示例 获取校园卡照片请求成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "total":1,
    "entities":[{
        "cardNo": "12345",
        "userId": "56789",
        "format": "jpg",
        "photo": "AAABBCCDE123111..."
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 更新校园卡照片

# 功能介绍

获取校园卡的照片数据。使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

仅校园卡存在原照片时才可更新，并且新照片与原照片需要通过对比审核校验才能更新成功。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号 必须提供此参数确定校园卡
photo string 照片数据 base64编码

# 响应参数

该接口响应无定制信息。从errno字段可知是否设置成功，如果不成功，error为原因描述

# 请求示例


示例 更新校园卡照片请求
POST /v1/me/card/photo?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

cardNo=12345&photo=AABBCCDDFF12311.....
1
2
3
4
5

# 响应示例: 更新失败，无原照片


示例 更新校园卡照片请求返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":422,
    "error":"原照片缺失，无法更新"
}
1
2
3
4
5
6
7

# 响应示例: 更新失败，对比校验失败


示例 更新校园卡照片请求返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":422,
    "error":"照片审核未通过"
}
1
2
3
4
5
6
7

# 响应示例


示例 更新校园卡照片请求成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

# 查询充值请求

# 功能介绍

查询校园卡充值的请求。使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
id long 申请(订单)流水号 可选，未提供时查询所有已支付但还未完成充值的订单
cardNo string 校园卡账号 必须提供此参数确定校园卡

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

  • 校园卡充值请求信息 Structure
{
    "id": {long},                   // 申请流水号（订单号）
    "cardNo": {string},             // 校园卡账号
    "applyAmount": {number},        // 申请充值金额
    "applyTime": {string},          // 申请时间 yyyy-MM-dd HH:mm:ss
    "expireTime": {string},         // 支付有效期 yyyy-MM-dd HH:mm:ss，必须在该时间前完成支付
    "rechargeAmount": {number},     // 支付/充值金额（理论上应和申请金额相同，仅在支付完成后提供)
    "payTime": {string},            // 支付完成时间 yyyy-MM-dd HH:mm:ss
    "serialNo": {string},           // 校园卡业务流水
    "status": {                     // 订单状态: 
                                    //    APPLY_PENDING(待申请),APPLY_FAILED(申请失败)
                                    //    PAY_PENDING(待支付),PAY_FAILED(支付失败),
                                    //    RECHARGE_PENDING(待充值),RECHARGING(充值处理中),RECHARGE_FAILED(充值失败),RECHARGED(充值完成)
        "code": {string},           // 状态代码
        "name": {string}            // 状态描述
    },
    "failedReason": {string},       // 失败原因描述，针对失败的状态
    "postUrl": {string},            // 提交支付系统的地址（仅在该订单可以支付时提供）
    "postData": {object}            // 提交支付系统的数据（仅在该订单可以支付时提供）
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 请求示例


示例 查询充值请求
GET /v1/me/card/recharge?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

id=123&cardNo=12345
1
2
3
4
5

# 响应示例


示例 查询充值请求成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "total":1,
    "entities":[{
        "id": 331615992016896,
        "cardNo": "12345",
        "applyAmount": 10.0,
        "applyTime": "2021-11-15 15:23:35",
        "expireTime": "2021-11-15 23:55:00",
        "serialNo": "202111150000044924",
        "postUrl": "https://cwc2.jdcw.sjtu.edu.cn/payment/pay/pay.action",
        "postData": {
            "data": "%3C%3Fxml+version%3D%221.0%22+encoding%3D%22GBK%22%3F%3E%0A%3Cbillinfo%3E%3Cversion%3E1.0.0.4%3C%2Fversion%3E%3Cbillno%3E331615992016896%3C%2Fbillno%3E%3Corderinfono%3E12345%3C%2Forderinfono%3E%3Corderinfoname%3E%3C%2Forderinfoname%3E%3CreturnURL%3E%3C%2FreturnURL%3E%3Cbilldtl%3E%3Cfeeitemid%3E%3C%2Ffeeitemid%3E%3Cfeeord%3E1%3C%2Ffeeord%3E%3Camt%3E10.00%3C%2Famt%3E%3C%2Fbilldtl%3E%3C%2Fbillinfo%3E",
            "sign": "fe3c680ac9eb12345dbdae18a11278c2",
            "subsysid": "111",
            "sysid": "000"
        },
        "status": {
            "code": "PAY_PENDING",
            "name": "待支付"
        }
    }]
}
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

# 提交充值请求

# 功能介绍

提交为校园卡充值的请求。使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号 必须提供此参数确定要充值的校园卡
amount integer 充值金额(单位元)

# 请求示例


示例 提交充值请求
POST /v1/me/card/recharge?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

cardNo=12345&amount=10.0
1
2
3
4
5

# 响应示例


示例 提交充值请求成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"success",
    "total":1,
    "entities":[{
        "id": 331615992016896,
        "cardNo": "12345",
        "applyAmount": 10.0,
        "applyTime": "2021-11-15 15:23:35",
        "expireTime": "2021-11-15 23:55:00",
        "serialNo": "202111150000044924",
        "postUrl": "https://cwc2.jdcw.sjtu.edu.cn/payment/pay/pay.action",
        "postData": {
            "data": "%3C%3Fxml+version%3D%221.0%22+encoding%3D%22GBK%22%3F%3E%0A%3Cbillinfo%3E%3Cversion%3E1.0.0.4%3C%2Fversion%3E%3Cbillno%3E331615992016896%3C%2Fbillno%3E%3Corderinfono%3E12345%3C%2Forderinfono%3E%3Corderinfoname%3E%3C%2Forderinfoname%3E%3CreturnURL%3E%3C%2FreturnURL%3E%3Cbilldtl%3E%3Cfeeitemid%3E%3C%2Ffeeitemid%3E%3Cfeeord%3E1%3C%2Ffeeord%3E%3Camt%3E10.00%3C%2Famt%3E%3C%2Fbilldtl%3E%3C%2Fbillinfo%3E",
            "sign": "fe3c680ac9eb12345dbdae18a11278c2",
            "subsysid": "111",
            "sysid": "000"
        },
        "status": {
            "code": "PAY_PENDING",
            "name": "待支付"
        }
    }]
}
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

# 提交拾卡信息

# 功能介绍

提交拾卡信息，请注意此接口要求以客户端凭据授予方式获取scope为card_info的令牌。

# 请求参数

参数名 类型 描述 备注
name string 卡面显示姓名 必须提供
code string 卡面显示学号/工号 必须提供
cardNo string 卡面显示卡号 必须提供
msg string 拾卡人留言 必须提供
photo string 卡照片下载连接 可选

# 响应参数

只有errno,error,total字段，无其他信息。从errno字段可知是否提交拾卡成功。

# 请求示例


示例 提交拾卡信息
POST /v1/card/foundLostCard?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

name=张三&code=1000000001&cardNo=1234567&msg=hello
1
2
3
4
5

# 响应示例


示例 提交拾卡成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

# 根据学工号或物理卡号查询卡信息

# 功能介绍

根据学工号或者物理卡号查询卡信息（卡账号、用户姓名、用户学工号），请注意此接口要求以客户端凭据授予方式获取scope为card_info的令牌。

# 请求参数

参数名 类型 描述 备注
cardId string 物理卡号 Hex String 此参数和userId不能同时缺失，同时提供时优先考虑此参数
userId string 学工号 此参数和cardId不能同时缺失，同时提供时优先考虑cardId参数

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

  • Card Info 校园卡信息 Structure
{
    "user":{canvas.profile},       // 只含name,code
    "cardNo":{string},             // 校园卡账号
    "cardId":{string}              // 校园卡物理卡号，hex string
}
1
2
3
4
5

# 请求示例


示例 根据物理卡号查询卡信息
GET /v1/card?access_token=token&cardId=12345678 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":[{
        "user":{
            "name":"张三",
            "code":"gh1234"
        },
        "cardNo":"12345",
        "cardId":"12345678"
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 冻结解冻校园卡

# 功能介绍

设置校园卡冻结/解冻状态，需使用客户端凭据授予方式获取scope为write_card_info的令牌即可访问。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号 必须提供
frozen boolean 冻结/解冻校园卡，冻结为true，解冻为false 冻结/解冻功能参数。

# 响应参数

只有errno,error,total字段，无其他信息。从errno字段可知是否设置成功。

# 请求示例


示例 冻结
POST /v1/card?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/x-www-form-urlencoded

frozen=true
1
2
3
4
5

# 响应示例


示例 冻结成功返回信息
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

# 查询校园卡余额转结订单

# 功能介绍

查询指定校园卡下正在处理中的向思源码钱包的余额转结订单。使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

此接口仅向交我办App开放。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

  • Transfer Order 转结订单信息 Structure
{
    "id": {long},                  // 转结订单号
    "cardNo":{string},             // 校园卡账号
    "amount":{double},             // 转结金额, 单位元
    "status": {                    // 当前状态
        "code": {string},          // 状态代码: PAY_PENDING - 待扣费，RECHARGE_PENDING - 待充值，RECHARGING - 充值处理中，RECHARGED - 已完成
        "name": {string}           //      REFUND_PENDING - 待退费，REFUNDED - 已取消，REFUND_FAILED - 退费失败
    },
    "payTime":{string},            // 扣费时间
    "rechargeTime":{string},	   // 充值时间
    "refundTime":{string}          // 退费时间
}
1
2
3
4
5
6
7
8
9
10
11
12

# 校园卡余额转结

# 功能介绍

将指定金额从校园卡转结至思源码钱包。使用授权码（Authorization Code）方式获取scope为write_card_info的令牌即可访问。

此接口仅向交我办App开放。

# 请求参数

参数名 类型 描述 备注
cardNo string 校园卡账号
queryPassword string 校园卡查询密码
amount double 转结金额 单位元

# 响应参数

资金转结的请求异步完成，如果请求成功，此接口返回当前该校园卡下所有待处理的转结订单，同查询校园卡余额转结订单

← Unicode APIs →