title: 卡券 header: develop nav: api

sidebar: cardticket

接口目录

1. 创建卡券
   1.1 步骤一：选取卡券背景色 1.2 步骤二：选择卡券类型并创建卡券
   1.2.1卡券基础信息字段（重要） 1.3 步骤三：上传Code码 1.4 步骤四：上传卡券Banner图（可选） 1.4.1 Banner创建 1.4.2 Banner修改 1.4.3 Banner删除 1.4.4 Banner详情查询 1.4.5 Banner列表批量查询

2. 领券事件推送

3. 跳转协议带参数 3.1 获取参数 3.2 解密参数

4. 核销同步

5. 管理卡券 5.1 查看卡券详情 5.2 批量查询卡券列表 5.3 删除卡券

百度卡券

小程序为开发者提供接入百度卡券的免费接口，接入后可在百度多种运营资源进行投放，同时发放的优惠券统一进入用户的「卡券包」查看和管理，并引导用户直达商家小程序浏览及购买商品。

用户在百度领券流程概述： 1） 用户在百度卡券包等运营资源位上领券； 2） 百度记录用户的领取记录，返回用户领券成功； 3） 通过领券事件推送（异部通知）和跳转协议带参数两种途径，告知开发者用户的领取记录； 注意：开发者收到后需为用户下发真实优惠券；

前提条件

1. 已完成开发者入驻和小程序创建；
2. 已使用百度官方提供的登录能力；
3. 开发者业务有优惠券功能，具备发券-核销能力。百度智能小程序仅作为平台投放、券的统一展示、集中管理。如，个人中心有我的优惠券/礼券/卡券等，用户可查看可使用。

1. 创建卡券

开发步骤

明确卡券ID与Code码的区别

创建卡券成功后获取百度分配的卡券ID，一个卡券ID代表一类卡券，包含相应库存数量的Code码。

例如： 创建100元代金券，获取一个卡券ID（couponId）用于投放，并需开发者上传对应业务的Code码，根据上传Code码的数量，百度设置库存100万。 用户A，领取到商户投放的50元代金券时，券面上会有一个唯一的标识码，即Code码。每个用户的Code码都不相同，所以卡券发放时，百度将会派发100万个不同的Code码给用户。

字段示意图

1.1 步骤一：选取卡券背景色

目前百度提供包括以上16种色值供开发者使用，选择适用的背景色，将背景色名称（如B010）填入color字段。

1.2 步骤二：选择卡券类型并创建卡券

百度提供以下3种卡券类型，1-代金券，2-折扣券，3-通用优惠券。

开发者须知：

1) 一个小程序内全部卡券的callbackUrl需为同一个；

2) description 字段传入文本格式支持富文本标签，如使用<br>换行；

3) 卡券管理当前不提供更新卡券接口，如有更新需求，需重新创建卡券。

接口地址

HTTP请求方式 POST/application-json https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/create?access_token=ACCESS_TOKEN

请求参数

POST数据示例

{
    "couponType":"DISCOUNT",
    "discount":30,
    "leastCost":100,
    "reduceCost":10,
    "baseInfo":{
        "title":"卡券标题",
        "color":"B080",
        "getLimit":3,
        "dateInfo":{
            "getStartTimestamp":1574952776,
            "getEndTimestamp":1577544776,
            "type":1,
            "beginTimestamp":1574952776,
            "endTimestamp":1577544776,
            "timeUnit":1,
            "timeValue":22
        },
       "appRedirectPath": "/pages/index/index"
    }
    "description":"使用描述",
    "callbackUrl":"卡券事件回调地址"
}

返回示例

{
    "errno":0,
    "msg":"success",
    "data":{
        "couponId":"xxxx"
    }
}

1- 代金券

{
    "couponType":"CASH",
    "leastCost":100,
    "reduceCost":50,
    "baseInfo":{
    ················        
    },
    "description":"使用描述",
    "callbackUrl":"卡券事件回调地址"
}

2- 折扣券

{
    "couponType":"DISCOUNT",
    "discount":80,
    "baseInfo":{
     ················        
     },
     "description":"使用描述",
     "callbackUrl":"卡券事件回调地址"
}

3- 通用优惠券

{
    "couponType":"GENERAL",
    "baseInfo":{
    ················        
    }
    "description":"使用描述",
    "callbackUrl":"卡券事件回调地址"
}

1.2.1卡券基础信息字段（重要）

1.3 步骤三：上传Code码

接口地址

HTTP请求方式 POST/form https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/code/batchUpload?access_token=ACCESS_TOKEN

请求参数

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": {
          "successNum":5,
          "failNum":2  //重复导入的code会忽略
     }
}

1.4 步骤四：上传卡券Banner

上传图片接口

为了保证开发者的卡券在用户的能快速、稳定地加载出图片素材，我们强烈建议开发者将卡券素材先调用接口导入百度服务器。 开发者需调用该接口上传商户图标至百度服务器，获取相应picUrl（卡券Banner图片）。请求参数为file，上传图片后，获取返回url。

开发者须知： 1) 图片尺寸：1032* 144px； 2) 当前一个卡券ID仅支持创建一个Banner；

请求地址

HTTP请求方式 POST/form-data https://openapi.baidu.com/file/2.0/smartapp/v1.0/coupon/upload/image?access_token=ACCESS_TOKEN

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": {
        "url": "https://b.bdstatic.com/searchbox/mappconsole/image/20191128/8d382c36-2b85-4f2c-b6d1-0d6afbc04dc8.png"
    }
}

1.4.1 Banner创建

请求地址

HTTP请求方式 POST/application-json https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/banner/add?access_token=ACCESS_TOKEN

请求参数

POST数据示例

{
    "couponId":"xxx",
    "picUrl":"/index/index",
    "title":"卡券标题",
    "appRedirectPath":"跳转的小程序页面路径"
}

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": {
        "bannerId": 23830865
    }
}

1.4.2 Banner修改

请求地址

HTTP请求方式 POST/application-json https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/banner/update?access_token=ACCESS_TOKEN

请求参数

POST数据示例

{
    "bannerId":"bannerId",
    "couponId":"xxx",
    "picUrl":"www.baidu.com",
    "title":"标题",
    "appRedirectPath":"跳转小程序页面路径"
}

参数说明

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": true
}

1.4.3 Banner删除

请求地址

HTTP请求方式 POST/form https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/banner/delete?access_token=ACCESS_TOKEN

请求参数

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": true
}

1.4.4 Banner详情查询

请求地址

 HTTP请求方式 GET https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/banner/get?access_token=ACCESS_TOKEN

请求参数

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": [
        {
            "bannerId": 23830865,
            "couponId": "23830866",
            "title": "titletest",
            "picUrl": "picUrlTest",
            "appRedirectPath": "destUrlTest",
            "createTime": 1574396789,
            "updateTime": 1574396788
        }
    ]
}

1.4.5 Banner列表批量查询

请求地址

HTTP请求方式 GET https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/banner/batchGet?access_token=ACCESS_TOKEN

请求参数

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": {
        "pageNo": 1,
        "total": 1,
        "dataList": [
            {
                "bannerId": 23830865,
                "couponId": "23830866",
                "title": "titletest",
                "picUrl": "picUrlTest",
                "appRedirectPath": "destUrlTest",
                "createTime": 1574396789,
                "updateTime": 1574396788
            }
        ]
    }
}

2 领券事件推送

卡券被用户领取会触发事件推送，该事件将发送至开发者填写的卡券回调地址callbackUrl。

百度服务器在3秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。 关于重试的消息排重，推荐使用FromUserName + CreateTime 排重。 假如服务器无法保证在3秒内处理并回复，可以直接回复空串，百度服务器不会对此作任何处理，并且不会发起重试。

开发者服务器收到请求必须做出下述回复:

1.直接回复success（推荐方式） 2.直接回复空串

用户在领取卡券时，百度会把这个事件推送到开发者填写的callbackUrl。

推送示例

    {
        "ToUserName":"app_id",
        "FromUserName":"open_id",
        "CreateTime":"1472551036",
        "MsgType":"event",
        "Event":"user_get_coupon",
        "CouponId":"pZI8Fjwsy5fVPRBeD78J4RmqVvBc",
        "UserCouponCode":"226009850808",
        "CouponTakeId":"xxxxx"
    }

参数说明

3. 跳转协议带参数

用户从百度卡券包卡券详情点击「立即使用」时，跳转打开开发者小程序的跳转协议路径页面地址，同时带上该券的领券参数coupon，开发者拿到参数后，对参数进行解密，可以获取到该用户的领券信息。

注意事项：coupon为加密信息，需要使用小程序App Secret (智能小程序密匙)进行解密（小程序开发者平台：设置->开发设置->开发者ID(App Secret (智能小程序密匙)))

3.1 获取参数

开发者需在卡券详情页点击立即使用跳转的页面上，通过 onShow() 获取当前页面路径中的coupon参数；

开发者须知 若点击「立即使用」 加密信息传递，注意需要在小程序app.js文件中增加onShow能力开发；

代码示例（放在app.js中）

onShow(event) {
        let extraData = event.referrerInfo.extraData;
        let coupon = extraData.coupon;
        swan.showModal({
            title: '提示' + coupon,
        });
    }

3.2 解密参数

对coupon参数进行解密，获取到用户的领券信息，为用户发券；

使用小程序App Secret (智能小程序密匙)进行解密（小程序开发者平台：设置->开发设置->开发者ID(App Secret (智能小程序密匙))）

解密结果说明

{"open_id":"xxx","coupon_id":"xxx","coupon_code":"xxx","app_key":"xxx","coupon_take_id":"xxx"}

参数说明

4. 核销同步

用户用券环节在开发者小程序内完成，开发者服务器核销掉该卡券后，需调用核销同步接口，同步至百度服务器。

消耗code接口是核销卡券的唯一接口，开发者可以调用当前接口将用户的优惠券进行核销，该过程不可逆。

接口请求说明

HTTP请求方式 POST/form https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/code/consume?access_token=ACCESS_TOKEN

请求参数

返回示例

{
    "errno": 0,
    "msg": "success",
    "data": true
}

5. 管理卡券

5.1 查看卡券详情

请求地址

HTTP请求方式 GET https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/get?access_token=ACCESS_TOKEN

请求参数

请求参数

{
    "errno":0,
    "msg":"success",
    "data":{
        "couponId":"xxxx",
        "couponType":"DISCOUNT",
        "discount":30,
        "baseInfo":{
            "title":"卡券标题",
            "color":"B10",
            "getLimit":3,
            "dateInfo":{
                "getStartTimestamp":1574952776,
                "getEndTimestamp":1577544776,
                "type":1,
                "beginTimestamp":1574952776,
                "endTimestamp":1577544776,
                "timeUnit":1,
                "timeValue":22
            }
        },
        "description":"使用描述",
        "callbackUrl":"卡券事件回调地址"
    }
}

5.2 批量查询卡券列表

接口描述：批量查询卡券接口。

请求地址：

HTTP请求方式 GET https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/batchGet?access_token=ACCESS_TOKEN

返回示例

{
    "errno":0,
    "msg":"success",
    "data":{
        "pageNo":1,
        "total":3,
        "dataList":[
            {
                "couponType":"DISCOUNT",
                "discount":30,
                "baseInfo":{
                    "title":"卡券标题",
                    "color":"B10",
                    "getLimit":3,
                    "dateInfo":{
                        "getStartTimestamp":1574952776,
                        "getEndTimestamp":1577544776,
                        "type":1,
                        "beginTimestamp":1574952776,
                        "endTimestamp":1577544776,
                        "timeUnit":1,
                        "timeValue":22
                    }
                },
                "description":"使用描述",
                "callbackUrl":"卡券事件回调地址"
            }
        ]
    }
}

5.3 删除卡券

请求地址

HTTP请求方式 POST/form https://openapi.baidu.com/rest/2.0/smartapp/v1.0/coupon/delete?access_token=ACCESS_TOKEN

请求参数

返回示例

    {
        "errno": 0,
        "msg": "success",
        "data": true
    }