DB35/T 1665-2017 校园一卡通统一管理平台技术规范

ICS35.240.99

P07

DB35

福建省地方标准

DB35/T1665-2017

校园一卡通统一管理平台技术规范

Technicalspecificationsforcampuscarduniformmanagementplatform

2017-05-05发布2017-08-05实施

福建省质量技术监督局发布

DB35/T1665-2017

目次

前言III

1范围1

2规范性引用文件1

3术语和定义1

4缩略语2

5概述2

5.1平台服务2

5.2校级应用子系统2

6服务接口概述3

6.1概述3

6.2调用方式3

6.3请求结构4

6.4公共参数4

6.5返回结果5

6.6签名机制6

6.7接口命名编码规则6

7卡帐管理服务7

7.1概述7

7.2账户管理接口7

7.3卡片管理接口14

7.4终端管理接口21

8身份识别服务26

9消费交易管理服务27

9.1概述27

9.2消费交易流程27

9.3金融交易管理服务接口38

9.4交易类接口40

10数据处理服务43

10.1概述43

10.2数据清分原则43

10.3数据处理43

10.4清分响应时间43

10.5清分数据备份44

10.6清分结算接口44

I

DB35/T1665—2017

11业务数据服务58

11.1概述58

11.2图书馆管理系统58

11.3水控管理系统62

11.4电控管理系统66

11.5门禁管理系统70

11.6食堂管理系统72

12用户卡73

12.1识别要求73

12.2应用技术要求74

13通讯要求80

13.1数据传输方式80

13.2传输约定81

13.3传输流程81

13.4断点续传82

13.5连接超时82

14重要编码说明82

14.1概述82

14.2错误编码类型83

14.3持卡人证件类型84

14.4持卡人卡类别84

14.5账户类型85

14.6性别85

14.7平台级别85

14.8应用系统类型85

14.9使用状态类型86

14.10支付方式类型86

14.11交易类型86

14.12借阅操作类型86

14.13门禁出入类型87

14.14账户状态87

14.15校园一卡通卡号87

II

DB35/T1665-2017

前言

本标准按GB/T1.1-2009《标准化工作导则第1部分：标准的结构和编写》给出的规则起草。

本标准由福建省信息化标准化技术委员会提出并归口。

本标准起草单位：福建远智科技有限公司、福建省网络计算与智能信息处理重点实验室、高新兴科

技集团有限公司、福州大学新一代网络技术研究所、福建正元智慧信息科技有限公司、福建银达汇智信

息科技有限公司、福建联讯网络科技有限公司、福建明点信息技术有限公司。

本标准主要起草人：陈辉、郭文忠、翁学宇、谢琦、吕茂祥、翁武忠、李浩、周华钱、陈昌、

陈羽中、蔡亮、陈锋情、钟三宇、王丹、王正东。

III

DB35/T1665-2017

校园一卡通统一管理平台技术规范

1范围

本标准规定了校园一卡通统一管理平台的系统架构、数据服务接口要求、用户卡规范与技术要求、

通信要求、消费交易流程、数据清分以及信息安全等。

本标准适用于福建省各级各类学校的校内与跨校园间消费（校园食堂、校园商铺、校医院、校内交

通、校园图书馆）、门禁考勤、水控电控、图书馆管理等业务领域，并实现福建省内学校一卡通业务数

据的汇聚与统一管理。

2规范性引用文件

下列文件对于本标准的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。

凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。

GB/T2311信息技术字符代码结构与扩充技术

GB2312信息交换用汉字编码字符集基本集

GB/T31778-2015数字城市一卡通互联互通通用技术要求

GB50918城镇建设智能卡系统工程技术规范

CJ/T166建设事业集成电路（IC）卡应用技术条件

CJ/T304建设事业CPU卡操作系统技术要求

3术语和定义

GB/T31778界定的以及下列术语和定义适用于本文件。

3.1

校园一卡通campuscard

由学校面向校内师生发行的具有在各学校应用所需的身份识别、消费结算等功能的IC卡，未来也可

以是满足身份识别、消费结算要求的各类虚拟介质。一卡通适用于校内与跨校园间的消费(校园食堂、

校园商铺、校内交通、校园图书馆)、门禁考勤、水控电控、图书馆管理等业务领域。

3.2

一卡通白名单whitelist

由校园一卡通统一管理平台管理的允许业务受理的一卡通互联互通标识清单，一卡通互联互通标识

由学校代码和一卡通卡号组成。

1

DB35/T1665—2017

3.3

一卡通黑名单blacklist

由校园一卡通统一管理平台管理的拒绝业务受理的一卡通互联互通标识清单，一卡通互联互通标识

由学校代码和一卡通卡号组成。

3.4

校级一卡通管理平台

校级一卡通管理平台主要负责校级应用子系统的管理、数据存储、汇聚，以及与校园一卡通统一管

理平台的数据交换。

4缩略语

CJ/T166所界定的缩略语及下列缩略语适用于本文件。

AID：应用标识符（ApplicationIderntifier)

ATS：复位应答（AnswerToSelect）

BCD：二进制编码的十进制（BinaryCodedDocimal）

COS：智能卡芯片操作系统（ChipOperatingSystem）

DDF：目录定义文件（DirectoryDefinitionFile）

HEX：十六进制数（Hexadecimal）

IC：集成电路（IntegratedCircuit）

MAC：报文认证码（MessageAuthenticationCode）

MF：主控文件

API：应用程序编程接口（ApplicationProgrammingInterface）

HTTP：超文本传输协议（HyperTextTransferProtocol)

XML：可扩展标记语言（ExtensibleMarkupLanguage）

5概述

5.1平台服务

校园一卡通统一管理平台提供的关键服务包括：

a)卡帐管理服务：为校级一卡通平台提供账务、一卡通卡片的统一管理服务；

b)安全认证服务：为校级数据中心提供一卡通账户的识别、安全认证等服务；

c)金融交易管理服务：为校级数据中心提供一卡通账户充值、消费综合处理等服务；

d)密钥管理服务：为校级数据中心提供主控密钥以及消费、圈存等各种应用密钥的生成与维护服

务；

e)数据处理服务：为校级数据中心提供清分结算和数据管理服务；

f)业务数据交换服务：为校级数据中心提供校级应用子系统的业务数据的归集服务。

5.2校级应用子系统

校级应用子系统目前主要包括图书馆管理系统、水控管理系统、电控管理系统、门禁管理系统、食

堂管理系统等。随着应用子系统的增加，校园一卡通统一管理平台的业务数据交换服务将进一步开放业

2

DB35/T1665-2017

务数据归集接口服务。

图1平台技术框架图

6服务接口概述

6.1概述

平台接口服务主要由5大接口服务组成，包括卡账管理服务、身份识别服务、金融交易管理服务、

数据处理服务、业务数据服务。卡账管理服务，对账户、卡片等进行统一管理，并开放对账户、卡片、

终端的管理接口；同时，平台设计中，账户与卡片、终端的关系为一对多的关系，一个账户可能绑定多

张卡和绑定多个终端。身份识别服务，开放身份识别接口，提供校级平台便捷进行用户校验。金融交易

管理服务，开放金融交易的账户类接口和交易类接口，提供校级平台进行账户金融管理。数据处理服务，

统一完成校级数据处理系统间的清分结算和数据管理。开放清分结算查询接口。业务数据服务，汇总业

务子系统的数据，包括图书馆管理系统、水控管理系统、电控管理系统、门禁管理系统、食堂管理系统

等。

6.2调用方式

对服务接口的调用是通过向校园一卡通统一管理平台的服务端地址发送HTTPGET请求，并按照接口

说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回处理结果。

3

DB35/T1665—2017

6.3请求结构

6.3.1服务地址

校园一卡通统一管理平台的服务接入地址见表1。

表1服务接入地址

请求地址

环境HTTP请求地址HTTPS请求地址

正式环境http://ykt.api.fjedu.top/https://ykt.api.fjedu.top/

6.3.2通信协议

支持通过HTTP或者HTTPS通道进行请求通信，为了获得更高的安全性，推荐使用HTTPS通道发送请求。

6.3.3请求方法

支持HTTPGET方法发送请求，这种方式下请求参数需要包含在请求的URL中。

6.3.4请求参数

每个请求都需要指定要执行的操作，即method参数（例如addAccount），以及每个操作都需要包含

的公共请求参数和指定操作所特有的请求参数。

6.3.5字符编码

请求及返回结果都使用UTF-8字符集进行编码。

6.4公共参数

6.4.1公共请求参数

公共请求参数是指每个接口都需要使用到的请求参数，见表2。

表2公共请求参数

名称参数命名类型是否必须示例值限制说明

接口名称methodStringYesaddAccountAPI接口名称

AppKeyapp_keyStringYes1000810000

时间戳timestampStringYes2015-01-01时间戳格请求的时间戳。日期格式按照ISO8601标准表示，

12:00:00yyyy-MM-dd并需要使用UTC时间。格式为：yyyy-MM-dd

HH:mm:ssHH:mm:ss，例如，2014-05-26：12:00:00(为北京

时间2014年5月26日12点0分0秒)

响应格式formatStringNoJSON类型限制支持XML，JSON两种格式，默认为XML格式。

版本versionStringYes1.0API协议版本

签名的摘要算sign_methodStringYesHMAC-SHA1c类型限制签名算法，可选值为：HMAC-SHA1，HMAC-MD5

法

签名算法版本sign_versionStringYes1.0签名算法版本，目前版本1.0,取值1.0

API输入参数签signatureStringYesAPI输入参数签名结果，签名算法参见“签名机

名结果制”

4

DB35/T1665-2017

示例如下：

http://ykt.api.fjedu.top/?timestamp=1476535566

&format=XML

&method=addAcount

&sign_method=HMAC-SHA1

&app_key=10000

&version=1.0

&sign_version=1.0

&signature=FZnIrdNSLax4lnWf6NkKDc7mp54%3D

6.4.2公共返回参数

用户发送的每次接口调用请求，无论成功与否，系统都会返回一个唯一识别码RequestID给用户。

示例如下：

<?xmlversion="1.0"encoding="utf-8"?>

<!—结果的根结点-->

<接口名称+Response>

<!—返回请求标签-->

<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>此为示例值

</接口名称+Response>

6.5返回结果

6.5.1返回结果说明

调用API服务后返回数据采用统一格式，返回的HTTP状态码为2xx，代表调用成功；返回4xx或5xx

的HTTP状态码代表调用失败。调用成功返回的数据格式主要有XML和JSON两种，外部系统可以在请求时

传入参数来制定返回的数据格式，默认为XML格式。

6.5.2成功结果

返回结果包括请求是否成功信息和具体的业务数据。

示例如下：

<?xmlversion="1.0"encoding="utf-8"?>

<!—结果的根结点-->

<接口名称+Response>

<!—返回请求标签-->

<RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>此为示例值

<!—返回结果数据-->

</接口名称+Response>

5

DB35/T1665—2017

6.5.3错误结果

调用接口出错后，将不会返回结果数据。调用方可根据错误代码来定位错误原因。当调用出错时，

HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外还包含

一个全局唯一的请求ID：RequestID。

示例如下：

<?xmlversion="1.0"encoding="UTF-8"?>

<Error>

<RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>此为示例值

<Code>UnsupportedOperation</Code>此为示例值

<Message>Thespecifiedactionisnotsupported.</Message>此为示例值

</Error>

6.6签名机制

校园一卡通管理平台接口服务会对每个访问的请求进行身份验证，所以无论使用HTTP还是HTTPS协

议提交请求，都需要在请求中包含签名（Signature）信息。

为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参

数，对签名进行验证，签名不合法的请求将会被拒绝。目前支持的签名算法有两种：HMAC_MD5,

HMAC_SHA1，HMAC_MD5和HMAC_SHA1都是128位长度的摘要算法，用16进制表示，一个十六进制的字符能

表示4个位，所以签名后的字符串长度固定为32个十六进制字符，签名大体过程如下：

a)对所有API请求参数（包括公共参数和业务参数，但除去sign参数和byte[]类型的参数），

根据参数名称的ASCII码表的顺序排序。如：foo=1,bar=2,foo_bar=3,foobar=4排序后的

顺序是bar=2,foo=1,foo_bar=3,foobar=4；

b)将排序好的参数名和参数值拼装在一起，根据上面的示例得到的结果为：

bar2foo1foo_bar3foobar4；

c)把拼装好的字符串采用utf-8编码，使用签名算法对编码后的字节流进行摘要。如果使用MD5

算法，则需要在拼装的字符串前后加上app的secret后，再进行摘要，如：

md5(secret+bar2foo1foo_bar3foobar4+secret)；如果使用HMAC_MD5算法，则需要用app的

secret初始化摘要算法后，再进行摘要，如：HMAC_MD5(bar2foo1foo_bar3foobar4)；

d)将摘要得到的字节流结果使用十六进制表示，如：hex(“helloworld”.getBytes(“utf-8”))=

“68656C6C6F776F726C64”。

6.7接口命名编码规则

接口编码说明：以SI(SystemInterface)开头，后面6位是十六进制编码0-F。

第一位和第二位：01卡账管理子系统接口；02身份识别子系统；03消费交易管理子系统；04数据处

理子系统。

第三位和第四位：卡账管理子系统接口（01账户管理模块；02卡片管理模块；03终端管理模块）；

身份识别子系统（01身份识别模块）；消费交易管理子系统（01账户类模块；02交易类模块）；数据处

理子系统（01清分结算模块；02数据分析模块）。

第五，六位：接口顺序编号（按照具体提示信息标号从01-FF进行编号）。

6

DB35/T1665-2017

7卡帐管理服务

7.1概述

卡账管理服务主要对账户、卡片等进行统一管理，并开放对账户、卡片、终端的管理接口。包含接

口:(1)账号管理接口；(2)卡片管理接口；(3)终端管理接口。

7.2账户管理接口

7.2.1新增平台账户接口

新增平台账户接口、接口传入参数及说明、返回参数见表3、表4、表5、表6。

表3新增平台账户接口

接口名称addAccounts

接口编码SI010101

功能说明新增平台账户

备注

表4新增平台账户接口传入参数

传入参数

名称参数命名类型是否必须示例值限制说明

账户信息列表accountListListYes见下表

表5新增平台账户接口传入参数说明

账户信息列表参数说明

名称参数命名类型是否必须示例值限制说明

长度不超

持卡人姓名userNameStringYes王明过15个字

符

只能输入

35010318880

持卡人证件号userIdCodeStringYes证件类型

4011516

的字符

1:表示身份证

2:表示学生证

持卡人证件类型userIdTypeIntYes1类型限制3:护照

4:台胞证

详见14.3

1:男

持卡人性别userSexIntYes1类型限制0:女

详见14.6

7

DB35/T1665—2017

表5（续）

账户信息列表参数说明

名称参数命名类型是否必须示例值限制说明

1:学生卡

2:教师卡

持卡人卡类别userCardTypeIntYes1类型限制

3:职工卡

详见14.4

1:个人

账户类型accountTypeIntYes1类型限制2:公共

详见14.5

备注remarkStringNo

表6返回参数

返回参数

名称参数命名类型示例值说明

公共参数详见6.4

7.2.2查询平台账户接口

查询平台账户接口、接口传入参数、返回参数及结果列表参数说明见表7、表8、表9、表10。

表7查询平台账户接口

接口名称getAccount

接口编码SI010102

功能说明查询指定账户信息

备注

表8传入参数

传入参数

名称参数命名类型是否必须示例值限制说明

证件号码userIdCodeStringNo35010318880只能输入至少一个参数

4011516身份证类不为空

型的字符

持卡人姓名userNameStringNo王明长度不超至少一个参数

过15个字不为空

符

校园一卡通卡号cardIdCodeStringNo66666621130数字组合至少一个参数

50901431不为空

账户编号accountIdStringNo10000至少一个参数

不为空

8

DB35/T1665-2017

表9返回参数

返回参数

名称参数命名类型示例值说明

公共参数详见6.4

结果列表resultListList见下表

表10结果列表参数说明

结果列表参数说明

名称参数命名类型示例值说明

账户编号accountIdString10000

持卡人姓名usernameString王明

校园一卡通卡号cardIdCodeString6666662113050901431数字组合

持卡人身份证号userIdCodeString350103188804011516

1:表示身份证

2:表示学生证

持卡人证件类型userIdTypeInt13:护照

4:台胞证

详见14.3

1:男

持卡人性别userSexInt10:女

详见14.6

1:学生卡

2:教师卡

持卡人卡类别userCardTypeInt1

3:职工卡

详见14.4

1:个人

账户类型accountTypeInt12:公共

详见14.5

备注remarkString

账户总资产totalBalanceFloat500.00

可用余额availableBalanceFloat50.02

待领余额claimBalanceFloat100.00

7.2.3修改账户信息接口

修改账户信息接口、传入参数、账户信息列表参数说明、返回参数见表11、表12、表13、表14。

9

DB35/T1665—2017

表11修改账户信息接口

接口名称updateAccounts

接口编码SI010103

功能说明通过持卡人姓名和证件号码，修改特定账户信息

备注

表12传入参数

传入参数

名称参数命名类型是否必须示例值限制说明

账户信息

accountListListYes见下表

列表

表13账户信息列表参数说明

账户信息列表参数说明

名称参数命名类型是否必须示例值限制说明

账户编号accountIdStringYes10000

校园一卡cardIdCodeStringNo66666621130数字组合

通卡号50901431

长度不超

持卡人姓