星巴克预付费券系统

• 文档介绍
• 名词解释
• 业务参数对象
• 资金渠道
• 券码历史记录
• 余额资金渠道
• 核销资金渠道
• 下单制码资金渠道
• 产品明细
• 会员信息
• 兑换码明细
• 用户通知类型
• 微信卡包制码通知类型
• 码状态更新操作类型
• 码信息查询返回数据
• 码明细查询
• 阶梯价核销券码明细
• 制码请求子订单明细
• 批量制码订单明细返回数据
• 制码/制码查询返回数据
• 制码/制码查询返回明细
• 制码/制码查询返回码明细
• 制码撤销返回数据
• 制码撤销返回明细
• 码状态更新返回数据
• 批量码激活同步返回数据
• 门店信息
• 查询时门店信息
• 单码返回数据
• 券码核销返回数据
• 券码核销查询返回数据
• 预核销返回数据
• 券码批量核销明细
• 批量核销撤销明细
• 取码方可用券查询返回数据
• ESB制码订单明细
• ESB制码订单返回码数据
• ESB制码返回明细
• 活动使用说明
• 券使用说明
• 最细粒度规则限制数量
• 根据查询码获取手机号返回数据
• 动态码发送手机验证码返回数据
• 校验验证码返回数据
• 获取动态码返回数据
• 码更新回调数据
• 批量码更新返回数据
• 批量码更新回调数据
• 串码通知到用户微信卡包接口同步返回报文
• 第三方异步制码通知的券码信息
• 激活信息
• 核销备注描述
• 二维码支付或兑换 extendData
• 券码历史记录扩展字段
• 接入说明
• 配置参数对象
• 券模板配置项
• 券配置项
• 发码方配置项
• 取码方配置项
• 线上交易类接口
• 同步单品发码（单个&批量发码与激活）
• 发码订单查询
• 码作废（退款）接口
• 码冻结接口
• 码解冻接口
• 码激活接口
• 同步批量码作废
• 码信息更新接口
• 码信息查询
• 批量码核销
• 批量码核销查询
• 批量码核销撤销
• 测试apimock同步
• 查询码信息查询
• 运营管理类接口
• 创建券产品
• 变更券产品
• 券产品详情查询
• 创建批次
• 批次编辑
• 批次详情查询
• 券码操作记录查询
• 箱本包处理类接口
• 激活查询
• 券码历史记录查询
• 激活
• 激活结果查询
• 作废
• 核销信息以及城市范围查询
• B2B饮料券箱本激活
• B2B饮料券箱本作废
• 卡号段激活实体卡券（B2B定制）
• 线下posp接口列表
• 二维码支付或兑换
• 当日撤销
• 电子凭证查询

文档介绍

文档目的

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

开发测环境

• 线上接口路径

https://dev-starbucks-gateway.e-buy.com/api/product

• 月饼券接口路径

https://dev-starbucks-gateway.e-buy.com/starbucksjs

• 线下接口路径

https://dev-starbucks-gateway.e-buy.com/ebuyweb-posp/api

• 运营类后管接口路径

https://dev-starbucks-gateway.e-buy.com/41/

产线环境

• 线上接口路径

https://starbucks-gateway.e-buy.com/api/product

• 月饼券接口路径

https://starbucks-gateway.e-buy.com/js

• 线下接口路径

https://starbucks-gateway.e-buy.com/ebuyweb-posp/api

• 运营类后管接口路径

https://starbucks-gateway.e-buy.com/41/

名词解释

HTTP

基于HTTP协议的通讯方式

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和验证，所以需要保护好。

业务参数对象

资金渠道

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

券码历史记录

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

余额资金渠道

• 
  
  • 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为codeArr，出现在返回报文中，非必填

制码请求子订单明细

• JSON Key为Items，必填

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

• 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，必填

激活信息

• JSON Key为extendData，必填

核销备注描述

• JSON  

二维码支付或兑换 extendData

• JSON 

券码历史记录扩展字段

• JSON 

接入说明

本文档展示了如何通过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

配置参数对象

券模板配置项

券模板配置

券配置项

发码方配置项

制码渠道配置

取码方配置项

销售渠道配置

线上交易类接口

同步单品发码（单个&批量发码与激活）

接口用途

• 支持请码方一次单品请求调用,单品发码数量上限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": "未使用"
            }]
        }]
    }
}

码作废（退款）接口

接口用途

• 当需要作废码时，取码方调用此接口

接口说明

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

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

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

码信息更新接口

接口用途

• 当需要对指定码的部分信息进行更新时，调用此接口

接口说明

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

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

码信息查询

接口用途

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

接口说明

• 码表中以掩码为分表位，每查询某个码时必须有明确的码号。
• 如果券码预售提前激活，还未生效前
  1、抖音本地， 直接返回券码状态不做拦截，核销时候会拦截无法使用
  2、其他的渠道直接返回  券码不在有效期

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

券状态枚举

批量码核销

接口用途

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

接口说明

• 一次可以多码核销,一次最多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"
        }
    ],
    "remark": {
        "oms": "test001"
    }
}

返回参数，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 元现金抵价券 "
        }]
    }
}

测试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]36408[/yapi_interface]

变更券产品

[yapi_interface]36474[/yapi_interface]

券产品详情查询

[yapi_interface]36426[/yapi_interface]

创建批次

[yapi_interface]36432[/yapi_interface]

批次编辑

[yapi_interface]36468[/yapi_interface]

批次详情查询

[yapi_interface]36444[/yapi_interface]

券码操作记录查询

接口签名参照

文档入口

接口用途

• 券码历史记录查询 （根据上送券码，查询当前券码历史相关记录信息）

action

• /paas/micro/ecoupon/_queryCodeDetailList

请求参数，中间件===>易百后台

请求报文举例

{
    "action": "_queryCodeDetailList",
    "appId": "ebuywha102410042",
    "content": "{\"code\":\"1006251009100030079=o6h7zgg4\"}",
    "headers": {
        "paas-version": "1.1.0"
    },
    "lang": "zh-CN",
    "signType": "sha256",
    "timestamp": 1759996455238,
    "uuid": "20251009-302a8467885349caba2dec5ad31bcc8e"
}

返回参数，易百后台===>中件间

返回报文举例（请求中 businessType 值为 12 时）

{
    "success": true,
    "errorMessage": "",
    "sign": "47864d480e95f53e9a6b7de0bd78f18e30eee2428ef04558779660104504a5c7",
    "action": "_queryCodeDetailList",
    "errorCode": "",
    "signType": "sha256",
    "uuid": "20250926-1d9de05de6834682bccba7ab5d704ca1",
    "content": {
        "returnData": [
            {
                "dateTime": "20250926161612",
                "returnCode": "00",
                "returnMsg": "操作成功",
                "code": "1006250926800024350=TdPPn8Bf",
                "mid": "",
                "shopName": "",
                "type": "1",
                "shopNo": "",
                "tid": "",
                "swift": ""
            },
            {
                "dateTime": "20250926161616",
                "returnCode": "00",
                "returnMsg": "SUCCESS",
                "code": "1006250926800024350=TdPPn8Bf",
                "extendData": {
                    "oms": "wv9O0WLS"
                },
                "mid": "",
                "shopName": "",
                "type": "4",
                "shopNo": "",
                "tid": "",
                "swift": ""
            },
            {
                "dateTime": "20250926161628",
                "returnCode": "00",
                "returnMsg": "SUCCESS",
                "code": "1006250926800024350=TdPPn8Bf",
                "extendData": {
                    "oms": "3PYkfBSP"
                },
                "mid": "",
                "shopName": "",
                "type": "4",
                "shopNo": "",
                "tid": "",
                "swift": ""
            },
            {
                "dateTime": "20250926161635",
                "returnCode": "00",
                "returnMsg": "SUCCESS",
                "code": "1006250926800024350=TdPPn8Bf",
                "mid": "",
                "type": "3",
                "tid": "",
                "swift": ""
            }
        ]
    },
    "timestamp": 1758874822508
}

箱本包处理类接口

激活查询

接口用途

• 激活前查询是否可以激活 （实际场景 激活前和激活后都会查询，如果上送券码都是激活返回已激活，如果上含未激活返回未激活）

action

• activePreQuery

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "99000009100010101732123",
    "qrcode": "R156A001-0000491-0505,R156A002-0000491-0505",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例（请求中 businessType 值为 12 时）

{
  "transDate": "20190107143930",
  "returnDesc": "success",
  "voucherBox": [{
    "boxId":"X22169-3141157-33475",
    "voucherPkg":[
        {
            "pkgId":"B1123-6430582-102F5",
            "voucherReel":[
                {
                    "reelId":"R112102F-0000242-2585",
                    "codeDetail":[
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000258-M4DEDSfV",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000242-EOHEMM9K",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                },
                {
                    "reelId":"R151102F-0000241-2555",
                    "codeDetail":[
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000255-e6tdHe8m",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000241-RTxJO2bX",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                }
            ]
        },
        {
            "pkgId":"B1123-6430582-102F5",
            "voucherReel":[
                {
                    "reelId":"R112102F-0000242-2585",
                    "codeDetail":[
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000258-M4DEDSfV",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000242-EOHEMM9K",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                },
                {
                    "reelId":"R151102F-0000241-2555",
                    "codeDetail":[
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000255-e6tdHe8m",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000241-RTxJO2bX",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                }
            ]
        }
    ]
}],
  "paidAmount": 0,
  "invoiceAmount": 0,
  "returnCode": "P00",
  "receiptAmount": 0,
  "printDetail": {
    "content": "00||"
  },
  "orderNo": "179031014530",
  "traceNo": "ccs203781546843174561"
}

返回报文举例（请求中 businessType 值不为 12，或为空，或不传时）

{
    "transDate":"20190107143930",
    "returnDesc":"success",
    "voucherPkg":[
        {
            "pkgId":"B1123-6430582-102F5",
            "voucherReel":[
                {
                    "reelId":"R112102F-0000242-2585",
                    "codeDetail":[
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000258-M4DEDSfV",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100500",
                            "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000242-EOHEMM9K",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                },
                {
                    "reelId":"R151102F-0000241-2555",
                    "codeDetail":[
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000255-e6tdHe8m",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        },
                        {
                            "createTime":"20190107100459",
                            "saleChannelOrderId":"044b5ff93e2d491fa364acb154079e05",
                            "remainTimes":2,
                            "status":"03",
                            "ticketName":"买N赠M券[望湘园_储值卡]",
                            "code":"1001901070000000241-RTxJO2bX",
                            "activityId":500706,
                            "validEnd":"00000000000000",
                            "sendChannelName":"测试易百制码",
                            "ticketId":500811,
                            "saleChannelName":"望湘园_储值卡",
                            "validStart":"00000000000000",
                            "faceValue":"0.0",
                            "createDate":"20190107",
                            "activityName":"【吉野家】 黏贴板主题-2018第6期",
                            "statusDesc":"未激活"
                        }
                    ]
                }
            ]
        }
    ],
    "paidAmount":0,
    "invoiceAmount":0,
    "returnCode":"P00",
    "receiptAmount":0,
    "printDetail":{
        "content":"00||"
    },
    "orderNo":"179031014530",
    "traceNo":"ccs203781546843174561"
}

券码历史记录查询

接口用途

• 券码历史记录查询 （根据上送券码，查询当前券码历史相关记录信息）
• 签名

action

• /api/whaleStarbucksCode/getCodeRecords

请求参数，中间件===>易百后台

请求报文举例

{
    "code": "1006250730320020870=gHN3981K",
    "requestId": 1754036646424,
    "sign": "k8l22s6PQHhwskkUx4BKD+dqCtCuYVuE5pC9ikbaIUG/K68xqvytLajPumygrF9VqP13vJHe0lWOUm0+9Fqzt17jU+36naYLoXh8o70BH4HIrA3xswmiHkgcoZ+OxQfOxLqLO/QghHKMPJFYu7El72a/HY12Q7QntGiMV2SADTq4VQIMfDjVZ4YmovN231TLD78cyJsdPUXmIRMbB+rqaR6cglTiPoyPOtdcgou1XFth2aC1zJH5WiCe/qwpiFSzLquQSo02theZ1C/A6OVqBKwNBOBxMQ0vnAZYUZ8QMG5ivxj4grGOoCSWcjHI4rRn3SKJNZJonNQgm68VAWPSIA=="
}

返回参数，易百后台===>中件间

返回报文举例（请求中 businessType 值为 12 时）

{
    "returnCode": "00",
    "transTime": 1754016597099,
    "requestId": "1754016596841",
    "returnData": [
        {
            "dateTime": "20250730143743",
            "returnCode": "00",
            "returnMsg": "操作成功",
            "code": "1006250730320020870=gHN3981K",
            "mid": "",
            "shopName": "",
            "type": "1",
            "shopNo": "",
            "tid": "",
            "swift": ""
        },
        {
            "dateTime": "20250730153314",
            "returnCode": "00",
            "returnMsg": "SUCCESS",
            "code": "1006250730320020870=gHN3981K",
            "mid": "860020051401034",
            "shopName": "星巴克北京银泰店",
            "type": "2",
            "shopNo": "1490",
            "tid": "54022101",
            "swift": "0"
        },
        {
            "dateTime": "20250730211518",
            "returnCode": "00",
            "returnMsg": "SUCCESS",
            "code": "1006250730320020870=gHN3981K",
            "mid": "860020051401034",
            "shopName": "星巴克北京银泰店",
            "type": "2",
            "shopNo": "1490",
            "tid": "54022101",
            "swift": "0",
            "extendData": {
                "shopNo": "test1",
                "voucherNo": "test1",
                "posSerialNo": "test1",
                "oms": "test1"
            }
        }
    ],
    "returnDesc": "success"
}

激活

接口用途

• 激活

action

• activeVoucher

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "99000009100010101732123",
    "qrcode": "R156A001-0000491-0505",
    "totalAmount": "3000",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "traceNo": "99000009100010101732123",
    "orderNo": "99000009100010101732123",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS"
}

激活结果查询

接口用途

• 激活结果查询

action

• activeResultQuery

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "99000009100010101732123",
    "originalTraceNo": "99000009100010101732129",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "traceNo": "99000009100010101732123",
    "orderNo": "99000009100010101732123",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS"
}

作废

接口用途

• 作废，作废后的券不可激活

action

• delVoucher

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "9900000910001010920150201",
    "qrcode": "10014030013500006013",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "traceNo": "9900000910001011020150201",
    "orderNo": "99000009100010101732123",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS"
}

核销信息以及城市范围查询

接口用途

• 核销信息以及城市范围查询

action

• queryVerifyInfo

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "9900000910001010720150201",
    "qrcode": "10085748356738476396436",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "transDate":"20190107143930",
    "returnDesc":"success",
    "voucherBox":[
        {
            "boxId":"X1123-6430582-102F5",
            "voucherPkg":[
                {
                    "pkgId":"B1123-6430582-102F5",
                    "voucherReel":[
                        {
                            "codeDetail":[
                                {
                                    "createTime":"20190107100500",
                                    "saleChannelOrderId":"a1c4efb107df46f0ba230de6477bd337",
                                    "remainTimes":2,
                                    "status":"03",
                                    "ticketName":"买N赠M券[望湘园_储值卡]",
                                    "code":"1001901070000000258-M4DEDSfV",
                                    "activityId":500706,
                                    "validEnd":"00000000000000",
                                    "sendChannelName":"测试易百制码",
                                    "ticketId":500811,
                                    "saleChannelName":"望湘园_储值卡",
                                    "validStart":"00000000000000",
                                    "faceValue":"0.0",
                                    "createDate":"20190107",
                                    "activityName":"【吉野家】 黏贴板主题-2018第6期",
                                    "statusDesc":"未激活"
                                }
                            ],
                            "reelId":"R112102F-0000242-2585"
                        }
                    ]
                }
            ]
        }
    ],
    "paidAmount":0,
    "invoiceAmount":0,
    "returnCode":"P00",
    "receiptAmount":0,
    "printDetail":{
        "content":"00||"
    },
    "orderNo":"179031014530",
    "traceNo":"ccs2037815468431420150201"
}

B2B饮料券箱本激活

接口用途

• 激活

action

• reelActiveVoucher

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "99000009100010101732123",
    "qrcode": "R156A001-0000491-0505",
    "totalAmount": "3000",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "traceNo": "99000009100010101732123",
    "orderNo": "99000009100010101732123",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS"
}

B2B饮料券箱本作废

接口用途

• 作废，作废后的券不可激活

action

• reelDelVoucher

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "9900000910001010920150201",
    "qrcode": "10014030013500006013",
    "businessType": 12
}

返回参数，易百后台===>中件间

返回报文举例

{
    "traceNo": "9900000910001011020150201",
    "orderNo": "99000009100010101732123",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS"
}

卡号段激活实体卡券（B2B定制）

接口用途

• 指定券码号段激活，相同激活订单号直接返回当前状态

   

action

• b2b/code/activeByPartNo

请求参数，中间件===>易百后台

请求报文举例

{
	"ver": 2,
	"partnerId": 1504,
	"sign": "skip",
	"merchantId": 10001,
	"partnerOrderId": "2040132213w9181w0q77awwwd8",
	"type": 2,
    "bin": "7020",
    "startCardSe": "0000041",
    "endCardSe": "0000045",
    "sellingPrice": "10000",
    "costPrice": "8888",
    "number": 14
}

返回参数，易百后台===>中件间

返回报文举例

{
    "createTime": "20200212100234",
    "message": "处理中",
    "sign": "EOMRl+jWgjGOTebWPRVqBDR1EPkyd/S7tsb/yEjvBoSfUZCEgVA6RNrjVEmIY15uJI9YV57tOZWy1FiVqJDH0lfEJnuk4DKpwcJMVCGXjQIH/Cd+PCibwBNknDWt9kaiB9JhxW8TrlBLYWq4ZyzffYtsF4qawyBgTLeUuPEOvoLZ2jA5OLtbSYVyI9g3OI4amcL25/GkRUw3ECmziAy9bTdVKmjV5FbWcyk45GM+K7/2a4/E6BihvVC2w6ge6xgDn0s5R9Ixaun5KhqcEJLHW/8vEAHMbx40uvsP91Aw9iiw5aZeGhpYoge89vAVTkC5boB8i+pgcpk0DqK4Jk25mA==",
    "statusCode": 80,
    "ver": 2
}

线下posp接口列表

二维码支付或兑换

接口用途

• 支付宝支付
• 微信被扫支付
• 银行二维码支付(工行、中行、中信、浦发等)
• 银行二维码积分兑换(工行、中行、中信、浦发等)
• 银联立码付
• 百度支付
• 翼支付
• 其他二维码支付
• 电子凭证核销：产品券/代金券/折扣券/买N赠M券/立减券
• 外卖或自助点单订单码自动上屏

action

• qrcodeSale

请求参数，中件间===>易百后台

请求报文举例

{
    "traceNo": "990000091000101620150201",
    "totalAmount": 40.8,
    "undiscountAmount": 0,
    "activityProductNo": "HDCP00000000001234",
    "qrcode": "280123121234567890",
    "goodsDetail": [{
            "goodsCategory": "001",
            "goodsId": "P00001",
            "goodsName": "牙膏",
            "price": 8,
            "quantity": 2,
            "rebateCode": "000"
        },
        {
            "goodsCategory": "101",
            "goodsId": "P00002",
            "goodsName": "洗发水",
            "price": 24.8,
            "quantity": 1,
            "rebateCode": "000"
        }
    ],
    "memberDetail": {
        "memberId": "M000001545",
        "memberName": "TONY",
        "grade": "1",
        "status": "1",
        "balance": 1000.00,
        "pointBalance": 30000
    },
    "extendData": {
        "rightsDetail": [{
            "snCode": "111111111xxxxxx"
        }],
        "shopNo":"test001",
        "voucherNo":"test001",
        "posSerialNo":"test001"
    }
}

返回参数，易百后台===>中件间

• 可能返回活动产品选项，需要进行选择

返回报文举例

{
    "traceNo": "9900000910001011720150201",
    "orderNo": "171698602301",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS",
    "paidAmount": 40.8,
    "receiptAmount": 40.8,
    "invoiceAmount": 40.8,
    "exchangeRate": 6.0939,
    "currency": "CNY",
    "discountCode": "0001",
    "discountNum": 20,
    "tenderCode": "8001",
    "activityProductNo": "2016123102",
    "activityProductName": "支付宝支付",
    "goodsDetail": [
        {
            "goodsCategory": "001",
            "goodsId": "P00001",
            "goodsName": "牙膏",
            "price": 8,
            "quantity": 2,
            "rebateCode": "000",
            "activityNo": "2016123101",
            "memo": "100123456789"
        },
        {
            "goodsCategory": "101",
            "goodsId": "P00002",
            "goodsName": "洗发水",
            "price": 24.8,
            "quantity": 1,
            "rebateCode": "000",
            "activityNo": "2016123101",
            "memo": "100123456789"
        }
    ],
    "fundChannel": [
        {
            "channelNo": "001",
            "channelName": "用户实付现金",
            "channelAmount": "20.8"
        },
        {
            "channelNo": "002",
            "channelName": "用户积分支付",
            "channelAmount": "20"
        }
    ],
    "printDetail": {
        "cardNo64": "622562****8888",
        "bank": "中国银行",
        "paymentOrderNo": "201612315689412157458787",
        "paymentUser": "139****@163.com",
        "pointSale": "20000",
        "qrCode1": "htt://www.api-location-url.com/url",
        "qrCode2": "",
        "qrCode3": "",
        "barCode1": "12345679",
        "barCode2": "",
        "barCode3": ""
    },
    "memberDetail": {
        "memberId": "M000001545",
        "memberName": "TONY",
        "grade": "1",
        "status": "1",
        "balance": 1000.00,
        "pointBalance": 30000
    },
    "voucherDetail": [
        {
            "voucherId": "001",
            "voucherName": "现金优惠券",
            "voucherType": "现金",
            "voucherCode": "123456789",
            "channelAmount": "20.8"
        },
        {
            "voucherId": "002",
            "voucherName": "买一赠一优惠券",
            "voucherType": "买赠",
            "voucherCode": "1232136781",
            "channelAmount": "20.8"
        }
    ]
}

当日撤销

接口用途

• 需要对原交易整体撤销时，可以在原交易的同一天调用此接口。

action

• void

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "9900000910001013220150201",
    "originalTraceNo": "9900000910001013120150201",
    "isRollback": false,
    "acquirer": "citicCashpay",
    "cardInfo": {
        "cardNo": "",
        "password": "",
        "valid": "",
        "track1": "",
        "track2": "",
        "track3": "",
        "cardSn": "",
        "icData": ""
    }
}

返回参数，易百后台===>中间件

返回报文举例

{
    "traceNo": "9900000910001013420150201",
    "orderNo": "171698602301",
    "cashOrderNo": "000025",
    "cashBank": "40",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS",
    "fundChannel": [
        {
            "channelNo": "001",
            "channelName": "用户实付现金",
            "channelAmount": "20.8"
        },
        {
            "channelNo": "002",
            "channelName": "用户积分支付",
            "channelAmount": "20"
        }
    ],
    "printDetail": {
        "cardNo64": "622562****8888",
        "bank": "中信银行",
        "paymentOrderNo": "201612315689412157458787",
        "pointSale": "20000",
        "qrCode1": "htt://www.api-location-url.com/url",
        "qrCode2": "",
        "qrCode3": "",
        "barCode1": "12345679",
        "barCode2": "",
        "barCode3": ""
    },
    "memberDetail": {
        "memberId": "M000001545",
        "memberName": "TONY",
        "grade": "1",
        "status": "1",
        "balance": 1000.00,
        "pointBalance": 30000
    },
    "voucherDetail": [
        {
            "voucherId": "001",
            "voucherName": "现金优惠券",
            "voucherType": "现金",
            "voucherCode": "123456789",
            "channelAmount": "20.8"
        },
        {
            "voucherId": "002",
            "voucherName": "买一赠一优惠券",
            "voucherType": "买赠",
            "voucherCode": "1232136781",
            "channelAmount": "20.8"
        }
    ]
}

支持撤销的交易

• cardPayment
• cardRedemption
• qrcodeSale

电子凭证查询

接口用途

• 查询电子凭证的产品信息，可抵用的金额以及所属的活动，支持易百自有电子凭证和第三方电子凭证。

action

• ecouponInquiry

请求参数，中间件===>易百后台

请求报文举例

{
    "traceNo": "9900000910001013620150201",
    "qrcode": "HDCP00000000001235"
}

返回参数，易百后台===>中间件

返回报文举例

{
    "traceNo": "9900000910001013720150201",
    "orderNo": "171698602301",
    "transDate": "20161231120533",
    "returnCode": "00",
    "returnDesc": "SUCCESS",
    "canPayAmount": 40.8,
    "activityProductNo": "2016123101",
    "activityProductName": "中信365权益"
}