# 电子券业务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|是|券状态|<p>00:未使用</p><p>01:已使用</p><p>08:已兑换</p><p>04:已冻结</p><p>05:已作废</p><p>06:已过期</p>|
||codeStatusDesc|String|否|券状态描述||
||activityName|String|否|活动名称||
||activityId|String|否|活动编号||
||activityProductNo|String|否|活动产品编号||
||productName|String|否|产品名称||
||ticketType|String|否|券类型||

# 券兑换

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

响应结果

<table>
  <tr>
    <th>字段</th><th >数据项</th><th >类型(最大长度)</th><th >是否必填</th><th >字段含义</th><th >备注</th>
  </tr>
  <tr  align="center" valign = "middle">
    <td rowspan="4">data</td>
    <td>code</td>
    <td>String</td>
    <td>是</td>
    <td>券号</td>
    <td></td>
  </tr>
  <tr  align="center" valign = "middle">
    <td>exchangeResult</td>
    <td>String</td>
    <td>是</td>
   <td>兑换结果</td>
    <td>00:兑换成功，其他为兑换失败</td>
  </tr>
   <tr  align="center" valign = "middle">
    <td>exchangeDesc</td>
    <td>String</td>
    <td>是</td>
    <td>兑换结果描述</td>
    <td>  </td>
  </tr>
</table>
<br>

# 券状态变更

请求参数

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

注：  updateType 枚举


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


响应结果

|字段|数据项|类型(最大长度)|是否必填|字段含义|备注|
| - | - | - | - | - | - |
|<p></p><p>data</p>|code|String|是|券号||
||codeUpdateResult|String|是|券更新结果|<p>00:更新成功，</p><p>其他为失败</p>|

# 券码核销

请求参数

|字段|类型(最大长度)|是否必填|字段含义|备注|
| - | - | - | - | - |
|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|是|核销结果|<p>00:成功</p><p></p><p>其他为失败</p><p></p>|
|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|否|核销撤销结果|<p>00: 成功</p><p>其他为失败</p>|
|code|String|是|券号||
|ticketId|String|是|券批次id|<p> </p><p></p>|

# 券状态变更通知

请求参数

|字段|类型(最大长度)|是否必填|字段含义|备注|
| - | - | - | - | - |
|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|否|通知结果|<p>00: 成功</p><p>其他为失败</p>|

<br><br>

# 券码预核销

## 基本信息

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

## 请求

### 请求参数


<table border="1" id="bkmrk-%E5%8F%82%E6%95%B0%E5%90%8D%E7%A7%B0-%E7%B1%BB%E5%9E%8B-%E5%BF%85%E5%A1%AB-%E9%BB%98%E8%AE%A4%E5%80%BC-%E5%A4%87%E6%B3%A8-%E5%85%B6%E4%BB%96" style="border-collapse: collapse; width: 100%; height: 619.524px;"><colgroup><col style="width: 21.2157%;"></col><col style="width: 22.0501%;"></col><col style="width: 6.7938%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">参数名称</td><td style="height: 29.7969px;">类型</td><td style="height: 29.7969px;">必填</td><td style="height: 29.7969px;">默认值</td><td style="height: 29.7969px;">备注</td><td style="height: 29.7969px;">其他信息</td></tr><tr style="height: 80.1875px;"><td style="height: 80.1875px;">traceNo</td><td style="height: 80.1875px;">String</td><td style="height: 80.1875px;">是</td><td style="height: 80.1875px;">收银机流水号</td><td style="height: 80.1875px;">不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列</td><td style="height: 80.1875px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">totalAmount</td><td style="height: 46.5938px;">Price</td><td style="height: 46.5938px;">是</td><td style="height: 46.5938px;">交易总金额</td><td style="height: 46.5938px;">单位：元</td><td style="height: 46.5938px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">undiscountAmount</td><td style="height: 46.5938px;">Price</td><td style="height: 46.5938px;">是</td><td style="height: 46.5938px;">不可打折金额</td><td style="height: 46.5938px;">单位：元，没有填写0</td><td style="height: 46.5938px;"> </td></tr><tr style="height: 96.9844px;"><td style="height: 96.9844px;">verifyType</td><td style="height: 96.9844px;">String</td><td style="height: 96.9844px;">是</td><td style="height: 96.9844px;">核销类型</td><td style="height: 96.9844px;">请与易百技术确认，枚举值：online为线上场景，offline为线下POS场景</td><td style="height: 96.9844px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">scene</td><td style="height: 46.5938px;">String</td><td style="height: 46.5938px;">否</td><td style="height: 46.5938px;">支付场景</td><td style="height: 46.5938px;">条码:bar\_code, 二维码:qr\_code</td><td style="height: 46.5938px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">orderSubject</td><td style="height: 46.5938px;">String</td><td style="height: 46.5938px;">否</td><td style="height: 46.5938px;">订单标题</td><td style="height: 46.5938px;">最长256</td><td style="height: 46.5938px;"> </td></tr><tr style="height: 39.7969px;"><td style="height: 39.7969px;">orderDescription</td><td style="height: 39.7969px;">String</td><td style="height: 39.7969px;">否</td><td style="height: 39.7969px;">订单描述</td><td style="height: 39.7969px;">最长256</td><td style="height: 39.7969px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">qrcode</td><td style="height: 46.5938px;">String</td><td style="height: 46.5938px;">是</td><td style="height: 46.5938px;">二维码内容</td><td style="height: 46.5938px;">串号、一维码或二维码内容</td><td style="height: 46.5938px;"> </td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">storeInfo</td><td style="height: 46.5938px;">Object&lt;[storeInfo](https://book.e-buy.com/books/e-buy-B6z/page/96da2)&gt;</td><td style="height: 46.5938px;">是</td><td style="height: 46.5938px;">门店信息</td><td style="height: 46.5938px;">门店编号、门店名称等</td><td style="height: 46.5938px;">  
</td></tr><tr style="height: 57.7969px;"><td style="height: 57.7969px;">goodsDetail</td><td style="height: 57.7969px;">List&lt;[goodsDetail](https://book.e-buy.com/books/e-buy-B6z/page/3def1 "goodsDetail")&gt;</td><td style="height: 57.7969px;">否</td><td style="height: 57.7969px;">产品明细</td><td style="height: 57.7969px;">验证产品明细时必填</td><td style="height: 57.7969px;"> </td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">memberDetail</td><td style="height: 35.3984px;">Object&lt;[memberDetail](https://book.e-buy.com/books/e-buy-B6z/page/9fc3d "memberDetail")&gt;</td><td style="height: 35.3984px;">否</td><td style="height: 35.3984px;">会员信息</td><td style="height: 35.3984px;">会员支付时必填</td><td style="height: 35.3984px;"> </td></tr></tbody></table>

### 请求示例

```json
{
  "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": "屈臣氏梧州蝶山区大学路旺城广场店"
  }
}
```

## 响应

### 响应参数

<table border="1" id="bkmrk-%E5%8F%82%E6%95%B0%E5%90%8D%E7%A7%B0-%E7%B1%BB%E5%9E%8B-%E5%BF%85%E5%A1%AB-%E9%BB%98%E8%AE%A4%E5%80%BC-%E5%A4%87%E6%B3%A8-%E5%85%B6%E4%BB%96-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col></colgroup><tbody><tr><td>参数名称</td><td>类型</td><td>必填</td><td>默认值</td><td>备注</td><td>其他信息</td></tr><tr><td>traceNo</td><td>String</td><td>是</td><td>收银机流水号</td><td>不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列</td><td>  
</td></tr><tr><td>orderNo</td><td>String</td><td>是</td><td>交易订单号</td><td>易百生成</td><td>  
</td></tr><tr><td>transDate</td><td>String</td><td>是</td><td>交易时间</td><td>格式为：yyyyMMddHHmmss</td><td>  
</td></tr><tr><td>returnCode</td><td>String</td><td>是</td><td>返回码</td><td>00表示交易成功，其他表示失败</td><td>  
</td></tr><tr><td>returnDesc</td><td>String</td><td>是</td><td>返回信息</td><td>交易结果描述或错误原因</td><td>  
</td></tr><tr><td>paidAmount</td><td>Price</td><td>是</td><td>支付成功总金额</td><td>单位：元</td><td>  
</td></tr><tr><td>receiptAmount</td><td>Price</td><td>否</td><td>商户实收金额</td><td>单位：元</td><td>  
</td></tr><tr><td>invoiceAmount</td><td>Price</td><td>否</td><td>商户开票金额</td><td>单位：元</td><td>  
</td></tr><tr><td>remainTimes</td><td>Number</td><td>是</td><td>券码当前可用次数</td><td>如果有限制每天使用多少次，代表当天可使用次数｜</td><td>  
</td></tr><tr><td>lockTime</td><td>String</td><td>否</td><td>锁定时间,单位（秒）</td><td>默认：300</td><td>  
</td></tr><tr><td>afterLock</td><td>String</td><td>否</td><td>锁定和解锁，锁定：1，解锁：0</td><td>默认：1，锁定返回校验参数</td><td>  
</td></tr><tr><td>exchangeRate</td><td>Number(8,6)</td><td>否</td><td>汇率</td><td>1外币等于多少人民币</td><td>  
</td></tr><tr><td>currency</td><td>String</td><td>否</td><td>货币类型</td><td>例如:CNY</td><td>  
</td></tr><tr><td>discountCode</td><td>String</td><td>否</td><td>折扣编码</td><td>由收银机分配，用于入账计折扣类型和折扣金额</td><td>  
</td></tr><tr><td>discountNum</td><td>Number</td><td>否</td><td>固定金额折扣数量</td><td>用于入账计折扣类型的数量</td><td>  
</td></tr><tr><td>tenderCode</td><td>String</td><td>否</td><td>支付方式编码</td><td>由收银机分配，用于入账计支付方式和入账金额</td><td>  
</td></tr><tr><td>activityProductNo</td><td>String</td><td>否</td><td>活动产品编号</td><td>  
</td><td>  
</td></tr><tr><td>activityProductName</td><td>String</td><td>否</td><td>活动产品名称</td><td>  
</td><td>  
</td></tr><tr><td>goodsDetail</td><td>List&lt;[goodsDetail](https://book.e-buy.com/books/e-buy-B6z/page/3def1 "goodsDetail")&gt;</td><td>否</td><td>折抵产品明细</td><td>返回后台已抵扣成功的产品明细</td><td>  
</td></tr><tr><td>fundChannel</td><td>List&lt;[fundChannel](https://book.e-buy.com/books/e-buy-B6z/page/14bfa "fundChannel")&gt;</td><td>否</td><td>资金渠道</td><td>  
</td><td>  
</td></tr><tr><td>printDetail</td><td>Object&lt;[printDetail](https://book.e-buy.com/books/e-buy-B6z/page/eed5a "printDetail")&gt;</td><td>否</td><td>打印信息</td><td>如需要在收银小票上打印信息时必填</td><td>  
</td></tr><tr><td>memberDetail</td><td>Object&lt;[memberDetail](https://book.e-buy.com/books/e-buy-B6z/page/9fc3d "memberDetail")&gt;</td><td>否</td><td>会员信息</td><td>返回本次交易的会员信息</td><td>  
</td></tr><tr><td>voucherDetail</td><td>List&lt;[voucherDetail](https://book.e-buy.com/books/e-buy-B6z/page/8f855 "voucherDetail")&gt;</td><td>否</td><td>优惠券信息</td><td>返回本次交易的优惠券信息</td><td>  
</td></tr><tr><td>extendsData</td><td>Object&lt;[extendsData](https://book.e-buy.com/books/e-buy-B6z/page/06905 "extendsData")&gt;</td><td>否</td><td>扩展信息</td><td>与ebuy约定</td><td>  
</td></tr></tbody></table>

### 响应示例

```json
{
    "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"
}
```