微信卡券接口

1  须知

   阅读卡券部分接口文档，请务必阅读微信公众平台开发者通用说明文档《微信开发者规范》和《微信公众号接口权限说明》两个章节，以获知微信公众平台接口的基本调用方法、开发者规范以及调用过程中异常问题的处理。

2 申请沙箱测试账号

如果你没有可用的卡券测试账号，可以通过微信接口测试号申请工具申请一个临时测试号用于卡券测试。你可以登录接口测试号申请 通过微信扫一扫获得一个全新的appid(已拥有卡券创建权限，包括朋友的券)和appsecret用于卡券接口调用。

注意：该appid创建的卡券不会被审核通过，仅限于小范围测试，开发者不可用于其他用途。

3 卡券HelloWorld

开发者可以通过debug工具，快速完成创建卡券、投放卡券和核销卡券的流程， 若要深入了解卡券接口，则需要对对应的部分的文档详细阅读。

步骤一 获取access_token

页面地址：http://mp.weixin.qq.com/debug/

接口类型：基础支持

接口列表：获取access_token接口

注意事项：参数填写开发者的appid和secret

点击检查问题，即可返回access_token，access_token的有效期是两小时，两小时之后须重新获取

步骤二 上传卡券logo

页面地址：http://mp.weixin.qq.com/debug/

接口类型：基础支持

接口列表：上传图片素材接口

access_token: 上一步获得的access_token

buffer：你选择的图片

点击检查问题，即可获取图片url，在下一步创建卡劵的参数中需要

步骤三 创建卡券

页面地址：http://mp.weixin.qq.com/debug/

接口类型：卡劵接口

接口列表：创建卡劵接口

access_token:第一步获得的access_token

JSON示例：

{ 
"card": {
  "card_type": "GROUPON",
  "groupon": {
      "base_info": {
          "logo_url": 
"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
          "brand_name":"微信餐厅",
          "code_type":"CODE_TYPE_TEXT",
          "title": "132元双人火锅套餐",
          "sub_title": "周末狂欢必备",
          "color": "Color010",
          "notice": "使用时向服务员出示此券",
          "service_phone": "020-88888888",
          "description": "不可与其他优惠同享\n如需团购券发票，请在消费时向商户提出\n店内均可使用，仅限堂食",
          "date_info": {
              "type": "DATE_TYPE_FIX_TERM",
              "fixed_term": 15 ,
              "fixed_begin_term": 0
          },
          "sku": {
              "quantity": 500000
          },
          "get_limit": 3,
          "use_custom_code": false,
          "bind_openid": false,
          "can_share": true,
        "can_give_friend": true,
          "location_id_list" : [123, 12321, 345345],
          "custom_url_name": "立即使用",
          "custom_url": "http://www.qq.com",
          "custom_url_sub_title": "6个汉字tips",
          "promotion_url_name": "更多优惠",
        "promotion_url": "http://www.qq.com"
      },
      "deal_detail": "以下锅底2选1（有菌王锅、麻辣锅、大骨锅、番茄锅、清补凉锅、酸 菜鱼锅可选）：\n大锅1份 12元\n小锅2份 16元 "}
}
}

注意事项：date_info中用的是Unix时间戳，注意把begin_timestamp修改小于当前时间，end_timestamp修改成今天之后的时间，这样在后面核销卡劵测试才能成功

接口地址：创建卡券接口

步骤四 创建二维码投放

页面地址：http://mp.weixin.qq.com/debug/

接口类型：卡劵接口

接口列表：创建二维码ticket接口

access_token：第一步获得的access_token

JSON示例：

{
"action_name": "QR_CARD", 
"action_info": {
"card": {
"card_id": "po_2DjgJ2zrboM6SzK3qNuje5iWQ", 
   }
 }
}

接口地址：创建二维码接口

步骤五 显示二维码

在上一步的返回中点击字段show_qrcode_url字段中的链接，即可显示卡券领取二维码。

示例：https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQEr8ToAAAAAAAAAASxodHRwOi8vd2V********NjRjVuAAIE3kqwVQMEgDPhAQ==

打开微信扫一扫，然后领取卡劵，如果显示卡劵未通过审核，那么需要下一步设置测试白名单，如果可以领取就忽略第六步。

可扫描以下二维码体验微信卡券：

步骤六 设置测试白名单

页面地址：http://mp.weixin.qq.com/debug/

接口类型：卡劵接口

接口列表：设置测试白名单接口

access_token：第一步获得的access_token

JSON示例：

{ "username":["usr1","usr2"] }

注意事项：其中usr1，sur2是领取卡劵的微信号

接口地址：设置白名单接口

步骤七 核销卡劵

页面地址：http://mp.weixin.qq.com/debug/

接口类型：卡劵接口

接口列表：核销卡劵接口

access_token：第一步获得的access_token

JSON示例：

{ "code"："759733467744" }

注意事项：仅支持审核通过且在有效期内的卡劵 接口地址：核销接口

4 卡券接口概览

微信卡券接口主要围绕卡券的创建、领取、投放以及卡券核销设置了一系列接口，开发者可以根据自己想实现的效果选择合适的接口

进行开发，以实现行业各有特色的卡券应用。

5 卡券术语介绍

以下是卡券开发过程中需要了解的关键概念：

6 开发者注意事项

6.1 微信版本判断

由于微信6.0.2版本后才支持卡券功能模块，低版本用户调用JS-SDK无效。因此，微信团队建议商户通过user agent来确定用户当前的版本号后再调用添加至卡包JS-SDK接口。以iPhone版本为例，可以通过user agent可获取如下版本示例信息：

"Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X)     
AppleWebKit/534.46(KHTML,like Geocko)Mobile/9B206 MicroMessenger/6.0.2 "

其中6.0.2为用户安装的微信版本号。商户可以判定版本号是否高于或者等于6.0.2。

6.2 卡券投放限制

公众号会话环境内仅支持调起该公众号域名下的卡券。未经平台允许不支持在公众号会话内推送其他商户的卡券，否则用户在领券时会提示：“未经制券商家授权，不可投放”。公众号会话外（如朋友圈、对话环境）无此限制。

注意事项

公众号的对话框中发生的行为以及从公众号对话框跳转的网页链接均处于该公众号的会话环境内。

6.3 编码规则

所有API接口POST的数据只支持UTF-8编码，否则会返回报错。

6.4 跳转外链带参数说明

为了满足商户基于卡券本身的扩展诉求，允许卡券内页添加url跳转外链。

在卡券跳转出去的外链均可以带有卡券信息的参数，用于开发者在页面内确认用户身份。

带有的的字段有encrypt_code、card_id、openid、outer_str（仅会员卡）。

注意事项： encrypt_code为加密码码，需调用解码接口获取真实Code码。 假如指定的url为http://www.qq.com，用户点击时，跳转的url则为： http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID&openid=xxxx&outer_str=xxxxx

6.5 联系我们

遇到卡券开发问题，可以通过邮箱weixin_card@foxmail.com 联系我们。也可以加入开发者QQ交流群205482166 512568283，验证请务必说明商家名及业务。

7 卡券资料包下载

开发者可下载卡券接口资料包：

- 创建&签名工具SDK；

- 卡券接口调用流程图；

- 新增接口特性说明；

- SDK for Android；

- SDK for iOS；