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

一卡通读卡服务接口文档

version : 1.4

错误码定义

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

版本信息

URL: /4/

参数说明

无

返回值

  • version - 读卡服务版本
  • card_version - 读卡模块版本
  • card_info - 读卡模块编译信息

服务认证

URL: /4/auth/<action>

  • 请求方式: GET
  • 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: /4/device/<action>

  • 请求方式： GET
  • 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
  • action: 可选 load , setkey

参数说明

  • load
    • pin - 密钥卡PIN码
  • setkey
    • key - 密钥

PSAM卡操作

URL: /4/samcard/<action>

  • 请求方式： GET
  • action: 可选值 setport , readsamno

参数说明

  • setport - 设置卡槽号
    • port : SAM 卡槽号，可选 1,2,3,4
  • readsamno - 读取SAM卡号

返回值

  • samno - SAM卡号

卡片初始化回收

URL: /4/cardinit/<action>

  • 请求 GET
  • action ：可选值 init , recycle

参数说明

  • init 表示初始化卡片
    • cardphyid - (必须)物理卡号
    • showcardno - (可选) 显示卡号
  • recycle 表示回收卡， 无参数

寻卡

URL：/4/requestcard

  • 请求 GET

参数说明

  • beep - 不为空时，寻卡成功读卡器蜂鸣

返回值

  • cardphyid - 物理卡号
  • cardtype_code - 卡类型码

读卡

URL: /4/readcard/<cardphyid>

  • 请求： GET
  • 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 - 授权额度批次

返回

  • 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 - 授权额度批次

读取授信交易流水

URL： /4/read_credit_record/<record_id>

  • 请求方式: GET
  • 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
  • action : recycle

参数

  • recyle - 清空卡信息
    • water - 水控钱包号列表，例如 1,2

返回

卡电子钱包充值初始化

URL：/4/init4load/<cardphyid>

  • 请求方式GET
  • cardphyid - 物理卡号

参数

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

返回

  • random - 卡随机数
  • samno - 终端号
  • mac1

卡电子钱包充值确认

URL: /4/credit4load/<cardphyid>

  • 请求方式 GET
  • cardphyid - 物理卡号

参数

  • hostdate - 主机日期，YYYYMMDD
  • hosttime - 主机时间，HH24MISS
  • mac2

返回

  • tac - 成功返回 tac

卡电子钱包消费

URL： /4/cardpurchase/<cardphyid>

  • 请求方式 GET
  • cardphyid - 物理卡号

参数

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

返回

  • tac - 成功返回 tac

水控钱包相关

URL： /4/watercard/<action>

  • 请求方式 POST
  • 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