title: 一卡通v5读卡服务接口文档 date: 2016-06-21 14:08:45 tags:

  • version : 1.7

错误码定义

  • 100 - 一般错误
  • 101 - 不支持的请求
  • 102 - 错误的请求参数
  • 103 - 没有指定的记录
  • 104 - 写卡失败
  • 105 - 未认证

版本信息请求参数

  • URL: /4/

  • 请求参数 无

  • 返回 version - 读卡服务版本 card_version - 读卡模块版本 card_info - 读卡模块编译信息 cfgid - 读卡服务配置ID ， V5版本

服务认证

  • URL: /4/auth/<action>

  • 请求方式 GET

  • Url 参数 action : 可选 init, verify； init 是认证初始化获取token, verify 是验证 token , 获取 request_token

  • 请求参数 init : 获取认证 token verify: 验证 token 的签名 signature: token 签名， 签名算法 SHA1withRSA

  • 返回 token: init 请求时返回的token request_token : verify 成功后返回 request_token token_expired : verify 成功后返回的 token 的有效期

获取读卡库支持配置清单

  • URL: /5/config_list

  • 请求方式 GET

  • 请求参数 无

  • 返回 config: 支持的配置清单，{ "id" : ... , "desc": ... } 对象数组

加载读卡器配置

  • URL: /5/init POST

  • 请求参数 id: 配置 ID 号

  • 返回 无

读卡器控制

  • URL: /4/device/<action>

  • 请求方式 GET

  • Url 参数 action : 可选值 open 打开读卡器, close 关闭读卡器, isopen 判读读卡器是否已打开, beep 读卡器蜂鸣

  • 请求参数 open： 打开读卡器， 参数 port, baud, samport

port （可选）读卡器端口， 100 表示USB接口， 默认100 baud （可选）读卡器波特率，默认 57600 samport （可选）SAM 卡槽号， 可选值 1, 2 ,3 ,4

`close` : 关闭读卡器
`isopen`: 判断读卡器是否已打开
`beep`: 读卡器蜂鸣
  • 返回 无

加载密钥卡

  • URL: /4/keycard/<action>

  • 请求方式 GET

  • Url 参数 action: 可选 load , setkey

  • 请求参数 load: 可选参数 pin

pin - 密钥卡PIN码

`setkey`: 可选参数 key

key - 密钥

  • 返回 无

PSAM卡操作

  • URL: /4/samcard/<action>

  • 请求方 GET

  • Url 参数 action: 可选值 setport , readsamno, publish, recycle, read, readtermseqno

  • 请求参数 setport: 设置卡槽号

port : SAM 卡槽号，可选 1,2,3,4

`publish`: 发行PSAM卡

cardno - 卡号 cardtype - 卡类别 expiredate - 有效期 termseqno（可选) - 流水号 cardver - 版本 termid - ID号 keyindex - 密钥索引 startdate - 启用日期 publishid - 发行方ID userid - 用户ID

`recycle`: 回收PSAM卡
`read`: 读取PSAM卡信息
`readsamno`: 读取SAM卡号
`readtermno`: 读取SAM卡号
`readtermseqno`: 读取SAM卡流水号
  • 返回 readsamno 请求时返回

samno` - SAM卡号

`readtermno` 请求时返回

termno - SAM卡号

`read` 请求时返回

cardno - 卡号 cardtype - 卡类别 expiredate - 有效期 termseqno - 流水号 cardver - 版本 termid - ID号 keyindex - 密钥索引 startdate - 启用日期 publishid - 发行方ID userid - 用户ID

`readtermseqno`:

termseqno - 终端流水号

卡片初始化回收

  • URL: /4/cardinit/<action>

  • 请求方式 GET

  • Url 参数 action：可选值 init , recycle

  • 请求参数 init: 表示初始化卡片

cardphyid - (必须)物理卡号 showcardno - (可选) 显示卡号

`recycle`: 表示回收卡， 无参数
  • 返回 无

寻卡

  • URL：/4/requestcard

  • 请求方式 GET

  • 请求参数 beep: 不为空时，寻卡成功读卡器蜂鸣

  • 返回 cardphyid: 物理卡号 cardtype_code: 卡类型码

读卡

  • URL: /4/readcard/<cardphyid>

  • 请求方式 GET

  • Url 参数 cardphyid: 物理卡号

  • 请求参数 cardmode: 为 1 时读取消费属性，0 或者没有参数时不读取消费模式 beep: 不为空时成后读卡器蜂鸣 fields: 卡属性列表多个属性用分号（;）

CF_CARDNO - 交易卡号 CF_SHOWCARDNO - 显示卡号 CF_FEETYPE - 收费类别（卡主类别） CF_SUBSIDYNO - 补助批次号 CF_CARDVERNO - 卡版本号 CF_CARDSTATUS - 卡状态 0正常, 1锁定,2冻结卡, 3挂失卡, 4注销卡, 5过期 CF_STARTDATE - 启用日期 CF_EXPIREDATE - 过期日期 CF_PUBLISHID - 发行方标识 CF_CARDTYPE - 卡类别 CF_APPTYPE - 应用类型 CF_CARDSTRUCTVER - 卡结构版本（应用版本） CF_SCHOOLCODE - 校区代码 CF_CUSTID - 客户号 CF_CUSTTYPE - 客户类别 CF_STUEMPNO - 学工号 CF_NAME - 姓名 CF_SEX - 性别 CF_DEPTCODE - 部门代码 CF_IDNO - 证件号码 CF_IDTYPE - 证件类型 CF_DUTYCODE - 职务代码 CF_BANKCARDNO - 银行卡号 CF_LOCKTERMID - 锁卡交易时终端机号 CF_LOCKTRANSDATE - 锁卡交易日期 CF_LOCKTRANSTIME - 锁卡交易时间 CF_DAYSUMAMT - 当日累计交易金额 CF_LOCKCARDCNT - 锁卡交易时交易次数 CF_SINGLEMAXAMT - 单次消费限额 CF_DAYMAXAMT - 日消费累计限额 CF_CARDCNT - 卡交易次数(最后一次交易) CF_TRANSAMT - 交易金额(最后一次交易) CF_TRANSTYPE - 交易类型(最后一次交易) CF_TERMID - 交易终端机编号(最后一次交易) CF_TRANSDATE - 交易日期(最后一次交易) CF_TRANSTIME - 交易时间(最后一次交易) CF_CARDBAL - 卡余额 CF_CARDPWD - 卡密码 CF_DPSCNT - 充值交易次数 CF_PAYCNT - 消费交易次数 CF_NATIONALITY - 民族 CF_COUNTRY - 国籍 CF_IDCODE - 身份代码 CF_CREDITLIMIT - 授信额度 CF_CREDITSEQNO - 授权额度批次 CF_CREDITENABLED - 是否运行授信消费

  • 返回 cardmode - 卡模式，可选值 A, B

写卡

  • URL： /4/writecard/<cardphyid>

  • 请求方式 GET

  • 请求参数 cardmode: 卡模式，可选值 'A', 'B' nobeep: 不为空，成功后不会蜂鸣 fields: 写卡的属性 key=value 格式，用分号(;)分割

CF_CARDNO - 交易卡号 CF_SHOWCARDNO - 显示卡号 CF_FEETYPE - 收费类别（卡主类别） CF_CARDSTATUS - 卡状态 0正常, 1锁定,2冻结卡, 3挂失卡, 4注销卡, 5过期卡 CF_STARTDATE - 启用日期 CF_EXPIREDATE - 过期日期 CF_CARDTYPE - 卡类别 CF_SCHOOLCODE - 校区代码 CF_CUSTID - 客户号 CF_CUSTTYPE - 客户类别 CF_STUEMPNO - 学工号 CF_NAME - 姓名 CF_SEX - 性别 CF_DEPTCODE - 部门代码 CF_IDNO - 证件号码 CF_IDTYPE - 证件类型 CF_DUTYCODE - 职务代码 CF_BANKCARDNO - 银行卡号 CF_SINGLEMAXAMT - 单次消费限额 CF_DAYMAXAMT - 日消费累计限额 CF_CARDPWD - 卡密码 CF_NATIONALITY - 民族 CF_COUNTRY - 国籍 CF_IDCODE - 身份代码 CF_CREDITLIMIT - 授信额度 CF_CREDITSEQNO - 授权额度批次 CF_CREDITENABLED - 是否运行授信消费, 0: 允许， 1: 不允许

  • 返回 无

读取授信交易流水

  • URL： /4/read_credit_record/<record_id>

  • 请求方式 GET

  • Url 参数 record_id: 1 - 10 表示流水号， 0 表示最近一笔流水

  • 请求参数 nobeep: 不为空时，读取到记录读卡器不会蜂鸣

  • 返回 record_count: 记录条数 records: 交易记录

transdate: 交易日期, 格式YYYYMMDD transtime: 交易时间， HHMISS devphyid : 终端编号, 8个字符 seqno: 终端流水号, 整数 totalamt: 累计授信交易总金额, 单位分 amount : 本次交易金额, 单位分 extrafee: 本次交易搭伙费/折扣， 单位分 daytotalamt: 当天累计授信交易总金额, 单位分 creditlimit: 剩余授信额度,单位分 paycnt: 交易前次数,整数 creditseqno: 授信序号 transflag: 交易标志 legal: 认证状态： valid 表示合法，invalid 表示不合法

清空卡信息

  • URL: /4/cardoper/<action>

  • 请求方式 GET

  • Url 参数 action : recycle

  • 请求参数 recyle: 清空卡信息

water - 水控钱包号列表，例如 1,2

  • 返回 无

卡电子钱包充值初始化

  • URL：/4/init4load/<cardphyid>

  • 请求方式 GET

  • Url 参数 cardphyid: 物理卡号

  • 请求参数 cardno: 交易卡号 amount: 充值金额，单位为分 dpscnt: 卡充值前次数，通过读卡获取

  • 返回 random: 卡随机数 samno: 终端号 mac1

卡电子钱包充值确认

  • URL: /4/credit4load/<cardphyid>

  • 请求方式 GET

  • Url 参数 cardphyid: 物理卡号

  • 请求参数 hostdate: 主机日期，YYYYMMDD hosttime: 主机时间，HH24MISS mac2

  • 返回 tac: 成功返回 tac

卡电子钱包消费

  • URL： /4/cardpurchase/<cardphyid>

  • 请求方式 GET

  • Url 参数 cardphyid: 物理卡号

  • 请求参数 cardno: 交易卡号 amount: 消费金额，单位分 paycnt: 消费前次数，通过读卡获取 transdate: 终端日期，格式 YYYYMMDD transtime: 终端时间，格式 HH24MISS

  • 返回 tac: 成功返回 tac

水控钱包相关

  • URL： /4/watercard/<action>

  • 请求方式 POST

  • Url 参数 action: 操作 ， publish, recycle, read, write

  • 请求参数 nobeep: 水控操作成功后不产生蜂鸣 publish: 初始化水控钱包

waterid - 水控钱包号 cardno - 卡号 custid - 客户号 cardtype - 卡类别 amount - 初始化时，写入卡金额， 单位分 price1 - 水价1, 单位分 price2 - 水价2, 单位分 price3 - 水价3, 单位分 expireddate - 有效期， 格式 YYYYMMDD

`recycle`: 回收水控钱包

waterid - 水控钱包号

`read`: 读取水控钱包信息

waterid - 水控钱包号

`write`: 写水控钱包

waterid - 水控钱包号 cardno - 卡号 custid - 客户号 cardtype - 卡类别 amount - 写入水控钱包余额, 单位 分 price1 - 水价1, 单位分 price2 - 水价2, 单位分 price3 - 水价3, 单位分 expiredate - 有效期， 格式 YYYYMMDD

  • 返回 waterid: 被操作的水控钱包号 cardno: 卡号 custid: 客户号 cardtype: 卡类别 cardbal: 水控钱包余额 expireddate: 卡上有效期 price1: 水价1 price2: 水价2 price3: 水价3

密钥卡发行、克隆、回收

  • URL: /4/key/<action>

  • 请求方式 GET

  • Url 参数 action: 可选参数包括 publishkeycard, clonekeycard, loadkeycard, dumpkeys

  • 请求参数 publishkeycard: 发行密钥卡

pin - PIN 码 masterkey - 主密钥

`clonekeycard`: 克隆密钥卡
> pin - 新密钥卡 PIN 码

`loadkeycard`: 加载密钥卡
> pin - PIN 码

`dumpkeys`: 保存密钥
> pin - PIN 码
  • 返回 dumpkeys: 读取密钥

keys - 返回密钥串

发行、读取、回收水控参数卡

  • URL: /4/waterparamcard/<action>

  • 请求方式 GET

  • Url 参数 action: 可选值 requestcard, write, read, recycle

  • 请求参数

requestcard - 寻卡

write - 写参数卡

请求格式为 json , Content-Type: application/json;

water_flag: 水控卡标志 packget_num: 水控钱包号 main_work_key: 主钱包密钥 packget_work_key: 水控钱包密钥 work_mode: 水控模式 water_packet_limit: 水控钱包上限 transfer_limit: 水控转账限额 feecfg: 费率配置 feetype: 收费类别 rate: 费率 start: 开始计费时间（分）/流量（升） deduct_time: 计费单位时间（秒）/流量(升) deduct_fee : 计费单位费率（金额分）

{
"water_flag": "LYCS",
"packget_num": 1,
"main_work_key": "4344334539413846",
"packget_work_key": "4344334539413846",
"work_mode": 1,
"water_packet_limit": 5000,
"transfer_limit": 500,
"feecfg": [
		{"feetype": 3,
		 "rate": [
			 {"start": 0, "deduct_time":10, "deduct_fee": 5},
			 {"start": 5, "deduct_time":15, "deduct_fee": 5}]
		},
		{"feetype": 6,
		 "rate": [
			 {"start": 0, "deduct_time":5, "deduct_fee": 5},
			 {"start": 3, "deduct_time":30, "deduct_fee": 10}]
		}
	]
}

read: 读取水控参数卡 recycle: 回收水控参数卡

  • 返回

requestard:

cardphyid - 卡片物理ID号