交易类接口 同步单条发码 接口用途 支持请码方一次单品请求调用,单品发码数量上限100 接口说明 每次调用时必须有明确的渠道订单编号。 commissionDate = -1时，所制码不具有支付功能（即码没有激活），如果需要激活该码的支付功能需要再次调用"码激活"接口。 同步单条发码时，saleChannelOrderId和saleChannelItemId可用同一值。 returnCode = "00"时，说明订单进入制码流程。itemResultCode = "00"时，说明订单制码成。 notifyType为券码发送到用户的形式，是否需要通知以券配置为开关 action MakeCode 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 saleChannelOrderId String 是 渠道制码订单id 最长32位，当上送相同订单号时返回上一次成功信息，如果上一次请码失败，则本次会重新生成码 requestId String 是 请求流水号 最长32位，用于标识唯一一笔交易 remark JSONString 是 订单备注信息 最长200位，订单查询时原样返回 notifyType Object< notifyType > 否 制码通知类型   item Object< makeOrderItems > 是 制码明细 同步制码时，仅支持单产品单码 请求报文举例 { "saleChannelId": "102410058", "saleChannelOrderId": "20181024154201", "requestId": "20181024154201", "notifyType": { "mobilePhone": "13524161800" }, "item": { "saleChannelItemId":"20181024154201", "commissionDate":"1", "validDays": 10, "ticketId": 1, "makeFundsChannel": { "channelBenefit": 0, "merchantBenefit": 500, "userRealAmount": 2500 } } } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< makeCodeResponseData > 否 码信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "saleChannelOrderId": "20181120155110", "tradeNo": "c1eca7fbda51430cb5100ec0699a5b00", "createTime": "20181120155225", "isNotify": "1", "codeNum": 1, "items": [{ "codeDetail": [{ "codeURL": "http://qrcode.url.ag/make?0000001496A382FA4725D24FA27839FC1680D136CAFE515519B94B1D&type=QRCODE", "code": "10116574123700278846", "useTimes": 10, "status": "00", "statusDesc": "未使用" }], "validEnd": "20181201000000", "validStart": "20181121000000", "itemResultMsg": "SUCCESS", "itemResultCode": "00", "saleChannelItemId": "20181120155110", "ticketId": 9000000010, "ticketName":"星巴克30元代金券", "activityId":"1000000006", "activityName":"中信银行星巴克代金券活动" }], "createDate": "20181120" } } 券状态枚举 字段 字段意义 备注 04 参数配置不正确 RequestId参数不能为空 appId参数不能为空 50 活动产品信息不存在 97 活动产品信息不存在 活动产品信息不存在 或者其他配置信息错误 06 活动产品未经过测试 50 销售渠道信息不存在 07 销售渠道和活动产品权限不匹配 发码订单查询 接口用途 当需要查询发码订单结果时，取码方调用此接口 当调用 同步单条发码 超时或未知状态，取码方调用此接口确认交易结果 此接口不支持 异步批量发码 的订单查询 接口说明 每一次销售渠道对接 whale 进行制码，生成一个制码订单。 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号 action MakeQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 originalChannelOrderId String 是 原取码方制码订单id 小于64个字符 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 请求报文举例 { "originalChannelOrderId": "20180912162026", "requestId":"20180912162026" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< makeQueryResponseData > 否 码信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "saleChannelOrderId": "20181025152303", "tradeNo": "cee533ae3e504179868e1801e697c5dc", "createTime": "20181025155331", "isNotify": "1", "codeNum": 1, "createDate": "20181025", "items": [{ "saleChannelItemId": "20181025105101", "itemResultMsg": "SUCCESS", "itemResultCode": "00", "validStart": "20181025155300", "ticketId": 1, "ticketName":"星巴克30元代金券", "activityId":"1000000006", "activityName":"中信银行星巴克代金券活动", "validEnd": "20181104155300", "codeDetail": [{ "codeURL": "http://xxxx/hbw?A3rVNNEgPLQV", "code": "10110544106453980943", "useTimes": 10, "status": "00", "statusDesc": "未使用" }, { "codeURL": "http://xxxx/hbw?A3rVNNEgPLQQ", "code": "10110544106453980944", "useTimes": 10, "status": "00", "statusDesc": "未使用" }] }, { "saleChannelItemId": "20181025105102", "itemResultMsg": "SUCCESS", "itemResultCode": "00", "validStart": "20181025155300", "ticketId": 2, "ticketName":"星巴克50元代金券", "activityId":"1000000006", "activityName":"中信银行星巴克代金券活动" "validEnd": "20181104155300", "codeDetail": [{ "codeURL": "http://xxxx/hbw?A3rVNNEgPLQV", "code": "10110544106453980943", "useTimes": 10, "status": "00", "statusDesc": "未使用" }] }] } } 异步批量发码 接口用途 电子凭证取码方需要批量(一次请求取码数超过1条)制码时，调用此接口 接口说明 每一次取码方对接 whale 进行制码，生成一个制码订单。 制码订单以渠道方订单编号为分表位，每次调用时必须有明确的订单编号。 制码请求接收后，会同步返回制码前校验结果，后端成功生成码后，异步通知到callBackUrl指定的回调接口。 action MakeBatchCode 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 saleChannelOrderId String 是 渠道制码订单id 小于64个字符 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 callBackUrl String 是 异步结果回调地址 易百以POST请求方式推送 items List< items > 是 制码子订单 一次制码请求最多支持10个子订单 请求报文举例 { "saleChannelOrderId": "20180912162026", "requestId": "20180912162026", "totalAmount": "15800", "notifyType": { "mobilePhone": "13524161800" }, "callBackUrl": "http://*****/***/api", "items": [{ "saleChannelItemId": "20180912162026001", "ticketId": 1, "validDays": 10, "validStart": "20180730000000", "validEnd": "20181201235959", "codeNum": 2, "makeFundsChannel": { "channelBenefit": 0, "merchantBenefit": 500, "userRealAmount": 2500 } }, { "saleChannelItemId": "20180912162026002", "ticketId": 2, "validDays": 10, "validStart": "20180730000000", "validEnd": "20181201235959", "codeNum": 1, "makeFundsChannel": { "channelBenefit": 100, "merchantBenefit": 0, "userRealAmount": 900 } }] } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   batchMakeCodeResponseData Object< batchMakeCodeResponseData > 否 批量制码返回数据 返回报文举例 { "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 String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< batchMakeCodeResponseData > 否 码信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "saleChannelOrderId": "20181025152303", "tradeNo": "cee533ae3e504179868e1801e697c5dc", "createTime": "20181025155331", "isNotify": "1", "codeNum": 1, "createDate": "20181025", "items": [{ "saleChannelItemId": "20181025105101", "itemResultMsg": "SUCCESS", "itemResultCode": "00", "validStart": "20181025155300", "ticketId": 1, "ticketName":"星巴克30元代金券", "activityId":"1000000006", "activityName":"中信银行星巴克代金券活动", "validEnd": "20181104155300", "codeDetail": [{ "codeURL": "http://xxxx/hbw?A3rVNNEgPLQV", "code": "10110544106453980943", "useTimes": 10, "status": "00", "statusDesc": "未使用" }, { "codeURL": "http://xxxx/hbw?A3rVNNEgPLQQ", "code": "10110544106453980944", "useTimes": 10, "status": "00", "statusDesc": "未使用" }] }, { "saleChannelItemId": "20181025105102", "itemResultMsg": "SUCCESS", "itemResultCode": "00", "validStart": "20181025155300", "ticketId": 2, "ticketName":"星巴克50元代金券", "activityId":"1000000006", "activityName":"中信银行星巴克代金券活动" "validEnd": "20181104155300", "codeDetail": [{ "codeURL": "http://xxxx/hbw?A3rVNNEgPLQV", "code": "10110544106453980943", "useTimes": 10, "status": "00", "statusDesc": "未使用" }] }] } } 发码撤销 接口用途 当需要撤销某笔制码订单时，取码方调用此接口 接口说明 当对原制码订单进行撤销时，生成一个撤销订单。 对原订单进行撤销时，整单所制码都将被撤销。如需对单码撤销，调用电子凭证码状态更新接口。 此接口可对 同步单条发码 、 异步批量发码 下单接口订单进行撤销操作 对已撤销成功订单不能再次撤销 如果订单撤销部分成功时返回"tradeStatus"="P" 对订单中部分券码撤销成功时，可以按原制码订单号再次调用撤销接口，如还是部分撤销成功请联系易百技术方協助解决 action MakeVoid 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 originalChannelOrderId String 是 原取码方制码订单id 小于64个字符 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 请求报文举例 { "originalChannelOrderId": "20180912162026", "requestId":"20180912162026" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data List< makeVoidResponseData > 否 码撤销信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "originalChannelOrderId": "20181018183139", "createDate": "20181018", "createTime": "20181018183454", "totalNum": 4, "tradeStatus": "A", "voidDetails": [{ "ticketId": 1, "originalChannelItemId": "99000014001", "voidNum": 2 }, { "ticketId": 2, "originalChannelItemId": "99000014002", "voidNum": 2 }] } } 发码撤销查询 接口用途 当需要查询对某笔订单的撤销结果时，取码方调用此接口 接口说明 当制码撤销结果未返回或因为超时等原因未能及时收到返回结果,可进行制码撤销查询 action MakeVoidQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 originalChannelOrderId String 是 取码方制码订单id 小于64个字符 orderDate String 是 原下单日期 yyyyMMdd requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 请求报文举例 { "originalChannelOrderId": "20180912162026", "orderDate": "20180905", "requestId":"20180912162026" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data List< makeVoidResponseData > 否 码撤销信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "originalChannelOrderId": "20181018183139", "createDate": "20181018", "createTime": "20181018183454", "totalNum": 4, "tradeStatus": "A", "voidDetails": [{ "ticketId": 1, "originalChannelItemId": "99000014001", "voidNum": 2 }, { "ticketId": 2, "originalChannelItemId": "99000014002", "voidNum": 2 }] } } 码作废（退款）接口 接口用途 当需要 作废 码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 已撤销(作废)/使用的码不能转换为其他状态。 冻结和解冻操作是相对的。 action CodeStatusUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 code String 是 码号 小于22个字符 optTag String(2) 是 操作分类 01：作废 请求报文举例 { "requestId": "20181019112535100000000000000008", "code": "1021242013780905000", "optTag":"01" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 returnMsg String 是 请求返回信息 data Object< statusUpdateData > 否 码状态更新返回数据 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "updateDate": "20241224", "codeSecret": "10032891673449546316", "codeValidEnd": "20250323235959", "statusDesc": "已作废", "data": {}, "tradeNo": "0601f61bf54a46b8a01899b444d47a38", "codeValidStart": "20241224000000", "currentStatus": "05", "updateTime": "20241224093435", "ticketId": 1000030006397 } } 失败返回报文举例 { "returnCode": "32", "returnMsg": "流水号重复，请调用查询接口", "data": {} } { "returnCode": "91", "returnMsg": "该码已使用不能更新状态[100***8707]", "data": {} } { "returnCode": "91", "returnMsg": "该码已作废不能更新状态[100***6316]", "data": {} }   券状态枚举 字段 字段意义 备注 91 更新码状态不支持当前操作 更新码状态不支持当前操作 10 券码不存在 02 本操作不支持，流水号长度不正确 码冻结接口 接口用途 当需要 冻结 码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 已撤销(作废)/使用的码不能转换为其他状态。 冻结和解冻操作是相对的。 action CodeStatusUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 channelOrderId String 是 销售渠道制码订单id 小于64个字符 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 code String 是 码号 小于22个字符 optTag String(2) 是 操作分类 02：冻结 请求报文举例 { "channelOrderId": "20180912162026", "requestId": "20181019112535100000000000000008", "code": "1021242013780905000", "optTag":"02" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 否 码状态更新返回数据 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "currentStatus": "01", "statusDesc": "已作废", "updateDate":"20181019", "updateTime":"20181019112535" } } 码解冻接口 接口用途 当需要 解冻 码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 已撤销(作废)/使用的码不能转换为其他状态。 冻结和解冻操作是相对的。 action CodeStatusUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 channelOrderId String 是 销售渠道制码订单id 小于64个字符 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 code String 是 码号 小于22个字符 optTag String(2) 是 操作分类 03：解冻 请求报文举例 { "channelOrderId": "20180912162026", "requestId": "20181019112535100000000000000008", "code": "1021242013780905000", "optTag":"03" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 否 码状态更新返回数据 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "currentStatus": "01", "statusDesc": "已作废", "updateDate":"20181019", "updateTime":"20181019112535" } } 码激活接口 接口用途 当需要 激活 码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 已撤销(作废)/使用的码不能转换为其他状态。 action CodeStatusUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 code String 是 码号 小于22个字符 codeValidDays Number 否 相对有效天数 除制码当天开始相应天数结束。validStart、validEnd组合与validDay、commissionDate组合可选其一，若全部填写以相对有效期优先 codeValidStart Number(14) 否 码有效开始时间 该字段填写时，validEnd必填格式:yyyyMMddHHmmss codeValidEnd Number(14) 否 码有效结束时间 该字段填写时，validStart必填格式:yyyyMMddHHmmss activateShopNo String(10) 否 激活门店号 activateOrg String(10) 否 激活机构 purchaseOrderNum String 否 用户购买订单号 notifyType Object< notifyType > 否 激活通知类型 makeFundsChannels Array< fundsChannel > 否 资金渠道 针对阶梯价场景为必填 makeFundsChannel Object< makeFundsChannel > 否 资金渠道 当需要在对账报表中体现时必填 optTag String(2) 是 操作分类 04：激活 请求报文举例 { "requestId": "20181019112535100000000000000008", "code": "1021242013780905000", "codeValidDays":9, "purchaseOrderNum":"20191119192700123", "optTag":"04" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 returnMsg String 是 请求返回信息 data Object< statusUpdateData > 否 码状态更新返回数据 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "currentStatus": "00", "statusDesc": "未使用", "updateDate":"20181019", "updateTime":"20181019112535" } } 失败返回报文举例 { "returnCode": "32", "returnMsg": "流水号重复，请调用查询接口", "data": {} } 批量码激活 接口用途 多码批量激活时，调用此接口 接口说明 一次可以多码激活,一次最多20个码。 action BatchCodeActivate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codeArray List 是 码号数组   callBackUrl String 是 激活成功后的回调地址   activateShopNo String(10) 否 激活门店号   activateOrg String(10) 否 激活机构   codeValidDays Number 否 相对有效天数 除制码当天开始相应天数结束。validStart、validEnd组合与validDay、commissionDate组合可选其一，若全部填写以相对有效期优先 codeValidStart Number(14) 否 码有效开始时间 该字段填写时，validEnd必填格式:yyyyMMddHHmmss codeValidEnd Number(14) 否 码有效结束时间 该字段填写时，validStart必填格式:yyyyMMddHHmmss purchaseOrderNum String 否 用户购买订单号   merchantRealAmount Number 否 用户购买时商户实收金额 单位：分 merchantBenefit Number 否 用户购买时商户优惠金额 单位：分 optTag String(2) 是 操作分类 04：激活 请求报文举例 { "requestId":"20181019112535100000000000000001", "codeArray": ["10215523190570712621"], "callBackUrl": "http://test.com/api/codeActivate", "purchaseOrderNum":"201911191947000001", "optTag": "04", } 同步返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 returnMsg String 是 请求返回信息   data/checkResult Object< data/checkResult > 是 批量码激活初步校验返回 同步返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "data": { "requestId": "10000000000000000000002", "tradeNo": "10000000000000000000002", "saleChannelId":10002410, "createDate": "20191119", "createTime": "20191119200100", "codeNum": 1, "resultCode": "00", "resultMsg": "SUCCESS", } } 回调返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 否 码状态更新返回数据 回调返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "currentStatus": "00", "statusDesc": "未使用", "updateDate":"20181019", "updateTime":"20181019112535" } } 批量码延期 接口用途 多码批量延期时，调用此接口 批量延期有两种方式：1.所有的码同一个有效期；2.每个码单独对应一个有效期。 接口说明 一次可以多码延期,一次最多1000个码。 action BatchCodeUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codeArray List 否 码号数组 所有的码同一个有效期，与codeObjArray选择一个上传。该值上传时codeValidEnd必填 codeValidEnd String 否 码有效期结束时间 codeArray上传时，该值必填 codeObjArray List 是 码更新集 每个码单独对应一个有效期。与codeArray选择一个上传 saleChannelId Long 否 取码方id   saleChannelOrderId String 否 取码方制码订单号 当codeArray和codeObjArray均无值时取该订单号下所有串码进行延期。当订单号有值时取码方id必填 callBackUrl String 是 更新成功后的回调地址   updateShopNo String(10) 否 更新门店号   updateOrg String(10) 否 更行机构   optTag String(2) 是 操作分类 B5：批量延期 请求报文举例 { "requestId":"20181019112535100000000000000001", "codeArray": ["10215523190570712621"], "callBackUrl": "http://test.com/api/codeVoid", "codeValidEnd": "20200224235959", "optTag": "B5", } 同步返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 是 批量码作废初步校验返回 同步返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "data": { "requestId": "10000000000000000000002", "tradeNo": "10000000000000000000002", "codeNum": 1 } } 回调返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateCallbackData > 否 码状态更新返回数据 回调返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "totalCodeNum": 1, "successCodeNum": 1, "codeArray": [{ "code": "100213321414112234", ... }], } } 批量码作废 接口用途 多码批量作废时，调用此接口 接口说明 一次可以多码作废,一次最多20个码。 action BatchCodeUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codeArray List 是 码号数组   saleChannelId Long 否 取码方id   saleChannelOrderId String 否 取码方制码订单号 当codeArray无值时取该订单号下所有串码进行作废。当订单号有值时取码方id必填 callBackUrl String 是 激活成功后的回调地址   updateShopNo String(10) 否 激活门店号   updateOrg String(10) 否 激活机构   optTag String(2) 是 操作分类 B1：批量作废 请求报文举例 { "requestId":"20181019112535100000000000000001", "codeArray": ["10215523190570712621"], "callBackUrl": "http://test.com/api/codeVoid", "optTag": "B1", } 同步返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 是 批量码作废初步校验返回 同步返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "data": { "requestId": "10000000000000000000002", "tradeNo": "10000000000000000000002", "codeNum": 1 } } 回调返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateCallbackData > 否 码状态更新返回数据 回调返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "totalCodeNum": 1, "successCodeNum": 1, "codeArray": [{ "codeId": "1212431432", "searchCode": "100***1234", "codeSecret": "100213321414112234", ... }], } } 码信息更新接口 接口用途 当需要对指定码的部分信息进行更新时，调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 action CodeDetailUpdate 请求参数，CHANNEL===> WHALE 字段 类型 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 code String 是 码号   updateOpts < updateOpt > 是 码明细更新操作 请求报文举例 { "requestId": "20180912162026", "code": "1012123342335432145", "updateOpts": { "updatePurchaseTime": "20181103105501", "updateMakeNotifyType": { "mobilePhone": "13510121314" }, "updateMerchantRealAmount": 1200 } } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateData > 否 码状态更新返回数据 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20180912162026", "currentStatus": "00", "statusDesc":"未使用", "updateDate":"20181019", "updateTime":"20181019112535" } } 码信息查询 接口用途 当需要查询某个指定码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 action CodeQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codes List 是 验码集合 最大不超过20 brandId String 否 核销门店所属品牌 组合劵必须上送，易百提供 cityId String 否 门店所在城市id 易百提供的城市id storeInfo Object< storeInfo > 否 门店串码查询时上送 请求报文举例 { "requestId": "20181019112535100000000000000002", "codes": ["1021242013780905000"], "brandId":"2429", "cityId":5493 } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 returnMsg String 是 请求返回信息 data Object< codeQueryResponseData > 否 码信息 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "171698602301", "data":{ "codeDetail":[{ "code":"1021242013780905000", "saleChannelOrderId":"20181120155110", "sendChannelName":"易百自制渠道", "saleChannelCode":"990001", "useTimes":1, "verifyTimes":1 "remainTimes":0, "createDate": "20180905", "createTime": "20180905160911", "validStart":"20181123000000", "validEnd":"20181124235959", "verifyDate":"20181123", "verifyTime":"20181124121243", "status": "01", "statusDesc": "已使用", "cityCheck":"Y", "ticketId":"9000000001", "faceValue":3000, "ticketName":"星巴克30元代金券", "shopNo":"1111", "shopName":"星巴克测试门店" "faceValue":1000, },{ "code":"1021242013780905001", "saleChannelOrderId":"20181120155110", "sendChannelName":"易百自制渠道", "remainTimes":1, "createDate": "20180905", "createTime": "20180905160911", "validStart":"20181123000000", "validEnd":"20181124235959", "verifyDate":"20181123", "verifyTime":"20181124121243", "status": "01", "statusDesc": "已使用", "cityCheck":"Y", "ticketId":"9000000001", "faceValue":3000, "ticketName":"星巴克30元代金券", "shopNo":"1111", "shopName":"星巴克测试门店" "faceValue":1000, }] } } 券状态枚举 字段 字段意义 备注 00 可使用 01 已使用 02 可使用(一码多次使用时，码还有可用次数) 03 未激活 未激活的码需调用激活接口才能 04 已冻结 05 已作废 06 已过期 07 未生效 当制码时选择次日生效，核销时会返回该状态 08 不能退款 仅核销场景-不支持核销撤销(根据业务场景配置是否支持隔日和当日核销撤销) 09 券不存在 券码不存在(券码查询、核销、核销撤销) 21 电子凭证不可用 券码不在有效期 35 码配置异常 51 改码不存在制码方 97 报文错误 接口调用参数校验不通过 C2 商户无权限 券码查询和核销 权限校验不通过 单码核销 接口用途 券码进行核销时，调用此接口 接口说明 一次只能对一个码进行核销。 action CodeVerify 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 verifyScene String 是 交易场景.offline线下,online线上   code String 是 码号   isProductCheck String 是 是否校验订单产品规则 是Y，否N requestId String 是 请求流水号确保永久唯一性 32位长度 refNo String 否 系统参考号 12位长度 cashierTransNo String 否 收银机流水号 最长64位长度 requestId String 是 请求流水号确保永久唯一性 32位长度 storeInfo Object< storeInfo > 否 门店核销时上送，组合劵必填   cashTotalAmount Number 否 订单总金额（收银机总金额也是用此字段） 单位：分 goodsDetail List< goodsDetail > 否 (只有在收银POS上发起交易时才上送)   remark String 否 备注（在核销撤销、核销查询等接口原样返回）   请求报文举例 { "verifyScene":"offline", "code": "10215523190570712621", "requestId": "20181019112535100000000000000001", "refNo": "181215430700", "cashierTransNo": "42441908138100007498001", "storeInfo": { "cityId":"1012", "swift": "00105", "tid": "99000014", "mid": "99000013341001", "shopNo": "C00001", "storeName": "上海浦东测试门店", "manageCompany": "上海浦东测试店管理公司", "companyId": "218" }, "cashTotalAmount": "20000", "goodsDetail": [{ "sku": "1112343", "qty": 1, "price": 3000, "type": "03", "spec": "03" }, { "sku": "1212342", "qty": 1, "price": 3500, "type": "03", "spec": "03" }] } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 returnMsg String 是 请求返回信息   data Object< data > 是 券码核销订单明细返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000002", "data": { "cashTotalAmount": 17800, "faceValue": 50000, "fundsChannel": { "totalAmount": 50000, "discountAmount": 50000, "merchantRealAmount": 40000, "channelBenefit": 10000, "merchantBenefit": 10000, "userRealAmount": 30000 }, "goodsDetail": [{ "sku": "1212342", "qty": 1, "price": 3500, "type": "03", "spec": "03" }], "code": "10215523190570712621", "ticketId": "3", "ticketName": "50 元现金抵价券 ", "activityNo": "2017071951", "activityName": "联动优势电子凭证", "thirdActivityId": "20190226134100", "returnCashParam":{ "tenderCode":"132" }, "printData": "00|产品：测试券|00|团购价：100|00|订单号：100000000002100002|00|兑换码：101105********4289|" } } 单码核销撤销 接口用途 当需要将本次核销交易撤销时调用 接口说明 此接口支持撤销指定日期的核销交易 action CodeVerifyVoid 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 小于32个字符 originalRequestId String 是 原核销请求流水号 32个字符，用于标识唯一一笔交易 请求报文举例 { "requestId": "10000000000000000000001", "originalRequestId":"10000000000000000000002" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回   amount Number 否 本次撤销金额单位分 仅在收银一体化时用到 code String 是 撤销的券码号   ticketName String 是 券名称   verifyRemark String 否 核销备注信息 核销接口上送原样返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": 10000000000000000000001, "amount": "5000", "code": "10215523190570712621", "ticketName": "50 元现金抵价券 " } 单码核销查询 接口用途 核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果 接口说明 此接口默认支持查询当日内核销交易 也可传参originalDate查询指定日核销交易 action CodeVerifyQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 originalRequestId String 是 原核销请求流水号 32个字符 originalDate String 否 原交易日期 传入需要查询的原交易日期，不传默认为当天格式为yyyyMMdd 请求报文举例 { "requestId": "20180905000", "originalRequestId":"1021867639235435", "originalDate": "20170912" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回   verifyRemark String 否 核销备注信息 核销接口上送原样返回 data Object< data > 是 券码核销订单明细返回   返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000002", "data": { "cashTotalAmount": 17800, "fundsChannel": { "totalAmount": 50000, "discountAmount": 50000, "merchantRealAmount": 40000, "channelBenefit": 10000, "merchantBenefit": 10000, "userRealAmount": 30000 }, "goodsDetail": [{ "sku": "1212342", "qty": 1, "price": 3500, "type": "03", "spec": "03" }], "code": "10215523190570712621", "ticketId": "3", "ticketName": "50 元现金抵价券 ", "activityNo": "2017071951", "activityName": "联动优势电子凭证", "printData": "00|产品：测试券|00|团购价：100|00|订单号：100000000002100002|00|兑换码：101105********4289|" } } 单码核销通知 接口用途 用于实现易百券核销成功后将核销状态通知到第三方系统 接口说明 接口异步通知第三方 请求参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 requestId String 是 核销流水号 小于64个字符 channelId String 是 通知渠道 ticketId String 是 券ID ticketName String 是 券名称 thirdActivityId String 是 第三方活动id code String 是 券号 shopNo String 否 门店编号 shopName String 否 门店名称 verifyRefno String 否 线下核销机具流水号 verifyTime String 是 券核销时间 格式：yyyyMMddHHmmss verifyType String 是 核销类型 1表示POS机验证； 2表示接口验证； 999 表示不用通知上下游 orderNo String 是 制码订单号 orderItemId String 是 制码子订单号，对接方唯一识别码 discountAmount String 否 核销折抵金额 单位分 请求报文举例 { "requestId": "10000000000000000000001", "ticketId":"9000000021", "ticketName":"汉堡王皇堡/天椒皇堡套餐[bobo测试取码方]", "thirdActivityId": "20190226134100", "code":"10112504119074937195", "shopNo":"1870002", "shopName":"家有好面龙阳路店", "verifyRefno":"178491000582", "verifyTime":"20181016103223", "verifyType":"1", "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5", "orderItemId":"10191f7aee084db8915dd77293a65906", "discountAmount":"2000" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 09   券码不存在 01   券码已使用 00   券码核销成功 returnMsg String 是 请求返回信息 requestId String 是 原样返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000001" } 单码核销撤销通知 接口用途 用于实现易百券核销撤销成功后将通知到第三方系统 接口说明 接口异步通知第三方 请求参数， WHALE <===>CHANNEL 字段 类型 是否必填 字段意义 备注 requestId String 是 核销撤销请求流水号 小于64个字符 verifyTime String 是 券核销撤销时间 格式：yyyyMMddHHmmss code String 是 劵码   originalRequestId String 是 原核销交易流水号 小于64个字符 orderNo String 否 制码订单号   orderItemId String 否 制码子订单号，对接方唯一识别码 请求报文举例 { "requestId": "10000000000000000000002", "verifyTime":"20181016103223", "code":"10215523190570712621", "originalRequestId": "10000000000000000001001", "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5", "orderItemId":"10191f7aee084db8915dd77293a65906" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000001" } 码预核销接口 接口用途 当需要确认码是否可用在当前场景时，调用此接口， 接口说明 建议单码场景使用。多码需确认是否满足需求。 action CodeCheck 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codes List 是 验码集合   cashTotalAmount Number 是 订单金额 单位：分 isProductCheck String 是 是否校验订单产品规则 是Y，否N brandId String 否 品牌id 多品牌使用的码，此字段必传 shopNo String(20) 否 门店号 线下场景必填 tid String(8) 否 终端号   cityId String 否 城市id，对接时使用ebuy城市id 有规则时必须上传 goodsDetail Object< goodsDetail > 否 折抵产品明细 目前支持单码预核销检查使用 请求报文举例 { "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 String 是 00为成功，其他均为失败   returnMsg String 是 请求返回信息   data/checkResult Object< data/checkResult > 是 劵码查询结果 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "data": { "checkResult":[{ "code":"1021242013780905000", "saleChannelCode":"990001", "saleChannelName":"易百码", "status": "00", "discountAmount":3000 },{ "code":"1021242013780905000", "saleChannelCode":"990001", "saleChannelName":"易百码", "status": "06", "discountAmount":3000, }] } } 券状态枚举 字段 字段意义 备注 00 可用 01 已使用 03 未激活 未激活的码需调用激活接口才能 04 已冻结 05 已作废 06 已过期   07 未生效 当制码时选择次日生效，核销时会返回该状态 09 码不存在 35 劵数据异常 联系易百确认 39 核销失败 91 核销异常 批量码核销 接口用途 多码批量核销时，调用此接口 接口说明 一次可以多码核销,一次最多10个码。 action BatchCodesVerify 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 verifyScene String 是 交易场景.offline线下,online线上 线上也可以传抖音、美团等 codes List 是 码号数组   verifyCodes List< codeArr > 否 指定券码阶梯价序号 isProductCheck String 是 是否校验订单产品规则 是Y，否N requestId String 是 请求流水号确保永久唯一性 32位长度 refNo String 否 系统参考号 12位长度 cashierTransNo String 否 收银机流水号 最长64位长度 storeInfo Object< storeInfo > 否 此信息为线下门店核销时上送 线下核销必填 cashTotalAmount Number 否 订单总金额 单位：分 goodsDetail List< goodsDetail > 否 (只有在收银POS上发起交易时才上送)   remark String 否 备注（在核销撤销、核销查询等接口原样返回）   请求报文举例 { "verifyScene":"online", "codes": ["10215523190570712621"], "requestId": "20181019112535100000000000000001", "refNo": "181215430700", "cashierTransNo": "42441908138100007498001", "storeInfo": { "cityId":"1012", "shopNo": "C00001", "shopName": "上海浦东测试门店", "manageCompany": "上海浦东测试店管理公司", "companyId": "218" }, "cashTotalAmount": "20000", "goodsDetail": [{ "sku": "1112343", "qty": 1, "price": 3000, "type": "03", "spec": "03" }, { "sku": "1212342", "qty": 1, "price": 3500, "type": "03", "spec": "03" }] } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 returnMsg String 是 请求返回信息   data/checkResult Object< data/checkResult > 是 券码核销信息明细返回 返回报文举例 { "requestId": "10000000000000000000002", "returnCode": "00", "returnMsg": "操作成功", "data": { "verifyResult":[{ "code":"1021242013780905000", "saleChannelCode":"990001", "saleChannelCode":"易百码", "status":"00", "fundsChannel": { "discountAmount": 3000, "merchantRealAmount":0.0, "channelBenefit": 0.0, "merchantBenefit": 0.0 }, "faceValue":3000, "ticketId":"3", "ticketName":"30元现金抵价券", "returnCashParam":{ "tenderCode":"135" } },{ "code":"1021242013780905000", "saleChannelCode":"990001", "saleChannelCode":"易百码", "status":"06", "fundsChannel": { "discountAmount": 1000, "merchantRealAmount":0.0, "channelBenefit": 0.0, "merchantBenefit": 0.0 }, "faceValue":1000, "ticketId":"6", "ticketName":"10元现金抵价券", "returnCashParam":{ "tenderCode":"132" } }] } } status枚举 字段 字段意义 备注 00 可使用 01 已使用 03 未激活 未激活的码需调用激活接口才能 04 已冻结 05 已作废 06 已过期   07 未生效 当制码时选择次日生效，核销时会返回该状态 09 码不存在 10 券码状态异常，券码无效 23 商户商品号传送错误 26 券码不能在本门店使用 C1 商户号门店信息有误 C2 商户无权限 T2 易百调用第三方失败 A4 其他异常 批量码核销查询 接口用途 批量核销接口调用超时对核销结果未知道，可以调用此接口来查询核销结果 接口说明 此接口默认支持查询当日内核销交易 也可传参originalDate查询指定日核销交易 action BatchCodeVerifyQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 originalRequestId String 是 原核销请求流水号 32个字符 originalDate String 否 原交易日期 传入需要查询的原交易日期，不传默认为当天格式为yyyyMMdd 请求报文举例 { "requestId": "20180905000", "originalRequestId":"1021867639235435", "originalDate": "20170912" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回   verifyRemark String 否 核销备注信息 核销接口上送原样返回 data/verifyQueryResponse Object< data/verifyQueryResponse > 是 券码核销订单明细返回   返回报文举例 { "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 String 是 请求流水号 小于32个字符 originalRequestId String 是 原核销请求流水号 32个字符，用于标识唯一一笔交易 codes List 否 原订单中批量核销撤销的码 此字段不填默认整订单撤销 voidDate String 否 原交易时间,默认当天 格式:YYYYMMDD isAtomicity String 否 是否需要支持原子性，原交易中码核销撤销要么全部成功要么全部失败 Y：是，N：否（默认） 请求报文举例 { "requestId": "10000000000000000000001", "originalRequestId":"10000000000000000000002" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 返回码32时，请调用单码核销查询接口CodeVerifyQuery，确认核销结果 returnMsg String 是 请求返回信息   verifyRemark String 否 核销备注信息 核销接口上送原样返回 data/voidResult Object< data/voidResult > 是 券码核销信息明细返回   返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": 10000000000000000000002, "data": { "voidResult":[{ "code":"1021242013780905000", "status":"00", "statusDesc":"成功", "amount": "5000", "ticketName": "50 元现金抵价券 " }] } } 取码方可用券查询 接口用途 当取码方需要知道自己可用的券时，可调用此接口 action ChannelTicketQuery 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 activityValidStart String 是 活动开始时间 yyyyMMddHHmmss activityValidEnd String 是 活动结束时间 yyyyMMddHHmmss requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 请求报文举例 { "requestId": "20181019112535100000000000000002", "activityValidStart": "20180901000000", "activityValidEnd": "20181231595959" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data List< channelTicketQuery > 否 券信息 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": [{ "ticketId": "10001", "ticketName": "星巴克30元代金券", "activityId": "20001", "activityName": "浦发星巴克代金券活动", "activityValidStart": "20180901000000", "activityValidEnd": "20181231595959", "thirdActivityId": "20190226134100", "codeValidStart": "20180901000000", "codeValidEnd": "20181231595959", "createDate": "20181018", "createTime": "20181018183454", "activityUseDescription": { "useDescription":活动使用说明"" }, "ticketUseDescription": { "ticketPicture":"www.baidu.com", "useThreshold":"使用门槛", "discountDescription":"优惠说明", "useDescription":"使用说明" } },{ "ticketId": "10002", "ticketName": "星巴克50元代金券", "activityId": "20001", "activityName": "浦发星巴克代金券活动", "activityValidStart": "20180901000000", "activityValidEnd": "20181231595959", "codeValidStart": "20180901000000", "codeValidEnd": "20181231595959", "createDate": "20181018", "createTime": "20181018183454", "activityUseDescription": { "useDescription":活动使用说明"" }, "ticketUseDescription": { "ticketPicture":"www.baidu.com", "useThreshold":"使用门槛", "discountDescription":"优惠说明", "useDescription":"使用说明" } }] } 外部核销通知 接口用途 用于实现外部系统劵成功后通知到易百 接口说明 第三方通知EBUY action CodeVerifyNotify 请求参数，CHANNEL ===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 小于32个字符 thirdVerifyId String 否 核销流水号 第三方码核销通知时上传该字段，用于标识在第三方库中的核销记录 ticketName String 否 券名称   brandId String 是 品牌 易百定义 code String 是 券号   mid String 否 商户号   shopNo String 否 门店编号   shopName String 否 门店名称   tid String 否 pos终端号   verifyTime String 是 券核销时间 格式：yyyyMMddHHmmss verifyType String 是 核销类型 1表示POS机验证；2表示接口验证 orderNo String 否 制码订单号   orderItemId String 否 制码子订单号，对接方唯一识别码   amount Number 否 核销金额 单位：分 请求报文举例 { "requestId": "10000000000000000000002", "originalRequestId":"10000000000000000000001", "ticketName":"汉堡王皇堡/天椒皇堡套餐", "code":"10112504119074937195", "shopNo":"1870002", "shopName":"家有好面龙阳路店", "verifyTime":"20181016103223", "verifyType":"1", "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5", "orderItemId":"10191f7aee084db8915dd77293a65906" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000002" } 外部核销撤销通知 接口用途 用于实现第三方核销撤销EBUY的劵成功后通知 WHALE 接口说明 第三方核销撤销成功后通知EBUY action CodeVerifyVoidNotify 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 核销撤销请求流水号 小于64个字符 originalRequestId String 是 第三方核销时流水号 32个字符，用于标识唯一一笔交易 voidTime String 是 券撤销时间 格式：yyyyMMddHHmmss code String 是 劵码   orderNo String 否 制码订单号   orderItemId String 否 制码子订单号，对接方唯一识别码 请求报文举例 { "requestId": "10000000000000000000002", "originalRequestId":"10000000000000000000001", "voidTime":"20181016103223", "code":"10215523190570712621", "orderNo":"a1b626f8b39b4852bfaedc69cc4dbff5", "orderItemId":"10191f7aee084db8915dd77293a65906" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   requestId String 是 原样返回 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "10000000000000000000001" } 串码通知到用户微信卡包接口 接口用途 当需要将已制出的串码通知到用户微信卡包时，调用此接口 接口说明 易百不提供插入微信卡包功能，插入卡包的服务商为该码的制码方。 此接口为异步执行，同步返回成功表明任务提交成功，实际插入卡包结果异步通知到。 action NotifyCodeToUser 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 code String 是 待通知串码号 callBackUrl String 是 结果回调地址   weChatCardPackageInfo Object< weChatCardPackageInfo > 否 微信卡包信息 请求报文举例 { "requestId":"20181018183139", "code": "100243020180912162026", "callBackUrl": "www.XXX.com", "weChatCardPackageInfo":{ "userUnionId":"1rbu123430vj" } } 同步返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< notifyCodeToCardPackageResponse > 否 同步返回报文 返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181018183139", } } 异步返回参数，ESB===>CHANNEL 默认情况下异步报文与同步报文一致 星巴克箱包本码查询 接口用途 当需查询箱包本码集合 接口说明 传入箱、本、码编号，分别获得对应的码列表   请求参数 字段 类型 是否必填 字段意义 备注 queryType String 是 查询类型 X 箱， B1 包， B2本 queryCode String 是 查询编号   请求报文举例 { "queryType": "X", "queryCode":"123" } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码 00 正常，非00是错误 returnMsg String 是 请求返回信息   codeList List 否 码信息   返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": [ "100000000001212121", "100000000001212122", "100000000001212123" ] } 异步第三方制码 接口用途 用于异步第三方制码的请求参数，发送到whale-gateway数据格式 接口说明 这里规定了标准的请求报文格式，发送到whale-gateway模块，然后具体对于不同码商的报文格式需要gateway转换 action MakeCode 请求参数，whale===>whale-gateway 字段 类型 是否必填 字段意义 备注 channelId String 是 渠道Id   channelTicketId String 是 渠道批次Id   codeValidEnd String 是 券码有效期结束时间 格式为yyyyMMdd235959 codeValidStart String 是 券码有效期开始时间 格式为yyyyMMdd000000 faceValue Double 是 券面值   netValue Double 是 净值   orderId String 是 订单Id   requestId String 是 请求流水号   saleChannelOrderId String 是 外部订单编号   totalCount String 是 制码数量   transDate String 是 交易日期 格式为 yyyyMMdd transTime String 是 交易时间 格式为 yyyyMMddHHmmss useTimes String 是 可核销次数   whaleTicketId String 是 whale券Id   saleChannelItemId String 是 子订单号   请求报文举例 { "channelId": "136", "faceValue": -1, "makeFundsChannel": { "benefitAmount": 0, "channelBenefit": 0, "discountAmount": 0, "merchantBenefit": 0, "merchantCustomBenefit": -1, "merchantCustomRealAmount": -1, "merchantRealAmount": 10, "totalAmount": 100, "userRealAmount": 80 }, "netValue": -1, "orderId": "d84c1302a5e84774813bc9f1b7aaea8a", "orderRemark": "testtttt", "requestId": "d84c1302a5e84774813bc9f1b7aaea8a", "saleChannelOrderId": "d84c1302a5e84774813bc9f1b7aaea8a", "totalCount": "1", "transDate": "20220506", "transTime": "20220506215213", "useTimes": "12", "whaleTicketId": "162" } 返回参数，whale-gateway===>whale 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   sendChannelOrderId String 否 订单号   thirdCodeFamilySet List< CodeFamilyInfoBO >       返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "sendChannelOrderId": "", "thirdCodeFamilySet": [] }   第三方码异步结果通知 接口用途 第三方券码异步处理完成后的通知接口 接口说明 接收统一的报文格式 action AsynThirdCodeCallback 请求参数，CHANNEL===>WHALE 字段 类型 是否必填 字段意义 备注 createDate String   创建日期   createTime String   创建时间   returnCode String   返回编码   outerOrderId String   制码订单号   codeFamilyInfo CodeFamilyInfoBO   券码                   同步批量码作废 接口用途 多码批量作废时，调用此接口 接口说明 一次可以多码作废,一次最多20个码。 action SyncBatchCodeUpdate 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codeArray List 是 码号数组   saleChannelId Long 否 取码方id   saleChannelOrderId String 否 取码方制码订单号 当codeArray无值时取该订单号下所有串码进行作废。当订单号有值时取码方id必填 callBackUrl String 是 激活成功后的回调地址   updateShopNo String(10) 否 激活门店号   updateOrg String(10) 否 激活机构   optTag String(2) 是 操作分类 B1：批量作废 请求报文举例 { "requestId":"20181019112535100000000000000001", "codeArray": ["10215523190570712621"], "callBackUrl": "http://test.com/api/codeVoid", "optTag": "B1", } 同步返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< statusUpdateCallbackData > 否 码状态更新返回数据 回调返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "data": { "tradeNo": "9e22d9a9e532435db77bccdfd8a74ee5", "requestId": "20181019112535100000000000000008", "totalCodeNum": 1, "successCodeNum": 1, "codeArray": [{ "codeId": "1212431432", "searchCode": "100***1234", "codeSecret": "100213321414112234", ... }], } }               异步第三方作废接口 接口用途 用于异步第三方制码的请求参数，发送到whale-gateway数据格式 接口说明 这里规定了标准的请求报文格式，接收ebuyweb-gateway请求 action syncUpdateCodeStatus 请求参数，whale===>whale-gateway 字段 类型 是否必填 字段意义 备注 outerOrderId String 是 渠道Id   channelTicketId String 是 渠道批次Id   reason String 否 退款原因   请求报文举例 { "outerOrderId": "03136aaaaaaaaaaa", "channelTicketId": "162", "reason": "reason" } 返回参数，whale-gateway===>whale 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   sendChannelOrderId String 否 订单号   thirdCodeFamilySet List< CodeFamilyInfoBO >       返回报文举例 { "returnCode": "00", "returnMsg": "SUCCESS", "sendChannelOrderId": "", "thirdCodeFamilySet": [] }   测试apimock同步 [yapi_interface]617[/yapi_interface] 查询码信息查询 接口用途 当需要查询某个指定码时，取码方调用此接口 接口说明 码表中以掩码为分表位，每查询某个码时必须有明确的码号。 action CodeQueryBySearchCode 请求参数，CHANNEL===> WHALE 字段 类型 是否必填 字段意义 备注 requestId String 是 请求流水号 32个字符，用于标识唯一一笔交易 codes List 是 验码集合   brandId String 否 核销门店所属品牌 组合劵必须上送，易百提供 cityId String 否 门店所在城市id 易百提供的城市id storeInfo Object< storeInfo > 否 门店串码查询时上送 请求报文举例 { "requestId": "20181019112535100000000000000002", "codes": ["1021242013780905000"], "brandId":"2429", "cityId":5493 } 返回参数， WHALE ===>CHANNEL 字段 类型 是否必填 字段意义 备注 returnCode String 是 请求返回码   returnMsg String 是 请求返回信息   data Object< codeQueryResponseData > 否 码信息 返回报文举例 { "returnCode": "00", "returnMsg": "操作成功", "requestId": "171698602301", "data":{ "codeDetail":[{ "code":"1021242013780905000", "saleChannelOrderId":"20181120155110", "sendChannelName":"易百自制渠道", "saleChannelCode":"990001", "useTimes":1, "verifyTimes":1 "remainTimes":0, "createDate": "20180905", "createTime": "20180905160911", "validStart":"20181123000000", "validEnd":"20181124235959", "verifyDate":"20181123", "verifyTime":"20181124121243", "status": "01", "statusDesc": "已使用", "cityCheck":"Y", "ticketId":"9000000001", "faceValue":3000, "ticketName":"星巴克30元代金券", "shopNo":"1111", "shopName":"星巴克测试门店" "faceValue":1000, },{ "code":"1021242013780905001", "saleChannelOrderId":"20181120155110", "sendChannelName":"易百自制渠道", "remainTimes":1, "createDate": "20180905", "createTime": "20180905160911", "validStart":"20181123000000", "validEnd":"20181124235959", "verifyDate":"20181123", "verifyTime":"20181124121243", "status": "01", "statusDesc": "已使用", "cityCheck":"Y", "ticketId":"9000000001", "faceValue":3000, "ticketName":"星巴克30元代金券", "shopNo":"1111", "shopName":"星巴克测试门店" "faceValue":1000, }] } } 券状态枚举 字段 字段意义 备注 00 可使用 01 已使用 02 可使用(一码多次使用时，码还有可用次数) 03 未激活 未激活的码需调用激活接口才能 04 已冻结 05 已作废 06 已过期   07 未生效 当制码时选择次日生效，核销时会返回该状态 09 券不存在   35 码配置异常 现金卡预核销 [yapi_interface]14869[/yapi_interface]