微信公众号管理卡券

更新日志

查询Code接口

查询code接口可以查询当前code是否可以被核销并检查code状态。当前可以被定位的状态为正常、已核销、转赠中、已删除、已失效和无效code。

接口调用请求说明

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

参数说明

POST数据

{
   "card_id" : "card_id_123+",
   "code" : "123456789",
   "check_consume" : true
}

参数说明

当check_consume为true时返回数据

卡券状态正常：

 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "user_card_status": "NORMAL"
} 

卡券状态异常：

{
 "errcode": 40127,
 "errmsg": "invalid user-card status! Hint: the card was given to user, but may be deleted or set unavailable ! hint: [iHBD40040ent3]"
}

当check_consume为false时返回数据

卡券状态正常：

 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "user_card_status": "NORMAL"
} 

卡券状态异常：

 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjnK8NLbWgwMgfMtnj3gaglw",
    "begin_time": 1457625600,
    "end_time": 1460217599
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": false,
  "user_card_status": "GIFTING"
} 

注意事项：

1.固定时长有效期会根据用户实际领取时间转换，如用户2013年10月1日领取，固定时长有效期为90天，即有效时间为2013年10月1日-12月29日有效。

2.无论check_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错：invalid serial code

获取用户已领取卡券接口

用于获取用户卡包里的，属于该appid下所有可用卡券，包括正常状态和未生效状态。

接口调用请求说明

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

参数说明

POST数据

{
  "openid": "12312313",
  "card_id": "xxxxxxxxxx"
}

  参数说明

返回数据

 {
"errcode":0,
"errmsg":"ok",
"card_list": [
      {"code": "xxx1434079154", "card_id": "xxxxxxxxxx"},
      {"code": "xxx1434079155", "card_id": "xxxxxxxxxx"}
      ]，
       "has_share_card": true
}

  参数说明

查看卡券详情

开发者可以调用该接口查询某个card_id的创建信息、审核状态以及库存数量。

接口调用请求说明

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

参数说明

POST数据

{
  "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回数据

{
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_type": "DISCOUNT",
    "discount": {
      "base_info": {
        "id": "pbLatjnP97_F9PudzBARQhn7xR7A",
        "logo_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q/0?wx_fmt=png",
        "code_type": "CODE_TYPE_NONE",
        "brand_name": "微信餐厅",
        "title": "9折优惠券",
        "date_info": {
          "type": "DATE_TYPE_FIX_TERM",
          "fixed_term": 30,
          "fixed_begin_term": 0
        },
        "color": "#10AD61",
        "notice": "到店使用",
        "description": "",
        "location_id_list": [
          218384742,
          402521653,
          402521608
        ],
        "get_limit": 3,
        "can_share": true,
        "can_give_friend": true,
        "status": "CARD_STATUS_VERIFY_OK",
        "sku": {
          "quantity": 100096,
          "total_quantity": 100100
        },
        "create_time": 1457525546,
        "update_time": 1457526240,
        "area_code_list": []
      },
      "discount": 10,
      "advanced_info": {
        "time_limit": [
          {
            "type": "MONDAY"
          },
          {
            "type": "TUESDAY"
          }
        ],
        "text_image_list": [],
        "business_service": [],
        "consume_share_card_list": [],
        "abstract": {
          "abstract": "点击了解更多",
          "icon_url_list": [
            "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ/0?wx_fmt=jpeg"
          ]
        },
        "share_friends": false
      }
    }
  }
}

base_info字段：

开发者注意事项

1.对于部分有特殊权限的商家，查询卡券详情得到的返回可能含特殊接口的字段。

2.由于卡券字段会持续更新，实际返回字段包含但不限于文档中的字段，建议开发者开发时对于不理解的字段不做处理，以免出错。

批量查询卡券列表

接口调用请求说明

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

参数说明

POST数据

{
  "offset": 0,
  "count": 10, 
  "status_list": ["CARD_STATUS_VERIFY_OK", "CARD_STATUS_DISPATCH"]
}

返回数据

{
  "errcode":0,
  "errmsg":"ok",
  "card_id_list":["ph_gmt7cUVrlRk8swPwx7aDyF-pg"],
  "total_num":1
}

注意事项：

1.未传入筛选条件时，该接口默认传回该商户名下所有状态的卡券；

2.开发者可以请求之后调用查看卡券详情接口确定卡券状态；

更改卡券信息接口

接口说明

支持更新所有卡券类型的部分通用字段及特殊卡券（会员卡、飞机票、电影票、会议门票）中特定字段的信息。

接口调用请求说明

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

参数说明

POST数据

{
       "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
       "member_card": {        //填写该cardid相应的卡券类型（小写）。
               "base_info": {
                   "logo_url": "http://www.supadmin.cn/uploads/allimg/120216/1_120216214725_1.jpg",
                   "color": "Color010",
                   "notice": "使用时向服务员出示此券",
                   "service_phone": "020-88888888",
                   "description": "不可与其他优惠同享n如需团购券发票，请在消费时向商户提出n店内均可使用，
                   仅限堂食n餐前不可打包，餐后未吃完，可打包n本团购券不限人数，建议2人使用，
                   超过建议人数须另收酱料费5元/位n本单谢绝自带酒水饮料"
                   "location_id_list" : [123, 12321, 345345]
               },
                  "bonus_cleared": "aaaaaaaaaaaaaa",
                  "bonus_rules": "aaaaaaaaaaaaaa",
                  "prerogative": ""
       }
}

通用字段修改：

不同类型卡券专属字段修改：

特别注意，以下支持更新的字段不在基本信息base_info的结构中。

返回数据说明

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

开发者注意事项注

1. 请开发者注意需要重新提审的字段，开发者调用更新接口时，若传入了提审字段则卡券需要重新进入审核状态；

2. 接口更新方式为覆盖更新：即开发者只需传入需要更改的字段，其他字段无需填入，否则可能导致卡券重新提审；

3. 若开发者置空某些字段，可直接在更新时传“”（空）；

4. 调用该接口后更改卡券信息后，请务必调用查看卡券详情接口验证是否已成功更改，

5.未列出的字段不支持修改更新。

修改库存接口

调用修改库存接口增减某张卡券的库存。

接口调用请求说明

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

参数说明

POST数据

{
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"increase_stock_value": 1231231,
"reduce_stock_value": 1231231
}

返回数据

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

更改Code接口

为确保转赠后的安全性，微信允许自定义Code的商户对已下发的code进行更改。 注：为避免用户疑惑，建议仅在发生转赠行为后（发生转赠后，微信会通过事件推送的方式告知商户被转赠的卡券Code）对用户的Code进行更改。

接口调用请求说明

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

参数说明

POST数据

{
  "code": "12345678",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
  "new_code": "3495739475"
}

返回数据

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

删除卡券接口

删除卡券接口允许商户删除任意一类卡券。删除卡券后，该卡券对应已生成的领取用二维码、添加到卡包JS API均会失效。 注意：如用户在商家删除卡券前已领取一张或多张该卡券依旧有效。即删除卡券不能删除已被用户领取，保存在微信客户端中的卡券。

接口调用请求说明

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

参数说明

POST数据

{
   "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回数据

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

设置卡券失效接口

为满足改票、退款等异常情况，可调用卡券失效接口将用户的卡券设置为失效状态。 

接口调用请求说明

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

参数说明

POST数据

非自定义卡券的请求
{
  "code": "12312313"
}
或自定义code卡券的请求。
{
  "code": "12312313",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回数据

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

注意事项：

1.设置卡券失效的操作不可逆，即无法将设置为失效的卡券调回有效状态，商家须慎重调用该接口。

2.商户调用失效接口前须与顾客事先告知并取得同意，否则因此带来的顾客投诉，微信将会按照《微信运营处罚规则》进行处罚。

统计卡券数据

为支持开发者调用API查看卡券相关数据，微信卡券团队封装数据接口并面向具备卡券功能权限的开发者开放使用。

开发者调用该接口可获取本商户下的所有卡券相关的总数据以及指定卡券的相关数据。

拉取卡券概况数据接口

接口说明

支持调用该接口拉取本商户的总体数据情况，包括时间区间内的各指标总量。

接口调用请求说明

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

请求参数说明

POST数据

｛
 "begin_date":"2015-06-15",  //请开发者按示例格式填写日期，否则会报错date format error
 "end_date":"2015-06-30",
 "cond_source":  0
｝

参数说明：

返回数据说明：

{
    "list": [
       {
           "ref_date": "2015-06-23",
           "view_cnt": 1,
           "view_user": 1,
           "receive_cnt": 1,
           "receive_user": 1,
           "verify_cnt": 0,
           "verify_user": 0,
           "given_cnt": 0,
           "given_user": 0,
           "expire_cnt": 0,
           "expire_user": 0
       }
   ] 
}

字段说明：

特别注意： 

1. 查询时间区间需<=62天，否则报错{errcode: 61501，errmsg: "date range error"}；

2. 传入时间格式需严格参照示例填写”2015-06-15”，否则报错{errcode":61500,"errmsg":"date format error"}

3. 该接口只能拉取非当天的数据，不能拉取当天的卡券数据，否则报错。

获取免费券数据接口

接口说明

支持开发者调用该接口拉取免费券（优惠券、团购券、折扣券、礼品券）在固定时间区间内的相关数据。

接口调用请求说明

http请求方式: POSThttps://api.weixin.qq.com/datacube/getcardcardinfo?access_token=ACCESS_TOKEN

请求参数说明

POST数据

｛
 "begin_date":"2015-06-15",
 "end_date":"2015-06-30",
 "cond_source": 0,
 "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE"
｝

参数说明：

返回数据说明 ：

{
    "list": [
       {
           "ref_date": "2015-06-23",
           "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE",
           "card_type":3,
           "view_cnt": 1,
           "view_user": 1,
           "receive_cnt": 1,
           "receive_user": 1,
           "verify_cnt": 0,
           "verify_user": 0,
           "given_cnt": 0,
           "given_user": 0,
           "expire_cnt": 0,
           "expire_user": 0
       }
   ]
}

字段说明：

特别注意：

1. 该接口目前仅支持拉取免费券（优惠券、团购券、折扣券、礼品券）的卡券相关数据，暂不支持特殊票券（电影票、会议门票、景区门票、飞机票）数据。

2. 查询时间区间需<=62天，否则报错{"errcode:" 61501，errmsg: "date range error"}；

3. 传入时间格式需严格参照示例填写如”2015-06-15”，否则报错｛"errcode":"date format error"｝

4. 该接口只能拉取非当天的数据，不能拉取当天的卡券数据，否则报错。

拉取会员卡概况数据接口

接口说明

支持开发者调用该接口拉取公众平台创建的会员卡相关数据。

接口调用请求说明

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

参数说明

POST数据

｛
 "begin_date":"2015-06-15",
 "end_date":"2015-06-30",
 "cond_source": 0
｝

参数说明：

返回数据说明 ：

{
   "list": [
       {
           "ref_date": "2015-06-23",
           "view_cnt": 0,
              "view_user": 0,
              "receive_cnt": 0,
              "receive_user": 0,
              "active_user": 0,
              "verify_cnt": 0,
              "verify_user": 0,
              "total_user": 86,
              "total_receive_user": 95
   ]
}

字段说明：

拉取单张会员卡数据接口

接口说明

支持开发者调用该接口拉取API创建的会员卡数据情况

接口调用请求说明

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

参数说明

POST数据

｛
 "begin_date":"2015-06-15",
 "end_date":"2015-06-30",
 "card_id":"xxxxxxxxxxxxxxxx"
｝

参数说明：

返回数据说明 ：

{
  "list": [
    {
      "ref_date": "2016-07-06",
      "merchanttype": 2,
      "cardid": "p4WkzwieuDBzzn7Jed6SBO0-ZgaU",
      "submerchantid": 0,
      "view_cnt": 2,
      "view_user": 1,
      "receive_cnt": 1,
      "receive_user": 1,
      "verify_cnt": 0,
      "verify_user": 0,
      "active_cnt": 1,
      "active_user": 1,
      "total_user": 249,
      "new_user": 0,
      "payOriginalFee": 0,
      "fee": 0
    }
  ]
}

字段说明：