# e-Buy 电子券4.0
# 文档介绍
#### 文档目的
此为取码方与易百电子凭证对接的报文协议 为实现取码方对接易百制码，制码查询，制码撤销，码信息查询，码状态修改，码信息修改等制码功能
# 名词解释
#### 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和验证，所以需要保护好。
# 接入说明
本文档展示了如何通过[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
```
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| 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 | 是 | 有效期结束时间 | |
# 配置参数对象
# 券模板配置项
### 券模板配置
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| 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": "未使用"
}]
}]
}
}
```
# 异步批量发码
#### **接口用途**
- 电子凭证取码方需要批量(一次请求取码数超过1条)制码时，调用此接口
#### **接口说明**
- 每一次取码方对接[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行制码，生成一个制码订单。
- 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号。
- 制码请求接收后，会同步返回制码前校验结果，后端成功生成码后，异步通知到callBackUrl指定的回调接口。
#### **action**
- `MakeBatchCode`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 渠道制码订单id | 小于64个字符 |
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| callBackUrl | String | 是 | 异步结果回调地址 | 易百以POST请求方式推送 |
| items | List<[items](https://book.e-buy.com/books/e-buy-40/page/3ad7c "items")> | 是 | 制码子订单 | 一次制码请求最多支持10个子订单 |
**请求报文举例**
```
{
"saleChannelOrderId": "20180912162026",
"requestId": "20180912162026",
"totalAmount": "15800",
"notifyType": {
"mobilePhone": "13524161800"
},
"callBackUrl": "http://*****/***/api",
"items": [{
"saleChannelItemId": "20180912162026001",
"ticketId": 1,
"validDays": 10,
"validStart": "20180730000000",
"validEnd": "20181201235959",
"codeNum": 2,
"makeFundsChannel": {
"channelBenefit": 0,
"merchantBenefit": 500,
"userRealAmount": 2500
}
}, {
"saleChannelItemId": "20180912162026002",
"ticketId": 2,
"validDays": 10,
"validStart": "20180730000000",
"validEnd": "20181201235959",
"codeNum": 1,
"makeFundsChannel": {
"channelBenefit": 100,
"merchantBenefit": 0,
"userRealAmount": 900
}
}]
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| batchMakeCodeResponseData | Object<[batchMakeCodeResponseData](https://book.e-buy.com/books/e-buy-40/page/a3f39 "batchMakeCodeResponseData")> | 否 | 批量制码返回数据 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"saleChannelOrderId": "201811261721",
"saleChannelId": 99000014,
"tradeNo": "4a784d0ec74d4211bb3c425f004f95ac",
"createTime": "20181126172115",
"codeNum": 5,
"createDate": "20181126"
}
}
```
# 批量发码结果通知
#### **接口用途**
- 异步批量下单接口所要求的码全部成功生成后，通过此接口将码信息回调到取码方
#### **接口说明**
- 接口与“异步批量发码”是一组接口来完成业务
- 此接口以[http](https://book.e-buy.com/books/e-buy-40/page/7f100 "基于HTTP协议的通讯方式") post请求方式回调取码方callBackUrl地址
- returnCode = "00"时，说明订单进入制码流程。resultCode = "00"时，说明子订单制码成。
- 如果未收到易百的回调请求，取码方可以传原订单号再次调用`异步批量发码`
**返回参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[batchMakeCodeResponseData](https://book.e-buy.com/books/e-buy-40/page/faa9a "batchMakeCodeResponseData")> | 否 | 码信息 |
**返回报文举例**
```
{
"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": "未使用"
}]
}]
}
}
```
# 发码撤销
#### **接口用途**
- 当需要撤销某笔制码订单时，取码方调用此接口
#### **接口说明**
- 当对原制码订单进行撤销时，生成一个撤销订单。
- 对原订单进行撤销时，整单所制码都将被撤销。如需对单码撤销，调用电子凭证码状态更新接口。
- 此接口可对`同步单条发码`、`异步批量发码`下单接口订单进行撤销操作
- 对已撤销成功订单不能再次撤销
- 如果订单撤销部分成功时返回"tradeStatus"="P"
- 对订单中部分券码撤销成功时，可以按原制码订单号再次调用撤销接口，如还是部分撤销成功请联系易百技术方協助解决
#### **action**
- `MakeVoid`
**请求参数，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 | List<[makeVoidResponseData](https://book.e-buy.com/books/e-buy-40/page/05f97 "makeVoidResponseData")> | 否 | 码撤销信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"originalChannelOrderId": "20181018183139",
"createDate": "20181018",
"createTime": "20181018183454",
"totalNum": 4,
"tradeStatus": "A",
"voidDetails": [{
"ticketId": 1,
"originalChannelItemId": "99000014001",
"voidNum": 2
}, {
"ticketId": 2,
"originalChannelItemId": "99000014002",
"voidNum": 2
}]
}
}
```
# 发码撤销查询
#### **接口用途**
- 当需要查询对某笔订单的撤销结果时，取码方调用此接口
#### **接口说明**
- 当制码撤销结果未返回或因为超时等原因未能及时收到返回结果,可进行制码撤销查询
#### **action**
- `MakeVoidQuery`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| originalChannelOrderId | String | 是 | 取码方制码订单id | 小于64个字符 |
| orderDate | String | 是 | 原下单日期 | yyyyMMdd |
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
**请求报文举例**
```
{
"originalChannelOrderId": "20180912162026",
"orderDate": "20180905",
"requestId":"20180912162026"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | List<[makeVoidResponseData](https://book.e-buy.com/books/e-buy-40/page/05f97 "makeVoidResponseData")> | 否 | 码撤销信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"originalChannelOrderId": "20181018183139",
"createDate": "20181018",
"createTime": "20181018183454",
"totalNum": 4,
"tradeStatus": "A",
"voidDetails": [{
"ticketId": 1,
"originalChannelItemId": "99000014001",
"voidNum": 2
}, {
"ticketId": 2,
"originalChannelItemId": "99000014002",
"voidNum": 2
}]
}
}
```
# 码作废（退款）接口
#### **接口用途**
- 当需要`作废`码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
- 已撤销(作废)/使用的码不能转换为其他状态。
- 冻结和解冻操作是相对的。
#### **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系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
| 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系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
| 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**
- `BatchCodeActivate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codeArray | List | 是 | 码号数组 | |
| callBackUrl | String | 是 | 激活成功后的回调地址 | |
| activateShopNo | String(10) | 否 | 激活门店号 | |
| activateOrg | String(10) | 否 | 激活机构 | |
| codeValidDays | Number | 否 | 相对有效天数 | 除制码当天开始相应天数结束。validStart、validEnd组合与validDay、commissionDate组合可选其一，若全部填写以相对有效期优先 |
| codeValidStart | Number(14) | 否 | 码有效开始时间 | 该字段填写时，validEnd必填格式:yyyyMMddHHmmss |
| codeValidEnd | Number(14) | 否 | 码有效结束时间 | 该字段填写时，validStart必填格式:yyyyMMddHHmmss |
| purchaseOrderNum | String | 否 | 用户购买订单号 | |
| merchantRealAmount | Number | 否 | 用户购买时商户实收金额 | 单位：分 |
| merchantBenefit | Number | 否 | 用户购买时商户优惠金额 | 单位：分 |
| optTag | String(2) | 是 | 操作分类 | 04：激活 |
**请求报文举例**
```
{
"requestId":"20181019112535100000000000000001",
"codeArray": ["10215523190570712621"],
"callBackUrl": "http://test.com/api/codeActivate",
"purchaseOrderNum":"201911191947000001",
"optTag": "04",
}
```
**同步返回参数，[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/26e35 "data")> | 是 | 批量码激活初步校验返回 |
**同步返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"requestId": "10000000000000000000002",
"tradeNo": "10000000000000000000002",
"saleChannelId":10002410,
"createDate": "20191119",
"createTime": "20191119200100",
"codeNum": 1,
"resultCode": "00",
"resultMsg": "SUCCESS",
}
}
```
**回调返回参数，[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"
}
}
```
# 批量码延期
#### **接口用途**
- 多码批量延期时，调用此接口
- 批量延期有两种方式：1.所有的码同一个有效期；2.每个码单独对应一个有效期。
#### **接口说明**
- 一次可以多码延期,一次最多1000个码。
#### **action**
- `BatchCodeUpdate`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codeArray | List | 否 | 码号数组 | 所有的码同一个有效期，与codeObjArray选择一个上传。该值上传时codeValidEnd必填 |
| codeValidEnd | String | 否 | 码有效期结束时间 | codeArray上传时，该值必填 |
| codeObjArray | List<CodeDelayInfo> | 是 | 码更新集 | 每个码单独对应一个有效期。与codeArray选择一个上传 |
| saleChannelId | Long | 否 | 取码方id | |
| saleChannelOrderId | String | 否 | 取码方制码订单号 | 当codeArray和codeObjArray均无值时取该订单号下所有串码进行延期。当订单号有值时取码方id必填 |
| callBackUrl | String | 是 | 更新成功后的回调地址 | |
| updateShopNo | String(10) | 否 | 更新门店号 | |
| updateOrg | String(10) | 否 | 更行机构 | |
| optTag | String(2) | 是 | 操作分类 | B5：批量延期 |
**请求报文举例**
```
{
"requestId":"20181019112535100000000000000001",
"codeArray": ["10215523190570712621"],
"callBackUrl": "http://test.com/api/codeVoid",
"codeValidEnd": "20200224235959",
"optTag": "B5",
}
```
**同步返回参数，[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/598b3 "statusUpdateData")> | 是 | 批量码作废初步校验返回 |
**同步返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"requestId": "10000000000000000000002",
"tradeNo": "10000000000000000000002",
"codeNum": 1
}
}
```
**回调返回参数，[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/01386 "statusUpdateCallbackData")> | 否 | 码状态更新返回数据 |
**回调返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181019112535100000000000000008",
"totalCodeNum": 1,
"successCodeNum": 1,
"codeArray": [{
"code": "100213321414112234",
...
}],
}
}
```
# 批量码作废
#### **接口用途**
- 多码批量作废时，调用此接口
#### **接口说明**
- 一次可以多码作废,一次最多20个码。
#### **action**
- `BatchCodeUpdate`
**请求参数，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<[statusUpdateData](https://book.e-buy.com/books/e-buy-40/page/598b3 "statusUpdateData")> | 是 | 批量码作废初步校验返回 |
**同步返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"requestId": "10000000000000000000002",
"tradeNo": "10000000000000000000002",
"codeNum": 1
}
}
```
**回调返回参数，[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"
}
}
```
# 码信息查询
#### **接口用途**
- 当需要查询某个指定码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
#### **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 | 商户无权限 | 券码查询和核销 权限校验不通过 |
# 单码核销
#### **接口用途**
- 券码进行核销时，调用此接口
#### **接口说明**
- 一次只能对一个码进行核销。
#### **action**
- `CodeVerify`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| verifyScene | String | 是 | 交易场景.offline线下,online线上 | |
| code | String | 是 | 码号 | |
| isProductCheck | String | 是 | 是否校验订单产品规则 | 是Y，否N |
| requestId | String | 是 | 请求流水号确保永久唯一性 | 32位长度 |
| refNo | String | 否 | 系统参考号 | 12位长度 |
| cashierTransNo | String | 否 | 收银机流水号 | 最长64位长度 |
| requestId | String | 是 | 请求流水号确保永久唯一性 | 32位长度 |
| 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 | 否 | 备注（在核销撤销、核销查询等接口原样返回） | |
**请求报文举例**
```
{
"verifyScene":"offline",
"code": "10215523190570712621",
"requestId": "20181019112535100000000000000001",
"refNo": "181215430700",
"cashierTransNo": "42441908138100007498001",
"storeInfo": {
"cityId":"1012",
"swift": "00105",
"tid": "99000014",
"mid": "99000013341001",
"shopNo": "C00001",
"storeName": "上海浦东测试门店",
"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"
}]
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[data](https://book.e-buy.com/books/e-buy-40/page/f7490 "data")> | 是 | 券码核销订单明细返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000002",
"data": {
"cashTotalAmount": 17800,
"faceValue": 50000,
"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": "联动优势电子凭证",
"thirdActivityId": "20190226134100",
"returnCashParam":{
"tenderCode":"132"
},
"printData": "00|产品：测试券|00|团购价：100|00|订单号：100000000002100002|00|兑换码：101105********4289|"
}
}
```
# 单码核销撤销
#### **接口用途**
- 当需要将本次核销交易撤销时调用
#### **接口说明**
- 此接口支持撤销指定日期的核销交易
#### **action**
- `CodeVerifyVoid`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 小于32个字符 |
| originalRequestId | String | 是 | 原核销请求流水号 | 32个字符，用于标识唯一一笔交易 |
**请求报文举例**
```
{
"requestId": "10000000000000000000001",
"originalRequestId":"10000000000000000000002"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| requestId | String | 是 | 原样返回 | |
| amount | Number | 否 | 本次撤销金额单位分 | 仅在收银一体化时用到 |
| code | String | 是 | 撤销的券码号 | |
| ticketName | String | 是 | 券名称 | |
| verifyRemark | String | 否 | 核销备注信息 | 核销接口上送原样返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": 10000000000000000000001,
"amount": "5000",
"code": "10215523190570712621",
"ticketName": "50 元现金抵价券 "
}
```
# 单码核销查询
#### **接口用途**
- 核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果
#### **接口说明**
- 此接口默认支持查询当日内核销交易
- 也可传参originalDate查询指定日核销交易
#### **action**
- `CodeVerifyQuery`
**请求参数，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 | Object<[data](https://book.e-buy.com/books/e-buy-40/page/f7490 "data")> | 是 | 券码核销订单明细返回 | |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000002",
"data": {
"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|"
}
}
```
# 单码核销通知
#### **接口用途**
- 用于实现易百券核销成功后将核销状态通知到第三方系统
#### **接口说明**
- 接口异步通知第三方
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 核销流水号 | 小于64个字符 |
| channelId | String | 是 | 通知渠道 |
|
| ticketId | String | 是 | 券ID |
|
| ticketName | String | 是 | 券名称 |
|
| thirdActivityId | String | 是 | 第三方活动id |
|
| code | String | 是 | 券号 |
|
| shopNo | String | 否 | 门店编号 |
|
| shopName | String | 否 | 门店名称 |
|
| verifyRefno | String | 否 | 线下核销机具流水号 |
|
| verifyTime | String | 是 | 券核销时间 | 格式：yyyyMMddHHmmss |
| verifyType | String | 是 | 核销类型 | 1表示POS机验证； 2表示接口验证；
999 表示不用通知上下游
|
| orderNo | String | 是 | 制码订单号 |
|
| orderItemId | String | 是 | 制码子订单号，对接方唯一识别码 |
|
| discountAmount | String | 否 | 核销折抵金额 | 单位分 |
**请求报文举例**
```
{
"requestId": "10000000000000000000001",
"ticketId":"9000000021",
"ticketName":"汉堡王皇堡/天椒皇堡套餐[bobo测试取码方]",
"thirdActivityId": "20190226134100",
"code":"10112504119074937195",
"shopNo":"1870002",
"shopName":"家有好面龙阳路店",
"verifyRefno":"178491000582",
"verifyTime":"20181016103223",
"verifyType":"1",
"orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
"orderItemId":"10191f7aee084db8915dd77293a65906",
"discountAmount":"2000"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 09 券码不存在
01 券码已使用
00 券码核销成功
|
| returnMsg | String | 是 | 请求返回信息 |
|
| requestId | String | 是 | 原样返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000001"
}
```
# 单码核销撤销通知
#### **接口用途**
- 用于实现易百券核销撤销成功后将通知到第三方系统
#### **接口说明**
- 接口异步通知第三方
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")<===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 核销撤销请求流水号 | 小于64个字符 |
| verifyTime | String | 是 | 券核销撤销时间 | 格式：yyyyMMddHHmmss |
| code | String | 是 | 劵码 | |
| originalRequestId | String | 是 | 原核销交易流水号 | 小于64个字符 |
| orderNo | String | 否 | 制码订单号 | |
| orderItemId | String | 否 | 制码子订单号，对接方唯一识别码 |
**请求报文举例**
```
{
"requestId": "10000000000000000000002",
"verifyTime":"20181016103223",
"code":"10215523190570712621",
"originalRequestId": "10000000000000000001001",
"orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
"orderItemId":"10191f7aee084db8915dd77293a65906"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| requestId | String | 是 | 原样返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000001"
}
```
# 码预核销接口
#### **接口用途**
- 当需要确认码是否可用在当前场景时，调用此接口，
#### **接口说明**
- 建议单码场景使用。多码需确认是否满足需求。
#### **action**
- `CodeCheck`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codes | List | 是 | 验码集合 | |
| cashTotalAmount | Number | 是 | 订单金额 | 单位：分 |
| isProductCheck | String | 是 | 是否校验订单产品规则 | 是Y，否N |
| brandId | String | 否 | 品牌id | 多品牌使用的码，此字段必传 |
| shopNo | String(20) | 否 | 门店号 | 线下场景必填 |
| tid | String(8) | 否 | 终端号 | |
| cityId | String | 否 | 城市id，对接时使用ebuy城市id | 有规则时必须上传 |
| goodsDetail | Object<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/1d7f7-Fbe "goodsDetail")> | 否 | 折抵产品明细 | 目前支持单码预核销检查使用 |
**请求报文举例**
```
{
"requestId":"2018111911253510000010",
"codes":["101111111111","1022222222222","1033333333333","104444444444"],
"cashTotalAmount":"20000",
"brandId":"121",
"tid":"99000014",
"shopNo":"123456",
"cityId":"1012",
"companyId":"11",
"goodsDetail":[{
"sku": "1112343",
"qty": 1,
"price": 3000,
"type": "03",
"spec": "03"
}, {
"sku": "1212342",
"qty": 1,
"price": 3500,
"type": "03",
"spec": "03"
}]
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 00为成功，其他均为失败 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data/checkResult | Object<[data/checkResult](https://book.e-buy.com/books/e-buy-40/page/e1e32 "checkResult")> | 是 | 劵码查询结果 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"checkResult":[{
"code":"1021242013780905000",
"saleChannelCode":"990001",
"saleChannelName":"易百码",
"status": "00",
"discountAmount":3000
},{
"code":"1021242013780905000",
"saleChannelCode":"990001",
"saleChannelName":"易百码",
"status": "06",
"discountAmount":3000,
}]
}
}
```
#### **券状态枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 00 | 可用 |
| 01 | 已使用 |
| 03 | 未激活 | 未激活的码需调用激活接口才能 |
| 04 | 已冻结 |
| 05 | 已作废 |
| 06 | 已过期 | |
| 07 | 未生效 | 当制码时选择次日生效，核销时会返回该状态 |
| 09 | 码不存在 |
| 35 | 劵数据异常 | 联系易百确认 |
| 39 | 核销失败 |
| 91 | 核销异常 |
# 批量码核销
#### **接口用途**
- 多码批量核销时，调用此接口
#### **接口说明**
- 一次可以多码核销,一次最多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 | 否 | 备注（在核销撤销、核销查询等接口原样返回） | |
**请求报文举例**
```
{
"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"
}]
}
```
**返回参数，[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 元现金抵价券 "
}]
}
}
```
# 取码方可用券查询
#### **接口用途**
- 当取码方需要知道自己可用的券时，可调用此接口
#### **action**
- `ChannelTicketQuery`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| activityValidStart | String | 是 | 活动开始时间 | yyyyMMddHHmmss |
| activityValidEnd | String | 是 | 活动结束时间 | yyyyMMddHHmmss |
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
**请求报文举例**
```
{
"requestId": "20181019112535100000000000000002",
"activityValidStart": "20180901000000",
"activityValidEnd": "20181231595959"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | List<[channelTicketQuery](https://book.e-buy.com/books/e-buy-40/page/f7664 "channelTicketQuery")> | 否 | 券信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": [{
"ticketId": "10001",
"ticketName": "星巴克30元代金券",
"activityId": "20001",
"activityName": "浦发星巴克代金券活动",
"activityValidStart": "20180901000000",
"activityValidEnd": "20181231595959",
"thirdActivityId": "20190226134100",
"codeValidStart": "20180901000000",
"codeValidEnd": "20181231595959",
"createDate": "20181018",
"createTime": "20181018183454",
"activityUseDescription": {
"useDescription":活动使用说明""
},
"ticketUseDescription": {
"ticketPicture":"www.baidu.com",
"useThreshold":"使用门槛",
"discountDescription":"优惠说明",
"useDescription":"使用说明"
}
},{
"ticketId": "10002",
"ticketName": "星巴克50元代金券",
"activityId": "20001",
"activityName": "浦发星巴克代金券活动",
"activityValidStart": "20180901000000",
"activityValidEnd": "20181231595959",
"codeValidStart": "20180901000000",
"codeValidEnd": "20181231595959",
"createDate": "20181018",
"createTime": "20181018183454",
"activityUseDescription": {
"useDescription":活动使用说明""
},
"ticketUseDescription": {
"ticketPicture":"www.baidu.com",
"useThreshold":"使用门槛",
"discountDescription":"优惠说明",
"useDescription":"使用说明"
}
}]
}
```
# 外部核销通知
#### **接口用途**
- 用于实现外部系统劵成功后通知到易百
#### **接口说明**
- 第三方通知EBUY
#### **action**
- `CodeVerifyNotify`
**请求参数，CHANNEL**===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 小于32个字符 |
| thirdVerifyId | String | 否 | 核销流水号 | 第三方码核销通知时上传该字段，用于标识在第三方库中的核销记录 |
| ticketName | String | 否 | 券名称 | |
| brandId | String | 是 | 品牌 | 易百定义 |
| code | String | 是 | 券号 | |
| mid | String | 否 | 商户号 | |
| shopNo | String | 否 | 门店编号 | |
| shopName | String | 否 | 门店名称 | |
| tid | String | 否 | pos终端号 | |
| verifyTime | String | 是 | 券核销时间 | 格式：yyyyMMddHHmmss |
| verifyType | String | 是 | 核销类型 | 1表示POS机验证；2表示接口验证 |
| orderNo | String | 否 | 制码订单号 | |
| orderItemId | String | 否 | 制码子订单号，对接方唯一识别码 | |
| amount | Number | 否 | 核销金额 | 单位：分 |
**请求报文举例**
```
{
"requestId": "10000000000000000000002",
"originalRequestId":"10000000000000000000001",
"ticketName":"汉堡王皇堡/天椒皇堡套餐",
"code":"10112504119074937195",
"shopNo":"1870002",
"shopName":"家有好面龙阳路店",
"verifyTime":"20181016103223",
"verifyType":"1",
"orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
"orderItemId":"10191f7aee084db8915dd77293a65906"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| requestId | String | 是 | 原样返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000002"
}
```
# 外部核销撤销通知
#### **接口用途**
- 用于实现第三方核销撤销EBUY的劵成功后通知[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")
#### **接口说明**
- 第三方核销撤销成功后通知EBUY
#### **action**
- `CodeVerifyVoidNotify`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 核销撤销请求流水号 | 小于64个字符 |
| originalRequestId | String | 是 | 第三方核销时流水号 | 32个字符，用于标识唯一一笔交易 |
| voidTime | String | 是 | 券撤销时间 | 格式：yyyyMMddHHmmss |
| code | String | 是 | 劵码 | |
| orderNo | String | 否 | 制码订单号 | |
| orderItemId | String | 否 | 制码子订单号，对接方唯一识别码 |
**请求报文举例**
```
{
"requestId": "10000000000000000000002",
"originalRequestId":"10000000000000000000001",
"voidTime":"20181016103223",
"code":"10215523190570712621",
"orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
"orderItemId":"10191f7aee084db8915dd77293a65906"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| requestId | String | 是 | 原样返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"requestId": "10000000000000000000001"
}
```
# 串码通知到用户微信卡包接口
#### **接口用途**
- 当需要将已制出的串码通知到用户微信卡包时，调用此接口
#### **接口说明**
- 易百不提供插入微信卡包功能，插入卡包的服务商为该码的制码方。
- 此接口为异步执行，同步返回成功表明任务提交成功，实际插入卡包结果异步通知到。
#### **action**
- `NotifyCodeToUser`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 待通知串码号 |
| callBackUrl | String | 是 | 结果回调地址 | |
| weChatCardPackageInfo | Object<[weChatCardPackageInfo](https://book.e-buy.com/books/e-buy-40/page/ad972-VKK "weChatCardPackageInfo")> | 否 | 微信卡包信息 |
**请求报文举例**
```
{
"requestId":"20181018183139",
"code": "100243020180912162026",
"callBackUrl": "www.XXX.com",
"weChatCardPackageInfo":{
"userUnionId":"1rbu123430vj"
}
}
```
**同步返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[notifyCodeToCardPackageResponse](https://book.e-buy.com/books/e-buy-40/page/d947b "notifyCodeToCardPackageResponse")> | 否 | 同步返回报文 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": {
"tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
"requestId": "20181018183139",
}
}
```
**异步返回参数，ESB===>CHANNEL**
- 默认情况下异步报文与同步报文一致
# 星巴克箱包本码查询
#### **接口用途**
- 当需查询箱包本码集合
#### **接口说明**
- 传入箱、本、码编号，分别获得对应的码列表
####
**请求参数**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| queryType | String | 是 | 查询类型 | X 箱， B1 包， B2本 |
| queryCode | String | 是 | 查询编号 | |
**请求报文举例**
```
{
"queryType": "X",
"queryCode":"123"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>CHANNEL**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 00 正常，非00是错误 |
| returnMsg | String | 是 | 请求返回信息 | |
| codeList | List<String> | 否 | 码信息 | |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"data": [
"100000000001212121",
"100000000001212122",
"100000000001212123"
]
}
```
# 异步第三方制码
#### **接口用途**
- 用于异步第三方制码的请求参数，发送到whale-gateway数据格式
#### **接口说明**
- 这里规定了标准的请求报文格式，发送到whale-gateway模块，然后具体对于不同码商的报文格式需要gateway转换
#### **action**
- **MakeCode**
**请求参数，whale===>whale-gateway**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
| channelId | String | 是 | 渠道Id | |
| channelTicketId | String | 是 | 渠道批次Id | |
| codeValidEnd | String | 是 | 券码有效期结束时间 | 格式为yyyyMMdd235959 |
| codeValidStart | String | 是 | 券码有效期开始时间 | 格式为yyyyMMdd000000 |
| faceValue | Double | 是 | 券面值 | |
| netValue | Double | 是 | 净值 | |
| orderId | String | 是 | 订单Id | |
| requestId | String | 是 | 请求流水号 | |
| saleChannelOrderId | String | 是 | 外部订单编号 | |
| totalCount | String | 是 | 制码数量 | |
| transDate | String | 是 | 交易日期 | 格式为
yyyyMMdd
|
| transTime | String | 是 | 交易时间 | 格式为
yyyyMMddHHmmss
|
| useTimes | String | 是 | 可核销次数 | |
| whaleTicketId | String | 是 | whale券Id | |
| saleChannelItemId | String | 是 | 子订单号 | |
**请求报文举例**
```JSON
{
"channelId": "136",
"faceValue": -1,
"makeFundsChannel": {
"benefitAmount": 0,
"channelBenefit": 0,
"discountAmount": 0,
"merchantBenefit": 0,
"merchantCustomBenefit": -1,
"merchantCustomRealAmount": -1,
"merchantRealAmount": 10,
"totalAmount": 100,
"userRealAmount": 80
},
"netValue": -1,
"orderId": "d84c1302a5e84774813bc9f1b7aaea8a",
"orderRemark": "testtttt",
"requestId": "d84c1302a5e84774813bc9f1b7aaea8a",
"saleChannelOrderId": "d84c1302a5e84774813bc9f1b7aaea8a",
"totalCount": "1",
"transDate": "20220506",
"transTime": "20220506215213",
"useTimes": "12",
"whaleTicketId": "162"
}
```
**返回参数，whale-gateway===>whale**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| sendChannelOrderId | String | 否 | 订单号 | |
| thirdCodeFamilySet | List<[CodeFamilyInfoBO](https://book.e-buy.com/books/e-buy-40/page/a5bfc)> | | | |
**返回报文举例**
```JSON
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"sendChannelOrderId": "",
"thirdCodeFamilySet": []
}
```
# 第三方码异步结果通知
#### **接口用途**
- 第三方券码异步处理完成后的通知接口
#### **接口说明**
- 接收统一的报文格式
#### **action**
- `AsynThirdCodeCallback`
**请求参数，CHANNEL===>WHALE**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
| createDate | String | | 创建日期 | |
| createTime | String | | 创建时间 | |
| returnCode | String | | 返回编码 | |
| outerOrderId | String | | 制码订单号 | |
| codeFamilyInfo | [CodeFamilyInfoBO](https://book.e-buy.com/books/e-buy-40/page/a5bfc) | | 券码 | |
# 同步批量码作废
#### **接口用途**
- 多码批量作废时，调用此接口
#### **接口说明**
- 一次可以多码作废,一次最多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",
...
}],
}
}
```
# 异步第三方作废接口
#### **接口用途**
- 用于异步第三方制码的请求参数，发送到whale-gateway数据格式
#### **接口说明**
- 这里规定了标准的请求报文格式，接收ebuyweb-gateway请求
#### **action**
- **syncUpdateCodeStatus**
**请求参数，whale===>whale-gateway**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
| outerOrderId | String | 是 | 渠道Id | |
| channelTicketId | String | 是 | 渠道批次Id | |
| reason | String | 否 | 退款原因 | |
**请求报文举例**
```JSON
{
"outerOrderId": "03136aaaaaaaaaaa",
"channelTicketId": "162",
"reason": "reason"
}
```
**返回参数，whale-gateway===>whale**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| sendChannelOrderId | String | 否 | 订单号 | |
| thirdCodeFamilySet | List<[CodeFamilyInfoBO](https://book.e-buy.com/books/e-buy-40/page/a5bfc)> | | | |
**返回报文举例**
```JSON
{
"returnCode": "00",
"returnMsg": "SUCCESS",
"sendChannelOrderId": "",
"thirdCodeFamilySet": []
}
```
# 测试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]14869[/yapi_interface]
# 后台管理类接口
# 新增活动接口
#### **接口用途**
- 当有新的电子凭证活动时，ERP调用此接口
#### **接口说明**
- PM做电子凭证立项后，3.0系统的活动Id绑定到电子凭证活动中，做一一对应关系
#### **action**
- `activityInsert`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| activityName | String | 是 | 活动名称 | 小于100个字符 |
| ebuyActivityId | String | 是 | 易百活动ID | 小于40个字符 |
| saleChannelId | String | 是 | 取码方 | |
| validStart | String | 是 | 活动有效开始时间 | |
| validEnd | String | 是 | 活动有效结束时间 | |
| isActive | String | 否 | 是否启用（Y/N） | 如不填，默认情况是启用 |
| createUser | String | 否 | 创建人 | |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| updateTime | String | 是 | 更新时间 | yyyyMMddHHmmss |
| activityConfig | Object<activityConfig> | 否 | 活动配置 |
**请求报文举例**
```
{
"activityName": "中信电子凭证活动",
"ebuyActivityId": "2018090500",
"saleChannelId":"10002401"
"validStart": "20180905112600",
"validEnd": "20181005112600",
"createUser": "xiedonglei",
"createTime": "20180905112600",
"activityConfig": {
"channelPublicKey": "publicKey",
"whalePublicKey": "publlicKey",
"verifyNotifyURL": "www.baidu.com"
}
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 返回码 | |
| returnMsg | String | 是 | 返回信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS"
}
```
# 制码通知查询接口
#### **接口用途**
- 当需要页面中展示制码通知时，ERP调用此接口
#### **接口说明**
- 如果销售渠道此次制码需要[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行短信通知，则生成一条制码通知数据。
- 制码通知以渠道方订单编号为分表位，每次调用时必须有明确的订单编号
#### **action**
- `makeNotifyQuery`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
**请求报文举例**
```
{
"saleChannelOrderId": "20180905000"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyId | String | 是 | 数据库通知id | |
| orderId | String | 是 | 数据库订单id | |
| saleChannelId | Long | 是 | 销售渠道id | |
| saleChannelOrderId | String | 是 | 销售渠道制码订单号 | |
| createDate | String | 是 | 订单创建日期 | YYYYmmdd |
| createTime | String | 是 | 订单创建时间 | YYYYmmddHHMMSS |
| orderMobile | String | 否 | 制码时上送手机号 | |
| codeNum | int | 是 | 订单制码总数 | |
| orderExtend | String | 否 | 订单扩展 | |
| isNotify | String | 是 | 是否通知 | 已通知，未通知 |
| isCanVoid | String | 是 | 是否可撤销 | 可撤销，不可撤销 |
| returnCode | String(2) | 是 | 订单返回码 | 00为成功，其他均为失败 |
| updateDate | String | 是 | 订单更新日期 | YYYYmmdd |
| updateTime | String | 是 | 订单更新时间 | YYYYmmddHHMMSS |
| status | String | 是 | 状态描述 |
**返回报文举例**
```
{
"orderId": "99000009100010101732123",
"requestId": "171698602301",
"saleChannelId": 123456,
"saleChannelOrderId":"10101732123",
"createDate":"20180905",
"createTime":"20180905160911",
"orderMobile":"13524121212",
"codeNum":1,
"isNotify":"已通知",
"isCanVoid":"可撤销",
"createDate":"20180905",
"createTime":"20180905160911",
"returnCode": "00",
"status": "订单初始状态"
}
```
# 制码通知重试接口
#### **接口用途**
- 当需要对制码重新通知时，ERP调用此接口
#### **接口说明**
- 如果销售渠道此次制码需要[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行短信通知，则生成一条制码通知数据。
- 制码通知以渠道方订单编号为分表位，每次调用时必须有明确的订单编号
#### **action**
- `makeNotifyRetry`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
**请求报文举例**
```
{
"saleChannelOrderId": "20180905000"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyId | String | 是 | 数据库通知id | |
| orderId | String | 是 | 数据库订单id | |
| saleChannelId | Long | 是 | 销售渠道id | |
| saleChannelOrderId | String | 是 | 销售渠道制码订单号 | |
| createDate | String | 是 | 订单创建日期 | YYYYmmdd |
| createTime | String | 是 | 订单创建时间 | YYYYmmddHHMMSS |
| orderMobile | String | 否 | 制码时上送手机号 | |
| codeNum | int | 是 | 订单制码总数 | |
| orderExtend | String | 否 | 订单扩展 | |
| isNotify | String | 是 | 是否通知 | 已通知，未通知 |
| isCanVoid | String | 是 | 是否可撤销 | 可撤销，不可撤销 |
| returnCode | String(2) | 是 | 订单返回码 | 00为成功，其他均为失败 |
| updateDate | String | 是 | 订单更新日期 | YYYYmmdd |
| updateTime | String | 是 | 订单更新时间 | YYYYmmddHHMMSS |
| status | String | 是 | 状态描述 |
**返回报文举例**
```
{
"orderId": "99000009100010101732123",
"requestId": "171698602301",
"saleChannelId": 123456,
"saleChannelOrderId":"10101732123",
"createDate":"20180905",
"createTime":"20180905160911",
"orderMobile":"13524121212",
"codeNum":1,
"isNotify":"已通知",
"isCanVoid":"可撤销",
"createDate":"20180905",
"createTime":"20180905160911",
"returnCode": "00",
"status": "订单初始状态"
}
```
# 新增销售渠道接口
#### **接口用途**
- 当有新的销售渠道对接时，ERP调用此接口
#### **接口说明**
- 每个第三取码方均为一个销售渠道，ERP调用此接口后能新增一个销售渠道供日后取码使用
#### **action**
- `saleChanneInsert`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelName | String | 是 | 销售渠道名称 | 小于100个字符 |
| isActive | String | 否 | 是否启用（Y/N） | 如不填，默认情况是启用 |
| remark | String | 否 | 备注 | |
| creatorName | String | 否 | 创建人 | |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| updateTime | String | 是 | 更新时间 | yyyyMMddHHmmss |
| saleChannelConfig | Object<[saleChannelConfig](https://book.e-buy.com/books/e-buy-40/page/65b9e "sendChannelConfig")> | 否 | 销售渠道配置 |
**请求报文举例**
```
{
"sendChannelName": "中信银行",
"isActive": "Y",
"remark":"备注信息",
"saleChannelConfig": {
"channelPublicKey": "publicKey",
"whalePublicKey": "publlicKey",
"verifyNotifyURL": "www.baidu.com"
}
}
```
**返回参数，中间件===>收银机**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 交易订单号 | 单位：元 |
| transDate | String | 是 | 交易时间 | 格式为：YYYYmmddHHMMSS |
| returnCode | String | 是 | 返回码 | 00表示交易成功，其他表示失败 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| rightsTimes | Integer | 是 | 权益次数 | 返回可以享受的权益次数 |
| moneyBalance | Price | 是 | 现金余额 | 单位：元 |
| pointBalance | Price | 是 | 积分余额 | 单位：分 |
| printDetail | Object<printDetail> | 否 | 打印信息 | 如需要在收银小票上打印信息时必填 |
| memberDetail | Object<[memberDetail](https://book.e-buy.com/books/e-buy-40/page/04511 "memberDetail")> | 否 | 会员信息 | 返回本次交易的会员信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "171698602301",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"rightsTimes": 1,
"moneyBalance": 40.8,
"pointBalance": 40000,
"printDetail": {
"cardNo64": "622562****8888",
"bank": "中信银行",
"paymentOrderNo": "201612315689412157458787",
"pointSale": "0",
"qrCode1": "htt://www.xxx.com/url",
"qrCode2": "",
"qrCode3": "",
"barCode1": "12345679",
"barCode2": "",
"barCode3": ""
},
"memberDetail": {
"memberId": "M000001545",
"memberName": "TONY",
"grade": "1",
"status": "1",
"balance": 1000.00,
"pointBalance": 30000
}
}
```
# 新增制码渠道接口
#### **接口用途**
- 当有新的制码渠道对接时，ERP调用此接口
#### **接口说明**
- 每个第三制码方均为一个制码渠道，ERP调用此接口后能新增一个制码渠道供日后制码使用
#### **action**
- `sendChanneInsert`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| sendChannelName | String | 是 | 制码渠道名称 | 小于100个字符 |
| isActive | String | 否 | 是否激活（Y/N） | 如不填，默认情况是激活 |
| sendChannelConfig | Object<[sendChannelConfig](https://book.e-buy.com/books/e-buy-40/page/fc221 "sendChannelConfig")> | 是 | 制码渠道配置 | 必填 |
**请求报文举例**
```
{
"sendChannelName": "资和信",
"isActive": "Y",
"sendChannelConfig": {
"thirdChannelNo": "M000001545",
"makeCodeURL": "www.baidu.com",
"verifyURL": "www.baidu.com",
"verifyNotifyURL": "www.baidu.com"
}
}
```
**返回参数，中间件===>收银机**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 交易订单号 | 单位：元 |
| transDate | String | 是 | 交易时间 | 格式为：YYYYmmddHHMMSS |
| returnCode | String | 是 | 返回码 | 00表示交易成功，其他表示失败 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| rightsTimes | Integer | 是 | 权益次数 | 返回可以享受的权益次数 |
| moneyBalance | Price | 是 | 现金余额 | 单位：元 |
| pointBalance | Price | 是 | 积分余额 | 单位：分 |
| printDetail | Object<printDetail> | 否 | 打印信息 | 如需要在收银小票上打印信息时必填 |
| memberDetail | Object<[memberDetail](https://book.e-buy.com/books/e-buy-40/page/04511 "memberDetail")> | 否 | 会员信息 | 返回本次交易的会员信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "171698602301",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"rightsTimes": 1,
"moneyBalance": 40.8,
"pointBalance": 40000,
"printDetail": {
"cardNo64": "622562****8888",
"bank": "中信银行",
"paymentOrderNo": "201612315689412157458787",
"pointSale": "0",
"qrCode1": "htt://www.xxx.com/url",
"qrCode2": "",
"qrCode3": "",
"barCode1": "12345679",
"barCode2": "",
"barCode3": ""
},
"memberDetail": {
"memberId": "M000001545",
"memberName": "TONY",
"grade": "1",
"status": "1",
"balance": 1000.00,
"pointBalance": 30000
}
}
```
# 新增券模板接口
#### **接口用途**
- 当需要创建新的券模板时，ERP调用此接口
#### **接口说明**
- 每个易百productId对应一个券模板，一个券模板可供多个活动使用
#### **action**
- `templateInsert`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| templateName | String | 是 | 券模板名称 | |
| sendChannelId | Long | 是 | 制码渠道ID | |
| brandId | Long | 是 | 品牌ID | |
| productId | Long | 是 | 易百产品ID | |
| ticketType | int | 是 | 券类型 | 1：代金券，2：折抵券，3：产品抵用券，4：复合产品券 |
| faceValue | String | 是 | 面值 | 12位字符串，分为单位 |
| sendType | String | 是 | 券模板名称 | 1：接口，2：批导 |
| isActive | String | 否 | 是否启用（Y/N） | 如不填，默认情况是启用 |
| remark | String | 否 | 备注 | |
| createUser | String | 否 | 创建人 | |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| updateTime | String | 是 | 更新时间 | yyyyMMddHHmmss |
| templateConfig | Object<[templateConfig](https://book.e-buy.com/books/e-buy-40/page/1ff8a "templateConfig")> | 否 | 券模板配置 |
**请求报文举例**
```
{
"templateName": "COSTA30元代金券",
"sendChannelId":123L,
"brandId":686L,
"productId":12345L,
"ticketType":1,
"sendType":1,
"faceValue":"000000003000"
"isActive": "Y",
"remark":"备注信息",
"createUser":"xiedonglei",
"templateConfig": {
"channelPublicKey": "publicKey",
"whalePublicKey": "publlicKey",
"verifyNotifyURL": "www.baidu.com"
}
}
```
**返回参数，中间件===>收银机**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复 |
| orderNo | String | 是 | 交易订单号 | 单位：元 |
| transDate | String | 是 | 交易时间 | 格式为：YYYYmmddHHMMSS |
| returnCode | String | 是 | 返回码 | 00表示交易成功，其他表示失败 |
| returnDesc | String | 是 | 返回信息 | 交易结果描述或错误原因 |
| rightsTimes | Integer | 是 | 权益次数 | 返回可以享受的权益次数 |
| moneyBalance | Price | 是 | 现金余额 | 单位：元 |
| pointBalance | Price | 是 | 积分余额 | 单位：分 |
| printDetail | Object<printDetail> | 否 | 打印信息 | 如需要在收银小票上打印信息时必填 |
| memberDetail | Object<[memberDetail](https://book.e-buy.com/books/e-buy-40/page/04511 "memberDetail")> | 否 | 会员信息 | 返回本次交易的会员信息 |
**返回报文举例**
```
{
"traceNo": "99000009100010101732123",
"orderNo": "171698602301",
"transDate": "20161231120533",
"returnCode": "00",
"returnDesc": "SUCCESS",
"rightsTimes": 1,
"moneyBalance": 40.8,
"pointBalance": 40000,
"printDetail": {
"cardNo64": "622562****8888",
"bank": "中信银行",
"paymentOrderNo": "201612315689412157458787",
"pointSale": "0",
"qrCode1": "htt://www.xxx.com/url",
"qrCode2": "",
"qrCode3": "",
"barCode1": "12345679",
"barCode2": "",
"barCode3": ""
},
"memberDetail": {
"memberId": "M000001545",
"memberName": "TONY",
"grade": "1",
"status": "1",
"balance": 1000.00,
"pointBalance": 30000
}
}
```
# 核销通知查询接口
#### **接口用途**
- 当需要页面中展示核销通知时，ERP调用此接口
#### **接口说明**
- 如果销售渠道此次制码需要[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行短信通知，则生成一条制码通知数据。
- 制码通知以渠道方订单编号为分表位，每次调用时必须有明确的订单编号
#### **action**
- `makeNotifyQuery`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
**请求报文举例**
```
{
"saleChannelOrderId": "20180905000"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyId | String | 是 | 数据库通知id | |
| orderId | String | 是 | 数据库订单id | |
| saleChannelId | Long | 是 | 销售渠道id | |
| saleChannelOrderId | String | 是 | 销售渠道制码订单号 | |
| createDate | String | 是 | 订单创建日期 | YYYYmmdd |
| createTime | String | 是 | 订单创建时间 | YYYYmmddHHMMSS |
| orderMobile | String | 否 | 制码时上送手机号 | |
| codeNum | int | 是 | 订单制码总数 | |
| orderExtend | String | 否 | 订单扩展 | |
| isNotify | String | 是 | 是否通知 | 已通知，未通知 |
| isCanVoid | String | 是 | 是否可撤销 | 可撤销，不可撤销 |
| returnCode | String(2) | 是 | 订单返回码 | 00为成功，其他均为失败 |
| updateDate | String | 是 | 订单更新日期 | YYYYmmdd |
| updateTime | String | 是 | 订单更新时间 | YYYYmmddHHMMSS |
| status | String | 是 | 状态描述 |
**返回报文举例**
```
{
"orderId": "99000009100010101732123",
"requestId": "171698602301",
"saleChannelId": 123456,
"saleChannelOrderId":"10101732123",
"createDate":"20180905",
"createTime":"20180905160911",
"orderMobile":"13524121212",
"codeNum":1,
"isNotify":"已通知",
"isCanVoid":"可撤销",
"createDate":"20180905",
"createTime":"20180905160911",
"returnCode": "00",
"status": "订单初始状态"
}
```
# 核销通知查询接口
#### **接口用途**
- 当需要页面中展示核销通知时，ERP调用此接口
#### **接口说明**
- 如果销售渠道此次制码需要[whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")进行短信通知，则生成一条制码通知数据。
- 制码通知以渠道方订单编号为分表位，每次调用时必须有明确的订单编号
#### **action**
- `makeNotifyQuery`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelOrderId | String | 是 | 销售渠道制码订单id | 小于64个字符 |
**请求报文举例**
```
{
"saleChannelOrderId": "20180905000"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyId | String | 是 | 数据库通知id | |
| orderId | String | 是 | 数据库订单id | |
| saleChannelId | Long | 是 | 销售渠道id | |
| saleChannelOrderId | String | 是 | 销售渠道制码订单号 | |
| createDate | String | 是 | 订单创建日期 | YYYYmmdd |
| createTime | String | 是 | 订单创建时间 | YYYYmmddHHMMSS |
| orderMobile | String | 否 | 制码时上送手机号 | |
| codeNum | int | 是 | 订单制码总数 | |
| orderExtend | String | 否 | 订单扩展 | |
| isNotify | String | 是 | 是否通知 | 已通知，未通知 |
| isCanVoid | String | 是 | 是否可撤销 | 可撤销，不可撤销 |
| returnCode | String(2) | 是 | 订单返回码 | 00为成功，其他均为失败 |
| updateDate | String | 是 | 订单更新日期 | YYYYmmdd |
| updateTime | String | 是 | 订单更新时间 | YYYYmmddHHMMSS |
| status | String | 是 | 状态描述 |
**返回报文举例**
```
{
"orderId": "99000009100010101732123",
"requestId": "171698602301",
"saleChannelId": 123456,
"saleChannelOrderId":"10101732123",
"createDate":"20180905",
"createTime":"20180905160911",
"orderMobile":"13524121212",
"codeNum":1,
"isNotify":"已通知",
"isCanVoid":"可撤销",
"createDate":"20180905",
"createTime":"20180905160911",
"returnCode": "00",
"status": "订单初始状态"
}
```
# 规则创建接口
#### **接口用途**
- 创建规则
#### **接口说明**
- 本接口用来后台管平台创建规则
#### **action**
- `createRule`
**请求参数，ERP===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| ruleScenceKey | String | 是 | 场景关键字 | 一般填写需要限制的表对象的表名 |
| ruleSceneItemKey | String | 否 | 场景对象ID | 一般填写需要限制的表的ID |
| ruleScene | String | 是 | 规则适用场景 | 自定义，例如制码和核销为不同的场景 |
| ruleName | String | 是 | 规则名称 | |
| ruleKey | String | 是 | 规则关键字 | 可理解为限制的类型，如BuyGet/ActivityLimit等 |
| ruleValue | JSONObject | 是 | 规则内容 | |
| startTime | String | 是 | 规则开始时间 | |
| endTime | String | 是 | 规则结束时间 | |
| messageTpl | String | 是 | 规则不满足提示消息模板 | 错误提示信息 |
| isActive | String | 否 | 是否启用 | Y/N 默认Y |
| isContinue | String | 否 | 规则不满足是否继续 | Y/N 默认N |
| ruleOrder | Integer | 否 | 规则执行顺序 | 默认0，数值越小优先级越高 |
**规则内容(ruleValue)说明**
**BuyGet 报文格式 根据不同的规则选择不同的字段**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| codeConfigList | String | 否 | 配置规则sku分组 | 分组格式\["111,222","333,444"\] |
| codeType | String | 否 | code类型 | 分组类型支持SKU(sku)/品类(type)/规格(spec) |
| checkExpression | String | 否 | 规则检查表达式 | 根据配置的分组检查上送产品是否满足 |
| returnExpression | String | 否 | 规则匹配返回产品表达式 | 检查表达式通过的情况下匹配返回产品是否满足 |
| limitMinAmount | BigDecimal | 否 | 满足规则的最小交易金额 | |
| amountOff | BigDecimal | 否 | 固定金额折扣 | 直接优惠折抵的金额 |
| discountOff | BigDecimal | 否 | 折扣 | 在规则匹配的金额基础上折扣 |
| superposition | Integer | 否 | 是否可以叠加使用 | 面100减20，如果可叠加就是满200减40 |
| fixedAmount | BigDecimal | 否 | 固定金额 | 例如：10元喝咖啡，将产品金额变为10元 |
| setMealFixedAmount | BigDecimal | 否 | 固定套餐金额 | 将匹配到多个产品设置为固定金额 |
| sort | String | 否 | 上送商品排序 | 例如：price/a 价格升序排列 |
| isMerchant | String | 否 | 是否为商户自由规则 | |
| faceValue | BigDecimal | 否 | 固定值 | 设置此值降直接替换规则计算的面值 |
| netValue | BigDecimal | 否 | 固定收银机入账金额 | |
| netRadio | BigDecimal | 否 | 固定收银机入账折扣 | |
| reduceValue | BigDecimal | 否 | 规定规则抵扣金额 | 对应元来的posPrice |
| cashierCode | String | 否 | 收银机对接编号 |
**限制规则报文结构**
- 目前支持的炼制规则包括
- ScenceLimit 场景限制
- ActivityLimit 活动限制
- CardBinLimit 卡bin限制
- CardNoLimit 卡号限制
- CityLimit 城市限制
- PosTidLimit POS终端限制
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| limitWay | String | 是 | 限量方式 | 数量限制(Q)/金额显示(A) |
| limitType | String | 是 | 限量类型 | 白名单(W)/黑名单(B) |
| retained | String | 否 | 是否支持滚存 | |
| binPrefixNum | Integer | 否 | bin码的前缀位数 | |
| binSuffixNum | Integer | 否 | bin码的后缀位数 | |
| description | String | 否 | 规则描述 | |
| limitItems | JSONArray | 是 | 限量明细 |
**限制明细报文结构**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| limitKey | String | 是 | 限量关键字 | 例如卡号、卡bin等 |
| limitMaxDay | Long | 是 | 日限量 | 0表示不限量 |
| limitMaxWeek | Long | 是 | 周限量 | 0表示不限量 |
| limitMaxMonth | Long | 是 | 月限量 | 0表示不限量 |
| limitMaxYear | Long | 是 | 年限量 | 0表示不限量 |
| limitMaxTotal | Long | 是 | 总限量 | 0表示不限量 |
| startTime | String | 是 | 开始时间 | yyyyMMddHHmmss |
| endTime | String | 是 | 结束时间 | yyyyMMddHHmmss |
**WeekTime 指定日限制**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| weekDay | String | 是 | 指定日期 | 指定一周中的日期 格式为7位 \[0\]表示不可使用 \[1\]表示可以使用。eg:0000000 日一二三四五六 |
| times | String | 否 | 指定时间段 | 每12位表示一个时间区间，多个用","分割。eg:090000120000,220000235959 |
**请求报文举例**
```
暂无
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ERP**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 00成功 |
| returnMsg | String | 是 | 请求返回信息 |
**返回报文举例**
```
暂无
```
# ESB制码订单
### Whale同步调用ESB制码接口
#### **接口用途**
- 当[Whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")需要进行第三方制码时，[Whale](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")将请求报文发送给ESB，ESB再统一对不同制码方通信。
#### **接口说明**
- 单产品制码时，为同步制码，需实时返回制码结果。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelId | String | 是 | 取码方id | |
| sendChannelId | String | 是 | 制码方id | |
| sendChannelOrderId | String(64) | 是 | 制码方订单号 | |
| whaleTradeNo | String(64) | 是 | 易百唯一订单号，ESB可用于与制码方作3订单唯一标识 | |
| channelMid | String | 是 | 渠道商户编号 | 制码方分配的商编，存于sendChannel表中 |
| channelTid | String | 是 | 渠道终端编号 | 制码方分配的终端号，存于sendChannel表中 |
| orderEncryptKey | String | 是 | 制码方报文加密密钥 | 3DES加密时为密钥，公私钥对加密时为公钥字符串 |
| createDate | String | 是 | 制码日期 | yyyyMMdd |
| createTime | String | 是 | 制码时间 | yyyyMMddHHmmss |
| items | <[makeOrderItems](https://book.e-buy.com/books/e-buy-40/page/esb-HRQ "makeOrderItems")> | 是 | 制码明细 |
**请求报文举例**
```
{
"saleChannelOrderId": "20181024154201",
"requestId": "20181024154201",
"notifyType": {
"mobilePhone": "13524161800"
},
"item": {
"saleChannelItemId":"20181024154201",
"commissionDate":"1",
"validDays": 10,
"ticketId": 1,
"makeFundsChannel": {
"channelBenefit": 0,
"merchantBenefit": 500,
"userRealAmount": 2500
}
}
}
```
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[makeCodeResponseData](https://book.e-buy.com/books/e-buy-40/page/d61e4 "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"
}
}
```
# ESB转发类接口--http转发请求接口
# http转发请求数据
### 第三方码实时作废请求报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdCodeVoidRequest`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 串码号 | |
| thirdCodeId | String | 否 | 制码时返回的第三方码id | |
| sendChannelOrderId | String | 否 | 制码时制码订单号 | |
| whaleTicketId | String | 是 | 易百券id | |
| channelTicketId | String | 否 | 制码方分配的产品id | |
| codeRemark | String | 否 | 码备注信息 |
### 第三方码核销转发请求报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdCodeVerifyTransferRequest`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 串码号 | |
| verifyScene | String | 是 | 核销场景 | online：线上，offline：线下 |
| tid | String | 否 | 易百终端id | 线下核销场景存在机具信息时必填 |
| shopNo | String | 否 | 易百门店编号 | 线下核销场景存在机具信息时必填 |
| shopName | String | 否 | 易百门店名称 | 线下核销场景存在机具信息时必填 |
| goodsDetail | List<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/1d7f7-Fbe "goodsDetail")> | 否 | (只有在收银POS上发起交易时才上送) |
### 第三方码核销转发返回报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdCodeVerifyTransferResponse`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| thirdTicketId | String | 是 | 串码号 | |
| thirdTicketName | String | 是 | 核销场景 | online：线上，offline：线下 |
| thirdActivityId | String | 否 | 易百终端id | 线下核销场景存在机具信息时必填 |
| thirdActivityName | String | 否 | 易百门店编号 | 线下核销场景存在机具信息时必填 |
| verifyTime | String | 否 | 易百门店名称 | 线下核销场景存在机具信息时必填 |
| verifyFundsChannel | Object<[verifyFundsChannel](https://book.e-buy.com/books/e-buy-40/page/http "verifyFundsChannel")> | 否 | 第三方码核销转发资金渠道 | |
| returnCode | String(2) | 是 | 第三方核销结果码 | 00：成功，其他均为失败 |
| returnMsg | String | 是 | 第三方核销结果 |
#### 第三方码核销转发资金渠道
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdVerifyTransferFundsChannel`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| faceValue | Number | 否 | 面值，券面金额 | |
| settlementAmount | Number | 否 | 结算金额 | |
| discountAmount | Number | 否 | 折抵金额 | |
| channelDiscountAmount | Number | 否 | 渠道折抵金额 | |
| merchantDiscountAmount | Number | 否 | 商户折抵金额 | |
| totalAmount | Number | 否 | 购买时订单总金额 | |
| userRealAmount | Number | 否 | 购买时用户实付 | |
| merchantRealAmount | Number | 否 | 商户实收金额 | |
| benefitAmount | Number | 否 | 购买时总优惠金额 | |
| channelBenefit | Number | 否 | 购买时渠道优惠 | |
| merchantBenefit | Number | 否 | 购买时商户优惠 |
### 第三方码查询转发请求报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdCodeQueryTransferRequest`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 串码号 | |
| requestId | String | 是 | 流水号 | |
| brandId | String | 否 | 易百终端id |
### 第三方码查询转发返回报文
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100 "网络通信时的一种数据交互格式") Key为`thirdCodeQueryTransferResponse`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String | 是 | 串码号 | |
| codeStatus | String | 是 | 码状态 | 见下文 |
| codeStatusDesc | String | 是 | 码状态描述 | |
| codeValidStart | String | 是 | 码有效期开始时间 | yyyyMMddHHmmss |
| codeValidEnd | String | 是 | 码有效期结束时间 | yyyyMMddHHmmss |
| purchaseTime | String | 是 | 电子凭证购买时间 | yyyyMMddHHmmss |
| verifyDate | String | 否 | 核销日期 | yyyyMMdd |
| verifyTime | String | 是 | 核销时间 | yyyyMMddHHmmss |
| ebuyTicketId | String | 否 | 易百产品id | 当第三方返回报文里有易百产品信息则必填 |
| ebuyTicketName | String | 否 | 易百产品名称 | 当第三方返回报文里有易百产品信息则必填 |
| thirdTicketId | String | 是 | 第三方产品id | |
| thirdTicketName | String | 是 | 第三方产品名称 | |
| ebuyActivityId | String | 否 | 易百活动id | |
| ebuyActivityName | String | 否 | 易百活动名称 | |
| thirdActivityId | String | 否 | 第三方活动id | |
| thirdActivityName | String | 否 | 第三方活动名称 | |
| returnCode | String(2) | 是 | 第三方查询结果码 | 00：成功，其他均为失败 |
| returnMsg | String | 是 | 第三方查询呢结果 |
#### **券状态枚举**
| 字段 | 字段意义 | 备注 |
|---|
| 00 | 可使用 |
| 01 | 已使用 |
| 02 | 可使用(一码多次使用时，码还有可用次数) |
| 03 | 未激活 | 未激活的码需调用激活接口才能 |
| 04 | 已冻结 |
| 05 | 已作废 |
| 06 | 已过期 | |
| 07 | 未生效 | 当制码时选择次日生效，核销时会返回该状态 |
| 09 | 码异常，不能用 |
# 新页面
# 第三方码激活
#### **接口用途**
- 当电子凭证平台需要调用外部制码方激活接口对某些码进行激活时，调用该接口。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做激活操作，ESB再根据不同制码方拼装报文并实时请求。
#### **url**
- `activityInsert`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 外部制码方id | |
| requestId | String(32) | 是 | 请求流水号 | |
| codeArray | List | 是 | 待激活码 | |
| validStart | String | 是 | 码有效开始时间 | |
| validEnd | String | 是 | 码有效结束时间 |
**请求报文举例**
```
{
"channelId":"10002401",
"requestId": "20180905112600001",
"codeArray": ["100809051126021", "100809051126022"],
"validStart": "20180905112600",
"validEnd": "20181005112600"
}
```
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 返回码 | |
| returnMsg | String | 是 | 返回信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "SUCCESS"
}
```
# 第三方码作废
#### **接口用途**
- 当电子凭证平台需要调用外部制码方码作废接口对某些码进行作废时，调用该接口。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做激活操作，ESB再根据不同制码方拼装报文并实时请求。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 制码方id | |
| optTag | String | 是 | 操作类型 | ThirdCodeVoid |
| transferUrl | String | 是 | 通知地址 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 | 内容如下文 |
**易百标准报文：第三方码实时作废**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | ThirdCodeVoid |
| bizContent | String<[thirdCodeVoidData](https://book.e-buy.com/books/e-buy-40/page/http "thirdCodeVoidData")> | 是 | 第三方码实时作废数据 | 需要base64解码 |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 渠道id。原样返回 | |
| requestId | String | 是 | 请求流水号。原样返回 | |
| returnCode | String | 是 | 返回码 | |
| returnMsg | String | 是 | 返回信息 |
# 第三方码核销转发
#### **接口用途**
- 当电子凭证平台需要调用外部制码方进行核销时，调用该接口。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做核销操作，ESB再根据不同制码方拼装报文并实时请求。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 制码方id | |
| transferAction | String | 是 | 操作类型 | ThirdCodeVerify |
| transferUrl | String | 是 | 通知地址 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 | 内容如下文 |
**易百标准报文：第三方码实时核销请求报文**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | ThirdCodeVerify |
| bizContent | String<[thirdVerifyTransferRequest](https://book.e-buy.com/books/e-buy-40/page/http "thirdVerifyTransferRequest")> | 是 | 第三方码实时作废数据 | 需要base64解码 |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 渠道id。原样返回 | |
| requestId | String | 是 | 请求流水号。原样返回 | |
| returnCode | String | 是 | 返回码 | |
| returnMsg | String | 是 | 返回信息 | |
| whaleMessage | String | 是 | 易百标准报文 | 内容如下文 |
**易百标准报文：第三方码实时核销返回报文**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | ThirdCodeVerify |
| bizContent | String<[thirdVerifyTransferResponse](https://book.e-buy.com/books/e-buy-40/page/http "thirdVerifyTransferResponse")> | 是 | 第三方码实时作废数据 | 需要base64解码 |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 第三方码查询转发
#### **接口用途**
- 当电子凭证平台需要调用外部制码方进行查询时，调用该接口。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做查询操作，ESB再根据不同制码方拼装报文并实时请求。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 制码方id | |
| transferAction | String | 是 | 操作类型 | ThirdCodeQuery |
| transferUrl | String | 是 | 通知地址 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 | 内容如下文 |
**易百标准报文：第三方码实时查询请求报文**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | ThirdCodeQuery |
| bizContent | String<[thirdQueryTransferRequest](https://book.e-buy.com/books/e-buy-40/page/http "thirdQueryTransferRequest")> | 是 | 第三方码实时查询数据 | 需要base64解码 |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 渠道id。原样返回 | |
| requestId | String | 是 | 请求流水号。原样返回 | |
| returnCode | String | 是 | 返回码 | |
| returnMsg | String | 是 | 返回信息 | |
| whaleMessage | String | 是 | 易百标准报文 | 内容如下文 |
**易百标准报文：第三方码实时查询返回报文**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | ThirdCodeQuery |
| bizContent | String<[thirdQueryTransferResponse](https://book.e-buy.com/books/e-buy-40/page/http "thirdQueryTransferResponse")> | 是 | 第三方码实时查询数据 | 需要base64解码 |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 易百码核销转发
#### **接口用途**
- 当电子凭证平台需要调用外部取码方进行查询时，调用该接口。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做查询操作，ESB再根据不同制码方拼装报文并实时请求。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| verifyUrl | String | 是 | 取码方核销地址 | |
| saleChannelId | String | 是 | 取码方渠道id | |
| code | String | 是 | 串码号 | |
| saleChannelOrderId | String | 是 | 取码方制码订单号 | |
| verifyScene | String | 是 | 核销场景 | online：线上，offline：线下 |
| brandId | String | 否 | 品牌id |
| tid | String | 否 | 易百终端id | 线下核销场景存在机具信息时必填 |
| shopNo | String | 否 | 易百门店编号 | 线下核销场景存在机具信息时必填 |
| shopName | String | 否 | 易百门店名称 | 线下核销场景存在机具信息时必填 |
| goodsDetail | List<[goodsDetail](https://book.e-buy.com/books/e-buy-40/page/1d7f7-Fbe "goodsDetail")> | 否 | (只有在收银POS上发起交易时才上送) | |
| messageFormat | String | 是 | 核销转发报文格式 | ebuy：易百标准报文，third：第三方自定义报文 |
**返回参数：易百码核销转发报文**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 电子凭证系统对接方id | 对应请求报文中saleChannelOrderId字段 |
| returnCode | String | 是 | 返回码 | 00：成功，其他均为失败。两位数字和字母组合 |
| returnMsg | String | 是 | 返回信息 |
# ESB转发类接口--mq转发请求接口
# 品牌方通知
### 电子凭证系统通知到品牌渠道
#### **接口用途**
- 当电子凭证发生变更操作需要通知到品牌渠道时，调用该接口。
#### **接口说明**
- 该接口为异步通知接口，电子凭证系统无需返回值，由ESB负责与外部系统交互。
- messageType字段的值在对接时确定，默认易百标准报文格式，赋值“ebuy”；如果品牌方有规定格式，则值为“third”。
- 队列名称：`whale.core.brandNotify`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")===>ESB**
**通知报文主体**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 品牌id | |
| notifyUrl | String | 是 | 通知地址 | |
| notifyType | String | 是 | 通知类型 | |
| messageType | String | 是 | 报文类型 | ebuy:易百标准报文格式，third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 |
**易百标准报文：制码通知**
- notifyType：`MakeCode`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | MakeCodeNotify |
| bizContent | JSONString<[makeCodeNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakecodenot "makeCodeNotify")> | 否 | 制码通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：制码订单作废**
- notifyType：`MakeVoid`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | MakeVoidNotify |
| bizContent | JSONString<[makeVoidNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakevoidnot "makeVoidNotify")> | 否 | 制码订单作废通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：码状态更新通知**
- notifyType：`UpdateCodeStatus`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | UpdateCodeStatusNotify |
| bizContent | JSONString<[updateCodeStatusNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAupdatecodes "updateCodeStatusNotify")> | 是 | 更新码状态通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：码延期通知**
- notifyType：`CodeDelay`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | CodeDelayNotify |
| bizContent | JSONString<[codeDelayNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAcodedelayno "codeDelayNotify")> | 是 | 码延期通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：码过期通知**
- notifyType：`CodeExpire`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | CodeExpireNotify |
| bizContent | JSONString<[codeExpireNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAcodeexpiren "codeExpireNotify")> | 是 | 码过期通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：串码核销**
- notifyType：`Verify`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyNotify |
| bizContent | JSONString<[verifyNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifynotif "verifyNotify")> | 是 | 核销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：串码核销撤销**
- notifyType：`VerifyVoid`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyVoidNotify |
| bizContent | JSONString<[verifyVoidNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifyvoidn "verifyVoidNotify")> | 是 | 核销撤销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 取码方通知
### 电子凭证系统通知到取码方
#### **接口用途**
- 当电子凭证发生变更操作需要通知到取码方时，调用该接口。
#### **接口说明**
- 该接口为异步通知接口，电子凭证系统无需返回值，由ESB负责与外部系统交互。
- messageType字段的值在对接时确定，默认易百标准报文格式，赋值“Ebuy”；如果品牌方有规定格式，则值为“Third”。
- 队列名称：`whale.core.saleChannelNotify`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>ESB**
**通知报文主体**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 品牌id | |
| notifyUrl | String | 是 | 通知地址 | |
| notifyType | String | 是 | 通知类型 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 |
**易百标准报文：串码核销**
- notifyType：`Verify`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyNotify |
| bizContent | JSONString<[verifyNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifynotif "verifyNotify")> | 是 | 核销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：串码核销撤销**
- notifyType：`VerifyVoid`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyVoidNotify |
| bizContent | JSONString<[verifyVoidNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifyvoidn "verifyVoidNotify")> | 是 | 核销撤销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：码状态更新**
- notifyType：`UpdateCodeStatus`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | UpdateCodeStatusNotify |
| bizContent | JSONString<[updateCodeStatusNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAupdatecodes "updateCodeStatusNotify")> | 是 | 更新码状态通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 制码方通知
### 电子凭证系统通知到制码方
#### **接口用途**
- 当电子凭证发生变更操作需要通知到制码方时，调用该接口。
#### **接口说明**
- 该接口为异步通知接口，电子凭证系统无需返回值，由ESB负责与外部系统交互。
- messageType字段的值在对接时确定，默认易百标准报文格式，赋值“Ebuy”；如果品牌方有规定格式，则值为“Third”。
- 队列名称：`whale.core.sendChannelNotify`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>ESB**
**通知报文主体**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 品牌id | |
| notifyUrl | String | 是 | 通知地址 | |
| notifyType | String | 是 | 通知类型 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 |
**易百标准报文：码状态更新通知**
- notifyType：`UpdateCodeStatus`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | UpdateCodeStatusNotify |
| bizContent | JSONString<[updateCodeStatusNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAupdatecodes "updateCodeStatusNotify")> | 是 | 更新码状态通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 代理渠道通知
### 电子凭证系统通知到代理商
#### **接口用途**
- 当电子凭证发生变更操作需要通知到代理商时，调用该接口。
#### **接口说明**
- 代理商：介于取码方与易百电子凭证系统之间，帮助取码方进行取码等操作，比如微信商家券系统系统。
- 该接口为异步通知接口，电子凭证系统无需返回值，由ESB负责与外部系统交互。
- messageType字段的值在对接时确定，默认易百标准报文格式，赋值“Ebuy”；如果品牌方有规定格式，则值为“Third”。
- 队列名称：`whale.core.agentChannelNotify`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>ESB**
**通知报文主体**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 代理商id | |
| notifyUrl | String | 是 | 通知地址 | |
| notifyType | String | 是 | 通知类型 | |
| messageType | String | 是 | 报文类型 | Ebuy:易百标准报文格式，Third:第三方自定义格式 |
| whaleMessage | String | 是 | 易百标准报文 |
**易百标准报文：串码核销**
- notifyType：`Verify`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyNotify |
| bizContent | JSONString<[verifyNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifynotif "verifyNotify")> | 是 | 核销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
**易百标准报文：串码核销撤销**
- notifyType：`VerifyVoid`
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String | 是 | 电子凭证系统对接方id | |
| action | String | 是 | 业务标识 | VerifyVoidNotify |
| bizContent | JSONString<[verifyVoidNotify](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAverifyvoidn "verifyVoidNotify")> | 是 | 核销撤销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 第三方微信卡包通知
### 调用第三方插入微信卡包接口
#### **接口用途**
- 当取码方需要易百协助调用制码方完成微信卡包通知时，电子凭证平台请求ESB调用此接口。
- 制码方需提供给易百相应URL。
#### **接口说明**
- 该接口为电子凭证平台调用ESB做用户卡包通知操作，ESB再根据不同制码方拼装报文并实时请求。
#### **url**
- `activityInsert`
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>ESB**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| channelId | String | 是 | 外部制码方id | |
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| codes | String | 是 | 码号 | |
| userUnionId | String | 否 | 微信用户唯一识别号 | |
| appId | String | 否 | 公众号id | |
| userOpenId | String | 否 | 微信用户唯一识别号 | |
| sign | String | 是 | 签名 |
**请求报文举例**
```
{
"channelId":"10002401",
"requestId": "20181019112535100000000000000002",
"codes": "1021242013780905000",
"userUnionId":"2429********************",
"sign":"deid3412dj98s34lix"
}
```
**返回参数，ESB===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | |
| returnMsg | String | 是 | 请求返回信息 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
}
```
# 动态码相关接口
# 获取动态码
#### **接口用途**
- 每间隔一段时间后，页面自动获取动态码时调用此接口。
#### **接口说明**
- 本接口调用需上传[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100#jwt "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")。[jwt](https://book.e-buy.com/books/e-buy-40/page/7f100#jwt "JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。")来源于验证码校验接口下发。
#### **action**
- `GenerateDynamicCode`
**请求参数，HTML===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 最长32位，用于标识唯一一笔交易，不能重复 |
| token | String | 是 | token令牌 |
**请求报文举例**
```
{
"requestId": "20181024154201",
"token":"1002342312234454"
}
```
**返回参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>HTML**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| returnCode | String | 是 | 请求返回码 | 00表示成功 |
| returnMsg | String | 是 | 请求返回信息 | |
| data | Object<[getDynamicResponseData](https://book.e-buy.com/link/264#bkmrk-json%C2%A0key%E4%B8%BAgetdynamicr "getDynamicResponseData")> | 是 | 根据查询码获取手机号返回 |
**返回报文举例**
```
{
"returnCode": "00",
"returnMsg": "操作成功",
"data": {
"createDate": "20181120",
"createTime": "20181120134012"
"tradeNo":"10000000000000000000002",
"setDynamicCodeList":["EBUY2q349ds3d0x0781","EBUY2q349ds3d0x0782","EBUY2q349ds3d0x0783","EBUY2q349ds3d0x0784","EBUY2q349ds3d0x0785"]
}
}
```
# 通知类接口
# 通知报文
### 制码通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeCodeNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：MakeCodeNotify-20200702154501-U3sdD930 |
| saleChannelId | Long | 是 | 取码方编号 | |
| saleChannelOrderId | String(64) | 是 | 取码方订单号 | |
| tradeNo | String(32) | 是 | 易百交易编号 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| codeNum | int | 是 | 总制码数量 | |
| userInfo | Object<[userInfo](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAuserinfo%EF%BC%8C%E5%BF%85%E5%A1%AB "userInfo")> | 否 | 用户信息 | |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 |
| items | List<[makeCodeNotifyItem](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakecodenot-0 "makeCodeNotifyItem")> |
### 制码通知子订单明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeCodeNotifyItem`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| saleChannelItemId | String(64) | 是 | 取码方子订单号 | |
| ticketId | String(20) | 否 | 易百券id | |
| ticketName | String(100) | 否 | 券名称 | |
| thirdSendTicketId | String(20) | 否 | 第三制码方分配的产品代码 | |
| brandTicketId | String(20) | 否 | 品牌方分配的产品代码 | |
| activityId | String(20) | 否 | 活动id | |
| activityName | String(100) | 否 | 活动名称 | |
| itemResultCode | String(2) | 是 | 子订单返回码 | |
| itemResultMsg | String(100) | 是 | 子订单返回信息 | |
| validStart | String | 是 | 码有效开始时间 | yyyyMMddHHmmss |
| validEnd | String | 是 | 码有效结束时间 | yyyyMMddHHmmss |
| codeDetail | List<[makeOrderCodeDetail](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakeorderco "makeOrderCodeDetail")> | 否 | 码详情 | |
| makeFundsChannel | Object<[makeFundsChannel](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakefundsch "makeFundsChannel")> | 否 | 资金渠道 | 是否有值取决于取码方是否上传 |
### 制码订单码明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeOrderCodeDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| codeURL | String(100) | 否 | 码链接 | |
| code | String(100) | 是 | 串码号 | |
| searchCode | String(100) | 否 | 查询码 | |
| useTimes | Integer | 是 | 码可核销次数 | |
| status | String(2) | 是 | 状态 | |
| statusDesc | String(10) | 是 | 状态描述 | |
| password | String(20) | 否 | 显示codeURL认证密码 | 此值在某些活动需要，易百会提前告知取码方 |
### 制码作废通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeVoidNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：MakeVoidNotify-20200702154501-U3sdD930 |
| saleChannelId | String(20) | 是 | 取码方id | |
| saleChannelOrderId | String(64) | 是 | 取码方订单号 | |
| createDate | String | 是 | 创建日期 | yyyyMMdd |
| createTime | String | 是 | 创建时间 | yyyyMMddHHmmss |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 |
| codeList | List<[makeVoidCodeDetail](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAmakevoidcod "makeVoidCodeDetail")> | 否 | 码明细 |
制码作废码明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeVoidCodeDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String(100) | 是 | 串码号 | |
| ticketId | String(20) | 是 | 易百券id |
### 更新码状态通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`updateCodeStatusNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：UpdateCodeStatusNotify-20200702154501-U3sdD930 |
| code | String(100) | 是 | 串码号 | |
| ticketId | Long | 是 | 券产品id | |
| optTag | String(2) | 是 | 操作标识 | 01:作废，02：冻结，03：解冻，04：激活 |
| updateDate | String | 是 | 更新日期 | yyyyMMdd |
| updateTime | String | 是 | 更新时间 | yyyyMMddHHmmss |
| saleChannelId | Long | 是 | 取码方编号 | |
| saleChannelOrderId | String | 是 | 取码方订单号 | |
| saleChannelItemId | String | 是 | 取码方自订单号 | 该码对应的制码订单中子订单号 |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 | |
| verifyRemark | String | 否 | 核销备注信息 | 核销接口上送原样返回 |
### 码延期通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`codeDelayNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：CodeDelayNotify-20200702154501-U3sdD930 |
| code | String(100) | 是 | 串码号 | |
| ticketId | Long | | 券产品id | |
| saleChannelId | String(20) | 是 | 取码方id | |
| saleChannelOrderId | String(64) | 是 | 取码方制码订单号 | |
| newValidStart | String(14) | 是 | 更新后串码有效期开始时间 | yyyyMMddHHmmss |
| newValidEnd | String(14) | 是 | 更新后串码有效期结束时间 | yyyyMMddHHmmss |
| updateDate | String | 是 | 更新日期 | yyyyMMdd |
| updateTime | String | 是 | 更新时间 | yyyyMMddHHmmss |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 | |
| verifyRemark | String | 否 | 核销备注信息 | 核销接口上送原样返回 |
### 核销通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`verifyNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：VerifyNotify-20200702154501-U3sdD930 |
| requestId | String(64) | 是 | 核销流水号 | |
| code | String(100) | 是 | 串码号 | |
| codeNum | Integer | 是 | 本次核销该串码号出现次数 | |
| saleChannelId | Long | 是 | 取码方编号 | |
| saleChannelOrderId | String(64) | 是 | 取码方制码订单号 | |
| saleChannelItemId | String(64) | 是 | 取码方制码子订单订单号 | |
| verifyNum | Integer | 是 | 本次核销请求串码兑换次数 | |
| useTimes | Integer | 否 | 总可使用次数 | |
| remainTimes | Integer | 否 | 剩余可使用次数 | |
| verifyRefno | String(64) | 否 | 系统参考号 | 走易百posp支付网关时产生 |
| verifyTime | String | 是 | 核销时间 | yyyyMMddHHmmss |
| verifyType | Integer | 是 | 核销类型 | 1:POS机验证；2:接口验证 |
| shopNo | String(20) | 否 | 门店店号 | |
| shopName | String(100) | 否 | 门店名称 | |
| cityId | String(20) | 是 | 城市ID | |
| cityName | String(100) | 是 | 城市名称 | |
| manageCompany | String(100) | 否 | 门店管理公司名称 | |
| ticketId | String(20) | 是 | 易百券id | |
| ticketName | String(100) | 是 | 券名称 | |
| ticketRemark | String(2000) | 否 | 券备注信息 | 若配置的产品中存在备注信息则原样下发 |
| thirdSendTicketId | String(20) | 否 | 第三制码方分配的产品代码 | |
| brandTicketId | String(20) | 否 | 品牌方分配的产品代码 | |
| cashierTransNo | String(64) | 否 | 收银机交易编号 | |
| userInfo | Object<[userInfo](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAuserinfo%EF%BC%8C%E5%BF%85%E5%A1%AB "userInfo")> | 否 | 用户信息 | |
| fineGrainedRuleLimit | Object<[fineGrainedRuleLimit](https://book.e-buy.com/books/e-buy-40/page/854d9 "fineGrainedRuleLimit")> | 否 | 最细粒度限量规则 | |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 | |
| verifyFundsChannel | [fundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel") | 是 | 资金信息包含Ab账户 |
|
### 核销撤销通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`verifyVoidNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：VerifyVoidNotify-20200702154501-U3sdD930 |
| requestId | String(64) | 是 | 核销撤销流水号 | |
| originalRequestId | String(64) | 是 | 原核销流水号 | |
| code | String(100) | 是 | 串码号 | |
| codeCount | Integer | 是 | 本次核销撤销该码出现次数 | |
| saleChannelId | Long | 是 | 取码方编号 | |
| saleChannelOrderId | String(64) | 是 | 取码方制码订单号 | |
| saleChannelItemId | String(63) | 是 | 取码方制码子订单订单号 | |
| verifyDate | String(8) | 是 | 原核销交易时间 | yyyyMMdd |
| verifyTime | String(14) | 是 | 原核销交易时间 | yyyyMMddHHmmss |
| verifyVoidDate | String(8) | 是 | 核销撤销日期 | yyyyMMdd |
| verifyVoidTime | String(14) | 是 | 核销撤销时间 | yyyyMMddHHmmss |
| verifyShopNo | String(20) | 否 | 原核销门店号 | |
| verifyShopName | String(100) | 否 | 原核销门店名称 | |
| ticketId | String(20) | 是 | 易百券id | |
| ticketName | String(100) | 是 | 券名称 | |
| ticketRemark | String(2000) | 否 | 券备注信息 | 若配置的产品中存在备注信息则原样下发 |
| thirdSendTicketId | String(20) | 否 | 第三制码方分配的产品代码 | |
| brandTicketId | String(20) | 否 | 品牌方分配的产品代码 | |
| originalCashierTransNo | String(64) | 否 | 原交易收银机交易编号 | |
| userInfo | Object<[userInfo](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAuserinfo%EF%BC%8C%E5%BF%85%E5%A1%AB "userInfo")> | 否 | 用户信息 | |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 | |
| verifyFundsChannel | [fundsChannel](https://book.e-buy.com/books/e-buy-40/page/cee63 "makeFundsChannel") | 是 | 资金信息包含Ab账户 |
|
### 码过期通知数据
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`codeExpireNotify`，必填 | 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| notifyRequestId | String(50) | 是 | 本次通知流水号 | 格式：CodeExpireNotify-20200702154501-U3sdD930 |
| orderRemark | JSONString | 否 | 制码请求上送内容原样下发 |
| codeExpireDetailList | List<[CodeExpireDetail](https://book.e-buy.com/link/325#bkmrk-json%C2%A0key%E4%B8%BAcodeexpired "codeExpireDetail")> | 否 | 码过期明细 |
### 码过期明细
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`codeExpireDetail`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| code | String(100) | 是 | 串码号 | |
| ticketId | Long | 是 | 券产品id | |
| validStart | String(14) | 是 | 码有效期开始时间 | yyyyMMddHHmmss |
| validEnd | String(14) | 是 | 码有效期结束时间 | yyyyMMddHHmmss |
### 用户信息
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`userInfo`，必填
- 该对象中字段目前不完全后期可能添加新字段
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| mobilePhone | String(11) | 否 | 手机号 | |
| weChatCardPackage | Object<[weChatCardPackage](https://book.e-buy.com/link/325#bkmrk-%E7%94%A8%E6%88%B7%E5%BE%AE%E4%BF%A1%E5%8D%A1%E5%8C%85%E4%BF%A1%E6%81%AF "weChatCardPackage")> | 否 | 微信卡包信息 |
### 用户微信卡包信息
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`weChatCardPackage`，必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| userUnionId | String(50) | 否 | 微信用户唯一识别号 | |
| appId | String(20) | 否 | 公众号id | |
| userOpenId | String(50) | 否 | appId对应公众号下用户唯一识别号 |
### 下单制码资金渠道
- [JSON](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式") Key为`makeFundsChannel`，非必填
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| totalAmount | Number | 是 | 总金额 | 单位：分 |
| channelBenefit | Number | 否 | 渠道出资优惠 | 单位：分 |
| merchantBenefit | Number | 否 | 商户出资优惠 | 单位：分 |
| userRealAmount | Number | 否 | 用户实付金额 | 单位：分 |
| merchantRealAmount | Number | 否 | 商户实收金额 | 单位：分 |
# 制码订单通知
#### **接口用途**
- 易百制码成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：制码通知**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | MakeCodeNotify |
| bizContent | JSONString<[makeCodeNotify](https://book.e-buy.com/link/325#bkmrk-%E5%88%B6%E7%A0%81%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "makeCodeNotify")> | 否 | 制码通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 制码订单作废通知
#### **接口用途**
- 易百制码订单作废成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：制码订单作废**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | MakeVoidNotify |
| bizContent | JSONString<[makeVoidNotify](https://book.e-buy.com/link/325#bkmrk-%E5%88%B6%E7%A0%81%E4%BD%9C%E5%BA%9F%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "makeVoidNotify")> | 否 | 制码订单作废通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 更新码状态通知
#### **接口用途**
- 取码方对码状态进行更新成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：码状态更新通知**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | UpdateCodeStatusNotify |
| bizContent | JSONString<[updateCodeStatusNotify](https://book.e-buy.com/link/325#bkmrk-%E6%9B%B4%E6%96%B0%E7%A0%81%E7%8A%B6%E6%80%81%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "updateCodeStatusNotify")> | 是 | 更新码状态通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 码延期通知
#### **接口用途**
- 取码方对码进行延期成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：码延期通知**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | CodeDelayNotify |
| bizContent | JSONString<[codeDelayNotify](https://book.e-buy.com/link/325#bkmrk-%E7%A0%81%E5%BB%B6%E6%9C%9F%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "codeDelayNotify")> | 是 | 码延期通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 码过期通知
#### **接口用途**
- 当易百自制码过期后，通知到外部。
- 每天凌晨将前一天过期的码执行通知。
- 单次通知最大支持**100**个串码。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：码过期通知**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | CodeExpireNotify |
| bizContent | JSONString<[CodeExpireNotify](https://book.e-buy.com/link/325#bkmrk-%E7%A0%81%E8%BF%87%E6%9C%9F%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "codeExpireNotify")> | 是 | 码延期通知[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串，Base64加密后 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 核销通知
#### **接口用途**
- 串码核销成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：串码核销**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | VerifyNotify |
| bizContent | JSONString<[verifyNotify](https://book.e-buy.com/link/325#bkmrk-%E6%A0%B8%E9%94%80%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "verifyNotify")> | 是 | 核销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 核销撤销通知
#### **接口用途**
- 串码核销撤销成功后，通知到外部。
#### **接口说明**
- 该接口为异步通知接口，对接方需要提供[http](https://book.e-buy.com/books/e-buy-40/page/7f100#http "基于HTTP协议的通讯方式")接口供易百post调用。
- 签名：该报文中签名是易百私钥签名，对接方需使用易百提供的公钥进行验签。签名及验签方式详见接入说明中签名算法栏。
- bizContent中的值为Base64加密后数据，此处为了查看方便，直接引用[Json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")对象。
**请求参数，[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100#whale "易百电子凭证4.0系统的别称")===>CHANNEL**
**易百标准报文：串码核销撤销**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| appId | String(10) | 是 | 电子凭证系统对接方id | |
| action | String(20) | 是 | 业务标识 | VerifyVoidNotify |
| bizContent | JSONString<[verifyVoidNotify](https://book.e-buy.com/link/325#bkmrk-%E6%A0%B8%E9%94%80%E6%92%A4%E9%94%80%E9%80%9A%E7%9F%A5%E6%95%B0%E6%8D%AE "verifyVoidNotify")> | 是 | 核销撤销通知报文[json](https://book.e-buy.com/books/e-buy-40/page/7f100#json "网络通信时的一种数据交互格式")字符串 | |
| version | String(10) | 是 | 版本号 |
| timestamp | String | 是 | 时间戳 | |
| sign | String | 是 | 签名 |
# 根据短码查询长码
#### **接口用途**
- 当需要查询某个指定码时，取码方调用此接口
#### **接口说明**
- 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
#### **action**
- `CodeQueryBySearchCode`
**请求参数，CHANNEL===>[WHALE](https://book.e-buy.com/books/e-buy-40/page/7f100 "易百电子凭证4.0系统的别称")**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| requestId | String | 是 | 请求流水号 | 32个字符，用于标识唯一一笔交易 |
| searchCodes | List | 是 | 验码集合 | |
| brandId | String | 否 | 核销门店所属品牌 | 组合劵必须上送，易百提供 |
**请求报文举例**
```
{
"requestId": "20181019112535100000000000000002",
"searchCodes": ["1021242013780905000"],
"brandId":"674"
}
```
**返回参数，[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":"1002006170000000308=WefZAWkU",
"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":"1002012040000181129-QfSjgv4j",
"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 | 码配置异常 |
# 电子券包本处理类接口
# 激活前查询
**接口用途**
- 激活前查询是否可以激活
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/activePreQuery`
**action**
- activePreQuery
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code，或本号reelId，或者包号pkgId，或者箱号boxId，用,号隔开 |
| 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"
}
```
# 激活
**接口用途**
- 激活
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/activeVoucher`
**action**
- activeVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code，或本号reelId，或者包号pkgId，或者箱号boxId，用,号隔开 |
| totalAmount | String | 否 | 折后金额 | 激活券的折后金额，多个券则为总折后金额，单位：分 |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"qrcode": "R156A001-0000491-0505,R156A002-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"
}
```
# 激活结果查询
**接口用途**
- 激活结果查询
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/activeResultQuery`
**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"
}
```
# 作废
**接口用途**
- 作废，作废后的券不可激活
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/delVoucher`
**action**
- delVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| 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"
}
```
# 核销信息以及城市范围查询
**接口用途**
- 核销信息以及城市范围查询
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/queryVerifyInfo`
**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"
}
```
# 箱本激活
**接口用途**
- 激活
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/reelActiveVoucher`
**action**
- activeVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复，必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| qrcode | String | 是 | 二维码内容 | 券号code，或本号reelId，或者包号pkgId，或者箱号boxId，用,号隔开 |
| totalAmount | String | 否 | 折后金额 | 激活券的折后金额，多个券则为总折后金额，单位：分 |
| businessType | Integer | 是 | 业务类型 | 当businessType=12时为新逻辑支持箱的概念，返回的数据中包含箱的结构，该字段不传或者不等于12则为原来的逻辑不做任何变动，返回数据中不包含箱的结构 |
**请求报文举例**
```
{
"traceNo": "99000009100010101732123",
"qrcode": "R156A001-0000491-0505,R156A002-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"
}
```
# 箱本作废
**接口用途**
- 作废，作废后的券不可激活
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/reelDelVoucher`
**action**
- delVoucher
**请求参数，中间件===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| 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"
}
```
# 线下posp接口列表
# 二维码支付或兑换
**接口用途**
- 支付宝支付
- 微信被扫支付
- 银行二维码支付(工行、中行、中信、浦发等)
- 银行二维码积分兑换(工行、中行、中信、浦发等)
- 银联立码付
- 百度支付
- 翼支付
- 其他二维码支付
- 电子凭证核销：产品券/代金券/折扣券/买N赠M券/立减券
- 外卖或自助点单订单码自动上屏
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/qrcodeSale`
**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 | Object | 否 | 扩展信息 | 特殊场景填值需与易百技术沟通 |
**请求报文举例**
```
{
"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"
}]
}
}
```
**返回参数，易百后台===>中件间**
- 可能返回[活动产品选项](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"
}
]
}
```
# 当日撤销
**接口用途**
- 需要对原交易整体撤销时，可以在原交易的同一天调用此接口。
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/void`
**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
# 交易结果查询
**接口用途**
- 在中间件未收到后台返回时，可以调用此接口查询原交易的状态。
**接口地址**
- `https://ebuywebposp-test.e-buychina.com/ebuyweb-posp/api/inquiry`
**action**
- `inquiry`
**请求参数，中件间===>易百后台**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| traceNo | String | 是 | 收银机流水号 | 不允许重复,必须以yyyyMMdd(当天)作为流水号开头+递增序列 |
| originalTraceNo | String | 是 | 原收银机流水号 | 传入需要查询的原交易收银机流水号 |
| originalDate | String | 否 | 原交易日期 | 传入需要查询的原交易日期，不传默认为当天格式为yyyyMMdd |
**请求报文举例**
```
{
"traceNo": "9900000910001014320150201",
"originalTraceNo": "9900000910001014220150201",
"originalDate": "20170912"
}
```
**返回参数，易百后台===>中件间**
| 字段 | 类型 | 是否必填 | 字段意义 | 备注 |
|---|
| 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 | 否 | 支付方式编码 | 由收银机分配，用于入账计支付方式 |
| activityProductNo | String | 否 | 活动产品编号 | |
| activityProductName | String | 否 | 活动产品名称 | |
| needSameCard | Boolean | 否 | 同一张卡支付 | 如满额立减类活动，需要同一张银行卡支付剩余金额 |
| 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": "9900000910001014420150201",
"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": "支付宝支付",
"needSameCard": true,
"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",
"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