##更新日誌版本號碼##

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

核銷目前分為線上核銷和線下核銷兩種類型。 線上核銷指使用者從券面進入一個HTML5網頁後主動銷券的過程，如 微信商城用券、自助核銷

等；

線下核銷 指用戶到店後，出示二維碼或出示串碼，由收銀員完成核銷動作，如
掃碼核銷、機具核銷

等。

#########

1線下核銷

#  1.1 查詢Code介面

#我們強烈建議開發者在調用核銷code接口之前調用查詢code接口，並在核銷之前對非法狀態的code(如轉贈中、已刪除、已核銷等)做出處理。

#介面呼叫請求說明

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

參數說明

更新內容	# 時間 ######################### ####V1.0###############1.規格核銷引導流程，建議開發者呼叫核銷介面前先呼叫查詢code介面查看code狀態#### ########2.最佳化查詢code接口，方便開發者使用，同時相容於舊接口#######	##2015-8-31

參數	是否必須	##說明
	POST資料	是
Json資料	access_token	是

#呼叫介面憑證############# ##

POST資料

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

############參數說明######

參數名稱	必填	##類型	#範例值	描述
code	是	string(20)	110201201245	單張卡券的唯一標準。
card_id		#string(32)	pFS7Fjg8kV1I dDz01r4SQwMkuCKc	##卡券ID代表一類卡券。自訂code卡券必填。
check_consume	#否	bool

############################################################# #######true############是否校驗code核銷狀態，填入true和false時的code異常狀態回傳資料不同。 ################

### ###### ###########################

當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

  1.2 核銷Code介面

消耗code介面是核銷卡券的唯一介面,開發者可以呼叫目前介面將使用者的優惠券進行核銷，該過程不可逆。

介面呼叫請求說明

#

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

参数说明

參數名稱	描述
##errcode	錯誤碼
#errmsg	錯誤訊息
openid	#用戶openid
card_id	卡券ID
#begin_time	開始使用時間
end_time	#結束時間
user_card_status	#目前code對應卡券的狀態 NORMAL          正常  CONSUMED     核銷  EXPIRE         GIFT_TIMEOUT  轉贈逾時  DELETE              ##code未被加入或被轉贈領取的情況則統一報錯：invalid serial code can_consume #是否可以核銷，true為可以核銷，false為不可核銷

參數	是否必須	##說明
	POST資料	是
Json資料	access_token	是

#呼叫介面憑證############# ##

#########POST資料##########

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

範例值

參數名稱	#必填	類型		##類型
描述		#card_id	###### ###否############string(32)###############pFS7Fjg8kV1Id############Dz01r4SQwMkuCKc# #####	卡券ID。建立卡券時use_custom_code填寫true時必填。非自訂Code不必填寫。
code	是	string(20)	1231231	需核銷的Code碼。

#

##########回傳資料### # #####

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

#

注意事項：

1.僅支援核銷有效狀態的卡券，若卡券處於異常狀態，均不可核銷。 （異常狀態包括：卡券刪除、未生效、過期、轉贈中、轉贈退回、失效）

#2.

自訂Code碼（use_custom_code為true）的優惠券，當code被核銷時，必須呼叫此介面。用於將用戶客戶端的code狀態變更。自訂code的卡券呼叫介面時， post資料中需包含card_id，否則報invalid serial code，非自訂code不需上報。 ##########

2 線上核銷

2.1 拉取卡券清單介面（JS-SDK）

微信JS-SDK 只能在微信內建瀏覽器中使用,其他瀏覽器呼叫無效。微信提供chooseCard介面供商家前端網頁呼叫,用於拉起使用者名下該商家篩選條件的卡券內容。點選查看 調起適用於門市的卡券清單並取得使用者選擇清單JS-SDK

2.2 Code解碼介面

code解碼介面支援兩個場景： 

1.商家取得choos_card_info後，將card_id和encrypt_code欄位通過解碼接口，取得真實code。 

2.卡券內跳到外鏈的簽章中會對code進行加密處理，透過呼叫解碼介面取得真實code。

介面呼叫請求說明

#

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

參數說明

參數名稱	描述
##errcode	錯誤碼。
errmsg	錯誤訊息。
openid	#使用者在該公眾號內的唯一身分識別。
card_id	#卡券ID。

參數	是否必須	##說明
	POST資料	是
Json資料	access_token	是

#呼叫介面憑證############# ##

#########POST資料##########

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

  参数说明

參數名稱	必填	##類型	#範例值	描述
#encrypt_code	是	string(128)	XXIzTtMqCxwOaawoE91 VJdsFmv7b 8g0VZIZkqf4mv7b ###8g0VZIZkqf4GpcFz 5ZZ0DVkXdE#######	經過加密的Code碼。

#

#返回資料

###

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

###### ###   參數說明#######

參數名稱	描述
errcode	錯誤碼
#errmsg	錯誤訊息
code	解密後取得的真實Code碼

   注意事項

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

2.如果開發者從url上取得到加密code,請注意先進行urldecode，否則報錯。

3.encrypt_code是卡券的code碼經過加密處理後得到的加密code碼，與code一一對應。

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

#########

2.3 查詢Code介面

#我們強烈建議開發者在呼叫核銷code介面之前呼叫查詢code接口，並在核銷之前對非法狀態的code(如轉贈中、已刪除、已核銷等)做出處理。

2.4 核銷Code介面

#線上核銷普通券的介面同線下核銷普通券的介面一致。