回调任务集市V2发货URL协议说明

特别声明
1.本文档仅针对已经接入支付,且已上线QQ空间的应用使用。
2.本协议说明用于实现交叉推广任务集市V2版本买方应用开发说明中的Step5;买方向用户发放奖励,详见这里)。

目录

1 什么是发货URL?

交叉推广渠道V2版本中,买方应用通过提供奖励来吸引用户完成其投放到任务集市中的任务,用户点击“去做任务”后,即可进入买方应用。通过该种方式,买方吸引用户进入应用,获得了用户安装量,提升了应用的活跃度。

任务集市V2发货URL用来给平台回调。符合领取条件的用户确认领取奖励后,腾讯后台将回调该URL给用户发放奖励。
任务集市V2发货URL由买方配置:登录op.open.qq.com后进入管理中心,选择进入试点应用后,在“支付结算”tab下,点击“任务集市V2”类的“我是买家”按钮,进入“填写任务信息”页面,在该页面最下方,点击“发货信息”链接,进行奖励道具发货URL的配置。

回调任务集市V2发货URL由平台发起,应用需根据下面所述的协议的参数,返回包以及错误码进行参数解析,执行奖励发放操作或返回错误码。

本步骤属于整体流程中的第8步:
cross_spread_v2_12.png

2 协议参数

平台发送给应用的请求中将包含下列参数,应用需根据协议的参数进行请求解析:
请开发者特别关注:
平台后续可能对协议进行扩展,因此请不要将参与签名的参数写死。
计算签名时,请以每次接收到的参数为准,接收到的所有参数除sig以外都要参与签名。

参数名称 类型 描述
openid string 与APP通信的用户key,跳转到应用首页后,URL后会带该参数。由平台直接传给应用。

根据APPID以及QQ号码生成,即不同的appid下,同一个QQ号生成的OpenID是不一样的。

appid string 应用的唯一ID。可以通过appid查找APP基本信息。
ts string linux时间戳。

注意开发者的机器时间与腾讯计费开放平台的时间相差不能超过15分钟。

payitem string 物品信息。主要用于第三方应用来识别发货商品。

请使用ID*num的格式。ID表示物品ID,num表示发放物品的数量。
例如物品1的ID为G001,发放数量为1,则payitem为:G001*1。
注:物品是分开发放的,不支持批量发放,即一个请求只发放一种物品,所以,payitem里始终只有一种物品的信息。 买方设置入口:登录op.open.qq.com后进入管理中心,选择进入1个应用后,在“支付结算”tab下的“任务集市V2”类,可看到“我是买家”按钮,点击进入后在“填写任务信息”的“奖品信息”中设置的礼包ID。

contractid string 交叉营销任务集市V2中买方发布任务成功后分配的唯一ID。
billno string 发放奖励流水号(64个字符长度。该字段和openid合起来是唯一的)。
version string 协议版本号,由于基于V3版OpenAPI,这里一定返回“v3”。
zoneid string 表示多区多服应用某一个大区的ID号;如果是单区单服应用,则这里传0。

(原来已上线支付的的单区单服应用zoneid可以不传值,系统默认为0;自2012年8月16日起,所有新接入支付的应用都必须传zoneid)。
在发货server配置页面,必须配置同样的大区ID号。回调发货的时候,根据ID调用应用对应的发货server IP,实现分区发货。

providetype string 发货类型,这里请传入2。

0表示道具购买,1表示每日礼包营销活动中的道具赠送,2表示交叉营销任务集市中的奖励发放。

sig string 请求串的签名,由需要签名的参数生成。

(1)签名方法请见文档:腾讯开放平台第三方应用签名参数sig的说明
(2)按照上述文档进行签名生成时,需注意回调协议里多加了一个步骤
在构造源串的第3步“将排序后的参数(key=value)用&拼接起来,并进行URL编码”之前,需对value先进行一次编码(编码规则为:除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”)。
(3)以每次接收到的参数为准,接收到的所有参数除sig以外都要参与签名。为方便平台后续对协议进行扩展,请不要将参与签名的参数写死。

3 请求示例

回调任务集市V2发货请求的签名生成较为复杂,许多应用在此出错,因此下面演示了sig签名的生成细节。开发者可以用下面的示例来验证sig的详细过程,但不能直接复制。

第一步: 应用接收到腾讯平台发送过来的请求
该请求通过平台发送,因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码(这一点请开发者关注,在回调协议中这里比较特殊)。
请求示例如下:
http://IP:9001/cgi-bin/provide_award?appid=15499&openid=00000000000000000000000014111111&contractid=10&
billno=-APPDJ100-20121010-80983&payitem=G001*10*10&version=v3&zoneid=0&providetype=2&ts=1331561610&
sig=wc6CcmOtN2eaIG5xuLRnAEgGv%2Bo%3D
特别提示:
1. 示例中的IP即买方应用在“我是买家”的“发货配置管理”页面中配置的发货服务器IP。
2. 示例中的红色部分为买方应用在“发货配置管理”页面中配置的奖励道具“发货URL”,供腾讯发货时调用。

第二步: 应用对该请求进行解析,根据得到的请求源参数来计算sig
对上面的请求进行解析,得到源参数如下:

method: GET
url_path: /cgi-bin/provide_award
假设appkey为:123456789876543


请求源参数以及对应的值为:
(注意:请以接收到的参数为准,除sig外的所有参数都需要参与签名。请仔细核对,如果拆分结果不对,则后面的步骤都是错误的。) 
appid : 15499
openid : 00000000000000000000000014111111
contractid : 10
billno : -APPDJ100-20121010-80983
payitem : G001*10*10
version : v3
zoneid : 0
providetype : 2
ts : 1331561610


需特别说明的是在回调发货协议中,在进行签名生成时,回调协议里多加了一个步骤:
在构造源串的第3步之前(sig生成通用步骤说明详见这里),需对value先按照如下编码规则进行编码(注意这里不是urlencode):
除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”。


编码后的参数为:
appid : 15499
openid : 00000000000000000000000014111111
contractid : 10
billno : %2DAPPDJ100%2D20121010%2D80983
payitem : G001*10*10
version : v3
zoneid : 0
providetype : 2
ts : 1331561610


执行构造源串的第3步:“将排序后的参数(key=value)用&拼接起来,并进行URL编码”(sig生成通用步骤说明详见这里)。


则源串为:GET&%2Fcgi-bin%2Fprovide_award&appid%3D15499%26billno%3D%252DAPPDJ100%252D20121010%252D80983%26
contractid%3D10%26openid%3D00000000000000000000000014111111%26payitem%3DG001%2A10%2A10%26
providetype%3D2%26ts%3D1331561610%26version%3Dv3%26zoneid%3D0


密钥为:123456789876543&

根据HMAC-SHA1加密算法将源串以及密钥进行加密,然后对加密后的字符串经过Base64编码后,得到的Sig的值。

生成的签名为:wc6CcmOtN2eaIG5xuLRnAEgGv+o=
 
第三步: 应用将自己生成的sig与腾讯支付后台发送的请求中的sig进行比对

注意: 应用接收到的腾讯支付平台发送过来的请求后,请先对请求中的sig值做一次URL解码;
然后再将解码后的sig值与应用自己生成的sig值进行比对。
在PHP中,通过$_GET['sig']获取sig值,PHP语言本身对sig值进行了URL解码,不需要再次解码。

如果sig值一致,表示该请求合法,应用可以处理该请求并将结果返回给腾讯支付后台。

4 协议返回包

应用的返回包应该包含如下参数:

ret: 返回码。

msg: 错误信息。

5 协议错误码

应用的错误码应该从0开始,按照整数递增的方式进行定义,建议应用按照如下描述定义错误码:


0: 成功

1: 系统繁忙

2: token已过期

3: token不存在

4: 请求参数错误:(这里填写错误的具体参数)


6 返回示例

正确返回示例:

Content-type: text/html; charset=utf-8
{
"ret":0,
"msg":"OK"
}

错误返回示例:(开发者返回给平台的错误码一定要控制在1-200的正整数之间,否则系统会报错。)

Content-type: text/html; charset=utf-8
{
"ret":4,
"msg":"参数错误"
}


相关文档

上一步:回调任务完成通知协议说明

其他相关文档:交叉推广渠道简介_V2 | 交叉推广常见问题

以上信息是否解决您的问题?

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部