# 星巴克预付费券系统
# 文档介绍
### 文档目的
此为取码方与易百电子凭证对接的报文协议 为实现取码方对接易百制码，制码查询，制码撤销，码信息查询，码状态修改，码信息修改等制码功能
### 开发测环境
- 线上接口路径
```
https://dev-starbucks-gateway.e-buy.com/api/product
```
- 月饼券接口路径
```
https://dev-starbucks-gateway.e-buy.com/starbucksjs
```
- 线下接口路径
```
https://dev-starbucks-gateway.e-buy.com/ebuyweb-posp/api
```
- 运营类后管接口路径
```
https://dev-starbucks-gateway.e-buy.com/41/
```
### 产线环境
- 线上接口路径
```
https://starbucks-gateway.e-buy.com/api/product
```
- 月饼券接口路径
```
https://starbucks-gateway.e-buy.com/js
```
- 线下接口路径
```
https://starbucks-gateway.e-buy.com/ebuyweb-posp/api
```
- 运营类后管接口路径
```
https://starbucks-gateway.e-buy.com/41/
```
# 名词解释
#### HTTP
基于[HTTP](https://book.e-buy.com/books/e-buy-40/page/7f100 "基于HTTP协议的通讯方式")协议的通讯方式
#### JSON
网络通信时的一种数据交互格式
#### WHALE
易百电子凭证4.0系统的别称
#### JWT
[JWT](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")是[JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") 格式来传递信息。 一个[JWT](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。
1. header 完整的头部就像下面这样的JSON： { "typ": "JWT", "alg": "HS256" } 然后将头部进行base64加密（该加密是可以对称解密的),构成了第一部分： eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
2. playload 载荷就是存放有效信息的地方，这些有效信息包含三个部分：标准中注册的声明、公共的声明、私有的声明。 标准中注册的声明 (建议但不强制使用)： iss: [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")签发者 sub: [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")所面向的用户 aud: 接收[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的一方 exp: [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的过期时间，这个过期时间必须要大于签发时间 nbf: 定义在什么时间之前，该[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")都是不可用的 iat: [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的签发时间 jti: [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的唯一身份标识，主要用来作为一次性token,从而回避重放攻击。 公共的声明 ： 公共的声明可以添加任何的信息，一般添加用户的相关信息或其他业务需要的必要信息.但不建议添加敏感信息，因为该部分在客户端可解密。 私有的声明 ： 私有声明是提供者和消费者所共同定义的声明，一般不建议存放敏感信息，因为base64是对称解密的，意味着该部分信息可以归类为明文信息。 定义一个payload： { "username":"张三", "password":"zs123456", "dynamic Code":"EBUY123456789abcdefg" } 然后将其进行base64加密，得到[JWT](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的第二部分： eyJvcmciOiLku4rml6XlpLTmnaEiLCJuYW1lIjoiRnJlZeeggeWGnCIsImV4cCI6MTUxNDM1NjEwMywiaWF0IjoxNTE0MzU2MDQzLCJhZ2UiOiIyOCJ9
3. signature [JWT](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的第三部分是一个签证信息，这个签证信息由三部分组成： header (base64后的) payload (base64后的) secret 这个部分需要base64加密后的header和base64加密后的payload使用.连接组成的字符串，然后通过header中声明的加密方式进行加盐secret组合加密，然后就构成了[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")的第三部分：49UF72vSkj-sA4aHHiYN5eoZ9Nb4w5Vb45PsLF7x\_NY 密钥secret是保存在服务端的，服务端会根据这个密钥进行生成token和验证，所以需要保护好。
# 业务参数对象
# 券码历史记录
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为returnData，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| String | 是 | 交易时间 | 格式: yyyyMMddHHmmss |
| String | 是 | 返回编码 | 00 |
| String | 是 | 返回编码描述 |
|
| String | 是 | 券码 |
|
| String | 否 | 商户号 |
|
| String | 否 | 门店名称 |
|
| String | 是 | 交易类型 | 1 发码 2 核销 3 作废 4核销撤销 |
| String | 否 | 门店号 |
|
| String | 否 | 终端号 |
|
| String | 否 | 索引序号 |
|
| [JSON](https://book.e-buy.com/books/c20ad/page/fe73f) | 否 | 扩展自定义字段 |
|
# 资金渠道
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`fundsChannel`，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| totalAmount | Number | 否 | 订单总金额 | 单位：分。totalAmount = discountAmount + userRealAmount |
| discountAmount | Number | 否 | 折扣金额 | 单位：分。discountAmount = merchantBenefit + channelBenefit |
| merchantRealAmount | Number | 否 | 商户实收金额 | 单位：分。merchantRealAmount = totalAmount - merchantBenefit |
| channelBenefit | Number | 否 | 渠道出资优惠 | 单位：分 |
| merchantBenefit | Number | 否 | 商户出资优惠 | 单位：分 |
| userRealAmount | Number | 否 | 用户实付金额 | 单位：分 |
# 余额资金渠道
- - [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`remainFundsChannel`，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| remainTotalAmount | Number | 否 | 剩余订单总金额 | 单位：分。 |
| remainDiscountAmount | Number | 否 | 剩余折扣金额 | 单位：分。 |
| remainMerchantRealAmount | Number | 否 | 剩余商户实收金额 | 单位：分。 |
| remainChannelBenefit | Number | 否 | 剩余渠道出资优惠 | 单位：分 |
| remainMerchantBenefit | Number | 否 | 剩余商户出资优惠 | 单位：分 |
| remainUserRealAmount | Number | 否 | 剩余用户实付金额 | 单位：分 |
# 核销资金渠道
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`verifyFundsChannel`，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| totalAmount | Number | 否 | 订单总金额 | 单位：分。totalAmount = discountAmount + userRealAmount |
| discountAmount | Number | 否 | 折扣金额 | 单位：分。discountAmount = merchantBenefit + channelBenefit |
| merchantRealAmount | Number | 否 | 商户实收金额(A账户) | 单位：分。merchantRealAmount = totalAmount - merchantBenefit |
| merchantCustomRealAmount | Number | 否 | 商户指定实收金额 | 单位：分。默认：-1。当商户制码或激活时指定实收金额，在核销时该字段与merchantRealAmount均为指定实收金额 |
| channelBenefit | Number | 否 | 渠道出资优惠 | 单位：分 |
| merchantBenefit | Number | 否 | 商户出资优惠
(B账户)
| 单位：分 |
| userRealAmount | Number | 否 | 用户实付金额 | 单位：分 |
| seq | Number | 否 | 阶梯序号 |
|
| seqStatus | String | 否 | 阶梯状态 | 00 初始化 01 已使用 |
| verifyRequestId | String | 否 | 核销流水号 | 对应当前阶梯流水号(单次订单层级) |
# 下单制码资金渠道
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeFundsChannel`，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| totalAmount | Number | 是 | 总金额(A+B) | 单位：分 |
| channelBenefit | Number | 否 | 渠道出资优惠 | 单位：分 |
| merchantBenefit | Number | 否 | 商户出资优惠(B账户) | 单位：分 |
| userRealAmount | Number | 否 | 用户实付金额 | 单位：分 |
| merchantRealAmount | Number | 否 | 商户实收金额(A账户) | 单位：分 |
| seq | Number | 否 | 阶梯序号 |
|
# 产品明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`goodsDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| sku | String | 是 | 商品SKU | |
| qty | Integer | 是 | 数量 | |
| price | Number | 是 | 单价 | 单位：分 |
| type | String | 是 | 商品品类 | |
| spec | String | 是 | 商品规格 | |
| rebateCode | String | 否 | 折扣代码 | 当收银端折扣过产品不能在后端再次折扣时在此标注 |
# 会员信息
### 码明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`memberDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| memberId | String | 否 | 会员ID | |
| memberName | String | 否 | 会员名称 | |
| grade | String | 否 | 会员等级 | |
| status | String | 否 | 会员状态 | |
| memberCode | String | 否 | 会员号码 | |
| balance | Long | 否 | 会员余额 | 单位：分 |
| pointBalance | Long | 否 | 会员积分余额 | 单位：分 |
# 兑换码明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`redeemCodeDetail`，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| realCode | String | 是 | 兑换码兑换后的真实串码号 | |
| realTicketId | Long | 是 | 兑换码兑换后的真实券id | |
| realTicketName | String | 是 | 兑换码兑换后的真实券名称 |
# 用户通知类型
### 制码通知类型
- 制码时，当需要易百通知到用户，可由取码方指定通知渠道及渠道用户信息
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| mobilePhone | String | 否 | 短信通知手机号 | |
| weiChat | String | 否 | 微信通知openId | 暂不支持 |
| aliPay | String | 否 | 支付宝通知id | 暂不支持 |
| thirdUserId | String | 否 | 第三方平台用户id | 不做业务处理，仅作为参数传递 |
| weChatCardPackageNotify | Object<[weChatCardPackageNotify](https://book.e-buy.com/books/e-buy-40/page/0a09c "weChatCardPackageNotify")> | 否 | 微信卡包通知 | |
# 微信卡包制码通知类型
- 当取码方需要易百协助调用制码方完成微信卡包通知时，制码时上传该字段
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| userUnionId | String | 否 | 微信用户唯一识别号 | |
| appId | String | 否 | 公众号id | |
| userOpenId | String | 否 | 微信用户唯一识别号 | |
| sendChannelId | String | 否 | 渠道id | 若是易百自制码，需要调用外部渠道进行微信卡包通知时上传该字段，字段值由易百事先分配；若是第三方制码，需要调用该制码方微信靠包通知接口时，无需上传该字段 |
# 码状态更新操作类型
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`updateOpts`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| updatePurchaseTime | String | 否 | 修改实际购买时间 | yyyyMMddHHmmss |
| updateValidEnd | String | 否 | 修改实际有效截至时间 | yyyyMMddHHmmss |
| updatePurchaseOrderNum | String | 否 | 修改用户购买订单号 | |
| updateMakeNotifyType | Object<[makeNotifyType](https://book.e-buy.com/books/e-buy-40/page/26657 "makeNotifyType")> | 否 | 修改制码通知信息 | |
| updateVerifyNotifyType | Object<[verifyNotifyType](https://book.e-buy.com/books/e-buy-40/page/26657 "verifyNotifyType")> | 否 | 修改核销通知信息 | |
| updateMerchantRealAmount | Long | 否 | 修改商户实收金额 | 单位：分 |
| updateMemberDetail | Object<[memberDetail](https://book.e-buy.com/books/e-buy-40/page/950a4 "memberDetail")> | 否 | 修改会员信息 | |
| activateShopNo | String(10) | 否 | 激活门店号 | |
| activateOrg | String(10) | 否 | 激活机构 | |
| remark | String(200) | 否 | 串码备注信息 |
# 码信息查询返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeQueryResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| codeDetail | List<[codeQueryCodeDetail](https://book.e-buy.com/books/e-buy-40/page/8cb22 "codeQueryCodeDetail")> | 否 | 码信息 |
# 码明细查询
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeQueryCodeDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 码号 | |
| saleChannelOrderId | String | 是 | 取码方制码订单号 | |
| saleChannelName | String | 是 | 取码方名称 | |
| saleChannelCode | String | 是 | 取码方code | |
| sendChannelName | String | 是 | 制码方名称 | |
| useTimes | Integer | 是 | 总可使用次数 | |
| remainTimes | Integer | 是 | 剩余核销次数 | |
| verifyTimes | Integer | 是 | 已核销次数 | |
| createDate | String | 是 | 码创建日期 | yyyyMMdd |
| createTime | String | 是 | 码创建时间 | yyyyMMddHHmmss |
| validStart | String | 否 | 码有效开始时间 | yyyyMMddHHmmss |
| validEnd | String | 否 | 码有效结束时间 | yyyyMMddHHmmss |
| activateDate | String | 否 | 激活日期 | yyyyMMdd |
| activateTime | String | 否 | 激活时间 | yyyyMMddHHmmss |
| activateShopNo | String | 否 | 激活门店 | |
| verifyDate | String | 否 | 码核销日期 | yyyyMMdd |
| verifyTime | String | 否 | 码核销时间 | yyyyMMddHHmmss |
| status | String | 是 | 状态 | |
| statusDesc | String | 是 | 状态描述 | |
| cityCheck | String | 否 | 劵所在城市是否可用 | Y可用N不可用。第三方码核销逻辑受第三方控制时，此字段无意义 |
| ticketId | String | 是 | 易百活动产品id | 由于历史原因，该字段存放易百活动产品id |
| whaleTicketId | String | 是 | 券id | 券系统中券批次id，例：1000000006400 |
| ticketName | String | 是 | 券名称 | |
| activityId | String | 是 | 活动id | |
| activityName | String | 是 | 活动名称 | |
| faceValue | Number | 否 | 券面值 | 单位：分 |
| shopNo | String | 否 | 核销门店编号 | |
| shopName | String | 否 | 核销门店名称 | |
| codeRemark | String | 否 | 串码备注字段 | |
| ebuyActivityProductId | String | 是 | 易百活动产品id | |
| ebuyActivityProductNo | String | 否 | 易百活动产品编号 | |
| fundsChannel | Object<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/0777d "fundsChannel")> | 否 | 资金渠道 | 在制码或激活时上传的资金明细 |
| remainFundsChannel | Object<[remainFundsChannel](https://book.e-buy.com/books/e-buy-40/page/2b449 "remainFundsChannel")> | 否 | 余额资金渠道 | |
| fundsChannels | Array<[fundChannel](https://book.e-buy.com/books/e-buy-40/page/0777d "fundsChannel")> | 否 | 资金渠道列表 | 仅针对阶梯价场景 |
# 阶梯价核销券码明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为codeArr，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 否 | 券码 |
|
| seq | Number | 否 | 阶梯序号 |
|
# 制码请求子订单明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`Items`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelItemId | String | 是 | 取码方子订单号 | 小于32个字符 |
| ticketId | Long | 否 | 券id | 一个产品对应一个券id，由易百提供。当是普通券活动时，此处必填。 |
| activityId | Long | 否 | 券id | 一个组合券活动对应一个活动id，由易百提供。当是组合券活动时，此处必填。ticketId和activityId有且仅有一个上送 |
| commissionDate | String | 否 | 码开启日期 | 0：当日生效，1：次日生效，-1：暂不激活，未激活状态。validDays填写时该字段必填 |
| validDays | Number | 否 | 相对有效天数 | 除制码当天开始相应天数结束。validStart、validEnd组合与validDay、commissionDate组合可选其一，若全部填写以相对有效期优先；若全部不填写，码的有效期以后台配置券有效期为准 |
| validStart | Number(14) | 否 | 码有效开始时间 | 该字段填写时，validEnd必填格式:yyyyMMddHHmmss |
| validEnd | Number(14) | 否 | 码有效结束时间 | 该字段填写时，validStart必填格式:yyyyMMddHHmmss |
| codeNum | Number | 否 | 该券制码数量 | 最小值：1，最大值：100 |
| makeFundsChannels | Array<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel")> | 否 | 资金渠道 | 仅针对阶梯价场景（commissionDate 不为-1）
|
| makeFundsChannel | Object<[makeFundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel")> | 否 | 资金渠道 | 取码方是零售模式时必填
|
# 批量制码订单明细返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchMakeCodeResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| channelOrderId | String | 是 | 取码方订单号 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| codeNum | int | 是 | 总制码数量 |
# 制码/制码查询返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeQueryResponseData`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 取码方订单号 | |
| tradeNo | String | 是 | 易百交易编号 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| isNotify | String | 是 | 是否通知到用户，通知形式以sendType为依据,当是要求手机短信通知时0表示短信未通知成功，当是要求微信卡包时0表示推送到微信卡包未成功 | 0：未通知，1：已通知 |
| codeNum | int | 是 | 总制码数量 | |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 |
| items | List<[makeQueryResponseItem](https://book.e-buy.com/books/e-buy-40/page/138bb "makeQueryResponseItem")> | 否 | 码信息 |
# 制码/制码查询返回明细
### 制码订单查询明细返回
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeQueryResponseItem`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelItemId | String | 是 | 取码方子订单号 | |
| ticketId | String | 否 | 券id | |
| ticketName | String | 否 | 券名称 | |
| brandTicketId | String | 否 | 品牌方券id | |
| thirdSendTicketId | String | 否 | 第三制码方券名称 | |
| ticketUseDescription | Object<[ticketUseDescription](https://book.e-buy.com/books/e-buy-40/page/8cb22-fjz "ticketUseDescription")> | 否 | 码使用描述 | |
| activityId | String | 否 | 活动id | |
| activityName | String | 否 | 活动名称 | |
| itemResultCode | String | 是 | 子订单返回码 | |
| itemResultMsg | String | 是 | 子订单返回信息 | |
| validStart | String | 是 | 码有效开始时间 | yyyyMMddHHmmss |
| validEnd | String | 是 | 码有效结束时间 | yyyyMMddHHmmss |
| codeDetail | List<[codeDetail](https://book.e-buy.com/books/e-buy-40/page/b73ce "codeDetail")> | 否 | 码详情 |
# 制码/制码查询返回码明细
### 订单券码明细返回
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeOrderResponseCodeDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| codeURL | String(100) | 是 | 码链接 | |
| code | String(100) | 是 | 串码 | |
| useTimes | Integer | 是 | 码可核销次数 | |
| status | String(2) | 是 | 状态 | |
| statusDesc | String(10) | 是 | 状态描述 | |
| password | String | 否 | 显示codeURL认证密码 | 此值在某些活动需要，易百会提前告知取码方 |
# 制码撤销返回数据
### 制码订单返回码数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeVoidResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| originalChannelOrderId | String | 是 | 取码方订单号 | |
| tradeNo | String | 是 | 易百订单号 | |
| createDate | String | 是 | 撤销日期 | yyyyMMdd |
| createTime | String | 是 | 撤销时间 | yyyyMMddHHmmss |
| totalNum | int | 是 | 本次总撤销券码数量 | |
| tradeStatus | String | 是 | 表示当前订单的所有券是否都撤销成功 | A:表示全部成功;P:表示部分成功 |
| voidDetails | List<[makeVoidResponseVoidDetail](https://book.e-buy.com/books/e-buy-40/page/9a968 "makeVoidResponseVoidDetail")> | 否 | 撤销信息 |
# 制码撤销返回明细
### 制码订单返回码
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`makeVoidResponseVoidDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ticketId | String | 是 | 券id | |
| originalChannelItemId | String | 是 | 原制码子订单号 | |
| voidNum | int | 是 | 子订单中撤销码数量 |
# 码状态更新返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`statusUpdateData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易号 | |
| requestId | String | 是 | 请求流水号 | |
| currentStatus | String | 是 | 当前码状态 | |
| statusDesc | String | 是 | 状态说明 | |
| updateDate | String | 是 | 更新日期 | |
| updateTime | String | 是 | 更新时间 |
# 批量码激活同步返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchCodeActivateResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 系统内部编号 | |
| requestId | String | 是 | 请求流水号 | |
| saleChannelId | String | 是 | 取码方ID | |
| createDate | Number(8) | 是 | 创建日期 | |
| createTime | Number(14) | 是 | 创建时间 | |
| codeNum | int | 是 | 激活码数量 | |
| resultCode | String | 是 | 批量码激活初步校验结果 | 00成功，其他失败 |
| resultMsg | String | 是 | 批量码激活初步校验结果 |
# 门店信息
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`storeInfo`此信息为线下门店核销时上送
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| swift | String | 否 | pos流水号 | |
| tid | String | 否 | 终端号 | 小于8个字符，有终端限制时必填 |
| mid | String | 否 | 商户号 | 15个长度 |
| cityId | String | 否 | 城市id，对接时使用ebuy城市id | 有城市限制时必须上传 |
| brandId | String | 是 | 品牌id | ebuy分配 |
| shopNo | String | 是 | 门店号 | |
| shopName | String | 是 | 门店名称 | |
| manageCompany | String | 否 | 管理公司名称 | 线下必填 |
| companyId | String | 否 | 管理公司编号 | 线下必填 |
# 查询时门店信息
- - [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`storeInfo`此信息为线下门店核销时上送
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| swift | String | 否 | pos流水号 | |
| tid | String | 否 | 终端号 | 小于8个字符，有终端限制时必填 |
| mid | String | 否 | 商户号 | 15个长度 |
| cityId | String | 否 | 城市id，对接时使用ebuy城市id | 有城市限制时必须上传 |
| brandId | String | 是 | 品牌id | ebuy分配 |
| shopNo | String | 是 | 门店号 | |
| shopName | String | 是 | 门店名称 | |
| manageCompany | String | 否 | 管理公司名称 | 线下必填 |
| companyId | String | 否 | 管理公司编号 | 线下必填 |
# 单码返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`singleMakeOrderResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百订单号 | |
| resultCode | String | 是 | 制码返回码 | |
| resultMsg | String | 是 | 制码返回信息 | |
| saleChannelOrderId | String | 是 | 取码方订单号 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| isNotify | String | 是 | 是否通知到用户，通知形式以sendType为依据,当是要求手机短信通知时0表示短信未通知成功，当是要求微信卡包时0表示推送到微信卡包未成功 | 0：未通知，1：已通知 |
| ticketId | String | 是 | 券id | |
| validStart | String | 是 | 码有效开始时间 | yyyyMMddHHmmss |
| validEnd | String | 是 | 码有效结束时间 | yyyyMMddHHmmss |
| codeDetail | Object<[codeDetail](https://book.e-buy.com/books/e-buy-40/page/b73ce "codeDetail")> | 否 | 码详情 |
# 券码核销返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeVerifyResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| cashTotalAmount | Number | 否 | 原样返回 |
|
| code | String | 是 | 原样返回 |
|
| ticketId | String | 是 | 券ID |
|
| ticketName | String | 是 | 券名称 |
|
| ticketType | String | 是 | 券类型 | cashCoupon(代金券),merchandiseCoupon(商品券),discountCoupon(折扣券),fullReduceCoupon(满减券),buyGetCoupon(买赠券),redeemCoupon(兑换券) |
| activityNo | String | 是 | 活动编号 | 在收银一体化时收银POS可以用此值来区别活动入账 |
| activityName | String | 是 | 表示券所属活动 |
|
| faceValue | Number | 否 | 劵面值 | 单位分 |
| thirdActivityId | String | 是 | 第三方活动id |
|
| returnCashParam | JSONObject | 否 | 扩展字段 | 目前适用于收银机 |
| printData | String | 否 | 此值仅在易百POS上核销时需要用到 |
|
| fundsChannel | Object<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/0777d "fundsChannel")> | 否 | 资金渠道 | 仅在收银一体化时用到 |
| goodsDetail | Object<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/fb7b9 "goodsDetail")> | 否 | 折抵产品明细 | 仅在收银一体化时用到 |
| redeemCodeDetail | Object<[redeemCodeDetail](https://book.e-buy.com/books/e-buy-40/page/060ad "redeemCodeDetail")> | 否 | 兑换码明细 | 当上送的码为兑换码类型时，核销返回兑换后的真实串码信息 |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 |
|
| orderId | String | 否 | 销售渠道id |
|
# 券码核销查询返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeVerifyQueryResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 单个串码核销查询结果 | 00：成功，其他：失败。当查询结果为成功时才会有下列参数返回 |
| returnMsg | String | 是 | 返回结果 | |
| verifyReturnCode | String | 是 | 原核销中该码核销结果 | 00：成功，其他：失败 |
| verifyReturnMsg | String | 是 | 原核销中该码核销结果 | |
| code | String | 是 | 串码号 | |
| saleChannelOrderId | String | 是 | 制码订单号 | |
| cashTotalAmount | String | 否 | 收音机上送总金额 | 单位：分 |
| ticketId | String | 是 | 券ID | |
| ticketName | String | 是 | 券产品名称 | |
| ticketShortName | String | 是 | 券产品短名称 | |
| ebuyActivityProduceId | String | 是 | 易百活动产品id | |
| ebuyActivityProduceNo | String | 是 | 易百活动产品编号 | |
| activityId | String | 是 | 活动id | |
| activityName | String | 是 | 表示券所属活动 | |
| faceValue | String | 否 | 劵面值 | 单位：分 |
| thirdActivityId | String | 是 | 第三方活动id | |
| returnCashParam | JSONObject | 否 | 扩展字段 | 目前适用于收银机 |
| printData | String | 否 | 此值仅在易百POS上核销时需要用到 | |
| fundsChannel | Object<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/0777d "fundsChannel")> | 否 | 资金渠道 | 仅在收银一体化时用到 |
| goodsDetail | Object<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/fb7b9 "goodsDetail")> | 否 | 折抵产品明细 | 仅在收银一体化时用到 |
| redeemCodeDetail | Object<[redeemCodeDetail](https://book.e-buy.com/books/e-buy-40/page/060ad "redeemCodeDetail")> | 否 | 兑换码明细 | 当上送的码为兑换码类型时，核销返回兑换后的真实串码信息 |
# 预核销返回数据
### 预核销明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeCheckResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 劵码 | |
| codeValidStart | String | 是 | 券码有效期开始时间 | |
| codeValidEnd | String | 是 | 劵码有效期结束时间 | |
| saleChannelCode | String | 否 | 取码方编号 | |
| saleChannelName | String | 否 | 取码方名称 | |
| status | String | 是 | 预核销结果 | 00成功，其他失败 |
| discountAmount | String | 否 | 折抵金额 | 单位：分 |
| ticketRemark | String | 否 | 券产品备注信息 | |
| ticketType | String | 是 | 券类型 | cacheCoupon(代金券),merchandiseCoupon(商品券),discountCoupon(折扣券),fullReduceCoupon(满减券),buyGetCoupon(买赠券),redeemCoupon(兑换券) |
| fineGrainedLimit | Object<[fineGrainedLimit](https://book.e-buy.com/books/e-buy-40/page/91831 "fineGrainedLimit")> | 是 | 最细粒度规则限制数量 | |
| ticketUseDescription | Object<[ticketUseDescription](https://book.e-buy.com/books/e-buy-40/page/8cb22-fjz "ticketUseDescription")> | 否 | 券使用描述 |
# 券码批量核销明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchCodeVerifyResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 原样返回 | |
| saleChannelCode | String | 否 | 取码方编号 | |
| saleChannelName | String | 否 | 取码方名称 | |
| ticketId | String | 否 | 券ID | |
| ticketName | String | 否 | 券名称 | |
| activityNo | String | 否 | 活动编号 | |
| activityName | String | 否 | 表示券所属活动 | |
| status | String | 是 | 核销结果 | 00成功，其他失败 |
| statusDesc | String | 是 | 核销结果描述 | 00成功，其他失败 |
| fundsChannel | Object<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/04025 "fundsChannel")> | 否 | 金额 | |
| faceValue | Number | 否 | 劵面值 | 单位分 |
| extendParam | Object | 否 | 扩展字段 | |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 | |
# 批量核销撤销明细
### 券码批量核销撤销明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchCodeVerifyVoidResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 原样返回 | |
| status | String | 是 | 00撤销成功，其他失败 | |
| amount | String | 是 | 金额 | |
| ticketName | String | 否 | 券名称 | |
| statusDesc | String | 是 | 撤销结果描述 |
# 取码方可用券查询返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`channelTicketQueryData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ticketId | String | 否 | 券id | 组合券活动时，此处非必填 |
| ticketName | String | 否 | 券名称 | 组合券活动时，此处非必填 |
| thirdActivityId | String | 是 | 第三方活动id | |
| activityId | String | 是 | 活动id | |
| activityName | int | 是 | 活动名称 | |
| activityType | int | 是 | 活动类型 | 0：普通券活动，1：组合券活动 |
| activityValidStart | String | 是 | 活动开始时间 | yyyyMMddHHmmss |
| activityValidEnd | String | 是 | 活动结束时间 | yyyyMMddHHmmss |
| codeValidStart | String | 是 | 券所制码有效开始时间 | yyyyMMddHHmmss |
| codeValidEnd | String | 是 | 券所制码有效结束时间 | yyyyMMddHHmmss |
| commissionDate | String | 是 | 券启用日期 | 0：当日生效，1：次日生效 |
| codeValidDay | int | 是 | 相对有效天数 | |
| createDate | String | 是 | 券创建日期 | yyyyMMdd |
| createTime | String | 是 | 券创建时间 | yyyyMMddHHmmss |
| serviceProvider | String | 是 | 系统服务提供商 | |
| sendChannelName | String | 是 | 发码方名称 | |
| saleChannelName | String | 是 | 取码方名称 | |
| brandNames | List | 是 | 品牌名称 | 组合券活动时，可能存在多个品牌 |
| activityUseDescription | Object<[activityUseDescription](https://book.e-buy.com/books/e-buy-40/page/a4a04 "activityUseDescription")> | 是 | 活动使用说明 | |
| ticketUseDescription | Object<[ticketUseDescription](https://book.e-buy.com/books/e-buy-40/page/8cb22-fjz "ticketUseDescription")> | 是 | 券使用说明 |
# ESB制码订单明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`Items`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelItemId | String | 是 | 取码方子订单号 | 小于32个字符 |
| tradeItemNo | String | 是 | 易百子订单号 | 小于32个字符 |
| ticketId | Long | 否 | 券id | 若制码方可根据易百券id进行制码则上传 |
| thirdProductId | Long | 否 | 制码方产品id | 若制码方只能根据制码方产品id进行制码则上传，存于券模板中 |
| codeNum | Number | 是 | 该产品制码数量 | 最小值：1，最大值：100。同步制码时只能填1 |
| useTimes | Number | 是 | 单码可兑换次数 | |
| validStart | Number(14) | 否 | 码有效开始时间 | 该字段填写时，validEnd必填格式:yyyyMMddHHmmss |
| validEnd | Number(14) | 否 | 码有效结束时间 | 该字段填写时，validStart必填格式:yyyyMMddHHmmss |
| faceValue | Number | 是 | 面值 | 券模板中配置的面值 |
| netValue | Number | 是 | 净值 | 制码资金渠道中的totalAmount，若取码方未上送则取券模板中默认的净值 |
| needThirdQrcode | int | 是 | 是否需要第三方二维码链接 | 0：否，1：是 |
| needThirdNotify | int | 是 | 是否需要第三方执行制码通知 | 0：否，1：是 |
| notifyType | <[notifyType](https://book.e-buy.com/books/e-buy-40/page/26657 "notifyType")> | 是 | 通知类型 | |
| itemEncryptKey | String | 是 | 报文加密密钥 | 3DES加密时为密钥，公私钥对加密时为公钥字符串。部分制码方根据不同活动配置不同加密密钥 |
# ESB制码订单返回码数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`esbMakeOrderResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelId | String | 是 | 取码方id | 需原样返回 |
| sendChannelId | String | 是 | 制码方id | 需原样返回 |
| sendChannelOrderId | String(64) | 是 | 制码方订单号 | 需原样返回 |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| isNotify | String | 是 | 是否通知到用户，通知形式以sendType为依据,当是要求手机短信通知时0表示短信未通知成功，当是要求微信卡包时0表示推送到微信卡包未成功 | 0：未通知，1：已通知 |
| codeNum | int | 是 | 总制码数量 | |
| items | List<[esbMakeOrderResponseCodes](https://book.e-buy.com/books/e-buy-40/page/esb-5ys "esbMakeOrderResponseCodes")> | 否 | 码信息 |
# ESB制码返回明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`esbMakeCodeResponseItem`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelItemId | String | 是 | 取码方子订单号 | 需原样返回 |
| tradeItemNo | String | 是 | 易百子订单号 | 小于32个字符 |
| ticketId | Long | 否 | 券id | 若制码方可根据易百券id进行制码则上传 |
| thirdProductId | Long | 否 | 制码方产品id | 若制码方只能根据制码方产品id进行制码则上传，存于券模板中 |
| validStart | Number(14) | 否 | 码有效开始时间 | 该字段填写时，validEnd必填格式:yyyyMMddHHmmss |
| validEnd | Number(14) | 否 | 码有效结束时间 | 该字段填写时，validStart必填格式:yyyyMMddHHmmss |
| itemResultCode | String | 是 | 子订单返回码 | |
| itemResultMsg | String | 是 | 子订单返回信息 | |
| codeDetail | List<[codeDetail](https://book.e-buy.com/books/e-buy-40/page/b73ce "codeDetail")> | 否 | 码详情 |
# 活动使用说明
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`activityUseDescription`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| useDescription | String | 否 | 使用说明 |
# 券使用说明
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`ticketUseDescription`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ticketPicture | String | 否 | 券图片 | |
| useThreshold | Long | 否 | 优惠门槛 | 消费满\*元 |
| discountDescription | String | 否 | 优惠说明 | |
| useDescription | String | 否 | 使用说明 | |
| useRule | String | 否 | 使用规则 |
# 最细粒度规则限制数量
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`fineGrainedRuleLimit`，出现在返回报文中，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| grainedKey | String | 是 | 粒度key | day,week,mouth,year,total |
| limitMaxValue | Number | 是 | 最大限制值 | 该粒度下总可使用次数 |
| current | Number | 是 | 当前已使用次数 | 该粒度下已使用次数，包含本次核销 |
# 根据查询码获取手机号返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`getMobileBySearchCodeResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易编号 | |
| mobilePhone | String | 是 | 用户手机号 | tag为01时 |
| [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。") | String | 是 | [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。") | | |
| dynamicCode | String | 是 | 动态码 | tag为02时 |
# 动态码发送手机验证码返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`sendVerificationCodeResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易编号 |
# 校验验证码返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`checkVerificationCodeResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易编号 | |
| dynamicCode | String | 是 | 动态码 | |
| [jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。") | String | 是 | 新[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100 "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。") | |
# 获取动态码返回数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`getDynamicResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易编号 | |
| requestId | String | 是 | 请求流水号原样返回 | |
| dynamicCodeList | List | 是 | 动态码列表 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
# 码更新回调数据
### 券码批量更新回调返回明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeUpdateCallbackData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| searchCode | String | 是 | 查询码 | |
| codeSecret | String | 是 | 密文码 | |
| codeStatus | String | 是 | 券状态 | |
| statusDesc | String | 否 | 状态描述 | |
| returnCode | String | 否 | 返回状态 | |
| returnMsg | String | 否 | 返回信息 | |
| useTimes | int | 是 | 码可使用次数 | |
| validStart | String | 是 | 码有效期开始时间 | |
| validEnd | String | 是 | 码有效期结束时间 | |
| ticketId | String | 是 | 券id | |
| activityId | String | 是 | 活动id | |
| saleChannelId | String | 是 | 取码方id | |
| sendChannelId | String | 是 | 制码方id | |
# 批量码更新返回数据
### 券码批量更新返回明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchCodeUpdateResponseData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 系统内部编号 | |
| requestId | String | 是 | 请求流水号 | |
| codeTotalNum | int | 是 | 待更新码数量 |
# 批量码更新回调数据
### 券码批量更新回调返回明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`batchCodeVoidCallbackData`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 系统内部编号 | |
| requestId | String | 是 | 请求流水号 | |
| totalCodeNum | int | 是 | 总数量 | |
| successCodeNum | int | 是 | 码更新成功数量 | |
| codeUpdateResultArray | List<[codeUpdateCallbackData](https://book.e-buy.com/books/e-buy-40/page/98f13 "codeUpdateCallbackData")> | 是 | 码更新结果集 |
# 串码通知到用户微信卡包接口同步返回报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`notifyCodeToCardPackageResponse`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| tradeNo | String | 是 | 易百交易编号 | |
| requestId | String | 是 | 原样下发 |
# 第三方异步制码通知的券码信息
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`codeFamilyInfoList`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 券码 | |
| codeMask | String | 否 | 电子券掩码 | |
| codeUrl | String | 否 | 短链 | |
| userTimes | Integer | 是 | 使用次数 | |
| codeStatus | String | 是 | 券码状态 | |
| validStart | Date | 是 | 有效期开始时间 | |
| validEnd | Date | 是 | 有效期结束时间 | |
# 激活信息
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为extendData，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| purchaseOrderId | String | 否 | 用户购买订单号 | |
# 核销备注描述
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| oms | String | 否 | OMS订单号 | OMS订单号 |
# 二维码支付或兑换 extendData
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| String | 否 | 门店号 |
|
| String | 否 | 小票号 | |
| String | 否 | pos机号 | |
# 券码历史记录扩展字段
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| String | 否 | 门店号 |
|
| String | 否 | 小票号 | |
| String | 否 | pos机号 | |
| oms | String | 否 | OMS订单号 | OMS订单号 |
# 接入说明
本文档展示了如何通过[http](https://book.e-buy.com/books/e-buy-40/page/7f100 "基于HTTP协议的通讯方式")请求，完成于易百电子凭证系统完成对接。 本文档主要面向的读者为各有需求接入电子凭证的，有一定开发能力的技术人员。
#### 本文档中必填字段仅限于易百自制码，第三方制码可能存在部分字段无法返回。在对接时可与易百技术人员沟通
#### 配置密钥
取码对接方对接时，需跟业务同事沟通后把公钥发送到指定邮箱。易百电子凭证系统会分配app\_id, version, saleChannelId, 易百电子凭证系统公钥等信息
开发者调用接口前需自行生成RSA密钥，RSA密钥包含：
- 应用私钥(APP\_PRIVATE\_KEY)
- 应用公钥(APP\_PUBLIC\_KEY）
#### RSA私钥与公钥生成方法
##### 1.运行 openssl
```
CMD> openssl
```
##### 2.生成明文RSA私钥
```
OpenSSL> genrsa -out rsa_private_key.pem 2048
```
- 其中 `rsa_private_key.pem` 为私钥保存的文件名，`2048`位为密钥长度
- 默认情况下，openssl 输出的密钥格式为 PKCS#1-PEM
##### 3.生成明文RSA公钥
```
OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
```
- 其中 `rsa_private_key.pem` 为私钥保存的文件名，`rsa_public_key.pem`为公钥保存的文件名
##### 4.如果是Java语言，私钥需要转成PKCS8格式
```
OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -out rsa_private_key.pkcs8 -nocrypt
```
- 其中 `rsa_private_key.pem` 为私钥保存的文件名，`rsa_private_key.pkcs8`为私钥PKCS8格式保存的文件名
生成密钥后在电子凭证管理中心进行密钥配置，配置完成后可以获取：
- 电子凭证公钥(WHALE\_PUBLIC\_KEY)。
#### 第三步：搭建和配置开发环境
##### 1.调用方法
| 内容 | 说明 |
|---|
| 通讯方式 | 采用 HTTPS 方式访问 |
| 提交方法 | POST (application/[json](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")) |
| 交互数据格式 | [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") |
| 字符编码 | UTF-8 |
| 签名算法 | SHA256WithRSA |
| 签名验证 | 提交和返回数据都需要验证签名 |
##### 2.报文结构
**请求报文和返回报文都采用如下的报文结构**
| 序号 | 参数 | 类型 | 参考数据 | 参数说明 | 备注 |
|---|
| 1 | action | String | MakeCode | 交易类型 | 具体接口有详细说明 |
| 2 | app\_id | String | 2014072300007148 | 应用ID | 开放平台分配给开发者的应用ID |
| 3 | biz\_content | String | BASE64 | 报文内容BASE64 | 具体接口中有详细说明，本域需要采用BASE64编码 |
| 4 | timestamp | String | 1483372334 | Unix时间戳 | 单位：秒 |
| 5 | version | String | 20171212 | 版本号 | 用于兼容不同的报文协议对应后台不同的处理方式 |
| 6 | sign | String | 7E65B60DCFA42B04 | 数据签名 | 详见：签名算法 |
**注意事项**
- 其中biz\_content字段是对请求参数或返回参数进行BASE64编码后得到的，例如：
[JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")
```
{
"traceNo": "99000009100010101732123",
"originalTraceNo": "99000009100010101732124"
}
```
[JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式")
```
{
"action" : "efuli.cashvoucher.send",
"app_id" : "2014072300007148",
"biz_content" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
"timestamp" : "1483372334",
"version" : "20171212",
"sign" : "7E65B60DCFA42B04"
}
```
```
action=efuli.cashvoucher.send&app_id=2014072300007148&biz_content=ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==×tamp=1483372334&version=20171212
```
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| makeNotifyConf | String | 是 | 制码通知配置 | 00：不通知，01：通知用户 |
| verifyNotifyConf | String | 是 | 核销通知配置 | 00：不通知，01：通知取码方，02：通知制码方，03：通知用户（多选时以"&"分隔，如01&02&03） |
| voidNotifyConf | String | 是 | 撤销通知配置 | 00：不通知，01：通知取码方，02：通知制码方，03：通知用户（多选时以"&"分隔，如01&02&03） |
| smsMakeNotifySrc | String | 否 | 制码通知类型 | 制码短信通道 |
| smsVerifyNotifySrc | String | 否 | 制码通知类型 | 核销短信通道 |
| makeNotify2UserTemplate | String | 否 | 制码通知用户模板 | |
| verifyNotify2UserTemplate | String | 否 | 核销通知用户模板 | |
| printTemplate | String | 否 | 小票打印模板 | |
| thirdCodeMap | String | 否 | 收银对接方编号 | |
| paymentParam | String | 否 | 收银机支付参数 | |
| needEbuyQrcode | String | 否 | 是否需要易百二维码 | 0：是，1：否 |
| needThirdQrcode | String | 否 | 是否需要第三方二维码 | 0：是，1：否 |
| needBarcode | String | 否 | 是否需要条形码 | 0：是，1：否 |
| connector | String | 否 | 合成码时指定查询码与验证码之间的连接符，默认“-” | |
| productType | String | 否 | 产品类型 | codeType为纸质码时使用 |
| productSize | String | 否 | 产品规格 | codeType为纸质码时使用 |
| codeType | String | 否 | 所制码类型 | 01：原始码，02：合成码，03：纸质码 |
# 券配置项
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| batchMakeNotifyConf | String | 是 | 批量制码接口通知配置 | 00：不通知，01：通知用户 |
| makeNotifyConf | String | 是 | 同步实时制码通知配置 | 00：不通知，01：通知用户 |
| verifyNotifyConf | String | 是 | 核销通知配置 | 00：不通知，01：通知取码方，02：通知制码方，03：通知用户（多选时以"&"分隔，如01&02&03） |
| voidNotifyConf | String | 是 | 撤销通知配置 | 00：不通知，01：通知取码方，02：通知制码方，03：通知用户（多选时以"&"分隔，如01&02&03） |
| smsMakeNotifySrc | String | 否 | 制码通知类型 | 制码短信通道 |
| smsVerifyNotifySrc | String | 否 | 制码通知类型 | 核销短信通道 |
| makeNotify2UserTemplate | String | 否 | 制码通知用户模板 | |
| verifyNotify2UserTemplate | String | 否 | 核销通知用户模板 | |
| verifyVoidNotify2UserTemplate | String | 否 | 核销撤销通知用户模板 | |
| printTemplate | String | 否 | 小票打印模板 | |
| thirdCodeMap | String | 否 | 收银对接方编号 | |
| paymentParam | String | 否 | 收银机支付参数 | |
| needEbuyQrcode | String | 否 | 是否需要易百二维码 | 0：否，1：是 |
| needThirdQrcode | String | 否 | 是否需要第三方二维码 | 0：否，1：是 |
| needBarcode | String | 否 | 是否需要条形码 | 0：否，1：是 |
| onlyAllowOneVerify | String | 否 | 一笔订单是否只能优惠一次 | N:否（默认）Y：是 |
| returnBuyProduct | String | 否 | 是否下发参与活动的买产品 | N:否（默认）Y：是 |
| needDynamicCode | String | 否 | 是否需要动态码 | N:否（默认）Y：是 |
# 发码方配置项
### 制码渠道配置
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| makeCodeUrl | String | 否 | 第三方制码URL | |
| needRealTimeVerify | String | 否 | 是否需要第三方接口实时核销 | 0：是，1：否 |
| forwardLink | String | 否 | 券使用跳转链接 |
# 取码方配置项
### 销售渠道配置
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| messageFormat | String | 否 | 与取码方对接时报文格式 | ebuy：易百标准格式，third：取码方报文格式 |
| needRealTimeVerify | String | 否 | 是否需要实时调用核销接口 | Y：是，N：否 |
| verifyUrl | String | 否 | 实时调用核销接口URL | |
| needRealTimeVerifyVoid | String | 否 | 是否需要实时调用核销撤销接口 | Y：是，N：否 |
| verifyVoidUrl | String | 否 | 实时调用核销撤销接口URL | |
| makeCallBackUrl | String | 否 | 异步制码时的回调接口 | |
| verifyCallBackUrl | String | 否 | 核销时的回调接口 | |
| voidVerifyCallBackUrl | String | 否 | 核销撤销时的回调接口 | |
| signKey | String | 否 | 签名key | |
| shortLinkModel | String | 否 | 取码方短链获取模式 | 00：默认模式，易百自制短链。01：自定义模式1，将码拼接到指定长链后，转换成短链。自定义模式2：将码做3DES加密，转成BaseString后拼接到指定长链，再转换成短链 |
| longLinkTemplate | String | 否 | 取码方长链模板 | 短链获取模式01、02时必填 |
| tripleDESKey | String | 否 | 3DES加密key | 短链获取模式02时必填 |
| activateOrg | String | 否 | 取码方对应的激活机构 | 用于对账表等有需要激活机构时 |
| activateShopNo | String | 否 | 取码方对应的激活门店 | 用于对账表等有需要激活门店时 |
# 线上交易类接口
# 同步单品发码（单个&批量发码与激活）
#### **接口用途**
- 支持请码方一次单品请求调用,单品发码数量上限100
#### **接口说明**
- 每次调用时必须有明确的渠道订单编号。
- commissionDate = -1时，所制码不具有支付功能（即码没有激活），如果需要激活该码的支付功能需要再次调用"码激活"接口。
- 同步单条发码时，saleChannelOrderId和saleChannelItemId可用同一值。
- returnCode = "00"时，说明订单进入制码流程。itemResultCode = "00"时，说明订单制码成。
- notifyType为券码发送到用户的形式，是否需要通知以券配置为开关
#### **action**
- `MakeCode`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 渠道制码订单id | 最长32位，当上送相同订单号时返回上一次成功信息，如果上一次请码失败，则本次会重新生成码 |
| requestId | String | 是 | 请求流水号 | 最长32位，用于标识唯一一笔交易 |
| remark | JSONString | 是 | 订单备注信息 | 最长200位，订单查询时原样返回 |
| notifyType | Object<[notifyType](https://book.e-buy.com/books/e-buy-40/page/26657 "notifyType")> | 否 | 制码通知类型 | |
| item | Object<[makeOrderItems](https://book.e-buy.com/books/e-buy-40/page/3ad7c "makeOrderItems")> | 是 | 制码明细 | 同步制码时，仅支持单产品单码 |
**请求报文举例**
```
{
"saleChannelId": "102410058",
"saleChannelOrderId": "20181024154201",
"requestId": "20181024154201",
"notifyType": {
"mobilePhone": "13524161800"
},
"item": {
"saleChannelItemId":"20181024154201",
"commissionDate":"1",
"validDays": 10,
"ticketId": 1,
"makeFundsChannel": {
"channelBenefit": 0,
"merchantBenefit": 500,
"userRealAmount": 2500
}
}
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[makeCodeResponseData](https://book.e-buy.com/books/e-buy-40/page/faa9a "makeCodeResponseData")> | 否 | 码信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"saleChannelOrderId": "20181120155110",
"tradeNo": "c1eca7fbda51430cb5100ec0699a5b00",
"createTime": "20181120155225",
"isNotify": "1",
"codeNum": 1,
"items": [{
"codeDetail": [{
"codeURL": "http://qrcode.url.ag/make?0000001496A382FA4725D24FA27839FC1680D136CAFE515519B94B1D&type=QRCODE",
"code": "10116574123700278846",
"useTimes": 10,
"status": "00",
"statusDesc": "未使用"
}],
"validEnd": "20181201000000",
"validStart": "20181121000000",
"itemResultMsg": "SUCCESS",
"itemResultCode": "00",
"saleChannelItemId": "20181120155110",
"ticketId": 9000000010,
"ticketName":"星巴克30元代金券",
"activityId":"1000000006",
"activityName":"中信银行星巴克代金券活动"
}],
"createDate": "20181120"
}
}
```
#### **券状态枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 04 | 参数配置不正确 | RequestId参数不能为空
appId参数不能为空
|
| 50 | 活动产品信息不存在 |
|
| 97 | 活动产品信息不存在 | 活动产品信息不存在
或者其他配置信息错误 |
| 06 | 活动产品未经过测试 |
|
| 50 | 销售渠道信息不存在 |
|
| 07 | 销售渠道和活动产品权限不匹配 |
|
# 发码订单查询
#### **接口用途**
- 当需要查询发码订单结果时，取码方调用此接口
- 当调用`同步单条发码`超时或未知状态，取码方调用此接口确认交易结果
- 此接口不支持`异步批量发码`的订单查询
#### **接口说明**
- 每一次销售渠道对接[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行制码，生成一个制码订单。
- 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号
#### **action**
- `MakeQuery`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| originalChannelOrderId | String | 是 | 原取码方制码订单id | 小于64个字符 |
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
**请求报文举例**
```
{
"originalChannelOrderId": "20180912162026",
"requestId":"20180912162026"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[makeQueryResponseData](https://book.e-buy.com/books/e-buy-40/page/faa9a "makeQueryResponseData")> | 否 | 码信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"saleChannelOrderId": "20181025152303",
"tradeNo": "cee533ae3e504179868e1801e697c5dc",
"createTime": "20181025155331",
"isNotify": "1",
"codeNum": 1,
"createDate": "20181025",
"items": [{
"saleChannelItemId": "20181025105101",
"itemResultMsg": "SUCCESS",
"itemResultCode": "00",
"validStart": "20181025155300",
"ticketId": 1,
"ticketName":"星巴克30元代金券",
"activityId":"1000000006",
"activityName":"中信银行星巴克代金券活动",
"validEnd": "20181104155300",
"codeDetail": [{
"codeURL": "http://xxxx/hbw?A3rVNNEgPLQV",
"code": "10110544106453980943",
"useTimes": 10,
"status": "00",
"statusDesc": "未使用"
},
{
"codeURL": "http://xxxx/hbw?A3rVNNEgPLQQ",
"code": "10110544106453980944",
"useTimes": 10,
"status": "00",
"statusDesc": "未使用"
}]
},
{
"saleChannelItemId": "20181025105102",
"itemResultMsg": "SUCCESS",
"itemResultCode": "00",
"validStart": "20181025155300",
"ticketId": 2,
"ticketName":"星巴克50元代金券",
"activityId":"1000000006",
"activityName":"中信银行星巴克代金券活动"
"validEnd": "20181104155300",
"codeDetail": [{
"codeURL": "http://xxxx/hbw?A3rVNNEgPLQV",
"code": "10110544106453980943",
"useTimes": 10,
"status": "00",
"statusDesc": "未使用"
}]
}]
}
}
```
# 码作废（退款）接口
#### **接口用途**
- 当需要`作废`码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 已撤销(作废)/使用的码不能转换为其他状态。
- 冻结和解冻操作是相对的。
#### **action**
- `CodeStatusUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| code | String | 是 | 码号 | 小于22个字符 |
| optTag | String(2) | 是 | 操作分类 | 01：作废 |
**请求报文举例**
```
{
"requestId": "20181019112535100000000000000008",
"code": "1021242013780905000",
"optTag":"01"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 |
|
| returnMsg | String | 是 | 请求返回信息 |
|
| data | Object<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/01386 "statusUpdateData")> | 否 | 码状态更新返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"updateDate": "20241224",
"codeSecret": "10032891673449546316",
"codeValidEnd": "20250323235959",
"statusDesc": "已作废",
"data": {},
"tradeNo": "0601f61bf54a46b8a01899b444d47a38",
"codeValidStart": "20241224000000",
"currentStatus": "05",
"updateTime": "20241224093435",
"ticketId": 1000030006397
}
}
```
**失败返回报文举例**
```
{
"returnCode": "32",
"returnMsg": "流水号重复，请调用查询接口",
"data": {}
}
```
```
{
"returnCode": "91",
"returnMsg": "该码已使用不能更新状态[100***8707]",
"data": {}
}
```
```
{
"returnCode": "91",
"returnMsg": "该码已作废不能更新状态[100***6316]",
"data": {}
}
```
#### **券状态枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 91 | 更新码状态不支持当前操作 | 更新码状态不支持当前操作 |
| 10 | 券码不存在 |
|
| 02 | 本操作不支持，流水号长度不正确 |
|
# 码冻结接口
#### **接口用途**
- 当需要`冻结`码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 已撤销(作废)/使用的码不能转换为其他状态。
- 冻结和解冻操作是相对的。
#### **action**
- `CodeStatusUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| code | String | 是 | 码号 | 小于22个字符 |
| optTag | String(2) | 是 | 操作分类 | 02：冻结 |
**请求报文举例**
```
{
"channelOrderId": "20180912162026",
"requestId": "20181019112535100000000000000008",
"code": "1021242013780905000",
"optTag":"02"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/01386 "statusUpdateData")> | 否 | 码状态更新返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181019112535100000000000000008",
"currentStatus": "01",
"statusDesc": "已作废",
"updateDate":"20181019",
"updateTime":"20181019112535"
}
}
```
# 码解冻接口
#### **接口用途**
- 当需要`解冻`码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 已撤销(作废)/使用的码不能转换为其他状态。
- 冻结和解冻操作是相对的。
#### **action**
- `CodeStatusUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| code | String | 是 | 码号 | 小于22个字符 |
| optTag | String(2) | 是 | 操作分类 | 03：解冻 |
**请求报文举例**
```
{
"channelOrderId": "20180912162026",
"requestId": "20181019112535100000000000000008",
"code": "1021242013780905000",
"optTag":"03"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/01386 "statusUpdateData")> | 否 | 码状态更新返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181019112535100000000000000008",
"currentStatus": "01",
"statusDesc": "已作废",
"updateDate":"20181019",
"updateTime":"20181019112535"
}
}
```
# 码激活接口
#### **接口用途**
- 当需要`激活`码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 已撤销(作废)/使用的码不能转换为其他状态。
#### **action**
- `CodeStatusUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| code | String | 是 | 码号 | 小于22个字符 |
| codeValidDays | Number | 否 | 相对有效天数 | 除制码当天开始相应天数结束。validStart、validEnd组合与validDay、commissionDate组合可选其一，若全部填写以相对有效期优先 |
| codeValidStart | Number(14) | 否 | 码有效开始时间 | 该字段填写时，validEnd必填格式:yyyyMMddHHmmss |
| codeValidEnd | Number(14) | 否 | 码有效结束时间 | 该字段填写时，validStart必填格式:yyyyMMddHHmmss |
| activateShopNo | String(10) | 否 | 激活门店号 |
|
| activateOrg | String(10) | 否 | 激活机构 |
|
| purchaseOrderNum | String | 否 | 用户购买订单号 |
|
| notifyType | Object<[notifyType](https://book.e-buy.com/books/e-buy-40/page/26657 "notifyType")> | 否 | 激活通知类型 |
|
| makeFundsChannels | Array<[fundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel")> | 否 | 资金渠道 | 针对阶梯价场景为必填 |
| makeFundsChannel | Object<[makeFundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel")> | 否 | 资金渠道 | 当需要在对账报表中体现时必填 |
| optTag | String(2) | 是 | 操作分类 | 04：激活 |
**请求报文举例**
```
{
"requestId": "20181019112535100000000000000008",
"code": "1021242013780905000",
"codeValidDays":9,
"purchaseOrderNum":"20191119192700123",
"optTag":"04"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 |
|
| returnMsg | String | 是 | 请求返回信息 |
|
| data | Object<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/01386 "statusUpdateData")> | 否 | 码状态更新返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181019112535100000000000000008",
"currentStatus": "00",
"statusDesc": "未使用",
"updateDate":"20181019",
"updateTime":"20181019112535"
}
}
```
**失败返回报文举例**
```
{
"returnCode": "32",
"returnMsg": "流水号重复，请调用查询接口",
"data": {}
}
```
# 同步批量码作废
#### **接口用途**
- 多码批量作废时，调用此接口
#### **接口说明**
- 一次可以多码作废,一次最多20个码。
#### **action**
- `SyncBatchCodeUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codeArray | List | 是 | 码号数组 | |
| saleChannelId | Long | 否 | 取码方id | |
| saleChannelOrderId | String | 否 | 取码方制码订单号 | 当codeArray无值时取该订单号下所有串码进行作废。当订单号有值时取码方id必填 |
| callBackUrl | String | 是 | 激活成功后的回调地址 | |
| updateShopNo | String(10) | 否 | 激活门店号 | |
| updateOrg | String(10) | 否 | 激活机构 | |
| optTag | String(2) | 是 | 操作分类 | B1：批量作废 |
**请求报文举例**
```
{
"requestId":"20181019112535100000000000000001",
"codeArray": ["10215523190570712621"],
"callBackUrl": "http://test.com/api/codeVoid",
"optTag": "B1",
}
```
**同步返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[statusUpdateCallbackData](https://book.e-buy.com/books/e-buy-40/page/15438 "statusUpdateCallbackData")> | 否 | 码状态更新返回数据 |
**回调返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181019112535100000000000000008",
"totalCodeNum": 1,
"successCodeNum": 1,
"codeArray": [{
"codeId": "1212431432",
"searchCode": "100***1234",
"codeSecret": "100213321414112234",
...
}],
}
}
```
# 码信息更新接口
#### **接口用途**
- 当需要对指定码的部分信息进行更新时，调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
#### **action**
- `CodeDetailUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| code | String | 是 | 码号 | |
| updateOpts | <[updateOpt](https://book.e-buy.com/books/e-buy-40/page/02522 "updateOpt")> | 是 | 码明细更新操作 |
**请求报文举例**
```
{
"requestId": "20180912162026",
"code": "1012123342335432145",
"updateOpts": {
"updatePurchaseTime": "20181103105501",
"updateMakeNotifyType": {
"mobilePhone": "13510121314"
},
"updateMerchantRealAmount": 1200
}
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/01386 "statusUpdateData")> | 否 | 码状态更新返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20180912162026",
"currentStatus": "00",
"statusDesc":"未使用",
"updateDate":"20181019",
"updateTime":"20181019112535"
}
}
```
# 码信息查询
#### **接口用途**
- 当需要查询某个指定码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 如果券码预售提前激活，还未生效前
1、抖音本地， 直接返回券码状态不做拦截，核销时候会拦截无法使用
2、其他的渠道直接返回 券码不在有效期
#### **action**
- `CodeQuery`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codes | List | 是 | 验码集合 | 最大不超过20 |
| brandId | String | 否 | 核销门店所属品牌 | 组合劵必须上送，易百提供 |
| cityId | String | 否 | 门店所在城市id | 易百提供的城市id |
| storeInfo | Object<[storeInfo](https://book.e-buy.com/books/e-buy-40/page/54229 "storeInfo")> | 否 | 门店串码查询时上送 |
**请求报文举例**
```
{
"requestId": "20181019112535100000000000000002",
"codes": ["1021242013780905000"],
"brandId":"2429",
"cityId":5493
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 |
|
| returnMsg | String | 是 | 请求返回信息 |
|
| data | Object<[codeQueryResponseData](https://book.e-buy.com/books/e-buy-40/page/0584c "codeQueryResponseData")> | 否 | 码信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "171698602301",
"data":{
"codeDetail":[{
"code":"1021242013780905000",
"saleChannelOrderId":"20181120155110",
"sendChannelName":"易百自制渠道",
"saleChannelCode":"990001",
"useTimes":1,
"verifyTimes":1
"remainTimes":0,
"createDate": "20180905",
"createTime": "20180905160911",
"validStart":"20181123000000",
"validEnd":"20181124235959",
"verifyDate":"20181123",
"verifyTime":"20181124121243",
"status": "01",
"statusDesc": "已使用",
"cityCheck":"Y",
"ticketId":"9000000001",
"faceValue":3000,
"ticketName":"星巴克30元代金券",
"shopNo":"1111",
"shopName":"星巴克测试门店"
"faceValue":1000,
},{
"code":"1021242013780905001",
"saleChannelOrderId":"20181120155110",
"sendChannelName":"易百自制渠道",
"remainTimes":1,
"createDate": "20180905",
"createTime": "20180905160911",
"validStart":"20181123000000",
"validEnd":"20181124235959",
"verifyDate":"20181123",
"verifyTime":"20181124121243",
"status": "01",
"statusDesc": "已使用",
"cityCheck":"Y",
"ticketId":"9000000001",
"faceValue":3000,
"ticketName":"星巴克30元代金券",
"shopNo":"1111",
"shopName":"星巴克测试门店"
"faceValue":1000,
}]
}
}
```
#### **券状态枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 00 | 可使用 |
|
| 01 | 已使用 |
|
| 02 | 可使用(一码多次使用时，码还有可用次数) |
|
| 03 | 未激活 | 未激活的码需调用激活接口才能 |
| 04 | 已冻结 |
|
| 05 | 已作废 |
|
| 06 | 已过期 |
|
| 07 | 未生效 | 当制码时选择次日生效，核销时会返回该状态 |
| 08 | 不能退款 | 仅核销场景-不支持核销撤销(根据业务场景配置是否支持隔日和当日核销撤销) |
| 09 | 券不存在 | 券码不存在(券码查询、核销、核销撤销) |
| 21 | 电子凭证不可用 | 券码不在有效期
|
| 35 | 码配置异常 |
|
| 51 | 改码不存在制码方 |
|
| 97 | 报文错误 | 接口调用参数校验不通过 |
| C2 | 商户无权限 | 券码查询和核销 权限校验不通过 |
# 批量码核销
#### **接口用途**
- 多码批量核销时，调用此接口
#### **接口说明**
- 一次可以多码核销,一次最多10个码。
#### **action**
- `BatchCodesVerify`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| verifyScene | String | 是 | 交易场景.offline线下,online线上 | 线上也可以传抖音、美团等 |
| codes | List | 是 | 码号数组 | |
| verifyCodes | List<[codeArr](https://book.e-buy.com/books/e-buy-40/page/cfa08)> | 否 | 指定券码阶梯价序号 |
|
| isProductCheck | String | 是 | 是否校验订单产品规则 | 是Y，否N |
| requestId | String | 是 | 请求流水号确保永久唯一性 | 32位长度 |
| refNo | String | 否 | 系统参考号 | 12位长度 |
| cashierTransNo | String | 否 | 收银机流水号 | 最长64位长度 |
| storeInfo | Object<[storeInfo](https://book.e-buy.com/books/e-buy-40/page/6f492 "storeInfo")> | 否 | 此信息为线下门店核销时上送 | 线下核销必填 |
| cashTotalAmount | Number | 否 | 订单总金额 | 单位：分 |
| goodsDetail | List<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/1d7f7-Fbe "goodsDetail")> | 否 | (只有在收银POS上发起交易时才上送) | |
| remark | [String](https://book.e-buy.com/books/c20ad/page/17d63) | 否 | 备注（在核销撤销、核销查询等接口原样返回） | |
**请求报文举例**
```
{
"verifyScene": "online",
"codes": [
"10215523190570712621"
],
"requestId": "20181019112535100000000000000001",
"refNo": "181215430700",
"cashierTransNo": "42441908138100007498001",
"storeInfo": {
"cityId": "1012",
"shopNo": "C00001",
"shopName": "上海浦东测试门店",
"manageCompany": "上海浦东测试店管理公司",
"companyId": "218"
},
"cashTotalAmount": "20000",
"goodsDetail": [
{
"sku": "1112343",
"qty": 1,
"price": 3000,
"type": "03",
"spec": "03"
},
{
"sku": "1212342",
"qty": 1,
"price": 3500,
"type": "03",
"spec": "03"
}
],
"remark": {
"oms": "test001"
}
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 |
| returnMsg | String | 是 | 请求返回信息 | |
| data/checkResult | Object<[data/checkResult](https://book.e-buy.com/books/e-buy-40/page/1afa3 "data")> | 是 | 券码核销信息明细返回 |
**返回报文举例**
```
{
"requestId": "10000000000000000000002",
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"verifyResult":[{
"code":"1021242013780905000",
"saleChannelCode":"990001",
"saleChannelCode":"易百码",
"status":"00",
"fundsChannel": {
"discountAmount": 3000,
"merchantRealAmount":0.0,
"channelBenefit": 0.0,
"merchantBenefit": 0.0
},
"faceValue":3000,
"ticketId":"3",
"ticketName":"30元现金抵价券",
"returnCashParam":{
"tenderCode":"135"
}
},{
"code":"1021242013780905000",
"saleChannelCode":"990001",
"saleChannelCode":"易百码",
"status":"06",
"fundsChannel": {
"discountAmount": 1000,
"merchantRealAmount":0.0,
"channelBenefit": 0.0,
"merchantBenefit": 0.0
},
"faceValue":1000,
"ticketId":"6",
"ticketName":"10元现金抵价券",
"returnCashParam":{
"tenderCode":"132"
}
}]
}
}
```
#### **status枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 00 | 可使用 |
| 01 | 已使用 |
| 03 | 未激活 | 未激活的码需调用激活接口才能 |
| 04 | 已冻结 |
| 05 | 已作废 |
| 06 | 已过期 | |
| 07 | 未生效 | 当制码时选择次日生效，核销时会返回该状态 |
| 09 | 码不存在 |
| 10 | 券码状态异常，券码无效 |
| 23 | 商户商品号传送错误 |
| 26 | 券码不能在本门店使用 |
| C1 | 商户号门店信息有误 |
| C2 | 商户无权限 |
| T2 | 易百调用第三方失败 |
| A4 | 其他异常 |
# 批量码核销查询
#### **接口用途**
- 批量核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果
#### **接口说明**
- 此接口默认支持查询当日内核销交易
- 也可传参originalDate查询指定日核销交易
#### **action**
- `BatchCodeVerifyQuery`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| originalRequestId | String | 是 | 原核销请求流水号 | 32个字符 |
| originalDate | String | 否 | 原交易日期 | 传入需要查询的原交易日期，不传默认为当天格式为yyyyMMdd |
**请求报文举例**
```
{
"requestId": "20180905000",
"originalRequestId":"1021867639235435",
"originalDate": "20170912"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| requestId | String | 是 | 原样返回 | |
| verifyRemark | String | 否 | 核销备注信息 | 核销接口上送原样返回 |
| data/verifyQueryResponse | Object<[data/verifyQueryResponse](https://book.e-buy.com/books/e-buy-40/page/19f3c-LQF "data")> | 是 | 券码核销订单明细返回 | |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000002",
"data": {
"verifyQueryResponse": [{
"cashTotalAmount": 17800,
"fundsChannel": {
"totalAmount": 50000,
"discountAmount": 50000,
"merchantRealAmount": 40000,
"channelBenefit": 10000,
"merchantBenefit": 10000,
"userRealAmount": 30000
},
"goodsDetail": [{
"sku": "1212342",
"qty": 1,
"price": 3500,
"type": "03",
"spec": "03"
}],
"code": "10215523190570712621",
"ticketId": "3",
"ticketName": "50 元现金抵价券 ",
"activityNo": "2017071951",
"activityName": "联动优势电子凭证",
"printData": "00|产品：测试券|00|团购价：100|00|订单号：100000000002100002|00|兑换码：101105********4289|"
}]
}
}
```
# 批量码核销撤销
#### **接口用途**
- 多码批量核销订单撤销时或订单中部分码撤销，调用此接口。
#### **接口说明**
- 撤销批量核销订单，调用前请确认订单是否符合撤销条件。
#### **action**
- `BatchCodeVerifyVoid`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 小于32个字符 |
| originalRequestId | String | 是 | 原核销请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codes | List | 否 | 原订单中批量核销撤销的码 | 此字段不填默认整订单撤销 |
| voidDate | String | 否 | 原交易时间,默认当天 | 格式:YYYYMMDD |
| isAtomicity | String | 否 | 是否需要支持原子性，原交易中码核销撤销要么全部成功要么全部失败 | Y：是，N：否（默认） |
**请求报文举例**
```
{
"requestId": "10000000000000000000001",
"originalRequestId":"10000000000000000000002"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 |
| returnMsg | String | 是 | 请求返回信息 | |
| verifyRemark | String | 否 | 核销备注信息 | 核销接口上送原样返回 |
| data/voidResult | Object<[data/voidResult](https://book.e-buy.com/books/e-buy-40/page/18997)> | 是 | 券码核销信息明细返回 | |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": 10000000000000000000002,
"data": {
"voidResult":[{
"code":"1021242013780905000",
"status":"00",
"statusDesc":"成功",
"amount": "5000",
"ticketName": "50 元现金抵价券 "
}]
}
}
```
# 测试apimock同步
\[yapi\_interface\]617\[/yapi\_interface\]
# 查询码信息查询
接口用途
接口说明
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
action
请求参数，CHANNEL===>WHALE
| 字段 |
类型 |
是否必填 |
字段意义 |
备注 |
|---|
| requestId |
String |
是 |
请求流水号 |
32个字符，用于标识唯一一笔交易 |
| codes |
List |
是 |
验码集合 |
|
| brandId |
String |
否 |
核销门店所属品牌 |
组合劵必须上送，易百提供 |
| cityId |
String |
否 |
门店所在城市id |
易百提供的城市id |
| storeInfo |
Object<storeInfo> |
否 |
门店串码查询时上送 |
请求报文举例
{
"requestId": "20181019112535100000000000000002",
"codes": ["1021242013780905000"],
"brandId":"2429",
"cityId":5493
}
返回参数，WHALE===>CHANNEL
| 字段 |
类型 |
是否必填 |
字段意义 |
备注 |
|---|
| returnCode |
String |
是 |
请求返回码 |
|
| returnMsg |
String |
是 |
请求返回信息 |
|
| data |
Object<codeQueryResponseData> |
否 |
码信息 |
返回报文举例
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "171698602301",
"data":{
"codeDetail":[{
"code":"1021242013780905000",
"saleChannelOrderId":"20181120155110",
"sendChannelName":"易百自制渠道",
"saleChannelCode":"990001",
"useTimes":1,
"verifyTimes":1
"remainTimes":0,
"createDate": "20180905",
"createTime": "20180905160911",
"validStart":"20181123000000",
"validEnd":"20181124235959",
"verifyDate":"20181123",
"verifyTime":"20181124121243",
"status": "01",
"statusDesc": "已使用",
"cityCheck":"Y",
"ticketId":"9000000001",
"faceValue":3000,
"ticketName":"星巴克30元代金券",
"shopNo":"1111",
"shopName":"星巴克测试门店"
"faceValue":1000,
},{
"code":"1021242013780905001",
"saleChannelOrderId":"20181120155110",
"sendChannelName":"易百自制渠道",
"remainTimes":1,
"createDate": "20180905",
"createTime": "20180905160911",
"validStart":"20181123000000",
"validEnd":"20181124235959",
"verifyDate":"20181123",
"verifyTime":"20181124121243",
"status": "01",
"statusDesc": "已使用",
"cityCheck":"Y",
"ticketId":"9000000001",
"faceValue":3000,
"ticketName":"星巴克30元代金券",
"shopNo":"1111",
"shopName":"星巴克测试门店"
"faceValue":1000,
}]
}
}
券状态枚举
| 字段 |
字段意义 |
备注 |
|---|
| 00 |
可使用 |
| 01 |
已使用 |
| 02 |
可使用(一码多次使用时，码还有可用次数) |
| 03 |
未激活 |
未激活的码需调用激活接口才能 |
| 04 |
已冻结 |
| 05 |
已作废 |
| 06 |
已过期 |
|
| 07 |
未生效 |
当制码时选择次日生效，核销时会返回该状态 |
| 09 |
券不存在 |
|
| 35 |
码配置异常 |
# 运营管理类接口
# 创建券产品
[yapi_interface]36408[/yapi_interface]
# 变更券产品
[yapi_interface]36474[/yapi_interface]
# 券产品详情查询
[yapi_interface]36426[/yapi_interface]
# 创建批次
[yapi_interface]36432[/yapi_interface]
# 批次编辑
[yapi_interface]36468[/yapi_interface]
# 批次详情查询
[yapi_interface]36444[/yapi_interface]
# 券码操作记录查询
**接口签名参照**
**[文档入口](https://book.e-buy.com/books/e-buy-41/chapter/7f100)**
**接口用途**
- 券码历史记录查询 （根据上送券码，查询当前券码历史相关记录信息）
**action**
- /paas/micro/ecoupon/\_queryCodeDetailList
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 券码 | 券号code |
**请求报文举例**
```
{
"action": "_queryCodeDetailList",
"appId": "ebuywha102410042",
"content": "{\"code\":\"1006251009100030079=o6h7zgg4\"}",
"headers": {
"paas-version": "1.1.0"
},
"lang": "zh-CN",
"signType": "sha256",
"timestamp": 1759996455238,
"uuid": "20251009-302a8467885349caba2dec5ad31bcc8e"
}
```
**返回参数，易百后台===>中件间**
| 参数名称 | 类型 | 必填 | 默认值 | 备注 | 其他信息 |
| uuid | string | 是 | | 请求序列号 | 最大长度：50
最小长度：1
Mock：@now('yyyyMMdd')-@string('lower',32) |
| success | boolean | 是 | | 交易成功与否 | Mock：@boolean |
| action | string | 是 | | 交易类型 | 最大长度：50
最小长度：1
Mock：addEcouponProduct |
| timestamp | number | 是 | | 返回时间戳 | Mock：@timestamp |
| errorCode | string | 是 | | 错误码 | 最大长度：50
Mock：@word |
| errorMessage | string | 是 | | 错误描述 | 最大长度：50
Mock：@csentence |
| signType | string | 否 | | 签名类型 | 最大长度：20
Mock：sha256 |
| sign | string | 否 | | 签名值 | 最大长度：500
Mock：@natural |
| **content** | object | 是 | | 返回报文 | |
| returnData | List<[voucherPkg](https://book.e-buy.com/books/c20ad/page/58238)> | 是 | | | |
**返回报文举例（请求中 businessType 值为 12 时）**
```
{
"success": true,
"errorMessage": "",
"sign": "47864d480e95f53e9a6b7de0bd78f18e30eee2428ef04558779660104504a5c7",
"action": "_queryCodeDetailList",
"errorCode": "",
"signType": "sha256",
"uuid": "20250926-1d9de05de6834682bccba7ab5d704ca1",
"content": {
"returnData": [
{
"dateTime": "20250926161612",
"returnCode": "00",
"returnMsg": "操作成功",
"code": "1006250926800024350=TdPPn8Bf",
"mid": "",
"shopName": "",
"type": "1",
"shopNo": "",
"tid": "",
"swift": ""
},
{
"dateTime": "20250926161616",
"returnCode": "00",
"returnMsg": "SUCCESS",
"code": "1006250926800024350=TdPPn8Bf",
"extendData": {
"oms": "wv9O0WLS"
},
"mid": "",
"shopName": "",
"type": "4",
"shopNo": "",
"tid": "",
"swift": ""
},
{
"dateTime": "20250926161628",
"returnCode": "00",
"returnMsg": "SUCCESS",
"code": "1006250926800024350=TdPPn8Bf",
"extendData": {
"oms": "3PYkfBSP"
},
"mid": "",
"shopName": "",
"type": "4",
"shopNo": "",
"tid": "",
"swift": ""
},
{
"dateTime": "20250926161635",
"returnCode": "00",
"returnMsg": "SUCCESS",
"code": "1006250926800024350=TdPPn8Bf",
"mid": "",
"type": "3",
"tid": "",
"swift": ""
}
]
},
"timestamp": 1758874822508
}
```
# 箱本包处理类接口
# 券码历史记录查询
**接口用途**
- 券码历史记录查询 （根据上送券码，查询当前券码历史相关记录信息）
- [签名](https://book.e-buy.com/books/c20ad/page/5878a)
**action**
- /api/whaleStarbucksCode/getCodeRecords
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 流水号 | 不允许重复，用于单次请求日志追踪查询 |
| code | String | 是 | 券码 | 券号code |
| sign | String | 是 | 签名串 | 券码查询签名串和顺序
signStr = "requestId=1754036646424&code=1006250730320020870=gHN3981K"
|
**请求报文举例**
```
{
"code": "1006250730320020870=gHN3981K",
"requestId": 1754036646424,
"sign": "k8l22s6PQHhwskkUx4BKD+dqCtCuYVuE5pC9ikbaIUG/K68xqvytLajPumygrF9VqP13vJHe0lWOUm0+9Fqzt17jU+36naYLoXh8o70BH4HIrA3xswmiHkgcoZ+OxQfOxLqLO/QghHKMPJFYu7El72a/HY12Q7QntGiMV2SADTq4VQIMfDjVZ4YmovN231TLD78cyJsdPUXmIRMbB+rqaR6cglTiPoyPOtdcgou1XFth2aC1zJH5WiCe/qwpiFSzLquQSo02theZ1C/A6OVqBKwNBOBxMQ0vnAZYUZ8QMG5ivxj4grGOoCSWcjHI4rRn3SKJNZJonNQgm68VAWPSIA=="
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| String | 是 | 返回响应码 |
|
| String | 是 | 交易时间 |
|
| String | 是 | 返回请求流水 |
|
| returnDesc | String | 是 | 返回信息 |
|
| List<[voucherPkg](https://book.e-buy.com/books/c20ad/page/58238)> | 否 | 交易记录信息 |
|
**返回报文举例（请求中 businessType 值为 12 时）**
```
{
"returnCode": "00",
"transTime": 1754016597099,
"requestId": "1754016596841",
"returnData": [
{
"dateTime": "20250730143743",
"returnCode": "00",
"returnMsg": "操作成功",
"code": "1006250730320020870=gHN3981K",
"mid": "",
"shopName": "",
"type": "1",
"shopNo": "",
"tid": "",
"swift": ""
},
{
"dateTime": "20250730153314",
"returnCode": "00",
"returnMsg": "SUCCESS",
"code": "1006250730320020870=gHN3981K",
"mid": "860020051401034",
"shopName": "星巴克北京银泰店",
"type": "2",
"shopNo": "1490",
"tid": "54022101",
"swift": "0"
},
{
"dateTime": "20250730211518",
"returnCode": "00",
"returnMsg": "SUCCESS",
"code": "1006250730320020870=gHN3981K",
"mid": "860020051401034",
"shopName": "星巴克北京银泰店",
"type": "2",
"shopNo": "1490",
"tid": "54022101",
"swift": "0",
"extendData": {
"shopNo": "test1",
"voucherNo": "test1",
"posSerialNo": "test1",
"oms": "test1"
}
}
],
"returnDesc": "success"
}
```
# 激活查询
**接口用途**
- 激活前查询是否可以激活 （实际场景 激活前和激活后都会查询，如果上送券码都是激活返回已激活，如果上含未激活返回未激活）
**action**
- activePreQuery
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"qrcode": "R156A001-0000491-0505,R156A002-0000491-0505",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | P00表示待激活（可激活）；P01表示正在激活中（不可激活）；P02表示有部分券处于不可激活状态（不可激活）；P03表示已全部激活；P09表示该门店该城市不可激活 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例（请求中 businessType 值为 12 时）**
```
{
"transDate": "20190107143930",
"returnDesc": "success",
"voucherBox": [{
"boxId":"X22169-3141157-33475",
"voucherPkg":[
{
"pkgId":"B1123-6430582-102F5",
"voucherReel":[
{
"reelId":"R112102F-0000242-2585",
"codeDetail":[
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000258-M4DEDSfV",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000242-EOHEMM9K",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
},
{
"reelId":"R151102F-0000241-2555",
"codeDetail":[
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000255-e6tdHe8m",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000241-RTxJO2bX",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
}
]
},
{
"pkgId":"B1123-6430582-102F5",
"voucherReel":[
{
"reelId":"R112102F-0000242-2585",
"codeDetail":[
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000258-M4DEDSfV",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000242-EOHEMM9K",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
},
{
"reelId":"R151102F-0000241-2555",
"codeDetail":[
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000255-e6tdHe8m",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000241-RTxJO2bX",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
}
]
}
]
}],
"paidAmount": 0,
"invoiceAmount": 0,
"returnCode": "P00",
"receiptAmount": 0,
"printDetail": {
"content": "00||"
},
"orderNo": "179031014530",
"traceNo": "ccs203781546843174561"
}
```
**返回报文举例（请求中 businessType 值不为 12，或为空，或不传时）**
```
{
"transDate":"20190107143930",
"returnDesc":"success",
"voucherPkg":[
{
"pkgId":"B1123-6430582-102F5",
"voucherReel":[
{
"reelId":"R112102F-0000242-2585",
"codeDetail":[
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000258-M4DEDSfV",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000242-EOHEMM9K",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
},
{
"reelId":"R151102F-0000241-2555",
"codeDetail":[
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000255-e6tdHe8m",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
},
{
"createTime":"20190107100459",
"saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000241-RTxJO2bX",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
]
}
]
}
],
"paidAmount":0,
"invoiceAmount":0,
"returnCode":"P00",
"receiptAmount":0,
"printDetail":{
"content":"00||"
},
"orderNo":"179031014530",
"traceNo":"ccs203781546843174561"
}
```
# 激活
**接口用途**
- 激活
**action**
- activeVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code |
| totalAmount | String | 否 | 折后金额 | 激活券的折后金额，多个券则为总折后金额，单位：分 |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
| extendData | JSONObject<[activeInfo](https://book.e-buy.com/books/c20ad/page/310dc)> | 否 | 扩展信息 | 特殊场景填值需与易百技术沟通 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"qrcode": "R156A001-0000491-0505",
"totalAmount": "3000",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 本次激活操作订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | A00表示正在激活中（等待，做结果查询）；A02表示有部分券处于不可激活状态（未进行激活）；A03表示其他异常（未进行激活） |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "99000009100010101732123",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS"
}
```
# 激活结果查询
**接口用途**
- 激活结果查询
**action**
- activeResultQuery
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| originalTraceNo | String | 是 | 激活操作订单号 | |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"originalTraceNo": "99000009100010101732129",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 原激活操作订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | R00表示激活成功；R01表示激活失败；R02表示找不到原订单 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "99000009100010101732123",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS"
}
```
# 作废
**接口用途**
- 作废，作废后的券不可激活
**action**
- delVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code |
**请求报文举例**
```
{
"traceNo": "9900000910001010920150201",
"qrcode": "10014030013500006013",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| orderNo | String | 是 | 本次作废操作订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | V00表示作废成功；V01表示作废失败；V03表示券号错误 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"traceNo": "9900000910001011020150201",
"orderNo": "99000009100010101732123",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS"
}
```
# 核销信息以及城市范围查询
**接口用途**
- 核销信息以及城市范围查询
**action**
- queryVerifyInfo
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "9900000910001010720150201",
"qrcode": "10085748356738476396436",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | H00表示可核销；H01表示该券未激活；H02表示该券已核销；H03表示券号有误 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"transDate":"20190107143930",
"returnDesc":"success",
"voucherBox":[
{
"boxId":"X1123-6430582-102F5",
"voucherPkg":[
{
"pkgId":"B1123-6430582-102F5",
"voucherReel":[
{
"codeDetail":[
{
"createTime":"20190107100500",
"saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
"remainTimes":2,
"status":"03",
"ticketName":"买N赠M券[望湘园_储值卡]",
"code":"1001901070000000258-M4DEDSfV",
"activityId":500706,
"validEnd":"00000000000000",
"sendChannelName":"测试易百制码",
"ticketId":500811,
"saleChannelName":"望湘园_储值卡",
"validStart":"00000000000000",
"faceValue":"0.0",
"createDate":"20190107",
"activityName":"【吉野家】 黏贴板主题-2018第6期",
"statusDesc":"未激活"
}
],
"reelId":"R112102F-0000242-2585"
}
]
}
]
}
],
"paidAmount":0,
"invoiceAmount":0,
"returnCode":"P00",
"receiptAmount":0,
"printDetail":{
"content":"00||"
},
"orderNo":"179031014530",
"traceNo":"ccs2037815468431420150201"
}
```
# B2B饮料券箱本激活
**接口用途**
- 激活
**action**
- reelActiveVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 本号reelId |
| totalAmount | String | 否 | 折后金额 | 激活券的折后金额，多个券则为总折后金额，单位：分 |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"qrcode": "R156A001-0000491-0505",
"totalAmount": "3000",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 本次激活操作订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | A00表示正在激活中（等待，做结果查询）；A02表示有部分券处于不可激活状态（未进行激活）；A03表示其他异常（未进行激活） |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "99000009100010101732123",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS"
}
```
# B2B饮料券箱本作废
**接口用途**
- 作废，作废后的券不可激活
**action**
- reelDelVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "9900000910001010920150201",
"qrcode": "10014030013500006013",
"businessType": 12
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| orderNo | String | 是 | 本次作废操作订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | V00表示作废成功；V01表示作废失败；V03表示券号错误 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| voucherPkg | List<[voucherPkg](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/dian-zi-quan-bao-xin-xi.html)> | 否 | 电子券包信息 | 返回电子券包信息 |
**返回报文举例**
```
{
"traceNo": "9900000910001011020150201",
"orderNo": "99000009100010101732123",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS"
}
```
# 卡号段激活实体卡券（B2B定制）
**接口用途**
- 指定券码号段激活，相同激活订单号直接返回当前状态
**action**
- b2b/code/activeByPartNo
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ver
| int
| 是
| 2
| 接口版本(固定参数值)
|
| partnerId
| int
| 是
| 1504
| 商户编号(固定参数值)
|
| merchantId
| string
| 是
| 10001(星巴克中国)
| App商家在非码系统中的编号(固定参数值)
|
| sign
| string
| 是
| | 参考签名举例
|
| partnerOrderId
| String
| 是
| | 激活订单号，商户激活操作唯一，最大28位。(若第一次请求成功的订单号再次请求，则返回此订单号处理进度，与startCardSe、endCardSe值无关)
|
| type
| int
| 是
| | 激活对象类型(固定值实体券2)
|
| bin
| string
| 是
| | 卡bin(实体券：7020)获取券码取前4位
|
| codeType
| string
| 是
| | 激活实体券时必填，3位
|
| startCardSe
| string
| 是
| | 起始激活卡券号段,含当前号段。（7位）
|
| endCardSe
| string
| 是
| | 终止激活卡券号段,含当前号段。（7位）
|
| number
| int
| 是
| | 激活数量
|
| sellingPrice
| int
| 是
| | 商品成本价 ，单位：分（激活实体券时必传，若没有A,B账户则传sellingPrice=costPrice）。
|
| costPrice
| int
| 是
| | 商品售价。此字段不能大于sellingPrice，单位：分（激活实体券时必传，若没有A,B账户则传sellingPrice=costPrice）（折扣价=成本价-售价）。
|
| validStart
| String
| 否
| | 有效期开始时间，格式：yyyy-MM-dd HH:mm:ss（激活实体券时使用，激活时若validStart 和 validEnd 都不传，默认三年有效期。）
|
| valid\_end
| string
| 否
| | 有效期结束时间,格式：yyyy-MM-dd HH:mm:ss（激活实体券时使用，激活时若validStart 和 validEnd 都不传，默认三年有效期。）
|
**请求报文举例**
```
{
"ver": 2,
"partnerId": 1504,
"sign": "skip",
"merchantId": 10001,
"partnerOrderId": "2040132213w9181w0q77awwwd8",
"type": 2,
"bin": "7020",
"startCardSe": "0000041",
"endCardSe": "0000045",
"sellingPrice": "10000",
"costPrice": "8888",
"number": 14
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ver
| int
| 是
| 2
| 接口版本
|
| statusCode
| int
| 是
| 100：SUCCESS
| 返回码：100表示创建成功；
80表示处理中；
81 表示处理完成。
|
| message
| string
| 是
| 成功
| 状态码描述
|
| createTime
| string
| 否
| | 激活订单创建时间（返回100、80、81时，有值）格式：yyyyMMddHHmmss
|
| sign
| string
| 是
| | 参考签名举例
|
| | | | | |
**返回报文举例**
```
{
"createTime": "20200212100234",
"message": "处理中",
"sign": "EOMRl+jWgjGOTebWPRVqBDR1EPkyd/S7tsb/yEjvBoSfUZCEgVA6RNrjVEmIY15uJI9YV57tOZWy1FiVqJDH0lfEJnuk4DKpwcJMVCGXjQIH/Cd+PCibwBNknDWt9kaiB9JhxW8TrlBLYWq4ZyzffYtsF4qawyBgTLeUuPEOvoLZ2jA5OLtbSYVyI9g3OI4amcL25/GkRUw3ECmziAy9bTdVKmjV5FbWcyk45GM+K7/2a4/E6BihvVC2w6ge6xgDn0s5R9Ixaun5KhqcEJLHW/8vEAHMbx40uvsP91Aw9iiw5aZeGhpYoge89vAVTkC5boB8i+pgcpk0DqK4Jk25mA==",
"statusCode": 80,
"ver": 2
}
```
# 线下posp接口列表
# 二维码支付或兑换
**接口用途**
- 支付宝支付
- 微信被扫支付
- 银行二维码支付(工行、中行、中信、浦发等)
- 银行二维码积分兑换(工行、中行、中信、浦发等)
- 银联立码付
- 百度支付
- 翼支付
- 其他二维码支付
- 电子凭证核销：产品券/代金券/折扣券/买N赠M券/立减券
- 外卖或自助点单订单码自动上屏
**action**
- `qrcodeSale`
**请求参数，中件间===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String(40) | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| totalAmount | Price | 是 | 交易总金额 | 单位：元 |
| undiscountAmount | Price | 是 | 不可打折金额 | 单位：元 如无此金额时可填0 |
| verifyType | String | 是 | 核销类型 | 请与易百技术确认，枚举值：wechatApp(微信小程序),h5,aliApp(支付宝小程序),pos(线下pos机具) |
| activityProductNo | String | 否 | 活动产品编号 | 二次交互时填写 |
| scene | String | 否 | 支付场景 | 条码:bar\_code, 二维码:qr\_code |
| orderSubject | String | 否 | 订单标题 | 最长256 |
| orderDescription | String | 否 | 订单描述 | 最长256 |
| qrcode | String | 是 | 二维码内容 | 串号、一维码或二维码内容 |
| goodsDetail | List<[goodsDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/goods-detail.html "goodsDetail")> | 是 | 产品明细 | 验证产品明细时必填 |
| memberDetail | Object<[memberDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/member-detail.html "memberDetail")> | 否 | 会员信息 | 会员支付时必填 |
| extendData | [JSON](https://book.e-buy.com/books/c20ad/page/extenddata) | 否 | 扩展信息 | 特殊场景填值需与易百技术沟通 |
**请求报文举例**
```
{
"traceNo": "990000091000101620150201",
"totalAmount": 40.8,
"undiscountAmount": 0,
"activityProductNo": "HDCP00000000001234",
"qrcode": "280123121234567890",
"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.00,
"pointBalance": 30000
},
"extendData": {
"rightsDetail": [{
"snCode": "111111111xxxxxx"
}],
"shopNo":"test001",
"voucherNo":"test001",
"posSerialNo":"test001"
}
}
```
**返回参数，易百后台===>中件间**
- 可能返回[活动产品选项](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-list/transaction-api/prompt-options.html "活动产品选项")，需要进行选择
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| orderNo | String | 是 | 交易订单号 | 易百生成 |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | 00表示交易成功，其他表示失败 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| paidAmount | Price | 是 | 支付成功总金额 | 单位：元 |
| receiptAmount | Price | 否 | 商户实收金额 | 单位：元 |
| invoiceAmount | Price | 否 | 商户开票金额 | 单位：元 |
| exchangeRate | Number(8,6) | 否 | 汇率 | 1外币等于多少人民币 |
| currency | String | 否 | 货币类型 | 例如:CNY |
| discountCode | String | 否 | 折扣编码 | 由收银机分配，用于入账计折扣类型 |
| discountNum | Number | 否 | 固定金额折扣数量 | 用于入账计折扣类型的数量 |
| tenderCode | String | 否 | 支付方式编码 | 由收银机分配，用于入账计支付方式 |
| remainTimes | Number | 是 | 券码当前可用次数 | 如果有限制每天使用多少次，代表当天可使用次数 |
| activityProductNo | String | 否 | 活动产品编号 | |
| activityProductName | String | 否 | 活动产品名称 | |
| goodsDetail | List<[goodsDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/goods-detail.html "goodsDetail")> | 否 | 折抵产品明细 | 返回后台已抵扣成功的产品明细 |
| fundChannel | List<[fundChannel](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/fund-channel.html "fundChannel")> | 否 | 资金渠道 | |
| printDetail | Object<[printDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/print-detail.html "printDetail")> | 否 | 打印信息 | 如需要在收银小票上打印信息时必填 |
| memberDetail | Object<[memberDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/member-detail.html "memberDetail")> | 否 | 会员信息 | 返回本次交易的会员信息 |
| voucherDetail | List<[voucherDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/voucher-detail.html "voucherDetail")> | 否 | 优惠券信息 | 返回本次交易的优惠券信息 |
| extendsData | Object<[extendsData](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/extends-data.html "extendsData")> | 否 | 扩展信息 | 与ebuy约定 |
**返回报文举例**
```
{
"traceNo": "9900000910001011720150201",
"orderNo": "171698602301",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"paidAmount": 40.8,
"receiptAmount": 40.8,
"invoiceAmount": 40.8,
"exchangeRate": 6.0939,
"currency": "CNY",
"discountCode": "0001",
"discountNum": 20,
"tenderCode": "8001",
"activityProductNo": "2016123102",
"activityProductName": "支付宝支付",
"goodsDetail": [
{
"goodsCategory": "001",
"goodsId": "P00001",
"goodsName": "牙膏",
"price": 8,
"quantity": 2,
"rebateCode": "000",
"activityNo": "2016123101",
"memo": "100123456789"
},
{
"goodsCategory": "101",
"goodsId": "P00002",
"goodsName": "洗发水",
"price": 24.8,
"quantity": 1,
"rebateCode": "000",
"activityNo": "2016123101",
"memo": "100123456789"
}
],
"fundChannel": [
{
"channelNo": "001",
"channelName": "用户实付现金",
"channelAmount": "20.8"
},
{
"channelNo": "002",
"channelName": "用户积分支付",
"channelAmount": "20"
}
],
"printDetail": {
"cardNo64": "622562****8888",
"bank": "中国银行",
"paymentOrderNo": "201612315689412157458787",
"paymentUser": "139****@163.com",
"pointSale": "20000",
"qrCode1": "htt://www.api-location-url.com/url",
"qrCode2": "",
"qrCode3": "",
"barCode1": "12345679",
"barCode2": "",
"barCode3": ""
},
"memberDetail": {
"memberId": "M000001545",
"memberName": "TONY",
"grade": "1",
"status": "1",
"balance": 1000.00,
"pointBalance": 30000
},
"voucherDetail": [
{
"voucherId": "001",
"voucherName": "现金优惠券",
"voucherType": "现金",
"voucherCode": "123456789",
"channelAmount": "20.8"
},
{
"voucherId": "002",
"voucherName": "买一赠一优惠券",
"voucherType": "买赠",
"voucherCode": "1232136781",
"channelAmount": "20.8"
}
]
}
```
# 当日撤销
**接口用途**
- 需要对原交易整体撤销时，可以在原交易的同一天调用此接口。
**action**
- `void`
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| originalTraceNo | String | 是 | 原收银机流水号 | 传入需要查询的原交易收银机流水号 |
| isRollback | Boolean | 是 | 标识本次请求是否为冲正交易(中间件发起) | 冲正发起需要另起线程并且先返回收银机交易失败结果，再异步冲正 |
| acquirer | String | 否 | 收单机构 | 如：citicCashpay表示中信收单，如果收单撤销是必填的 |
| cardInfo | Object<[cardInfo](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/card-info.html "cardInfo")> | 否 | 卡信息 | 卡支付类交易需要填入原交易卡信息 |
**请求报文举例**
```
{
"traceNo": "9900000910001013220150201",
"originalTraceNo": "9900000910001013120150201",
"isRollback": false,
"acquirer": "citicCashpay",
"cardInfo": {
"cardNo": "",
"password": "",
"valid": "",
"track1": "",
"track2": "",
"track3": "",
"cardSn": "",
"icData": ""
}
}
```
**返回参数，易百后台===>中间件**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| orderNo | String | 是 | 交易订单号 | |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | 00表示交易成功，其他表示失败 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| fundChannel | List<[fundChannel](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/fund-channel.html "fundChannel")> | 否 | 资金渠道 | |
| printDetail | Object<[printDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/print-detail.html "printDetail")> | 否 | 打印信息 | 如需要在收银小票上打印信息时必填 |
| memberDetail | Object<[memberDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/member-detail.html "memberDetail")> | 否 | 会员信息 | 返回本次交易的会员信息 |
| voucherDetail | List<[voucherDetail](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/voucher-detail.html "voucherDetail")> | 否 | 优惠券信息 | 返回本次交易的优惠券信息 |
| cashOrderNo | String | 否 | 收单原流水号 | 收单撤销时返回 |
| cashBank | String | 否 | 收单机构标识 | 收单撤销时返回 |
| purchaseOrder | List<[purchaseOrder](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/qian-gou-dan-xin-xi.html)> | 否 | 收单签购单信息 | [签购单信息](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/qian-gou-dan-xin-xi.html) |
**返回报文举例**
```
{
"traceNo": "9900000910001013420150201",
"orderNo": "171698602301",
"cashOrderNo": "000025",
"cashBank": "40",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"fundChannel": [
{
"channelNo": "001",
"channelName": "用户实付现金",
"channelAmount": "20.8"
},
{
"channelNo": "002",
"channelName": "用户积分支付",
"channelAmount": "20"
}
],
"printDetail": {
"cardNo64": "622562****8888",
"bank": "中信银行",
"paymentOrderNo": "201612315689412157458787",
"pointSale": "20000",
"qrCode1": "htt://www.api-location-url.com/url",
"qrCode2": "",
"qrCode3": "",
"barCode1": "12345679",
"barCode2": "",
"barCode3": ""
},
"memberDetail": {
"memberId": "M000001545",
"memberName": "TONY",
"grade": "1",
"status": "1",
"balance": 1000.00,
"pointBalance": 30000
},
"voucherDetail": [
{
"voucherId": "001",
"voucherName": "现金优惠券",
"voucherType": "现金",
"voucherCode": "123456789",
"channelAmount": "20.8"
},
{
"voucherId": "002",
"voucherName": "买一赠一优惠券",
"voucherType": "买赠",
"voucherCode": "1232136781",
"channelAmount": "20.8"
}
]
}
```
**支持撤销的交易**
- cardPayment
- cardRedemption
- qrcodeSale
# 电子凭证查询
**接口用途**
- 查询电子凭证的产品信息，可抵用的金额以及所属的活动，支持易百自有电子凭证和第三方电子凭证。
**action**
- `ecouponInquiry`
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 电子凭证号 | 要查询的电子凭证号 |
**请求报文举例**
```
{
"traceNo": "9900000910001013620150201",
"qrcode": "HDCP00000000001235"
}
```
**返回参数，易百后台===>中间件**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| orderNo | String | 是 | 交易订单号 | 单位：元 |
| transDate | String | 是 | 交易时间 | 格式为：yyyyMMddHHmmss |
| returnCode | String | 是 | 返回码 | 00，C3表示券码可用，其他表示不可用 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| canPayAmount | Price | 是 | 可抵用的总金额 | 单位：元 |
| activityProductNo | String | 否 | 活动产品编号 | 该电子凭证所属的活动产品编号 |
| activityProductName | String | 否 | 活动产品名称 | 该电子凭证所属的活动产品名称 |
| extendsData | Object<[extendsData](https://gitbook.e-fuli.com/ebuy-cashier-integration-api/cn/api-introduction/parameter-object/extends-data.html "extendsData")> | 否 | 扩展信息 | 与ebuy约定 |
**返回报文举例**
```
{
"traceNo": "9900000910001013720150201",
"orderNo": "171698602301",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"canPayAmount": 40.8,
"activityProductNo": "2016123101",
"activityProductName": "中信365权益"
}
```