e-Buy 电子券4.0

• 文档介绍
• 名词解释
• 接入说明
• 业务参数对象
• 资金渠道
• 余额资金渠道
• 核销资金渠道
• 下单制码资金渠道
• 产品明细
• 会员信息
• 兑换码明细
• 用户通知类型
• 微信卡包制码通知类型
• 码状态更新操作类型
• 码信息查询返回数据
• 码明细查询
• 制码请求子订单明细
• 阶梯价核销券码明细
• 批量制码订单明细返回数据
• 制码/制码查询返回数据
• 制码/制码查询返回明细
• 制码/制码查询返回码明细
• 制码撤销返回数据
• 制码撤销返回明细
• 码状态更新返回数据
• 批量码激活同步返回数据
• 门店信息
• 查询时门店信息
• 单码返回数据
• 券码核销返回数据
• 券码核销查询返回数据
• 预核销返回数据
• 券码批量核销明细
• 批量核销撤销明细
• 取码方可用券查询返回数据
• ESB制码订单明细
• ESB制码订单返回码数据
• ESB制码返回明细
• 活动使用说明
• 券使用说明
• 最细粒度规则限制数量
• 根据查询码获取手机号返回数据
• 动态码发送手机验证码返回数据
• 校验验证码返回数据
• 获取动态码返回数据
• 码更新回调数据
• 批量码更新返回数据
• 批量码更新回调数据
• 串码通知到用户微信卡包接口同步返回报文
• 第三方异步制码通知的券码信息
• 配置参数对象
• 券模板配置项
• 券配置项
• 发码方配置项
• 取码方配置项
• 交易类接口
• 同步单条发码
• 发码订单查询
• 异步批量发码
• 批量发码结果通知
• 发码撤销
• 发码撤销查询
• 码作废（退款）接口
• 码冻结接口
• 码解冻接口
• 码激活接口
• 批量码激活
• 批量码延期
• 批量码作废
• 码信息更新接口
• 码信息查询
• 单码核销
• 单码核销撤销
• 单码核销查询
• 单码核销通知
• 单码核销撤销通知
• 码预核销接口
• 批量码核销
• 批量码核销查询
• 批量码核销撤销
• 取码方可用券查询
• 外部核销通知
• 外部核销撤销通知
• 串码通知到用户微信卡包接口
• 星巴克箱包本码查询
• 异步第三方制码
• 第三方码异步结果通知
• 同步批量码作废
• 异步第三方作废接口
• 测试apimock同步
• 查询码信息查询
• 现金卡预核销
• 后台管理类接口
• 新增活动接口
• 制码通知查询接口
• 制码通知重试接口
• 新增销售渠道接口
• 新增制码渠道接口
• 新增券模板接口
• 核销通知查询接口
• 核销通知查询接口
• 规则创建接口
• ESB制码订单
• ESB转发类接口--http转发请求接口
• http转发请求数据
• 第三方码激活
• 第三方码作废
• 第三方码核销转发
• 第三方码查询转发
• 易百码核销转发
• ESB转发类接口--mq转发请求接口
• 品牌方通知
• 取码方通知
• 制码方通知
• 代理渠道通知
• 第三方微信卡包通知
• 动态码相关接口
• 获取动态码
• 通知类接口
• 通知报文
• 制码订单通知
• 制码订单作废通知
• 更新码状态通知
• 码延期通知
• 码过期通知
• 核销通知
• 核销撤销通知
• 根据短码查询长码
• 电子券包本处理类接口
• 激活前查询
• 激活
• 激活结果查询
• 作废
• 核销信息以及城市范围查询
• 箱本激活
• 箱本作废
• 线下posp接口列表
• 二维码支付或兑换
• 当日撤销
• 交易结果查询

文档介绍

文档目的

此为取码方与易百电子凭证对接的报文协议 为实现取码方对接易百制码，制码查询，制码撤销，码信息查询，码状态修改，码信息修改等制码功能

名词解释

HTTP

基于HTTP协议的通讯方式

JSON

网络通信时的一种数据交互格式

WHALE

易百电子凭证4.0系统的别称

JWT

JWT是JSON Web Token的简写，它定义了一种在客户端和服务器端安全传输数据的规范，通过 JSON 格式来传递信息。 一个JWT实际上就是一个字符串，它由三部分组成，第一段是 header（头部），第二段是 payload（主体信息或称为载荷），第三段是 signature（数字签名）。

1. header 完整的头部就像下面这样的JSON： { "typ": "JWT", "alg": "HS256" } 然后将头部进行base64加密（该加密是可以对称解密的),构成了第一部分： eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

2. playload 载荷就是存放有效信息的地方，这些有效信息包含三个部分：标准中注册的声明、公共的声明、私有的声明。 标准中注册的声明 (建议但不强制使用)： iss: jwt签发者 sub: jwt所面向的用户 aud: 接收jwt的一方 exp: jwt的过期时间，这个过期时间必须要大于签发时间 nbf: 定义在什么时间之前，该jwt都是不可用的 iat: jwt的签发时间 jti: jwt的唯一身份标识，主要用来作为一次性token,从而回避重放攻击。 公共的声明 ： 公共的声明可以添加任何的信息，一般添加用户的相关信息或其他业务需要的必要信息.但不建议添加敏感信息，因为该部分在客户端可解密。 私有的声明 ： 私有声明是提供者和消费者所共同定义的声明，一般不建议存放敏感信息，因为base64是对称解密的，意味着该部分信息可以归类为明文信息。 定义一个payload： { "username":"张三", "password":"zs123456", "dynamic Code":"EBUY123456789abcdefg" } 然后将其进行base64加密，得到JWT的第二部分： eyJvcmciOiLku4rml6XlpLTmnaEiLCJuYW1lIjoiRnJlZeeggeWGnCIsImV4cCI6MTUxNDM1NjEwMywiaWF0IjoxNTE0MzU2MDQzLCJhZ2UiOiIyOCJ9

3. signature JWT的第三部分是一个签证信息，这个签证信息由三部分组成： header (base64后的) payload (base64后的) secret 这个部分需要base64加密后的header和base64加密后的payload使用.连接组成的字符串，然后通过header中声明的加密方式进行加盐secret组合加密，然后就构成了jwt的第三部分：49UF72vSkj-sA4aHHiYN5eoZ9Nb4w5Vb45PsLF7x_NY 密钥secret是保存在服务端的，服务端会根据这个密钥进行生成token和验证，所以需要保护好。

接入说明

本文档展示了如何通过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.调用方法

2.报文结构

请求报文和返回报文都采用如下的报文结构

注意事项

• 其中biz_content字段是对请求参数或返回参数进行BASE64编码后得到的，例如：

{
    "traceNo": "99000009100010101732123",
    "originalTraceNo": "99000009100010101732124"
}

• BASE64编码后得到：

ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==

• 赋值给biz_content字段。

• 如果请求报文无法解析，或传过来的app_id无效，则异常提示返回的报文中sign字段为空。

报文举例

{
     "action" : "efuli.cashvoucher.send",
     "app_id" : "2014072300007148",
     "biz_content" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "timestamp" : "1483372334",
     "version" : "20171212",
     "sign" : "7E65B60DCFA42B04"
 }

3.签名算法

a.筛选并排序

获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。

• 注意：biz_content字段需要先Base64编码，再进行拼接

b.拼接

将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。

c.签名值计算

使用各自语言对应的SHA256WithRSA签名函数利用应用私钥（APP_PRIVATE_KEY）对待签名字符串进行签名，并进行Base64编码。

示例报文

 {
     "action" : "efuli.cashvoucher.send",
     "app_id" : "102410000",
     "biz_content" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "timestamp" : "1483372334",
     "version" : "20171212",
     "sign" : "7E65B60DCFA42B04"
 }

应用私钥（APP_PRIVATE_KEY）

-----BEGIN RSA PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdR0+PdnzkvvaNbSEp5Q8RpaelnrHu4msHAPiw1/DJXFPucoEPqPmDAq4IoaW02/mbvHQGr8d/g/g+cbCqUVctl8ygigTvlOAsoWJWrd76gk9lK+SsQBx3BN1pMbPADAljtFS3oJw10MjCg/wIgmwWaqdCRB1QGwJzw3HnripbHr59BKMv/VYPvgDJx+ohQrfLd9fysbJRcsQKqCs72jxD8U9KHO87upvpZtJT2QYdVrntsWL1UUxfyEIKmZy2Lf3UZvqKC4sahgH6pQhCMIhwBWm06FyktRji1ewNfF6zIpkCla/HvJzfqXaqhouXJm2qgRjJ/crfTjONdd/9iuNlAgMBAAECggEAS4GbwY0p4ouHRFha7okIVfmIZautUrkilscxnXzeHV2U8cnJCiKePvY/ZOdt7UkaKVks/rTO+vn5aMkd/nZ0evAAjiYUvoxjnymPU3u/q9Z5lWGgM83HnKAaR9FTsWRV8ab2cP3LYM6uQywoCFHM4GotiFO5GucMo1T2Tzq/HOUAjMzQASQ0ywaANZvNoZDw6ScMPUgGnYnHWbs34l7F2abyKyDiNo7sPtMtRpFYi+go+S7dygMX0G1IFoCIr4X2HNu/4e3XIFvJjzoUhCF/byDcM992LvcWVgM3Ke/F1oBm+bCFit67hN6mxoi2SEARdQGnBysvVo1FLPHKZ60FVQKBgQDidFk8hq8YKEvcjqPSJSd8Oo30zeyWf0R/QNLQOAIqYKCJAcAiHDcYMx5clQQxjFTYXriY+B1J3he6w3+5NStZqL1o1lcy5w7dhcVFXT1yn2KwUiO6YSJ25KeJHvXtDH66WGIQJMmbg90J2u4HRJxYNODmeVdS1seK5qaL0uxs6wKBgQCxzHbdbkoiJgFd/c7BdTKnZh2h6x7SsX44IcbTqKsx7zA61ogoegHaKB4yq3xaR8Gm9uazo5SCtbjS0bO5iQLrv8oLUDaNm5Ckm2ENk/M+TB0Hq24eFytiwUAS6FmdCncjq4xb2x8mqOQQiGvlyD91Na4HRBwxP16Wqwhz3Nac7wKBgAY1lIDRXJm3+SSKELnhZOzGGkBdKSCTSsiGeYFWF9Ebpys6jg8hYO1b8XguadgF9gmcx0kCfKMa4OGxHJ5yc8bYlqD6R5fQuBqg4WDehqHO9wDIr8wbf7ts158t5yZh0lO/uqigqZqHCheMFjzCx9qvUH9hUmCmHQCVBHoPBYaTAoGBAJcixAPURaYjglQAdOlUE3vivNuvvqLBCBb090tifCvVM71AMbuegsaMBadyyCECECY6iL85FPvLN1HVuh3DzrzRahEV3VmgXGLgRa7CDintj1u+qLthXJr0xN+NrOdmRwIGSCio6iD1vfAj1vwbrX2X5Nf+WKywPlp7BpNerPv3AoGALv4iJpOJVAW3Pmuvmc1a3cAsAvv0DGjiGOXn+IyBdX9tJtKppVPEwElibNAltvvgWX++5ctYD2SXNQLV56rkZCmauXP2gTPG3tCutH4jNiNIBUCfDXlt9DDyQAe0KfRFemzIa5rTWA7wRNsVTCm3n4ZqPlKfMC4HmOGU2hgN3LY=
-----END RSA PRIVATE KEY-----

拼接报文参数

action=efuli.cashvoucher.send&app_id=2014072300007148&biz_content=ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==&timestamp=1483372334&version=20171212

签名值计算

gUTdEB0lAS/ECkP98weSHf6k31Fmd4hcw0zPG8ewbMTfDFSubKlel/1C16upb2AHzN873HMwUlkcTg7ZuN92KDIkfsbINd2IwVY2tWMvKt5O8gqC2a8XbS25ZObUlLK5zZmU7mQ/DLbyY+EAhkYdGnwskloJkydi2zmLv99xT5G01yXBLSNiTrPBTsc2OhBkA44kknnok0x+hS4HfcgQwGPMG4y+V5aT1bhPDypwdbfAg+EN/5XoSECsIcsvBirdk+BGPjBIuwHHF+Hir/3E3i20ImtlowBc6jwh5qFOVqGN/w2UEPfg6xJxHyW04FBipt6mw7huD4PA4pA4qZRnsg==

签名Demo Java版

点击下载 signdemo.zip

业务参数对象

资金渠道

• JSON Key为fundsChannel，出现在返回报文中，非必填

余额资金渠道

• 
  
  • JSON Key为remainFundsChannel，出现在返回报文中，非必填

  字段	类型	是否必填	字段意义	备注
  remainTotalAmount	Number	否	剩余订单总金额	单位：分。
  remainDiscountAmount	Number	否	剩余折扣金额	单位：分。
  remainMerchantRealAmount	Number	否	剩余商户实收金额	单位：分。
  remainChannelBenefit	Number	否	剩余渠道出资优惠	单位：分
  remainMerchantBenefit	Number	否	剩余商户出资优惠	单位：分
  remainUserRealAmount	Number	否	剩余用户实付金额	单位：分

核销资金渠道

• JSON Key为verifyFundsChannel，出现在返回报文中，非必填

下单制码资金渠道

• JSON Key为makeFundsChannel，非必填

产品明细

• JSON Key为goodsDetail，必填

会员信息

码明细

• JSON Key为memberDetail，必填

兑换码明细

• JSON Key为redeemCodeDetail，出现在返回报文中，非必填

用户通知类型

制码通知类型

• 制码时，当需要易百通知到用户，可由取码方指定通知渠道及渠道用户信息

微信卡包制码通知类型

• 当取码方需要易百协助调用制码方完成微信卡包通知时，制码时上传该字段

码状态更新操作类型

• JSON Key为updateOpts，必填

码信息查询返回数据

• JSON Key为codeQueryResponseData，必填

码明细查询

• JSON Key为codeQueryCodeDetail，必填

制码请求子订单明细

• JSON Key为Items，必填

阶梯价核销券码明细

• JSON Key为codeArr，出现在返回报文中，非必填

批量制码订单明细返回数据

• JSON Key为batchMakeCodeResponseData，必填

制码/制码查询返回数据

• JSON 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>	否	码信息

制码/制码查询返回明细

制码订单查询明细返回

• JSON Key为makeQueryResponseItem，必填

制码/制码查询返回码明细

订单券码明细返回

• JSON Key为makeOrderResponseCodeDetail，必填

制码撤销返回数据

制码订单返回码数据

• JSON Key为makeVoidResponseData，必填

制码撤销返回明细

制码订单返回码

• JSON Key为makeVoidResponseVoidDetail，必填

码状态更新返回数据

• JSON Key为statusUpdateData，必填

批量码激活同步返回数据

• JSON Key为batchCodeActivateResponseData，必填

门店信息

• JSON Key为storeInfo此信息为线下门店核销时上送

查询时门店信息

• • JSON 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 Key为singleMakeOrderResponseData，必填

券码核销返回数据

• JSON Key为codeVerifyResponseData，必填

券码核销查询返回数据

• JSON Key为codeVerifyQueryResponseData，必填

预核销返回数据

预核销明细

• JSON Key为codeCheckResponseData，必填

券码批量核销明细

• JSON Key为batchCodeVerifyResponseData，必填

批量核销撤销明细

券码批量核销撤销明细

• JSON Key为batchCodeVerifyVoidResponseData，必填

取码方可用券查询返回数据

• JSON Key为channelTicketQueryData，必填

ESB制码订单明细

• JSON Key为Items，必填

ESB制码订单返回码数据

• JSON Key为esbMakeOrderResponseData，必填

ESB制码返回明细

• JSON Key为esbMakeCodeResponseItem，必填

活动使用说明

• JSON Key为activityUseDescription，必填

券使用说明

• JSON Key为ticketUseDescription，必填

最细粒度规则限制数量

• JSON Key为fineGrainedRuleLimit，出现在返回报文中，非必填

根据查询码获取手机号返回数据

• JSON Key为getMobileBySearchCodeResponseData，必填

动态码发送手机验证码返回数据

• JSON Key为sendVerificationCodeResponseData，必填

校验验证码返回数据

• JSON Key为checkVerificationCodeResponseData，必填

获取动态码返回数据

• JSON Key为getDynamicResponseData，必填

码更新回调数据

券码批量更新回调返回明细

• JSON Key为codeUpdateCallbackData，必填

批量码更新返回数据

券码批量更新返回明细

• JSON Key为batchCodeUpdateResponseData，必填

批量码更新回调数据

券码批量更新回调返回明细

• JSON Key为batchCodeVoidCallbackData，必填

串码通知到用户微信卡包接口同步返回报文

• JSON Key为notifyCodeToCardPackageResponse，必填

第三方异步制码通知的券码信息

• JSON Key为codeFamilyInfoList，必填

配置参数对象

券模板配置项

券模板配置

券配置项

发码方配置项

制码渠道配置

取码方配置项

销售渠道配置

交易类接口

同步单条发码

接口用途

• 支持请码方一次单品请求调用,单品发码数量上限100

接口说明

• 每次调用时必须有明确的渠道订单编号。
• commissionDate = -1时，所制码不具有支付功能（即码没有激活），如果需要激活该码的支付功能需要再次调用"码激活"接口。
• 同步单条发码时，saleChannelOrderId和saleChannelItemId可用同一值。
• returnCode = "00"时，说明订单进入制码流程。itemResultCode = "00"时，说明订单制码成。
• notifyType为券码发送到用户的形式，是否需要通知以券配置为开关

action

• MakeCode

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "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===>CHANNEL

返回报文举例

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

券状态枚举

发码订单查询

接口用途

• 当需要查询发码订单结果时，取码方调用此接口
• 当调用同步单条发码超时或未知状态，取码方调用此接口确认交易结果
• 此接口不支持异步批量发码的订单查询

接口说明

• 每一次销售渠道对接whale进行制码，生成一个制码订单。
• 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号

action

• MakeQuery

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "originalChannelOrderId": "20180912162026",
    "requestId":"20180912162026"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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进行制码，生成一个制码订单。
• 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号。
• 制码请求接收后，会同步返回制码前校验结果，后端成功生成码后，异步通知到callBackUrl指定的回调接口。

action

• MakeBatchCode

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "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===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "saleChannelOrderId": "201811261721",
        "saleChannelId": 99000014,
        "tradeNo": "4a784d0ec74d4211bb3c425f004f95ac",
        "createTime": "20181126172115",
        "codeNum": 5,
        "createDate": "20181126"
    }
}

批量发码结果通知

接口用途

• 异步批量下单接口所要求的码全部成功生成后，通过此接口将码信息回调到取码方

接口说明

• 接口与“异步批量发码”是一组接口来完成业务
• 此接口以http post请求方式回调取码方callBackUrl地址
• returnCode = "00"时，说明订单进入制码流程。resultCode = "00"时，说明子订单制码成。
• 如果未收到易百的回调请求，取码方可以传原订单号再次调用异步批量发码

返回参数，CHANNEL===>WHALE

返回报文举例

{
    "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

请求报文举例

{
    "originalChannelOrderId": "20180912162026",
    "requestId":"20180912162026"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "originalChannelOrderId": "20180912162026",
    "orderDate": "20180905",
    "requestId":"20180912162026"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "requestId": "20181019112535100000000000000008",
    "code": "1021242013780905000",
    "optTag":"01"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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": {}
}

券状态枚举

码冻结接口

接口用途

• 当需要冻结码时，取码方调用此接口

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
• 已撤销(作废)/使用的码不能转换为其他状态。
• 冻结和解冻操作是相对的。

action

• CodeStatusUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "channelOrderId": "20180912162026",
    "requestId": "20181019112535100000000000000008",
    "code": "1021242013780905000",
    "optTag":"02"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20181019112535100000000000000008",
        "currentStatus": "01",
        "statusDesc": "已作废",
        "updateDate":"20181019",
        "updateTime":"20181019112535"
    }
}

码解冻接口

接口用途

• 当需要解冻码时，取码方调用此接口

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
• 已撤销(作废)/使用的码不能转换为其他状态。
• 冻结和解冻操作是相对的。

action

• CodeStatusUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "channelOrderId": "20180912162026",
    "requestId": "20181019112535100000000000000008",
    "code": "1021242013780905000",
    "optTag":"03"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20181019112535100000000000000008",
        "currentStatus": "01",
        "statusDesc": "已作废",
        "updateDate":"20181019",
        "updateTime":"20181019112535"
    }
}

码激活接口

接口用途

• 当需要激活码时，取码方调用此接口

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
• 已撤销(作废)/使用的码不能转换为其他状态。

action

• CodeStatusUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20181019112535100000000000000008",
    "code": "1021242013780905000",
    "codeValidDays":9,
    "purchaseOrderNum":"20191119192700123",
    "optTag":"04"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "requestId":"20181019112535100000000000000001",
    "codeArray": ["10215523190570712621"],
    "callBackUrl": "http://test.com/api/codeActivate",
    "purchaseOrderNum":"201911191947000001",
    "optTag": "04",
}

同步返回参数，WHALE===>CHANNEL

同步返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "data": {
        "requestId": "10000000000000000000002",
        "tradeNo": "10000000000000000000002",
        "saleChannelId":10002410,
        "createDate": "20191119",
        "createTime": "20191119200100",
        "codeNum": 1,
        "resultCode": "00",
        "resultMsg": "SUCCESS",
    }
}

回调返回参数，WHALE===>CHANNEL

回调返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20181019112535100000000000000008",
        "currentStatus": "00",
        "statusDesc": "未使用",
        "updateDate":"20181019",
        "updateTime":"20181019112535"
    }
}

批量码延期

接口用途

• 多码批量延期时，调用此接口
• 批量延期有两种方式：1.所有的码同一个有效期；2.每个码单独对应一个有效期。

接口说明

• 一次可以多码延期,一次最多1000个码。

action

• BatchCodeUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId":"20181019112535100000000000000001",
    "codeArray": ["10215523190570712621"],
    "callBackUrl": "http://test.com/api/codeVoid",
    "codeValidEnd": "20200224235959",
    "optTag": "B5",
}

同步返回参数，WHALE===>CHANNEL

同步返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "data": {
        "requestId": "10000000000000000000002",
        "tradeNo": "10000000000000000000002",
        "codeNum": 1
    }
}

回调返回参数，WHALE===>CHANNEL

回调返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20181019112535100000000000000008",
        "totalCodeNum": 1,
        "successCodeNum": 1,
        "codeArray": [{
            "code": "100213321414112234",
            ...
            }],
    }
}

批量码作废

接口用途

• 多码批量作废时，调用此接口

接口说明

• 一次可以多码作废,一次最多20个码。

action

• BatchCodeUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId":"20181019112535100000000000000001",
    "codeArray": ["10215523190570712621"],
    "callBackUrl": "http://test.com/api/codeVoid",
    "optTag": "B1",
}

同步返回参数，WHALE===>CHANNEL

同步返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "data": {
        "requestId": "10000000000000000000002",
        "tradeNo": "10000000000000000000002",
        "codeNum": 1
    }
}

回调返回参数，WHALE===>CHANNEL

回调返回报文举例

{
    "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

请求报文举例

{
    "requestId": "20180912162026",
    "code": "1012123342335432145",
    "updateOpts": {
        "updatePurchaseTime": "20181103105501",
        "updateMakeNotifyType": {
            "mobilePhone": "13510121314"
        },
        "updateMerchantRealAmount": 1200
    }
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20180912162026",
        "currentStatus": "00",
        "statusDesc":"未使用",
        "updateDate":"20181019",
        "updateTime":"20181019112535"
    }
}

码信息查询

接口用途

• 当需要查询某个指定码时，取码方调用此接口

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
  

action

• CodeQuery

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20181019112535100000000000000002",
    "codes": ["1021242013780905000"],
    "brandId":"2429",
    "cityId":5493
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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,
        }]
    }
}

券状态枚举

单码核销

接口用途

• 券码进行核销时，调用此接口

接口说明

• 一次只能对一个码进行核销。

action

• CodeVerify

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "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===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "requestId": "10000000000000000000001",
    "originalRequestId":"10000000000000000000002"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": 10000000000000000000001,
    "amount": "5000",
    "code": "10215523190570712621",
    "ticketName": "50 元现金抵价券 "
}

单码核销查询

接口用途

• 核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果

接口说明

• 此接口默认支持查询当日内核销交易
• 也可传参originalDate查询指定日核销交易

action

• CodeVerifyQuery

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20180905000",
    "originalRequestId":"1021867639235435",
    "originalDate": "20170912"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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===>CHANNEL

请求报文举例

{
    "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===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": "10000000000000000000001"
}

单码核销撤销通知

接口用途

• 用于实现易百券核销撤销成功后将通知到第三方系统

接口说明

• 接口异步通知第三方

请求参数，WHALE<===>CHANNEL

请求报文举例

{
    "requestId": "10000000000000000000002",
    "verifyTime":"20181016103223",
    "code":"10215523190570712621",
    "originalRequestId": "10000000000000000001001",
    "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
    "orderItemId":"10191f7aee084db8915dd77293a65906"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": "10000000000000000000001"
}

码预核销接口

接口用途

• 当需要确认码是否可用在当前场景时，调用此接口，

接口说明

• 建议单码场景使用。多码需确认是否满足需求。

action

• CodeCheck

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "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===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "data": {
        "checkResult":[{
            "code":"1021242013780905000",
            "saleChannelCode":"990001",
            "saleChannelName":"易百码",
            "status": "00",
            "discountAmount":3000
        },{
            "code":"1021242013780905000",
            "saleChannelCode":"990001",
            "saleChannelName":"易百码",
            "status": "06",
            "discountAmount":3000,
        }]
    }
}

券状态枚举

批量码核销

接口用途

• 多码批量核销时，调用此接口

接口说明

• 一次可以多码核销,一次最多10个码。

action

• BatchCodesVerify

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "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===>CHANNEL

返回报文举例

{
    "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枚举

批量码核销查询

接口用途

• 批量核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果

接口说明

• 此接口默认支持查询当日内核销交易
• 也可传参originalDate查询指定日核销交易

action

• BatchCodeVerifyQuery

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20180905000",
    "originalRequestId":"1021867639235435",
    "originalDate": "20170912"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "requestId": "10000000000000000000001",
    "originalRequestId":"10000000000000000000002"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": 10000000000000000000002,
    "data": {
        "voidResult":[{
              "code":"1021242013780905000",
              "status":"00",
              "statusDesc":"成功",
              "amount": "5000",
              "ticketName": "50 元现金抵价券 "
        }]
    }
}

取码方可用券查询

接口用途

• 当取码方需要知道自己可用的券时，可调用此接口

action

• ChannelTicketQuery

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20181019112535100000000000000002",
    "activityValidStart": "20180901000000",
    "activityValidEnd": "20181231595959"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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

请求报文举例

{
    "requestId": "10000000000000000000002",
    "originalRequestId":"10000000000000000000001",
    "ticketName":"汉堡王皇堡/天椒皇堡套餐",
    "code":"10112504119074937195",
    "shopNo":"1870002",
    "shopName":"家有好面龙阳路店",
    "verifyTime":"20181016103223",
    "verifyType":"1",
    "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
    "orderItemId":"10191f7aee084db8915dd77293a65906"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": "10000000000000000000002"
}

外部核销撤销通知

接口用途

• 用于实现第三方核销撤销EBUY的劵成功后通知WHALE

接口说明

• 第三方核销撤销成功后通知EBUY

action

• CodeVerifyVoidNotify

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "10000000000000000000002",
    "originalRequestId":"10000000000000000000001",
    "voidTime":"20181016103223",
    "code":"10215523190570712621",
    "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5",
    "orderItemId":"10191f7aee084db8915dd77293a65906"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "操作成功",
    "requestId": "10000000000000000000001"
}

串码通知到用户微信卡包接口

接口用途

• 当需要将已制出的串码通知到用户微信卡包时，调用此接口

接口说明

• 易百不提供插入微信卡包功能，插入卡包的服务商为该码的制码方。
• 此接口为异步执行，同步返回成功表明任务提交成功，实际插入卡包结果异步通知到。

action

• NotifyCodeToUser

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId":"20181018183139",
    "code": "100243020180912162026",
    "callBackUrl": "www.XXX.com",
    "weChatCardPackageInfo":{
        "userUnionId":"1rbu123430vj"
    }
}

同步返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": {
        "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5",
        "requestId": "20181018183139",
    }
}

异步返回参数，ESB===>CHANNEL

• 默认情况下异步报文与同步报文一致

星巴克箱包本码查询

接口用途

• 当需查询箱包本码集合

接口说明

• 传入箱、本、码编号，分别获得对应的码列表

请求参数

请求报文举例

{
    "queryType": "X",
    "queryCode":"123"
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "returnCode": "00",
    "returnMsg": "SUCCESS",
    "data": [
    	"100000000001212121",
        "100000000001212122",
        "100000000001212123"
    ]
}

异步第三方制码

接口用途

• 用于异步第三方制码的请求参数，发送到whale-gateway数据格式

接口说明

• 这里规定了标准的请求报文格式，发送到whale-gateway模块，然后具体对于不同码商的报文格式需要gateway转换

action

• MakeCode

请求参数，whale===>whale-gateway

请求报文举例

{
  "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": "00",
    "returnMsg": "SUCCESS",
    "sendChannelOrderId": "",
    "thirdCodeFamilySet": []
}

第三方码异步结果通知

接口用途

• 第三方券码异步处理完成后的通知接口

接口说明

• 接收统一的报文格式

action

• AsynThirdCodeCallback

请求参数，CHANNEL===>WHALE

同步批量码作废

接口用途

• 多码批量作废时，调用此接口

接口说明

• 一次可以多码作废,一次最多20个码。

action

• SyncBatchCodeUpdate

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId":"20181019112535100000000000000001",
    "codeArray": ["10215523190570712621"],
    "callBackUrl": "http://test.com/api/codeVoid",
    "optTag": "B1",
}

同步返回参数，WHALE===>CHANNEL

回调返回报文举例

{
    "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": "03136aaaaaaaaaaa",
  "channelTicketId": "162",
  "reason": "reason"
}

返回参数，whale-gateway===>whale

返回报文举例

{
	"returnCode": "00",
    "returnMsg": "SUCCESS",
    "sendChannelOrderId": "",
    "thirdCodeFamilySet": []
}

测试apimock同步

[yapi_interface]617[/yapi_interface]

查询码信息查询

接口用途

• 当需要查询某个指定码时，取码方调用此接口

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。

action

• CodeQueryBySearchCode

请求参数，CHANNEL===>WHALE

请求报文举例

{
    "requestId": "20181019112535100000000000000002",
    "codes": ["1021242013780905000"],
    "brandId":"2429",
    "cityId":5493
}

返回参数，WHALE===>CHANNEL

返回报文举例

{
    "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,
        }]
    }
}

券状态枚举

现金卡预核销

[yapi_interface]14869[/yapi_interface]

后台管理类接口

新增活动接口

接口用途

• 当有新的电子凭证活动时，ERP调用此接口

接口说明

• PM做电子凭证立项后，3.0系统的活动Id绑定到电子凭证活动中，做一一对应关系

action

• activityInsert

请求参数，ERP===>WHALE

请求报文举例

{
    "activityName": "中信电子凭证活动",
    "ebuyActivityId": "2018090500",
    "saleChannelId":"10002401"
    "validStart": "20180905112600",
    "validEnd": "20181005112600",
    "createUser": "xiedonglei",
    "createTime": "20180905112600",
    "activityConfig": {
        "channelPublicKey": "publicKey",
        "whalePublicKey": "publlicKey",
        "verifyNotifyURL": "www.baidu.com"
    }
}

返回参数，WHALE===>ERP