核銷微信平臺的卡券

更新日志

該部分主要介紹開發(fā)者如何在用戶使用券之后讓卡券從用戶的微信客戶端消失的過程，這個步驟稱為核銷。

核銷目前分為線上核銷和線下核銷兩種類型。

線上核銷指用戶從券面進(jìn)入一個HTML5網(wǎng)頁后主動銷券的過程，如微信商城用券、自助核銷等；

線下核銷指用戶到店后，出示二維碼或者出示串碼，由收銀員完成核銷動作，如掃碼核銷、機(jī)具核銷等。

1線下核銷

  1.1 查詢Code接口

我們強(qiáng)烈建議開發(fā)者在調(diào)用核銷code接口之前調(diào)用查詢code接口，并在核銷之前對非法狀態(tài)的code(如轉(zhuǎn)贈中、已刪除、已核銷等)做出處理。

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

HTTP請求方式: 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ù)據(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ù)據(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.固定時長有效期會根據(jù)用戶實(shí)際領(lǐng)取時間轉(zhuǎn)換，如用戶2013年10月1日領(lǐng)取，固定時長有效期為90天，即有效時間為2013年10月1日-12月29日有效。

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

  1.2 核銷Code接口

消耗code接口是核銷卡券的唯一接口,開發(fā)者可以調(diào)用當(dāng)前接口將用戶的優(yōu)惠券進(jìn)行核銷，該過程不可逆。

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

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

參數(shù)說明

POST數(shù)據(jù)

非自定義Code卡券的請求
{
  "code": "12312313"
}
或自定義Code卡券的請求
{
  "code": "12312313",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回數(shù)據(jù) 

 {
"errcode":0,
"errmsg":"ok",
"card":{"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"},
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}

注意事項(xiàng)：

1.僅支持核銷有效狀態(tài)的卡券，若卡券處于異常狀態(tài)，均不可核銷。（異常狀態(tài)包括：卡券刪除、未生效、過期、轉(zhuǎn)贈中、轉(zhuǎn)贈退回、失效）

2.自定義Code碼（use_custom_code為true）的優(yōu)惠券，在code被核銷時，必須調(diào)用此接口。用于將用戶客戶端的code狀態(tài)變更。自定義code的卡券調(diào)用接口時， post數(shù)據(jù)中需包含card_id，否則報invalid serial code，非自定義code不需上報。

2 線上核銷

2.1 拉取卡券列表接口（JS-SDK）

微信 JS-SDK 只能在微信內(nèi)置瀏覽器中使用,其他瀏覽器調(diào)用無效。微信提供chooseCard接口供商戶前端網(wǎng)頁調(diào)用,用于拉起用戶名下該商家篩選條件的卡券內(nèi)容。 點(diǎn)擊查看 調(diào)起適用于門店的卡券列表并獲取用戶選擇列表JS-SDK

2.2 Code解碼接口

code解碼接口支持兩種場景： 

1.商家獲取choos_card_info后，將card_id和encrypt_code字段通過解碼接口，獲取真實(shí)code。 

2.卡券內(nèi)跳轉(zhuǎn)外鏈的簽名中會對code進(jìn)行加密處理，通過調(diào)用解碼接口獲取真實(shí)code。

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

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

參數(shù)說明

POST數(shù)據(jù)

{
  "encrypt_code":"XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"
}

  參數(shù)說明

返回數(shù)據(jù)

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

   參數(shù)說明

   注意事項(xiàng)

1.只能解碼本公眾號卡券獲取的加密code。 

2.開發(fā)者若從url上獲取到加密code,請注意先進(jìn)行urldecode，否則報錯。

3.encrypt_code是卡券的code碼經(jīng)過加密處理得到的加密code碼，與code一一對應(yīng)。

4.開發(fā)者只能解密本公眾號的加密code，否則報錯。

2.3 查詢Code接口

我們強(qiáng)烈建議開發(fā)者在調(diào)用核銷code接口之前調(diào)用查詢code接口，并在核銷之前對非法狀態(tài)的code(如轉(zhuǎn)贈中、已刪除、已核銷等)做出處理。

2.4 核銷Code接口

線上核銷普通券的接口同線下核銷普通券的接口一致。