更新日志

該部分主要介紹開(kāi)發(fā)者如何在用戶(hù)使用券之后讓卡券從用戶(hù)的微信客戶(hù)端消失的過(guò)程，這個(gè)步驟稱(chēng)為核銷(xiāo)。

核銷(xiāo)目前分為線(xiàn)上核銷(xiāo)和線(xiàn)下核銷(xiāo)兩種類(lèi)型。

線(xiàn)上核銷(xiāo)指用戶(hù)從券面進(jìn)入一個(gè)HTML5網(wǎng)頁(yè)后主動(dòng)銷(xiāo)券的過(guò)程，如微信商城用券、自助核銷(xiāo)等；

線(xiàn)下核銷(xiāo)指用戶(hù)到店后，出示二維碼或者出示串碼，由收銀員完成核銷(xiāo)動(dòng)作，如掃碼核銷(xiāo)、機(jī)具核銷(xiāo)等。

1線(xiàn)下核銷(xiāo)

  1.1 查詢(xún)Code接口

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

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)

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

參數(shù)說(shuō)明

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

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

  1.2 核銷(xiāo)Code接口

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

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)

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

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

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

注意事項(xiàng)：

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

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

2 線(xiàn)上核銷(xiāo)

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

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

2.2 Code解碼接口

code解碼接口支持兩種場(chǎng)景： 

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

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

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)

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

  參數(shù)說(shuō)明

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

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

   參數(shù)說(shuō)明

   注意事項(xiàng)

1.只能解碼本公眾號(hào)卡券獲取的加密code。 

2.開(kāi)發(fā)者若從url上獲取到加密code,請(qǐng)注意先進(jìn)行urldecode，否則報(bào)錯(cuò)。

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

4.開(kāi)發(fā)者只能解密本公眾號(hào)的加密code，否則報(bào)錯(cuò)。

2.3 查詢(xún)Code接口

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

2.4 核銷(xiāo)Code接口

線(xiàn)上核銷(xiāo)普通券的接口同線(xiàn)下核銷(xiāo)普通券的接口一致。