赤い封筒を振っての紹介
摇一摇红包说明
功能说明
摇一摇周边红包接口是为线下商户提供的发红包功能。用户可以在商家门店等线下场所通过摇一摇周边领取商家发放的红包,在线上转发分享无效。
开发者可通过接口开发摇一摇红包功能,特点包括:
可选择使用模板加载页或自定义Html5页面调起微信原生红包页面(详见创建红包活动中use_template字段,1为使用模板,2为使用自定义Html5页面)
原生红包页面拆红包,无需通过公众号消息下发
提供关注公众号能力,用户可自行选择是否关注(裂变红包分享时无效)
完成页面可配置跳转链接,可跳转商户的其他自定义Html5页面
同一个用户在单个红包活动中只能领取1次红包
申请红包接口权限:登录摇一摇周边商户后台https://zb.weixin.qq.com ,进入开发者支持,申请开通摇一摇红包组件接口;
红包预下单:调用微信支付的api进行红包预下单,告知需要发放的红包金额,人数,生成红包ticket;
创建活动并录入红包信息:调用摇周边平台的api录入创建红包活动并录入信息,传入预下单时生成的红包ticket;
调用jsapi抽红包:在摇出的页面中通过调用jsapi抽红包,抽中红包的用户可以拆红包;
调用以上接口时,红包提供商户和红包发放商户公众号要求一致。
说明:
红包提供商户:红包预下单接口传入的参数wxappid所代表的商户
红包发放商户:调用红包接口创建红包活动、录入红包信息、发放红包的商户公众号
红包预下单接口
接口说明
设置单个红包的金额,类型等,生成红包信息。预下单完成后,需要在72小时内调用jsapi完成抽红包的操作。(红包过期失效后,资金会退回到商户财付通帐号。)
接口调用说明
服务器端调用
http请求方式: POSThttps://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder
POST数据格式:XML
需要商户证书
请求参数说明
参数 | 字段 | 是否必须 | 示例值 | 类型 | 说明 |
随机字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8Z NMTM67VS | String(32) | 随机字符串,不长于32位 |
签名 | sign | 是 | C380BEC2BFD727A4B68451335 19F3AD6 | String(32) | 生成签名方式查看签名算法 |
商户订单号 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。接口根据商户订单号支持重入, 如出现超时可再调用。 |
商户号 | mch_id | 是 | 10000098 | String(32) | 红包提供者的商户号(微信支付分配的商户号) |
公众账号appid | wxappid | 是 | wx8888888888888888 | String(32) | 红包提供者公众号的appid,对应头像展示在红包页面 |
商户名称 | send_name | 是 | 天虹百货 | String(32) | 红包提供者名称,展示在红包页面 |
红包类型 | hb_type | 是 | NORMAL | String(16) | NORMAL-普通红包;GROUP-裂变红包(可分享红包给好友,无关注公众号能力)。 |
总金额 | total_amount | 是 | 1000 | int | 总付款金额,单位分 |
红包发放总人数 | total_num | 是 | 1 | int | 红包发放总人数,即总共有多少人可以领到该组红包(包括分享者)。普通红包填1,裂变红包必须大于1。 |
红包金额设置方式 | amt_type | 是 | ALL_RAND | String(32) | 红包金额设置方式,只对裂变红包生效。ALL_RAND—全部随机 |
红包祝福语 | wishing | 是 | 感谢您参加猜灯谜活动,祝您元宵节快乐 | String(16) | 红包祝福语,展示在红包页面 |
活动名称 | act_name | 是 | 猜灯谜抢红包活动 | String(32) | 活动名称,在不支持原生红包的微信版本中展示在红包消息 |
备注 | remark | 是 | 猜越多得越多,快来抢! | String(32) | 备注信息,在不支持原生红包的微信版本中展示在红包消息 |
授权商户号 | auth_mchid | 是 | 1000052601 | String(32) | 用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的商户号:1000052601 |
授权商户APPID | auth_appid | 是 | wxbf42bd79c4391863 | String(32) | 用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的appid:wxbf42bd79c4391863 |
风控设置 | risk_cntl | 是 | NORMAL | String(32) | 用于管控接口风险。具体值如下:NORMAL—正常情况;IGN_FREQ_LMT—忽略防刷限制,强制发放;IGN_DAY_LMT—忽略单用户日限额限制,强制发放;IGN_FREQ_DAY_LMT—忽略防刷和单用户日限额限制,强制发放;如无特殊要求,请设为NORMAL。若忽略某项风险控制,可能造成资金损失,请谨慎使用。 |
请求示例
<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[恭喜发财 ]]></wishing>
<act_name><![CDATA[ 新年红包 ]]></act_name>
<remark><![CDATA[新年红包 ]]></remark>
<risk_cntl><![CDATA[NORMAL]]></risk_cntl>
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>
返回数据说明
返回格式为xml
参数 | 字段 | 是否必须 | 示例值 | 类型 | 说明 |
返回状态码 | return_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL;此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断 |
返回信息 | return_msg | 否 | 签名失败 | String(128) | 返回信息,如非空,为错误原因 签名失败 参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
参数 | 字段 | 是否必须 | 示例值 | 类型 | 说明 |
签名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 生成签名方式查看 签名算法 |
业务结果 | result_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL |
错误代码 | err_code | 否 | SUCCESS | String(32) | 错误码信息 |
错误代码描述 | err_code_des | 否 | 系统错误 | String(128) | 结果信息描述 |
以下字段在return_code 和result_code都为SUCCESS的时候有返回
参数 | 字段 | 是否必须 | 示例值 | 类型 | 说明 |
商户订单号 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。 |
商户号 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商户号 |
公众账号appid | wxappid | 是 | wx8888888888888888 | String(32) | 商户appid |
总金额 | total_amount | 是 | 1000 | int | 总付款金额,单位分 |
ticket | sp_ticket | 是 | 2J6MtR+SlbZ8Ga4EDi64X5 vC4Xv01ofX4uWOqqTc9kGJYhkq5 st5ucrXKxkjnC/UuvLeuhdIfiYg i4hJuJ95qjt9mwxqSBEmjGbZlL+ sqM9upoWsEjup28KPvaVrdao/Hg 6WqyqUL5E2zPHfM1sb1w== | String | sp_ticket,一个普通红包对应一个ticket |
红包订单号 | detail_id | 是 | 0000000666201504290000042120 | 红包内部订单号 | |
发送时间 | 是 | 20150429203444 | 红包发放时间 |
成功示例
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[发放成功.]]></return_msg>
<result_code><![CDATA[SUCCESS]]></result_code>
<err_code><![CDATA[0]]></err_code>
<err_code_des><![CDATA[发放成功.]]></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[系统繁忙,请稍后再试.]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code><![CDATA[268458547]]></err_code>
<err_code_des><![CDATA[系统繁忙,请稍后再试.]]></err_code_des>
<mch_billno><![CDATA[0010010404201411170000046542]]></mch_billno>
<mch_id>10010404</mch_id>
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid>
<total_amount>3</total_amount>
</xml>
错误码
错误代码 | 描述 | 解决方案 |
CA_ERROR | 请求未携带证书,或请求携带的证书出错 | 到商户平台下载证书,请求带上证书后重试。 |
SIGN_ERROR | 商户签名错误 | 按文档要求重新生成签名后再重试。 |
NO_AUTH | 没有权限 | 请联系微信支付开通api权限。 |
FREQ_LIMIT | 受频率限制 | 请对请求做频率控制 |
XML_ERROR | 请求的xml格式错误,或者post的数据为空 | 检查请求串,确认无误后重试 |
PARAM_ERROR | 参数错误 | 请查看err_code_des,修改设置错误的参数 |
OPENID_ERROR | Openid错误 | 根据用户在商家公众账号上的openid,获取用户在红包公众账号上的openid 错误。请核对商户自身公众号appid和用户在此公众号下的openid。 |
NOTENOUGH | 余额不足 | 商户账号余额不足,请登录微信支付商户平台充值 |
FATAL_ERROR | 重复请求时,参数与原单不一致 | 使用相同商户单号进行重复请求时,参数与第一次请求时不一致,请检查并修改参数后再重试。 |
TIME _LIMITED | 企业红包的发送时间受限 | 请北京时间0:00-8:00时间之外触发红包赠送 |
SECOND_OVER_LIMITED | 企业红包的按分钟发放受限 | 每分钟发送红包数量不得超过1800个;(可联系微信支付wxhongbao@tencent.com调高额度) |
DAY_ OVER_LIMITED | 企业红包的按天日发放受限 | 单个商户日发送红包数量不大于10000个;(可联系微信支付wxhongbao@tencent.com调高额度) |
MONEY_LIMIT | 红包金额发放限制 | 每个红包金额必须大于1元,小于1000元(可联系微信支付wxhongbao@tencent.com调高额度至4999元) |
SEND_FAILED | 红包发放失败,请更换单号再重试。 | 原商户单号已经失败,如果还要对同一个用户发放红包, 需要更换新的商户单号再试。 |
SYSTEMERROR | 系统繁忙,请再试。 | 可用同一商户单号再次调用,只会发放一个红包。 |
签名算法
第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。
特别注意以下重要规则:
参数名ASCII码从小到大排序(字典序);
如果参数的值为空不参与签名;
参数名区分大小写;
验证调用返回或微信主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
第二步,在stringA最后拼接上key=商户支付密钥得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。
举例:
假设传送的参数如下:
appid: wxd930ea5d5a258f4f
mch_id: 10000100
device_info: 1000
Body: test
nonce_str: ibuaiVcKdpRxkhJA
第一步:对参数按照key=value的格式,并按照参数名ASCII字典序排序如下:stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
第二步:拼接支付密钥:
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
最终得到最终发送的数据:
<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>
生成随机数算法
微信支付API接口协议中包含固定nonce_str,主要保证签名不可预测。我们推荐生成随机数算法如下:
调用随机数生成函数,将得到的值转换为字符串。
商户证书
1. 获取商户证书
微信支付接口中,涉及资金回滚的接口会使用到商户证书,包括退款、撤销接口。商家在申请微信支付成功后,收到的相应邮件通知中,附件会包含接口需要用到的证书文件,有四个证书文件,分别说明如下。
证书文件说明:
证书附件 | 描述 | 使用场景 | 备注 |
pkcs12格式(apiclient_cert.p12) | 包含了私钥信息的证书文件,为p12(pfx)格式,由微信支付签发给您用来标识和界定您的身份 | 撤销、退款申请API中调用 | windows上可以直接双击导入系统,导入过程中会提示输入证书密码,证书密码默认为您的商户ID(如:10010000) |
证书pem格式(apiclient_cert.pem) | 从apiclient_cert.p12中导出证书部分的文件,为pem格式,请妥善保管不要泄漏和被他人复制 | PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供 | 您也可以使用openssl命令来自己导出:openssl pkcs12 -clcerts -nokeys -in apiclient_cert.p12 -out apiclient_cert.pem |
证书密钥pem格式(apiclient_key.pem) | 从apiclient_cert.p12中导出密钥部分的文件,为pem格式 | PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供 | 您也可以使用openssl命令来自己导出:openssl pkcs12 -nocerts -in apiclient_cert.p12 -out apiclient_key.pem |
CA证书(rootca.pem) | 微信支付api服务器上也部署了证明微信支付身份的服务器证书,您在使用api进行调用时也需要验证所调用服务器及域名的真实性 | 该文件为签署微信支付证书的权威机构的根证书,可以用来验证微信支付服务器证书的真实性 | 部分工具已经内置了若干权威机构的根证书,无需引用该证书也可以正常进行验证,这里提供给您在未内置所必须根证书的环境中载入使用 |
2. 使用商户证书
apiclient_cert.p12是商户证书文件,除PHP外的开发均使用此证书文件。
商户如果使用.NET环境开发,请确认Framework版本大于2.0,必须在操作系统上双击安装证书apiclient_cert.p12后才能被正常调用。
商户证书调用或安装都需要使用到密码,该密码的值为微信商户号(mchid)
PHP开发环境请使用商户证书文件apiclient_cert.pem和apiclient_key.pem ,rootca.pem是CA证书。
3. 商户证书安全
证书文件放在非web服务器虚拟目录的文件夹下,防止被他人下载。商户服务器要做好病毒和木马防护工作,不被非法侵入者窃取证书文件。
创建红包活动
接口说明
创建红包活动,设置红包活动有效期,红包活动开关等基本信息,返回活动id
接口调用说明
服务器端调用
http请求方式: POST
URL: https://api.weixin.qq.com/shakearound/lottery/addlotteryinfo?access_token=ACCESSTOKEN&use_template=1&logo_url=LOGO_URL
请求参数说明
参数 | 类型 | 说明 |
access_token | string | accesstoken,以参数的形式拼装在url后 |
use_template | int | 是否使用模板,1:使用,2:不使用,以参数的形式拼装在url后。(模版即交互流程图中的红包加载页,使用模板用户不需要点击可自动打开红包;不使用模版需自行开发HTML5页面,并在页面调用红包jsapi) |
logo_url | string | 使用模板页面的logo_url,不使用模板时可不加。展示在摇一摇界面的消息图标。图片尺寸为120x120。 |
POST BODY:JSON格式的结构体
参数 | 类型 | 说明 |
title | string | 抽奖活动名称(选择使用模板时,也作为摇一摇消息主标题),最长6个汉字,12个英文字母。 |
desc | string | 抽奖活动描述(选择使用模板时,也作为摇一摇消息副标题),最长7个汉字,14个英文字母。 |
onoff | int | 抽奖开关。0关闭,1开启,默认为1 |
begin_time | long | 抽奖活动开始时间,unix时间戳,单位秒 |
expire_time | long | 抽奖活动结束时间,unix时间戳,单位秒,红包活动有效期最长为91天 |
sponsor_appid | string | 红包提供商户公众号的appid,需与预下单中的公众账号appid(wxappid)一致 |
total | long | 红包总数,红包总数是录入红包ticket总数的上限,因此红包总数应该大于等于预下单时红包ticket总数。 |
jump_url | string | 红包关注界面后可以跳转到第三方自定义的页面 |
key | string | 开发者自定义的key,用来生成活动抽奖接口的签名参数,长度32位。使用方式见sign生成规则 |
请求示例
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"
}
返回数据说明
参数 | 类型 | 说明 |
errcode | int | 错误码。0为成功,其他为失败。详细请参考错误码表 |
errmsg | string | 错误信息 |
lottery_id | string | 生成的红包活动id |
page_id | int | 生成的模板页面ID |
示例
{
"errcode":0,
"errmsg":"",
"lottery_id":"xxxxxxllllll",
"page_id":1,
}
录入红包信息
接口说明
在调用"创建红包活动"接口之后,调用此接口录入红包信息。注意,此接口每次调用,都会向某个活动新增一批红包信息,如果红包数少于100个,请通过一次调用添加所有红包信息。如果红包数大于100,可以多次调用接口添加。请注意确保多次录入的红包ticket总的数目不大于创建该红包活动时设置的total值。
接口调用说明
服务器端调用
http请求方式: POST
URL:https://api.weixin.qq.com/shakearound/lottery/setprizebucket?access_token=ACCESSTOKEN
请求参数说明
参数 | 类型 | 说明 |
access_token | string | accesstoken,以参数的形式拼装在url后 |
POST BODY:JSON格式的结构体
参数 | 类型 | 说明 |
lottery_id | string | 红包抽奖id,来自addlotteryinfo返回的lottery_id |
mchid | string | 红包提供者的商户号,,需与预下单中的商户号mch_id一致 |
sponsor_appid | string | 红包提供商户公众号的appid,需与预下单中的公众账号appid(wxappid)一致 |
prize_info_list | json数组 | 红包ticket列表,如果红包数较多,可以一次传入多个红包,批量调用该接口设置红包信息。每次请求传入的红包个数上限为100 |
ticket | string | 预下单时返回的红包ticket,单个活动红包ticket数量上限为100000个,可添加多次。 |
请求示例
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=="
}
]
}
返回数据说明
参数 | 类型 | 说明 |
errcode | int | 错误码。0为成功,其他为失败。详细请参考错误码表 |
errmsg | string | 错误信息 |
repeat_ticket_list | array | 重复使用的ticket列表,如为空,将不返回 |
expire_ticket_list | array | 过期的ticket列表,如为空,将不返回 |
invalid_amount_ticket_list | array | 金额不在大于1元,小于1000元的ticket列表,如为空,将不返回 |
success_num | int | 成功录入的红包数量 |
wrong_authmchid_ticket_list | array | 原因:生成红包的时候,授权商户号auth_mchid和auth_appid没有写摇周边的商户号 |
invalid_ticket_list | array | ticket解析失败,可能有错别字符或不完整 |
示例
{
"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
}
设置红包活动抽奖开关
接口说明
开发者实时控制红包活动抽奖的开启和关闭。注意活动抽奖开关只在红包活动有效期之内才能生效,如果不能确定红包活动有效期,请尽量将红包活动有效期的范围设置大。
接口调用说明
服务器端调用
http请求方式: Get
URL:https://api.weixin.qq.com/shakearound/lottery/setlotteryswitch?access_token=ACCESSTOKEN&lottery_id=LOTTERYID&onoff=1
请求参数说明
参数 | 类型 | 说明 |
access_token | string | accesstoken,以参数的形式拼装在url后 |
lottery_id | string | 红包抽奖id,来自addlotteryinfo返回的lottery_id |
onoff | int | 活动抽奖开关,0:关闭,1:开启 |
返回数据说明
参数 | 类型 | 说明 |
errcode | int | 错误码。0为成功,其他为失败。详细请参考错误码表 |
errmsg | string | 错误信息 |
示例
{
"errcode":0,
"errmsg":""
}
红包JSAPI
接口说明
在第三方页面中,通过调用JSAPI来触发用户抽红包的操作,如果抽到红包,会呼出微信的原生红包页面。用户只有通过摇周边的入口才能抽中红包。每个用户在一个活动抽奖id下最多只能中一个红包。创建红包活动时,选择使用模板页面的开发者不需要调用该接口
引入BeaconShakehbJsBridge'
<scripttype="text/javascript"src="http://zb.weixin.qq.com/app/shakehb/BeaconShakehbJsBridge.js">
</script>
API详细说明
抽红包JS API调用与微信的JS API调用格式一致,如下:
函数:invoke
用途:主动调用指定API
通用形式:BeaconShakehbJsBridge.invoke("API名称", {调用参数});
API 名称:jumpHongbao
参数:openid、lottery_id、noncestr、sign
回调函数:无
调用参数说明
参数 | 说明 |
openid | 用户openid。必填 |
lottery_id | 红包抽奖id,必填,来自addlotteryinfo返回的lottery_id |
noncestr | 随机字符串,不长于32位。必填 |
sign | 签名,详见下面的签名生成规则 |
Sign生成规则
1.除sign字段外,所有参数按照字段名的ASCII码从小到大排序后(字典序),使用URL键值对的格式(即Param1=value1&Param2=value2…)拼接而成签名原始串,空值不参与签名组串。
2.签名原始串中,字段名和字段值都采用原始值,不进行URL转义。
3.签名原始串末尾补上key参数(通过“创建红包活动”接口设置的key),如 Param1=value1&Param2=value2…&key=keyvalue
4.得到的字符串进行MD5,并转换为大写。即 sign=ToUpperCase(MD5(Param1=value1&Param2=value2…&key=keyvalue))
5.出于安全考虑,开发者必须在服务器端实现生成签名的逻辑。
请求示例
BeaconShakehbJsBridge.ready(function(){
//跳转到抽红包页面
BeaconShakehbJsBridge.invoke('jumpHongbao',{
lottery_id:'LOTTERY_ID ',
noncestr:'378507853820041854759013507217',
openid:'OPENID',
sign:'SIGN'
});
});
用户侧错误码说明
提示文案 | 错误码 | 错误信息 | 解决方案 |
出错了 | 5 | 摇周边ticket过期 | 检查是不是从微信摇一摇进入 |
出错了 | 11002 | 摇一摇ticket不存在 | 检查是不是从微信摇一摇进入 |
出错了 | 11003 | 无效的摇一摇ticket | 检查是不是从微信摇一摇进入 |
出错了 | 11004 | 获取商户appid失败 | 检查是不是从微信摇一摇进入 |
出错了 | 11005 | 摇周边频率检查失败 | 检查是不是从微信摇一摇进入 |
出错了 | 11009 | 系统异常 | 请重试 |
出错了 | 11010 | 随机字符串长度过长 | 对自定义页面时调jsapi参数校验出错,请检查 |
出错了 | 11011 | LotteryID解析失败 | 对自定义页面时调jsapi参数校验出错,请检查 |
出错了 | 11012 | 签名校验失败 | 对自定义页面时调jsapi参数校验出错,请检查 |
出错了 | 11013 | openid无效 | 对自定义页面时调jsapi参数校验出错,请检查 |
出错了 | 11014 | pass_ticket无效 | 检查是不是从微信摇一摇进入 |
出错了 | 12013 | 绑定用户和红包失败 | 抽到红包ticket后,微信支付返回的错误 |
出错了 | 12014 | 微信支付查询红包ticket失败 | 抽到红包ticket后,微信支付返回的错误 |
出错了 | 12015 | 抽奖操作频率过高 | 请重试 |
出错了 | 12019 | page_id无效 | 使用模版时校验出错 |
红包绑定用户事件通知
接口说明
用户进入红包页面时,后台会将一个红包ticket和用户openid绑定,微信会把这个事件推送到开发者填写的URL(登录公众平台进入开发者中心设置)。推送内容包含用户openid,红包活动id,红包ticket、金额以及红包绑定时间。
注:红包绑定用户不等同于用户领取红包。用户进入红包页面后,有可能不拆红包,但该红包ticket已被绑定,不能再被其他用户绑定,过期后会退回商户财付通账户。
推送XML数据包示例
<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>
调用参数说明
字段 | 说明 |
ToUserName | 开发者微信号。 |
FromUserName | 红包绑定用户(一个OpenID)。 |
CreateTime | 消息创建时间 (整型)。 |
MsgType | 消息类型,event |
Event | 事件类型,ShakearoundLotteryBind |
LotteryId | 红包活动id |
ticket | 红包ticket |
money | 红包金额 |
BindTime | 红包绑定时间 |
红包查询接口
接口说明
查询红包活动信息。
接口调用说明
服务器端调用
http请求方式: Get
URL:https://api.weixin.qq.com/shakearound/lottery/querylottery?access_token=ACCESSTOKEN&lottery_id=LOTTERYID
请求参数说明
参数 | 类型 | 说明 |
access_token | string | accesstoken,以参数的形式拼装在url后 |
lottery_id | string | 红包抽奖id,来自addlotteryinfo返回的lottery_id |
返回数据说明
参数 | 类型 | 说明 |
errcode | int | 错误码。0为成功,其他为失败。详细请参考错误码表 |
errmsg | string | 错误信息 |
title | string | 抽奖活动名称(选择使用模板时,也作为摇一摇消息主标题),最长6个汉字,12个英文字母。 |
desc | string | 抽奖活动描述(选择使用模板时,也作为摇一摇消息副标题),最长7个汉字,14个英文字母。 |
onoff | int | 抽奖开关。0关闭,1开启,默认为1 |
begin_time | long | 抽奖活动开始时间,unix时间戳,单位秒 |
expire_time | long | 抽奖活动结束时间,unix时间戳,单位秒,红包活动有效期最长为91天 |
sponsor_appid | string | 红包提供商户公众号的appid |
appid | string | 创建活动的开发者appid |
prize_count | long | 已录入的红包总数 |
prize_count_limit | long | 创建活动时预设的录入红包ticket数量上限 |
jump_url | string | 红包关注界面后可以跳转到第三方自定义的页面 |
expired_prizes | long | 过期红包ticket数量 |
drawed_prizes | long | 已发放的红包ticket数量 |
available_prizes | long | 可用的红包ticket数量 |
expired_value | long | 已过期的红包金额总和 |
drawed_value | long | 已发放的红包金额总和 |
available_value | long | 可用的红包金额总和 |
注意:调用SetPrizeBucket录入红包次数超过3000次的,或红包总数超过1万个的活动,目前暂不支持expired_prizes, drawed_prizes, available_prizes, expired_value, drawed_value, available_value这6个字段的查询。需要查询时,可以通过邮箱zhoubian@tencent.com联系我们,也可加入开发者QQ交流群390582489。
示例
{
"errcode":0,
"errmsg":""
result:{
lottery_id:” 9sQqUrmdFaY6v9z8TartOA”,
title:”活动标题”,
desc:”活动描述”,
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
}
}