交易类接口

同步单条发码
发码订单查询
异步批量发码
批量发码结果通知
发码撤销
发码撤销查询
码作废（退款）接口
码冻结接口
码解冻接口
码激活接口
批量码激活
批量码延期
批量码作废
码信息更新接口
码信息查询
单码核销
单码核销撤销
单码核销查询
单码核销通知
单码核销撤销通知
码预核销接口
批量码核销
批量码核销查询
批量码核销撤销
取码方可用券查询
外部核销通知
外部核销撤销通知
串码通知到用户微信卡包接口
星巴克箱包本码查询
异步第三方制码
第三方码异步结果通知
同步批量码作废
异步第三方作废接口
测试apimock同步
查询码信息查询
现金卡预核销

同步单条发码

接口用途

支持请码方一次单品请求调用,单品发码数量上限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<CodeDelayInfo>	是	码更新集	每个码单独对应一个有效期。与codeArray选择一个上传
saleChannelId	Long	否	取码方id
saleChannelOrderId	String	否	取码方制码订单号	当codeArray和codeObjArray均无值时取该订单号下所有串码进行延期。当订单号有值时取码方id必填
callBackUrl	String	是	更新成功后的回调地址
updateShopNo	String(10)	否	更新门店号
updateOrg	String(10)	否	更行机构
optTag	String(2)	是	操作分类	B5：批量延期

请求报文举例

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

同步返回参数，WHALE===>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

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

返回报文举例

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

异步第三方制码

接口用途

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

接口说明

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

action

MakeCode

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

字段	类型	是否必填	字段意义	备注
channelId	String	是	渠道Id
channelTicketId	String	是	渠道批次Id
codeValidEnd	String	是	券码有效期结束时间	格式为yyyyMMdd235959
codeValidStart	String	是	券码有效期开始时间	格式为yyyyMMdd000000
faceValue	Double	是	券面值
netValue	Double	是	净值
orderId	String	是	订单Id
requestId	String	是	请求流水号
saleChannelOrderId	String	是	外部订单编号
totalCount	String	是	制码数量
transDate	String	是	交易日期	格式为 yyyyMMdd
transTime	String	是	交易时间	格式为 yyyyMMddHHmmss
useTimes	String	是	可核销次数
whaleTicketId	String	是	whale券Id
saleChannelItemId	String	是	子订单号

请求报文举例

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