微信公眾號(hào)管理卡券

更新日志

查詢Code接口

查詢code接口可以查詢當(dāng)前code是否可以被核銷并檢查code狀態(tài)。當(dāng)前可以被定位的狀態(tài)為正常、已核銷、轉(zhuǎn)贈(zèng)中、已刪除、已失效和無效code。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/code/get?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

參數(shù)說明

當(dāng)check_consume為true時(shí)返回?cái)?shù)據(jù)

卡券狀態(tài)正常：

 {
  "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"
} 

卡券狀態(tài)異常：

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

當(dāng)check_consume為false時(shí)返回?cái)?shù)據(jù)

卡券狀態(tài)正常：

 {
  "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"
} 

卡券狀態(tài)異常：

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

注意事項(xiàng)：

1.固定時(shí)長有效期會(huì)根據(jù)用戶實(shí)際領(lǐng)取時(shí)間轉(zhuǎn)換，如用戶2013年10月1日領(lǐng)取，固定時(shí)長有效期為90天，即有效時(shí)間為2013年10月1日-12月29日有效。

2.無論check_consume填寫的是true還是false,當(dāng)code未被添加或者code被轉(zhuǎn)贈(zèng)領(lǐng)取是統(tǒng)一報(bào)錯(cuò)：invalid serial code

獲取用戶已領(lǐng)取卡券接口

用于獲取用戶卡包里的，屬于該appid下所有可用卡券，包括正常狀態(tài)和未生效狀態(tài)。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/user/getcardlist?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

  參數(shù)說明

返回?cái)?shù)據(jù)

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

  參數(shù)說明

查看卡券詳情

開發(fā)者可以調(diào)用該接口查詢某個(gè)card_id的創(chuàng)建信息、審核狀態(tài)以及庫存數(shù)量。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/get?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

{
  "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回?cái)?shù)據(jù)

{
  "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折優(yōu)惠券",
        "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": "點(diǎn)擊了解更多",
          "icon_url_list": [
            "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ/0?wx_fmt=jpeg"
          ]
        },
        "share_friends": false
      }
    }
  }
}

base_info字段：

開發(fā)者注意事項(xiàng)

1.對(duì)于部分有特殊權(quán)限的商家，查詢卡券詳情得到的返回可能含特殊接口的字段。

2.由于卡券字段會(huì)持續(xù)更新，實(shí)際返回字段包含但不限于文檔中的字段，建議開發(fā)者開發(fā)時(shí)對(duì)于不理解的字段不做處理，以免出錯(cuò)。

批量查詢卡券列表

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/batchget?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

返回?cái)?shù)據(jù)

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

注意事項(xiàng)：

1.未傳入篩選條件時(shí)，該接口默認(rèn)傳回該商戶名下所有狀態(tài)的卡券；

2.開發(fā)者可以請(qǐng)求之后調(diào)用查看卡券詳情接口確定卡券狀態(tài)；

更改卡券信息接口

接口說明

支持更新所有卡券類型的部分通用字段及特殊卡券（會(huì)員卡、飛機(jī)票、電影票、會(huì)議門票）中特定字段的信息。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/update?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

{
       "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
       "member_card": {        //填寫該cardid相應(yīng)的卡券類型（小寫）。
               "base_info": {
                   "logo_url": "http:\/\/www.supadmin.cn\/uploads\/allimg\/120216\/1_120216214725_1.jpg",
                   "color": "Color010",
                   "notice": "使用時(shí)向服務(wù)員出示此券",
                   "service_phone": "020-88888888",
                   "description": "不可與其他優(yōu)惠同享\n如需團(tuán)購券發(fā)票，請(qǐng)?jiān)谙M(fèi)時(shí)向商戶提出\n店內(nèi)均可使用，
                   僅限堂食\n餐前不可打包，餐后未吃完，可打包\n本團(tuán)購券不限人數(shù)，建議2人使用，
                   超過建議人數(shù)須另收醬料費(fèi)5元/位\n本單謝絕自帶酒水飲料"
                   "location_id_list" : [123, 12321, 345345]
               },
                  "bonus_cleared": "aaaaaaaaaaaaaa",
                  "bonus_rules": "aaaaaaaaaaaaaa",
                  "prerogative": ""
       }
}

通用字段修改：

不同類型卡券專屬字段修改：

特別注意，以下支持更新的字段不在基本信息base_info的結(jié)構(gòu)中。

返回?cái)?shù)據(jù)說明

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

開發(fā)者注意事項(xiàng)注

1. 請(qǐng)開發(fā)者注意需要重新提審的字段，開發(fā)者調(diào)用更新接口時(shí)，若傳入了提審字段則卡券需要重新進(jìn)入審核狀態(tài)；

2. 接口更新方式為覆蓋更新：即開發(fā)者只需傳入需要更改的字段，其他字段無需填入，否則可能導(dǎo)致卡券重新提審；

3. 若開發(fā)者置空某些字段，可直接在更新時(shí)傳“”（空）；

4. 調(diào)用該接口后更改卡券信息后，請(qǐng)務(wù)必調(diào)用查看卡券詳情接口驗(yàn)證是否已成功更改，

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

修改庫存接口

調(diào)用修改庫存接口增減某張卡券的庫存。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/modifystock?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

返回?cái)?shù)據(jù)

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

更改Code接口

為確保轉(zhuǎn)贈(zèng)后的安全性，微信允許自定義Code的商戶對(duì)已下發(fā)的code進(jìn)行更改。 注：為避免用戶疑惑，建議僅在發(fā)生轉(zhuǎn)贈(zèng)行為后（發(fā)生轉(zhuǎn)贈(zèng)后，微信會(huì)通過事件推送的方式告知商戶被轉(zhuǎn)贈(zèng)的卡券Code）對(duì)用戶的Code進(jìn)行更改。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/code/update?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

返回?cái)?shù)據(jù)

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

刪除卡券接口

刪除卡券接口允許商戶刪除任意一類卡券。刪除卡券后，該卡券對(duì)應(yīng)已生成的領(lǐng)取用二維碼、添加到卡包JS API均會(huì)失效。 注意：如用戶在商家刪除卡券前已領(lǐng)取一張或多張?jiān)摽ㄈ琅f有效。即刪除卡券不能刪除已被用戶領(lǐng)取，保存在微信客戶端中的卡券。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/delete?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

{
   "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回?cái)?shù)據(jù)

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

設(shè)置卡券失效接口

為滿足改票、退款等異常情況，可調(diào)用卡券失效接口將用戶的卡券設(shè)置為失效狀態(tài)。 

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/code/unavailable?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

非自定義卡券的請(qǐng)求
{
  "code": "12312313"
}
或自定義code卡券的請(qǐng)求。
{
  "code": "12312313",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回?cái)?shù)據(jù)

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

注意事項(xiàng)：

1.設(shè)置卡券失效的操作不可逆，即無法將設(shè)置為失效的卡券調(diào)回有效狀態(tài)，商家須慎重調(diào)用該接口。

2.商戶調(diào)用失效接口前須與顧客事先告知并取得同意，否則因此帶來的顧客投訴，微信將會(huì)按照《微信運(yùn)營處罰規(guī)則》進(jìn)行處罰。

統(tǒng)計(jì)卡券數(shù)據(jù)

為支持開發(fā)者調(diào)用API查看卡券相關(guān)數(shù)據(jù)，微信卡券團(tuán)隊(duì)封裝數(shù)據(jù)接口并面向具備卡券功能權(quán)限的開發(fā)者開放使用。

開發(fā)者調(diào)用該接口可獲取本商戶下的所有卡券相關(guān)的總數(shù)據(jù)以及指定卡券的相關(guān)數(shù)據(jù)。

拉取卡券概況數(shù)據(jù)接口

接口說明

支持調(diào)用該接口拉取本商戶的總體數(shù)據(jù)情況，包括時(shí)間區(qū)間內(nèi)的各指標(biāo)總量。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/datacube/getcardbizuininfo?access_token=ACCESS_TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

｛
 "begin_date":"2015-06-15",  //請(qǐng)開發(fā)者按示例格式填寫日期，否則會(huì)報(bào)錯(cuò)date format error
 "end_date":"2015-06-30",
 "cond_source":  0
｝

參數(shù)說明：

返回?cái)?shù)據(jù)說明：

{
    "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. 查詢時(shí)間區(qū)間需<=62天，否則報(bào)錯(cuò){errcode: 61501，errmsg: "date range error"}；

2. 傳入時(shí)間格式需嚴(yán)格參照示例填寫”2015-06-15”，否則報(bào)錯(cuò){errcode":61500,"errmsg":"date format error"}

3. 該接口只能拉取非當(dāng)天的數(shù)據(jù)，不能拉取當(dāng)天的卡券數(shù)據(jù)，否則報(bào)錯(cuò)。

獲取免費(fèi)券數(shù)據(jù)接口

接口說明

支持開發(fā)者調(diào)用該接口拉取免費(fèi)券（優(yōu)惠券、團(tuán)購券、折扣券、禮品券）在固定時(shí)間區(qū)間內(nèi)的相關(guān)數(shù)據(jù)。

接口調(diào)用請(qǐng)求說明

http請(qǐng)求方式: POSThttps://api.weixin.qq.com/datacube/getcardcardinfo?access_token=ACCESS_TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

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

參數(shù)說明：

返回?cái)?shù)據(jù)說明 ：

{
    "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. 該接口目前僅支持拉取免費(fèi)券（優(yōu)惠券、團(tuán)購券、折扣券、禮品券）的卡券相關(guān)數(shù)據(jù)，暫不支持特殊票券（電影票、會(huì)議門票、景區(qū)門票、飛機(jī)票）數(shù)據(jù)。

2. 查詢時(shí)間區(qū)間需<=62天，否則報(bào)錯(cuò){"errcode:" 61501，errmsg: "date range error"}；

3. 傳入時(shí)間格式需嚴(yán)格參照示例填寫如”2015-06-15”，否則報(bào)錯(cuò)｛"errcode":"date format error"｝

4. 該接口只能拉取非當(dāng)天的數(shù)據(jù)，不能拉取當(dāng)天的卡券數(shù)據(jù)，否則報(bào)錯(cuò)。

拉取會(huì)員卡概況數(shù)據(jù)接口

接口說明

支持開發(fā)者調(diào)用該接口拉取公眾平臺(tái)創(chuàng)建的會(huì)員卡相關(guān)數(shù)據(jù)。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/datacube/getcardmembercardinfo?access_token=ACCESS_TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

參數(shù)說明：

返回?cái)?shù)據(jù)說明 ：

{
   "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
   ]
}

字段說明：

拉取單張會(huì)員卡數(shù)據(jù)接口

接口說明

支持開發(fā)者調(diào)用該接口拉取API創(chuàng)建的會(huì)員卡數(shù)據(jù)情況

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/datacube/getcardmembercarddetail?access_token=ACCESS_TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

參數(shù)說明：

返回?cái)?shù)據(jù)說明 ：

{
  "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
    }
  ]
}

字段說明：