投放卡券

更新日志

1 创建二维码接口

开发者可调用该接口生成一张卡券二维码供用户扫码后添加卡券到卡包。

自定义Code码的卡券调用接口时，POST数据中需指定code，非自定义code不需指定，指定openid同理。指定后的二维码只能被用户扫描领取一次。

获取二维码ticket后，开发者可用通过ticket换取二维码接口。

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

参数说明

POST数据 

开发者可以设置扫描二维码领取单张卡券，此时POST数据为：

 {
"action_name": "QR_CARD", 
"expire_seconds": 1800,
"action_info": {
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", 
"code": "198374613512",
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"is_unique_code": false ,
"outer_str":"12b"
  }
 }
}

当开发者设置扫描二维码领取多张卡券，此时POST数据为：

{
"action_name": "QR_MULTIPLE_CARD", 
"action_info": {
"multiple_card": {
"card_list": [
{
"card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo88",
"code":"2392583481",
"outer_str":"12b"
}, 
{
"card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo98",
"code":"2392583482",
"outer_str":"12b"
}
]
}
}
}

参数说明

返回数据

{
 "errcode": 0,
 "errmsg": "ok",
 "ticket":      "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",//获取ticket后需调用换取二维码接口获取二维码图片，详情见字段说明。
 "expire_seconds": 1800,
 "url": "http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o ",
 "show_qrcode_url": " https://mp.weixin.qq.com/cgi-bin/showqrcode?  ticket=gQH98DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0czVzRlSWpsamlyM2plWTNKVktvAAIE6SfgVQMEgDPhAQ%3D%3D"
 }

   参数说明

注意事项：

1.自定义code的卡券，生成的二维码每次只能领取一次，若开发者想要使用自己的串码系统并且想要用微信的二维码

投放，须先将自定义code导入；

2.领取多张的二维码一次最多填入5个card_id，否则报错。

2 HTML5线上发券（JS-SDK接口）

微信 JS-SDK 仅支持在微信内置浏览器中使用,其他浏览器调用无效。

微信提供addCard接口供商户前端网页调用,用于将一张或多张卡券添加到用户卡包。详情见批量添加卡券接口。

3 通过卡券货架投放卡券

卡券货架简介

卡券货架支持开发者通过调用接口生成一个卡券领取H5页面，并获取页面链接，进行卡券投放动作。 目前卡券货架仅支持非自定义code的卡券，自定义code的卡券需先调用导入code接口将code导入才能正常使用。

3.1 创建货架接口

接口说明

开发者需调用该接口创建货架链接，用于卡券投放。创建货架时需填写投放路径的场景字段。

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/landingpage/create?access_token=$TOKEN

请求参数说明

POST数据

{  
"banner":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7h  icFN",
   "page_title": "惠城优惠大派送",
   "can_share": true,
   "scene": "SCENE_NEAR_BY",
   "card_list": [
       {
           "card_id": "pXch-jnOlGtbuWwIO2NDftZeynRE",
           "thumb_url": "www.qq.com/a.jpg"
       },
       {
           "card_id": "pXch-jnAN-ZBoRbiwgqBZ1RV60fI",
           "thumb_url": "www.qq.com/b.jpg"
       }
   ]
}

参数说明

返回数据说明

{
     "errcode":0,
     "errmsg":"ok",
     "url":"www.test.url",
     "page_id":1
 }

字段说明

4 群发卡券

请开发者特别注意，目前群发卡券接口仅支持投放非自定义Code码的卡券。自定义code码的商户若想使用该功能需调用导入code接口将自定义code先导入微信服务器。

4.1 导入自定义code(仅对自定义code商户)

接口简介

该模块只针对自定义code商户，非自定义code开发者请自动忽略。 开发者可以将自定义code提前导入至微信服务器，以获得和非自定义code商户同样的投放能力，如分组群发、客服消息下发卡券等。

导入code后的卡券在投放时等同于非自定义code卡券

新创建卡券

如果开发者打算新创建一张支持导入code模式的卡券，不同于以往的创建方式，建议开发者采用以下流程创建预存code模式卡券，否则会报错。

步骤一：创建预存模式卡券，将库存quantity初始值设置为0，并填入get_custom_code_mode字段;

步骤二：待卡券通过审核后，调用导入code接口并核查code;

步骤三：调用修改库存接口，须令卡券库存小于或等于导入code的数目。(为了避免混乱建议设置为相等)

非新创建卡券

如果开发者已经有一张卡券，想把它改为预存code模式，建议开发者按照以下流程对卡券进行更新。

步骤一：调用导入code接口导入一定量的自定义code并核查code;

步骤二：调用更改卡券信息接口填入get_custom_code_mode字段;

步骤三：调用修改库存接口将卡券库存quantity设置为与导入code数目相等的数字。

4.1.1 填入/更新导入code必需字段

接口说明

自定义code的卡券仅支持API创建，创建时务必在base_info中加入以下字段(详情见接口文档CreateCard创建卡券接口)， 加入以下两个指定字段后，才可以调用code导入接口进行code导入

创建卡券时JSON示例

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
     "base_info": {
     ··········
     "use_custom_code":true,
     "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
         },
          "advanced_info": {
      ··········
          },
         "deal_detail": "示例"
     }
   }
}

更新卡券时JSON示例

 {
      "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
      "groupon": { 
      "base_info": {
      ·········		            
        "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
      ·········
              }
        }
 }

 注意事项：

 创建/更新填入get_custom_code_mode时，须检查库存数与已经导入code数目的关系，当导入code的数目小于库存数时，会报错。

4.1.2 导入code接口

在自定义code卡券成功创建并且通过审核后，必须将自定义code按照与发券方的约定数量调用导入code接口导入微信后台。

接口说明

开发者可调用该接口将自定义code导入微信卡券后台，由微信侧代理存储并下发code。

注： 1）单次调用接口传入code的数量上限为100个。

2）每一个 code 均不能为空串。

3）导入结束后系统会自动判断提供方设置库存与实际导入code的量是否一致。

4）导入失败支持重复导入，提示成功为止。

接口调用请求说明

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/deposit?access_token=ACCESS_TOKEN

请求参数说明

POST数据

{
   "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
   "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

字段说明

返回数据说明

{
  "errcode":0,
  "errmsg":"ok"
}

字段说明

4.1.3 查询导入code数目接口

接口说明

支持开发者调用该接口查询code导入微信后台成功的数目。

接口调用请求说明

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/getdepositcount?access_token=ACCESS_TOKEN

请求参数说明

POST数据

{
   "card_id" : " pDF3iY0_dVjb_Pua96MMewA96qvA "
}

字段说明

返回数据说明

{
  "errcode":0,
  "errmsg":"ok"，
  "count":123
}

字段说明

4.1.4 核查code接口

为了避免出现导入差错，强烈建议开发者在查询完code数目的时候核查code接口校验code导入微信后台的情况。

接口说明

支持开发者调用该接口查询code导入微信后台的情况。

接口调用请求说明

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/checkcode?access_token=ACCESS_TOKEN

请求参数说明

POST数据

{
   "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
   "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

字段说明

返回数据说明

{
  "errcode":0,
  "errmsg":"ok"
  "exist_code":["11111","22222","33333"],
  "not_exist_code":["44444","55555"]
}

字段说明

4.2 图文消息群发卡券

支持开发者调用该接口获取卡券嵌入图文消息的标准格式代码，将返回代码填入上传图文素材接口中content字段，即可获取嵌入卡券的图文消息素材。

特别注意：目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/mpnews/gethtml?access_token=TOKEN

参数说明

POST数据

{
  "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

返回数据

 {
"errcode":0,
"errmsg":"ok",
"content":"<iframeclass=\"res_iframecard_iframejs_editor_card\"data-src=\"http: \/\/mp.weixin.qq.com\/bizmall\/appmsgcard?action=show&biz=MjM5OTAwODk4MA%3D%3D&cardid=p1Pj9jnXTLf2nF7lccYScFUYqJ0&wechat_card_js=1#wechat_redirect\">"
}

4.3 根据分组群发卡券消息

支持调用该接口向指定分组的用户群发卡券消息。详情见根据分组进行群发接口

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.4 根据OpenID列表群发卡券消息

支持根据OpenID群发原生卡券。订阅号不可用，服务号认证后具备接口权限。详情见根据OpenID列表群发接口

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.5 客服消息下发卡券

支持开发者调用该接口下发卡券。订阅号不可用，服务号认证后可用。详情见客服接口-发消息

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.6 预览接口

支持开发者调用该接口下发卡券。订阅号不可用，服务号认证后可用。详情见预览接口

5 投放渠道数据统计

为方便开发者统计各渠道的卡券投放数据，新增字段outer_str（原outer_id）。将不同设值的outer_str（原outer_id）填入card_ext的json结构中，当用户领取卡券时会将相应设值的outer_id带入领取事件中，推送至开发者服务器。

示例： 在二维码投放方式中设置outer_str为12b

{
"action_name": "QR_CARD", 
"action_info": {
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", 
"code": "198374613512",
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"expire_seconds": "1800"，
"is_unique_code": false ,
"outer_str" : "12b"
  }
 }
}

领取事件XML文件

<xml> <ToUserName><![CDATA[toUser]]></ToUserName> 
<FromUserName><![CDATA[FromUser]]></FromUserName> 
<FriendUserName><![CDATA[FriendUser]]></FriendUserName> 
<CreateTime>123456789</CreateTime> 
<MsgType><![CDATA[event]]></MsgType> 
<Event><![CDATA[user_get_card]]></Event> 
<CardId><![CDATA[cardid]]></CardId> 
<IsGiveByFriend>1</IsGiveByFriend>
<UserCardCode><![CDATA[12312312]]></UserCardCode>
<OuterStr>12b</OuterStr>
</xml>

6 设置测试白名单

接口说明

由于卡券有审核要求，为方便公众号调试，可以设置一些测试帐号，这些帐号可领取未通过审核的卡券，体验整个流程。

开发者注意事项

1.同时支持“openid”、“username”两种字段设置白名单，总数上限为10个。

2.设置测试白名单接口为全量设置，即测试名单发生变化时需调用该接口重新传入所有测试人员的ID.

3.白名单用户领取该卡券时将无视卡券失效状态，请开发者注意。

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/testwhitelist/set?access_token=TOKEN

参数说明

POST数据

{
  "openid": [
      "o1Pj9jmZvwSyyyyyyBa4aULW2mA", 
      "o1Pj9jmZvxxxxxxxxxULW2mA"
               ],
  "username": [
      "afdvvf",
      "abcd"
                ]
 }

参数说明

返回说明

{
   "errcode":0,
   "errmsg":"ok"
}