电子券业务API


券详情查询

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号
orderNo String 否 制码订单号 暂时支持一单一券场景
traceNo String 是 交易流水号 全局唯一

响应结果

字段 数据项 类型(最大长度) 是否必填 字段含义 备注
data codeUrl String 否 券短链 券二维码
code String 是 券号
ebuyTicketId String 是 易百券批次号
faceValue String 是 券面值 单位(元)
validStart String 否 券有效期 起 格式: yyyy-mm-dd hh:mm:ss
validEnd String 否 券有效期 止 格式: yyyy-mm-dd hh:mm:ss
codeStatus String 是 券状态

00:未使用

01:已使用

08:已兑换

04:已冻结

05:已作废

06:已过期
codeStatusDesc String 否 券状态描述
activityName String 否 活动名称
activityId String 否 活动编号
activityProductNo String 否 活动产品编号
productName String 否 产品名称
ticketType String 否 券类型

券兑换

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号
traceNo String 是 交易流水号 全局唯一

响应结果

字段数据项类型(最大长度)是否必填字段含义备注
data code String 是 券号
exchangeResult String 是 兑换结果 00:兑换成功，其他为兑换失败
exchangeDesc String 是 兑换结果描述

券状态变更

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号 多个券号用英文逗号隔开（对接批量券状态更新需提前和易百沟通，暂时默认不支持批量操作）
traceNo String 是 交易流水号 全局唯一
updateType String 是 更新类型 支持作废、冻结、解冻; 枚举值见备注

注： updateType 枚举

updateType 操作名称 更新前状态 更新后状态 备注
invalid 串码作废 00：未使用、初始化
03：未激活
04：已冻结		 05:已作废
freeze 冻结串码 00：未使用 04：已冻结 已冻结的串码，可以调用解冻操作后恢复原状态
unfreeze 解冻串码 04：已冻结 00：未使用

响应结果

字段 数据项 类型(最大长度) 是否必填 字段含义 备注

data

 code String 是 券号
codeUpdateResult String 是 券更新结果

00:更新成功，

其他为失败

券码核销

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号 多张券码用逗号隔开，英文逗号
traceNo String 是 交易流水号 全局唯一
shopNo String 是 门店编号
shopName String 否 门店名称
tansTime String 是 核销时间 格式 yyyyMMddhhssSSS
goodsList List<GoodsInfo> 否 券兑换的商品明细 代金券默认为A0001
totalAmount String 是 订单总金额 单位（元）
verifyScene String 是 核销场景 线上：online, 线下：offline

GoodsInfo

字段 类型(最大长度) 是否必填 字段含义 备注
goodsId String 是 券兑换商品id
price String 是 兑换商品金额 全局唯一
rebateCode String 否 标签编号
count String 是 兑换商品数量 默认为1

响应结果

字段 数据项 类型(最大长度) 是否必填 字段含义 备注
data List<VerifyResultData> List 是 核销结果集

VerifyResultData定义

字段 类型(最大长度) 是否必填 字段含义 备注
verifyResult String 是 核销结果

00:成功

其他为失败
activityNo String 否 活动编号
activityName String 否 活动名称
totalAmount String 否 订单总金额 单位(元)
userRealAmount String 否 用户购券实付金额 单位(元)
merchantRealAmount String 否 商户实收金额 单位(元)
discountAmount String 否 券折抵金额 单位(元)
channelBenefit String 否 渠道优惠金额 单位(元)
merchantBenefit String 否 商户优惠金额 单位(元)
faceValue String 否 券面值 单位(元)
remainUseTimes String 否 剩余可用次数
code String 是 券号

券核销撤销

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号 多个券用逗号隔开，不传默认撤销originTraceNo 对应核销的所有券
traceNo String 是 当前交易流水号 全局唯一
originTraceNo String 是 核销时上送的流水号
originVerifyDate String 否 原核销日期 yyyyMMdd

响应结果

字段 数据项 类型(最大长度) 是否必填 字段含义 备注
data List<VerifyVoidResultData> List 是 核销撤销结果

VerifyVoidResultData定义

字段 类型(最大长度) 是否必填 字段含义 备注
resultDesc String 否 核销撤销结果结果描述
result String 否 核销撤销结果

00: 成功

其他为失败
code String 是 券号
ticketId String 是 券批次id

券状态变更通知

请求参数

字段 类型(最大长度) 是否必填 字段含义 备注
code String 是 券号
traceNo String 是 当前交易流水号 全局唯一
saleChannelOrderId String 否 发券时渠道侧订单号 核销、核销撤销场景必传
shopNo String 否 核销门店编号 核销场景必传
timeStamp String 否 发生时间戳(毫秒)
notifyType String 是 当前通知交易类型
validStartDate String 否 券有效期开始时间 yyyy-MM-dd HH:mm:ss
validEndDate String 否 券有效期截止时间 yyyy-MM-dd HH:mm:ss

注： notifyType 枚举

notifyType 操作名称 更新前状态 更新后状态
verifyNotify 券核销 未使用 已使用
verifyCancelNotify 券核销撤销 已使用 未使用
invalidNotify 券作废 未使用 已作废
renewalNotify 券延期 已过期 可使用
expireNotify 过期通知 过期 已过期

通知报文（案例）签名过程：

JSONObject notifyJson = new JSONObject(true);

notifyJson.put("code", "10034343334344443209");

notifyJson.put("traceNo", "4200001172202109274275163730");

notifyJson.put("notifyType", "verifyNotify");

byte[] encodeBase64 = Base64.encodeBase64(notifyJson.toJSONString().getBytes("UTF-8"));

String bizContent = new String(encodeBase64, "UTF-8");

Map<String, String> map = new TreeMap<>();

map.put("appKey", "274b9cf9f01543619baa726ed24ddd19");

map.put("action", "verifyNotify");

map.put("format", "json");

map.put("charset", "utf-8");

map.put("signType", "sha256");

map.put("timestamp", "1483372334");

map.put("bizContent", bizContent);

StringBuilder buffer = new StringBuilder();

for (Map.Entry<String, String> item : map.entrySet()) {

buffer.append(item.getKey()).append("=").append(item.getValue()).append("&");

}

String signStr = buffer.toString() + "appSecret=XXXXXXXXXXXX";// appSecret(需易百提供);

String checkSign = SHAUtil.sha256(signStr);

System.out.println(signStr);

System.out.println(checkSign);

}

参与签名报文字符串：

action=verifyNotify&appKey=274b9cf9f01543619baa726ed24ddd19&bizContent=eyJjb2RlIjoiMTAwMzQzNDMzMzQzNDQ0NDMyMDkiLCJ0cmFjZU5vIjoiNDIwMDAwMTE3MjIwMjEwOTI3NDI3NTE2MzczMCIsIm5vdGlmeVR5cGUiOiJ2ZXJpZnlOb3RpZnkifQ==&charset=utf-8&format=json&signType=sha256&timestamp=1483372334&appSecret=XXXXXXXXXXXX

签名结果：

17e9fe1250c33fccf517ce4b5810f2c731fa45058181a15cffc4ab38332460d4

响应结果

字段 类型(最大长度) 是否必填 字段含义 备注
resultDesc String 否 通知结果描述
result String 否 通知结果

00: 成功

其他为失败



券码预核销

基本信息

预核销电子凭证，模拟电子凭证核销交易提前获取核销结果信息；前置校验相关核销逻辑，不会改变券码状态。

请求

请求参数

参数名称 类型 必填 默认值 备注 其他信息
traceNo String 是 收银机流水号 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列  
totalAmount Price 是 交易总金额 单位：元  
undiscountAmount Price 是 不可打折金额 单位：元，没有填写0  
verifyType String 是 核销类型 请与易百技术确认，枚举值：online为线上场景，offline为线下POS场景  
scene String 否 支付场景 条码:bar_code, 二维码:qr_code  
orderSubject String 否 订单标题 最长256  
orderDescription String 否 订单描述 最长256  
qrcode String 是 二维码内容 串号、一维码或二维码内容  
storeInfo Object<storeInfo> 是 门店信息 门店编号、门店名称等
goodsDetail List<goodsDetail> 否 产品明细 验证产品明细时必填  
memberDetail Object<memberDetail> 否 会员信息 会员支付时必填  

请求示例

{
  "traceNo": "9900000910001011320150201",
  "totalAmount": 40.8,
  "undiscountAmount": 0,
  "activityProductNo": "HDCP00000000001234",
  "qrcode": "280123121234567890",
  "lockTime": "300",
  "afterLock": "0",
  "goodsDetail": [
    {
      "goodsCategory": "001",
      "goodsId": "P00001",
      "goodsName": "牙膏",
      "price": 8,
      "quantity": 2,
      "rebateCode": "000"
    },
    {
      "goodsCategory": "101",
      "goodsId": "P00002",
      "goodsName": "洗发水",
      "price": 24.8,
      "quantity": 1,
      "rebateCode": "000"
    }
  ],
  "memberDetail": {
    "memberId": "M000001545",
    "memberName": "TONY",
    "grade": "1",
    "status": "1",
    "balance": 1000,
    "pointBalance": 30000
  },
  "storeInfo": {
    "shopNo": "6788",
    "shopName": "屈臣氏梧州蝶山区大学路旺城广场店"
  }
}

响应

响应参数

参数名称 类型 必填 默认值 备注 其他信息
traceNo String 是 收银机流水号 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列
orderNo String 是 交易订单号 易百生成
transDate String 是 交易时间 格式为：yyyyMMddHHmmss
returnCode String 是 返回码 00表示交易成功，其他表示失败
returnDesc String 是 返回信息 交易结果描述或错误原因
paidAmount Price 是 支付成功总金额 单位：元
receiptAmount Price 否 商户实收金额 单位：元
invoiceAmount Price 否 商户开票金额 单位：元
remainTimes Number 是 券码当前可用次数 如果有限制每天使用多少次，代表当天可使用次数｜
lockTime String 否 锁定时间,单位（秒） 默认：300
afterLock String 否 锁定和解锁，锁定：1，解锁：0 默认：1，锁定返回校验参数
exchangeRate Number(8,6) 否 汇率 1外币等于多少人民币
currency String 否 货币类型 例如:CNY
discountCode String 否 折扣编码 由收银机分配，用于入账计折扣类型和折扣金额
discountNum Number 否 固定金额折扣数量 用于入账计折扣类型的数量
tenderCode String 否 支付方式编码 由收银机分配，用于入账计支付方式和入账金额
activityProductNo String 否 活动产品编号

activityProductName String 否 活动产品名称

goodsDetail List<goodsDetail> 否 折抵产品明细 返回后台已抵扣成功的产品明细
fundChannel List<fundChannel> 否 资金渠道

printDetail Object<printDetail> 否 打印信息 如需要在收银小票上打印信息时必填
memberDetail Object<memberDetail> 否 会员信息 返回本次交易的会员信息
voucherDetail List<voucherDetail> 否 优惠券信息 返回本次交易的优惠券信息
extendsData Object<extendsData> 否 扩展信息 与ebuy约定

响应示例

{
    "activityProductName":"屈臣氏50元代金券（45元购）_210479",
    "activityProductNo":"00000000954625",
    "canPayAmount":50,
    "extendsData":{
        "oriCode":"10032971483179019246",
        "vDiscountDesc":"",
        "vEndTime":"20260731235959",
        "vUseInfo":"",
        "activityProductId":954625,
        "vStartTime":"20260701000000",
        "ticketType":"cashCoupon"
    },
    "fundChannel":[
        {
            "channelAmount":0,
            "channelName":"用户实际支付",
            "channelNo":"user_real_money"
        }
    ],
    "invoiceAmount":50,
    "orderNo":"206352631301",
    "paidAmount":50,
    "printDetail":{
        "content":"00001F0E652D42757920B5E7D7D3C6BED6A42F0E617574682D707265766572696679"
    },
    "receiptAmount":50,
    "remainTimes":1,
    "returnCode":"00",
    "returnDesc":"操作成功",
    "rpcContext":"10.255.10.6:48450-->10.255.10.190:30032",
    "step":"01",
    "totalAmount":55,
    "uuid":"1ee8a0be009f4c8ebc8a19b088be3f71"
}