微信搖一搖紅包介紹說明

• 1 搖一搖紅包說明
• 2 紅包預(yù)下單接口
• 3 創(chuàng)建紅包活動(dòng)
• 4 錄入紅包信息
• 5 設(shè)置紅包活動(dòng)抽獎(jiǎng)開關(guān)
• 6 紅包JSAPI
• 7 紅包綁定用戶事件通知
• 8 紅包查詢接口

搖一搖紅包說明

功能說明

搖一搖周邊紅包接口是為線下商戶提供的發(fā)紅包功能。用戶可以在商家門店等線下場(chǎng)所通過搖一搖周邊領(lǐng)取商家發(fā)放的紅包，在線上轉(zhuǎn)發(fā)分享無(wú)效。

開發(fā)者可通過接口開發(fā)搖一搖紅包功能，特點(diǎn)包括：

1. 可選擇使用模板加載頁(yè)或自定義Html5頁(yè)面調(diào)起微信原生紅包頁(yè)面(詳見創(chuàng)建紅包活動(dòng)中use_template字段，1為使用模板，2為使用自定義Html5頁(yè)面)
2. 原生紅包頁(yè)面拆紅包，無(wú)需通過公眾號(hào)消息下發(fā)
3. 提供關(guān)注公眾號(hào)能力，用戶可自行選擇是否關(guān)注(裂變紅包分享時(shí)無(wú)效)
4. 完成頁(yè)面可配置跳轉(zhuǎn)鏈接，可跳轉(zhuǎn)商戶的其他自定義Html5頁(yè)面
5. 同一個(gè)用戶在單個(gè)紅包活動(dòng)中只能領(lǐng)取1次紅包

用戶側(cè)交互流程

 

紅包組件接口調(diào)用流程

1. 申請(qǐng)紅包接口權(quán)限：登錄搖一搖周邊商戶后臺(tái)https://zb.weixin.qq.com ,進(jìn)入開發(fā)者支持，申請(qǐng)開通搖一搖紅包組件接口;
2. 紅包預(yù)下單：調(diào)用微信支付的api進(jìn)行紅包預(yù)下單，告知需要發(fā)放的紅包金額，人數(shù)，生成紅包ticket；
3. 創(chuàng)建活動(dòng)并錄入紅包信息：調(diào)用搖周邊平臺(tái)的api錄入創(chuàng)建紅包活動(dòng)并錄入信息，傳入預(yù)下單時(shí)生成的紅包ticket；
4. 調(diào)用jsapi抽紅包：在搖出的頁(yè)面中通過調(diào)用jsapi抽紅包，抽中紅包的用戶可以拆紅包；
5. 調(diào)用以上接口時(shí)，紅包提供商戶和紅包發(fā)放商戶公眾號(hào)要求一致。

 說明：
  紅包提供商戶：紅包預(yù)下單接口傳入的參數(shù)wxappid所代表的商戶
  紅包發(fā)放商戶：調(diào)用紅包接口創(chuàng)建紅包活動(dòng)、錄入紅包信息、發(fā)放紅包的商戶公眾號(hào)

紅包預(yù)下單接口

接口說明

設(shè)置單個(gè)紅包的金額，類型等，生成紅包信息。預(yù)下單完成后，需要在72小時(shí)內(nèi)調(diào)用jsapi完成抽紅包的操作。（紅包過期失效后，資金會(huì)退回到商戶財(cái)付通帳號(hào)。）

接口調(diào)用說明

服務(wù)器端調(diào)用
http請(qǐng)求方式: POST
https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder
POST數(shù)據(jù)格式：XML
需要商戶證書

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

請(qǐng)求示例

<xml>     
<sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>     
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>     
<mch_id><![CDATA[10000097]]></mch_id>     
<wxappid><![CDATA[wxcbda96de0b165486]]></wxappid>     
<send_name><![CDATA[send_name]]></send_name>     
<hb_type><![CDATA[NORMAL]]></hb_type>     
<auth_mchid><![CDATA[10000098]]></auth_mchid>     
<auth_appid><![CDATA[wx7777777]]></auth_appid>     
<total_amount><![CDATA[200]]></total_amount>     
<amt_type><![CDATA[ALL_RAND]]></amt_type>     
<total_num><![CDATA[3]]></total_num>     
<wishing><![CDATA[恭喜發(fā)財(cái) ]]></wishing>     
<act_name><![CDATA[ 新年紅包 ]]></act_name>     
<remark><![CDATA[新年紅包 ]]></remark>     
<risk_cntl><![CDATA[NORMAL]]></risk_cntl>     
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>
 

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

返回格式為xml

以下字段在return_code為SUCCESS的時(shí)候有返回

以下字段在return_code 和result_code都為SUCCESS的時(shí)候有返回

成功示例

<xml> 	
<return_code><![CDATA[SUCCESS]]></return_code> 	
<return_msg><![CDATA[發(fā)放成功.]]></return_msg> 
<result_code><![CDATA[SUCCESS]]></result_code> 
<err_code><![CDATA[0]]></err_code> 	
<err_code_des><![CDATA[發(fā)放成功.]]></err_code_des> 	
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno> 
<mch_id>10010404</mch_id> 	
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 	
<sp_ticket><![CDATA[0cca98c8c8e814883]]></sp_ticket> 
<total_amount>3</total_amount> 	
<detail_id><![CDATA[001001040420141117000004888]]></detail_id> 
<send_time><![CDATA[20150101080000]]></send_time> 
</xml>  

失敗示例

<xml>     
<return_code><![CDATA[FAIL]]></return_code> 	
<return_msg><![CDATA[系統(tǒng)繁忙,請(qǐng)稍后再試.]]></return_msg> 	
<result_code><![CDATA[FAIL]]></result_code> 	
<err_code><![CDATA[268458547]]></err_code> 	
<err_code_des><![CDATA[系統(tǒng)繁忙,請(qǐng)稍后再試.]]></err_code_des> 	
<mch_billno><![CDATA[0010010404201411170000046542]]></mch_billno> 	        
<mch_id>10010404</mch_id> 	
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 	 
<total_amount>3</total_amount> 
</xml>

錯(cuò)誤碼

簽名算法

第一步，設(shè)所有發(fā)送或者接收到的數(shù)據(jù)為集合M，將集合M內(nèi)非空參數(shù)值的參數(shù)按照參數(shù)名ASCII碼從小到大排序（字典序），使用URL鍵值對(duì)的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

 特別注意以下重要規(guī)則：
 參數(shù)名ASCII碼從小到大排序（字典序）；
 如果參數(shù)的值為空不參與簽名；
 參數(shù)名區(qū)分大小寫；
 驗(yàn)證調(diào)用返回或微信主動(dòng)通知簽名時(shí)，傳送的sign參數(shù)不參與簽名，將生成的簽名與該sign值作校驗(yàn)。

第二步，在stringA最后拼接上key=商戶支付密鑰得到stringSignTemp字符串，并對(duì)stringSignTemp進(jìn)行MD5運(yùn)算，再將得到的字符串所有字符轉(zhuǎn)換為大寫，得到sign值signValue。

 舉例：
 假設(shè)傳送的參數(shù)如下：
 appid： wxd930ea5d5a258f4f
 mch_id： 10000100
 device_info： 1000
 Body： test
 nonce_str： ibuaiVcKdpRxkhJA
 第一步：對(duì)參數(shù)按照key=value的格式，并按照參數(shù)名ASCII字典序排序如下：stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
 第二步：拼接支付密鑰：
 stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
 sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
 最終得到最終發(fā)送的數(shù)據(jù)：
<xml> 	
<appid>wxd930ea5d5a258f4f</appid> 	
<mch_id>10000100</mch_id> 	
<device_info>1000</device_info> 	
<body>test</body> 	
<nonce_str>ibuaiVcKdpRxkhJA</nonce_str> 	
<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign> 	
</xml>

生成隨機(jī)數(shù)算法

微信支付API接口協(xié)議中包含固定nonce_str，主要保證簽名不可預(yù)測(cè)。我們推薦生成隨機(jī)數(shù)算法如下：

 調(diào)用隨機(jī)數(shù)生成函數(shù)，將得到的值轉(zhuǎn)換為字符串。	

商戶證書

1. 獲取商戶證書

微信支付接口中，涉及資金回滾的接口會(huì)使用到商戶證書，包括退款、撤銷接口。商家在申請(qǐng)微信支付成功后，收到的相應(yīng)郵件通知中，附件會(huì)包含接口需要用到的證書文件，有四個(gè)證書文件，分別說明如下。

證書文件說明：

2. 使用商戶證書

apiclient_cert.p12是商戶證書文件，除PHP外的開發(fā)均使用此證書文件。
商戶如果使用.NET環(huán)境開發(fā)，請(qǐng)確認(rèn)Framework版本大于2.0，必須在操作系統(tǒng)上雙擊安裝證書apiclient_cert.p12后才能被正常調(diào)用。
商戶證書調(diào)用或安裝都需要使用到密碼，該密碼的值為微信商戶號(hào)（mchid）
PHP開發(fā)環(huán)境請(qǐng)使用商戶證書文件apiclient_cert.pem和apiclient_key.pem ，rootca.pem是CA證書。

3. 商戶證書安全

證書文件放在非web服務(wù)器虛擬目錄的文件夾下，防止被他人下載。商戶服務(wù)器要做好病毒和木馬防護(hù)工作，不被非法侵入者竊取證書文件。

創(chuàng)建紅包活動(dòng)

接口說明

創(chuàng)建紅包活動(dòng)，設(shè)置紅包活動(dòng)有效期，紅包活動(dòng)開關(guān)等基本信息，返回活動(dòng)id

接口調(diào)用說明

服務(wù)器端調(diào)用
http請(qǐng)求方式: POST
URL: https://api.weixin.qq.com/shakearound/lottery/addlotteryinfo?access_token=ACCESSTOKEN&use_template=1&logo_url=LOGO_URL

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

POST BODY：JSON格式的結(jié)構(gòu)體

請(qǐng)求示例

Content-Type: application/json Post Body:
{                                                            
 "title": "title",                           
 "desc": "desc",                             
 "onoff": 1,                                 
 "begin_time": 1428854400,                            
 "expire_time": 1428940800,                           
 "sponsor_appid": "wxxxxxxxxxxxxxx",
 "total": 10,
 "jump_url": JUMP_URL,     
 "key": "keyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"                            
}
 

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

示例

{     
 "errcode":0,     
 "errmsg":"",     
 "lottery_id":"xxxxxxllllll", 
 "page_id":1, 
}

錄入紅包信息

接口說明

在調(diào)用"創(chuàng)建紅包活動(dòng)"接口之后，調(diào)用此接口錄入紅包信息。注意，此接口每次調(diào)用，都會(huì)向某個(gè)活動(dòng)新增一批紅包信息，如果紅包數(shù)少于100個(gè)，請(qǐng)通過一次調(diào)用添加所有紅包信息。如果紅包數(shù)大于100，可以多次調(diào)用接口添加。請(qǐng)注意確保多次錄入的紅包ticket總的數(shù)目不大于創(chuàng)建該紅包活動(dòng)時(shí)設(shè)置的total值。

接口調(diào)用說明

服務(wù)器端調(diào)用
http請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/shakearound/lottery/setprizebucket?access_token=ACCESSTOKEN

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

POST BODY：JSON格式的結(jié)構(gòu)體

請(qǐng)求示例

Content-Type: application/json Post Body:
{     
"lottery_id": "xxxxxxllllll",     
"mchid": "10000098",     
"sponsor_appid": "wx8888888888888888",   
"prize_info_list": [         
     {            
   "ticket": "v1|ZiPs2l0hpMBp3uwGI1rwp45vOdz/V/zQ/00jP9MeWT+e47/q1FJjwCIP34frSjzOxAEzJ7k2CtAg1pmcShvkChBWqbThxPm6MBuzceoHtj79iHuHaEn0WAO+j4sXnXnbGswFOlDYWg1ngvrRYnCY3g=="
     },
     {
   "ticket": "v1|fOhNUTap1oepSm5ap0hx1gmATM\/QX\/xn3sZWL7K+5Z10sbV5\/mZ4SwxwxbK2SPV32eLRvjd4ww1G3H5a+ypqRrySi+4oo97y63KoEQbRCPjbkyQBY8AYVyvD40V2b9slTQCm2igGY98mPe+VxZiayQ=="
     }
   ]
}

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

示例

{	     
"errcode":0,     
"errmsg":"",     
"repeat_ticket_list":[         
     {            
"ticket": "v1|ZiPs2l0hpMBp3uwGI1rwp45vOdz/V/zQ/00jP9MeWT+e47/q1FJjwCIP34frSjzOxAEzJ7k2CtAg1pmcShvkChBWqbThxPm6MBuzceoHtj79iHuHaEn0WAO+j4sXnXnbGswFOlDYWg1ngvrRYnCY3g=="                       
     },
     {
"ticket":"v1|ZiPs2l0zzXCsdfwe45dxCdHiukOdz/V/zQ/89xcnC5XnT+e47/q1FJjwCO4frSjzOxAEzJ7k2CtAg1pmcShvkChBWzc45dDGC32Dcxx4DGxczjDCGsdjowe9iHuaEn0WAO+GswFOlDYWg1ngvrRYnCY3g=="         	}    		
     } 
  ], 	
"success_num":100 
}

設(shè)置紅包活動(dòng)抽獎(jiǎng)開關(guān)

接口說明

開發(fā)者實(shí)時(shí)控制紅包活動(dòng)抽獎(jiǎng)的開啟和關(guān)閉。注意活動(dòng)抽獎(jiǎng)開關(guān)只在紅包活動(dòng)有效期之內(nèi)才能生效，如果不能確定紅包活動(dòng)有效期，請(qǐng)盡量將紅包活動(dòng)有效期的范圍設(shè)置大。

接口調(diào)用說明

服務(wù)器端調(diào)用
http請(qǐng)求方式: Get
URL:https://api.weixin.qq.com/shakearound/lottery/setlotteryswitch?access_token=ACCESSTOKEN&lottery_id=LOTTERYID&onoff=1

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

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

示例

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

紅包JSAPI

接口說明

在第三方頁(yè)面中，通過調(diào)用JSAPI來觸發(fā)用戶抽紅包的操作，如果抽到紅包，會(huì)呼出微信的原生紅包頁(yè)面。用戶只有通過搖周邊的入口才能抽中紅包。每個(gè)用戶在一個(gè)活動(dòng)抽獎(jiǎng)id下最多只能中一個(gè)紅包。創(chuàng)建紅包活動(dòng)時(shí)，選擇使用模板頁(yè)面的開發(fā)者不需要調(diào)用該接口

引入BeaconShakehbJsBridge'

<scripttype="text/javascript"src="http://zb.weixin.qq.com/app/shakehb/BeaconShakehbJsBridge.js">
</script>

API詳細(xì)說明

抽紅包JS API調(diào)用與微信的JS API調(diào)用格式一致，如下：

函數(shù)：invoke
用途：主動(dòng)調(diào)用指定API
通用形式：BeaconShakehbJsBridge.invoke("API名稱", {調(diào)用參數(shù)});
API 名稱：jumpHongbao
參數(shù)：openid、lottery_id、noncestr、sign
回調(diào)函數(shù)：無(wú)

調(diào)用參數(shù)說明

Sign生成規(guī)則

1.除sign字段外，所有參數(shù)按照字段名的ASCII碼從小到大排序后（字典序），使用URL鍵值對(duì)的格式（即Param1=value1&Param2=value2…）拼接而成簽名原始串，空值不參與簽名組串。
2.簽名原始串中，字段名和字段值都采用原始值，不進(jìn)行URL轉(zhuǎn)義。 
3.簽名原始串末尾補(bǔ)上key參數(shù)(通過“創(chuàng)建紅包活動(dòng)”接口設(shè)置的key)，如 Param1=value1&Param2=value2…&key=keyvalue 
4.得到的字符串進(jìn)行MD5，并轉(zhuǎn)換為大寫。即                  sign=ToUpperCase(MD5(Param1=value1&Param2=value2…&key=keyvalue))
5.出于安全考慮，開發(fā)者必須在服務(wù)器端實(shí)現(xiàn)生成簽名的邏輯。

請(qǐng)求示例

BeaconShakehbJsBridge.ready(function(){
//跳轉(zhuǎn)到抽紅包頁(yè)面
     BeaconShakehbJsBridge.invoke('jumpHongbao',{
     lottery_id:'LOTTERY_ID ',
     noncestr:'378507853820041854759013507217',
     openid:'OPENID',
     sign:'SIGN'
});
});

用戶側(cè)錯(cuò)誤碼說明

紅包綁定用戶事件通知

接口說明

用戶進(jìn)入紅包頁(yè)面時(shí)，后臺(tái)會(huì)將一個(gè)紅包ticket和用戶openid綁定，微信會(huì)把這個(gè)事件推送到開發(fā)者填寫的URL（登錄公眾平臺(tái)進(jìn)入開發(fā)者中心設(shè)置）。推送內(nèi)容包含用戶openid，紅包活動(dòng)id，紅包ticket、金額以及紅包綁定時(shí)間。

注：紅包綁定用戶不等同于用戶領(lǐng)取紅包。用戶進(jìn)入紅包頁(yè)面后，有可能不拆紅包，但該紅包ticket已被綁定，不能再被其他用戶綁定，過期后會(huì)退回商戶財(cái)付通賬戶。

推送XML數(shù)據(jù)包示例

<xml> 	
<ToUserName><![CDATA[toUser]]></ToUserName> 	
<FromUserName><![CDATA[fromUser]]></FromUserName> 
<CreateTime>1442824314</CreateTime> 
<MsgType><![CDATA[event]]></MsgType> 	
<Event><![CDATA[ShakearoundLotteryBind]]></Event> 	
<LotteryId><![CDATA[lotteryid]]></LotteryId> 	
<Ticket><![CDATA[ticket]]></Ticket> 	
<Money>88</Money> 	
<BindTime>1442824313</BindTime> 
</xml>  

調(diào)用參數(shù)說明

紅包查詢接口

接口說明

查詢紅包活動(dòng)信息。

接口調(diào)用說明

服務(wù)器端調(diào)用
http請(qǐng)求方式: Get
URL:https://api.weixin.qq.com/shakearound/lottery/querylottery?access_token=ACCESSTOKEN&lottery_id=LOTTERYID

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

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

 注意：調(diào)用SetPrizeBucket錄入紅包次數(shù)超過3000次的，或紅包總數(shù)超過1萬(wàn)個(gè)的活動(dòng)，目前暫不支持expired_prizes, drawed_prizes, available_prizes, expired_value, drawed_value, available_value這6個(gè)字段的查詢。需要查詢時(shí)，可以通過郵箱zhoubian@tencent.com聯(lián)系我們，也可加入開發(fā)者QQ交流群390582489。

示例

{     	
"errcode":0,    		
"errmsg":""
result:{
    lottery_id:” 9sQqUrmdFaY6v9z8TartOA”,
    title:”活動(dòng)標(biāo)題”,
    desc:”活動(dòng)描述”,
    onoff:”1”,
    begin_time:” 1446360417”,
    expire_time:” 1446400000”,
    sponsor_appid:” wxf5b5e87a6a0fde94”,
    appid:”wx4428b5f51c53a582”,
    prize_count_limit:1000,
    prize_count: 810,
    jump_url:”http://www.qq.com/”,
    expired_prizes: 100,
    drawed_prizes:200,
    available_prizes:510,
    expired_value: 10000,
    drawed_value:20000,
    available_value: 51000
    }  
}