微信卡券接口

1须知

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

 

2申请沙箱测试账号

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

注意：该appid创建的卡券不会被审核通过，仅白名单内用户可以领取，用于小范围测试，开发者不可用于其他用途。

 

3卡券HelloWorld

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

步骤一 获取access_token

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

接口类型：基础支持

接口列表：获取access_token接口

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

点击检查问题，即可返回access_token，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 卡券术语介绍

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

参数名	描述
card_id	卡券ID。一个卡券ID对应一类卡券，包含了相应库存数量的Code码。
code	卡券Code码。一张卡券的唯一标识，核销卡券时使用此串码，支持商户自定义。
openid	用户在该公众号下的唯一身份。
access_token	调用接口的凭证，有效时间为7200s，每次请求刷新， 通过 获取access_token接口 获取,开发者需妥善保存并建立缓存机制。
jsapi_ticket	调用微信内网页调用微信原生功能的JS-SDK接口须使用的签名票据，详情见: JS-SDK部分
api_ticket	调用微信卡券接口时签名的临时票据，有效时间为7200s， 7200s内重复请求保持不变，通过 获取api_ticket接口 获取。
card_ext	可扩展的卡券的附加信息，用于投放卡券是附带卡券基本信息。
outer_str	领券渠道的场景值 。支持商户自定义场景值填入card_ext进行卡券投放， 当用户领取时会将相应场景值通过事件通知商户。
事件推送	在 卡券通过审核、卡券被领取、卡券被删除、卡券被核销 时， 均会推送事件通知开发者，接收地址为公众平台开发者中心填写的服务器URL。
自定义入口	通过API创建卡券支持商户自定义卡券详情页跳转外链的单元,用户跳转至该链接时会在链接后缀有卡券的card_id和加密的code。

 

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交流群653614989（七群） 642762748（八群），验证请务必说明商家名及业务。

 

7 卡券资料包下载

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

• 创建&签名工具SDK；

• 卡券接口调用流程图；

• 新增接口特性说明；

• SDK for Android；

• SDK for iOS；