微信平台开发者创建卡券

1 更新通知

2016年5月15日起，微信卡券团队对会员卡能力进行全面升级。在原有能力基础上进行以下能力升级，旨在帮助商家更好地进行会员管理。

-强化客户端一级入口：会员到店即用，快速定位商户会员卡；

-自定义卡面能力：开发者可以根据会员身份设置不同的卡面背景；

-门店扫码方案：新用户到店扫码领卡，老用户到店扫码快速打开会员卡，实现会员点餐、买单等多种功能

-支付即会员：支持开发者设置微信支付后为用户下发领卡消息，顾客支付即会员，快速拉新；

-运营策略调整：会员卡新增开放类目限制，自4月20日起，仅限会员卡类目内的商户新建会员卡，原有会员卡不受影响，详情请见：《会员卡公告》

2 创建卡券

2.1 接口调用顺序

2.2 接口调用说明

在进行卡券创建前，请开发者根据自身业务场景确定以下几点

2.2.1 明确卡券ID与Code码的区别

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

例如： 创建50元代金券，获取一个卡券ID（card_id）用于投放，并设置库存100万。顾客小A，领取到商户投放的50元代金券时，券面

上会有一个唯一的标识码，即code码。每个用户的code码都不相同，所以该商户最终卡券发放完毕时，微信将会派发100万个不同的code码给用户。

2.2.2 是否自定义Code码

微信卡券的Code码可由微信后台随机分配，同时支持商户自定义，两者的区别如下：

备注：自定义code码的开发者若想要获得和非自定义code商户相同的群发卡券、客服消息派发卡券的能力。可以通过导入自定义code接口将非定义code导入到微信服务器，若仅在h5投放则无须导入，导入code后code由微信随机下发，不可指定。

2.2.3 选择合适的码型

商户可以根据自身的业务模式和能支持的核销方式，选择合适的券面码型，并在创建卡券填入code_type字段。

举例：若A商户选了二维码类型的卡券，则A商户的核销员在核销时可以通过手机商户助手扫码核销卡券；若B商户选择了仅code类型的

码型，则其核销员就只能通过输入串号的方式核销卡券。

2.2.4 记录用户领券行为

记录用户领券行为有多种方式：

1. 用户领取卡券后会推送事件通知开发者，领取卡券事件中包含卡券ID、Code码、领取人OpenID、转赠人OpenID。卡券被核销时同样会推送事件，详情见卡券事件通知。

2. 调用查询Code接口获取该Code码的状态（是否被领取、核销、删除），若Code码被用户领取且处于有效状态，可获取领券人OpenID。

3. 从卡券详情页跳转外部链接时，微信后台会自动带上卡券ID、Code码等信息，详情见跳转外链带参数说明。

4. 在卡券投放接口中加入场景字段outer_str，该字段值会在用户领取时伴随事件通知商户。

例如：创建二维码接口时设置outer_str为1，添加卡券JS-SDK时设置为2，则可通过对领取事件的分析得出两个不同投放渠道带来的领券效果，及时调整投放策略。

2.2.5 活用自定义入口

为满足商户功能扩展的需求，新增可自定义两个卡券内的入口，支持跳转到商户自定义的HTML5网页。 

三个自定义入口基于不同的场景定位设置，区别如下：

不同入口示例：

2.3 步骤一：上传卡券图片素材

  为了保证商户的卡券在用户的微信内能快速、稳定地加载出图片素材，我们强烈建议开发者将商户的卡券素材先调用接口导入微信

CDN。

2.3.1 上传图片接口

开发者需调用该接口上传商户图标至微信服务器，获取相应logo_url/icon_list/image_url，用于卡券创建。

开发者注意事项

1.上传的图片限制文件大小限制1MB，仅支持JPG、PNG格式。

2.调用接口获取图片url仅支持在微信相关业务下使用。

接口调用请求说明

HTTP请求方式: POST/FROM
URL:https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN

参数说明

请求数据

调用示例（使用curl命令，用FORM表单方式上传一个图片）：
curl –F
buffer=@test.jpg

 返回数据

返回正确的示例：
{"url":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"}

返回错误的示例
{"errcode":40009,"errmsg":"invalid image size"}

   参数说明

2.4 步骤二：设置卡券适用门店

请点击查看微信门店接口文档，获取门店 ID 后填入创建卡券接口中的相应字段 location_id_list，即可设置该卡券的适用门店。

2.5 步骤三：选取卡券背景颜色

选择适用色值，在步骤四：创建卡券中将颜色名（如Color010）填入color字段。

目前微信提供包括以上十种色值的共计十四种色值供开发者使用。

2.6 步骤四：创建卡券

创建卡券接口是微信卡券的基础接口，用于创建一类新的卡券，获取card_id，创建成功并通过审核后，商家可以通过文档提供的其他接口将卡券下发给用户，每次成功领取，库存数量相应扣除。

开发者须知

1.需自定义Code码的商家必须在创建卡券时候，设定use_custom_code为true，且在调用投放卡券接口时填入指定的Code码。指定OpenID同理。特别注意：在公众平台创建的卡券均为非自定义Code类型。

2.can_share字段指领取卡券原生页面是否可分享，建议指定Code码、指定OpenID等强限制条件的卡券填写false。

3.特别注意：编码方式仅支持使用UTF-8，否则会报错。

4.创建成功后该卡券会自动提交审核，审核结果将通过事件通知商户。开发者可调用设置白名单接口设置用户白名单，领取未通过审核的卡券，测试整个卡券的使用流程。

接口调用请求说明

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

参数说明

POST数据示例

{
  "card": {
      "card_type": "GROUPON",
      "groupon": {
          "base_info": {
              "logo_url":  "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
              "brand_name": "微信餐厅",
              "code_type": "CODE_TYPE_TEXT",
              "title": "132元双人火锅套餐",
              "color": "Color010",
              "notice": "使用时向服务员出示此券",
              "service_phone": "020-88888888",
              "description": "不可与其他优惠同享\n如需团购券发票，请在消费时向商户提出\n店内均可使用，仅限堂食",
              "date_info": {
                  "type": "DATE_TYPE_FIX_TIME_RANGE",
                  "begin_timestamp": 1397577600,
                  "end_timestamp": 1472724261
              },
              "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
              ],
              "center_title": "顶部居中按钮",
              "center_sub_title": "按钮下方的wording",
              "center_url": "www.qq.com",
              "custom_url_name": "立即使用",
              "custom_url": "http://www.qq.com",
              "custom_url_sub_title": "6个汉字tips",
              "promotion_url_name": "更多优惠",
              "promotion_url": "http://www.qq.com",
              "source": "大众点评"
          },
           "advanced_info": {
               "use_condition": {
                   "accept_category": "鞋类",
                   "reject_category": "阿迪达斯",
                   "can_use_with_other_discount": true
               },
               "abstract": {
                   "abstract": "微信餐厅推出多种新季菜品，期待您的光临",
                   "icon_url_list": [
                       "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj  piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                   ]
               },
               "text_image_list": [
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品精选食材，以独特的烹饪方法，最大程度地刺激食 客的味蕾"
                   },
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品迎合大众口味，老少皆宜，营养均衡"
                   }
               ],
               "time_limit": [
                   {
                       "type": "MONDAY",
                       "begin_hour":0,
                       "end_hour":10,
                       "begin_minute":10,
                       "end_minute":59
                   },
                   {
                       "type": "HOLIDAY"
                   }
               ],
               "business_service": [
                   "BIZ_SERVICE_FREE_WIFI",
                   "BIZ_SERVICE_WITH_PET",
                   "BIZ_SERVICE_FREE_PARK",
                   "BIZ_SERVICE_DELIVER"
               ]
           },
          "deal_detail": "以下锅底2选1（有菌王锅、麻辣锅、大骨锅、番茄锅、清补 凉锅、酸菜鱼锅可选）：\n大锅1份 12元\n小锅2份 16元 "
      }
  }
}

字段示图 

团购券

JSON示例

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "deal_detail": "示例"
     }
 }
}

代金券

JSON示例

{
 "card": {
     "card_type": "CASH",
     "cash": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "least_cost": 1000,
         "reduce_cost": 100,
     }
 }
}

折扣券

JSON示例：

{
 "card": {
     "card_type": "DISCOUNT",
     "discount": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "discount": 30
     }
   }
}

兑换券

JSON示例

{
"card": {
    "card_type": "GIFT",
    "gift": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        "gift":"可兑换音乐木盒一个"
    }
  }
}

优惠券

JSON示例

{
"card": {
    "card_type": "GENERAL_COUPON",
    "general_coupon": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        "default_detail":"优惠券专用，填写优惠详情"
    }
  }
}

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

  base_info（卡券基础信息）字段-必填字段

 base_info（卡券基础信息）字段-非必填字段

Advanced_info（卡券高级信息）字段

注意事项：

1.高级字段为商户额外展示信息字段，非必填,但是填入某些结构体后，须填充完整方可显示：如填入text_image_list结构体

时，须同时传入image_url和text，否则也会报错；
2.填入时间限制字段（time_limit）,只控制显示，不控制实际使用逻辑，不填默认不显示

3.创建卡券时，开发者填入的时间戳须注意时间戳溢出时间，设置的时间戳须早于2038年1月19日

4.预存code模式的卡券须设置quantity为0，导入code后方可增加库存

返回说明

数据示例：

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

2.8 跳转外链带参数说明

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

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

3 设置快速买单

功能介绍

微信卡券买单功能是微信卡券的一项新的能力，可以方便消费者买单时，直接录入消费金额，自动使用领到的优惠（券或卡）抵扣，并拉起微信支付快速完成付款。

微信买单（以下统称微信买单）的好处：

1、无需商户具备微信支付开发能力，即可完成订单生成，与微信支付打通。

2、可以通过手机公众号、电脑商户后台，轻松操作收款并查看核销记录，交易对账，并支持离线下载。

3、支持会员营销，二次营销，如会员卡交易送积分，抵扣积分，买单后赠券等。

开通指引

步骤一：申请开通内测白名单权限后，开发者可以登录微信公众平台mp.weixin.qq.com，进入【卡券功能】-【卡券概况】，点击查看资料和权限

步骤二：在高级权限区，有标注微信买单的权限状态，商户先需要开通微信支付，并为收款门店配置核销员，才能激活申请权限。未获得权限时，点击“申请“，开通买单权限

步骤三：为收款门店配置收款员“或直接点击”卡券核销“，可前往添加门店核销员，便于后续接收结算通知。

3.1 设置买单接口

买单接口说明

创建卡券之后，开发者可以通过设置微信买单接口设置该card_id支持微信买单功能。值得开发者注意的是，设置买单的card_id必须已经配置了门店，否则会报错。

接口调用请求说明

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

参数说明

POST数据

{
  “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“,
  “is_open”: true
}

字段说明

返回数据

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

字段说明

注意事项：

1.设置快速买单的卡券须支持至少一家有核销员门店，否则无法设置成功；

2.若该卡券设置了center_url（居中使用跳转链接）,须先将该设置更新为空后再设置自快速买单方可生效。

3.2 买单事件推送

微信买单完成时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：

<xml>
<ToUserName><![CDATA[gh_e2243xxxxxxx]]></ToUserName>
<FromUserName><![CDATA[oo2VNuOUuZGMxxxxxxxx]]></FromUserName>
<CreateTime>1442390947</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_pay_from_pay_cell]]></Event>
<CardId><![CDATA[po2VNuCuRo-8sxxxxxxxxxxx]]></CardId>
<UserCardCode><![CDATA[38050000000]]></UserCardCode>
<TransId><![CDATA[10022403432015000000000]]></TransId>
<LocationId>291710000</LocationId>
<Fee><![CDATA[10000]]></Fee>
<OriginalFee><![CDATA[10000]]> </OriginalFee>
</xml>

4 设置自助核销

功能介绍

自助核销与扫码/输码核销互为补充，卡券商户助手通过扫码/输码完成核销的同时，也确保了用券的真实性，适合有强对账需求的商户使用；而自助核销由用户发起，全程由用户操作，适合对账需求不强的商户使用。

目前，自助核销可能适合以下场景使用：

1.不允许店员上班期间带手机；

2.高峰期店内人流量大，扫码/输码核销速度不能满足短时需求；

3.会议入场，短时有大量核销任务；

4.1 设置自助核销接口

接口说明

创建卡券之后，开发者可以通过设置微信买单接口设置该card_id支持自助核销功能。值得开发者注意的是，设置自助核销的card_id必须已经配置了门店，否则会报错。

接口调用请求说明

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

参数说明

POST数据

{
  “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“,
  “is_open”: true
}

字段说明

返回数据

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

字段说明

注意事项：

1.设置自助核销的卡券须支持至少一家门店，否则无法设置成功；

2.若该卡券设置了center_url（居中使用跳转链接）,须先将该设置更新为空后再设置自助核销功能方可生效。

5 接口调试工具

开发者可以通过卡券创建接口在线调试工具进行卡券创建HelloWorld。获取到access_token后，开发者可以将要POST的JSON数据贴至接口调试工具中，获得Card_id以进行下一步投放动作。