回调赠送道具发货URL的协议说明_V3.0

特别声明
本文档基于V3版OpenAPI协议。

本接口适用于多种场景:
(1)抽奖送礼包
应用中提供抽奖按钮,用户消耗Q点即可点击按钮进行抽奖,如果用户中奖的是道具,腾讯将回调赠送道具发货URL(需按照本协议进行开发),将道具发放给用户。

本接口属于“抽奖送礼包”活动的最后一个环节。

(2)开通包月送礼包
用户触发领取道具条件后,腾讯将回调赠送道具发货URL(需按照本协议进行开发),将道具发放给用户。

本接口属于下面的流程图所示最后一个环节。
marketing_25.png

(3)单笔消耗送礼包
用户在应用中单次消耗Q点达到一定数额后,如果送给用户的礼包中有道具,腾讯将回调赠送道具发货URL(需按照本协议进行开发),将道具发放给用户。

本接口为“单笔消耗送礼包”活动中给用户赠送道具礼包时调用的接口。

目录

1 什么是赠送道具发货URL?

应用中有时需要举办活动,符合条件的用户将获赠礼包(例如游戏道具/物品),用于提升用户活跃度或提升用户付费群。
赠送道具发货URL用来给腾讯台后台回调。用户完成任务后,腾讯后台将回调该URL给用户发放道具/物品。
赠送道具发货URL在应用接入营销活动时注册,注册地址为管理中心“支付结算”tab下“营销接入”类的“发货配置”页面。

2 协议参数

回调赠送道具发货URL由腾讯发起,腾讯发送给应用的请求中将包含下面所述参数,应用需根据协议的参数进行请求解析,执行发放操作,返回相应的返回包。
请开发者特别关注:
平台后续可能对协议进行扩展,因此请不要将参与签名的参数写死。计算签名时,请以每笔交易接收到的参数为准,接收到的所有参数除sig以外都要参与签名。

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

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

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

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

payitem string 物品信息。使用ID*price*num的格式。

ID表示物品ID,price表示单价(以Q点为单位,单价最少不能少于2Q点。1Q币=10Q点),num表示数量。
例如物品1的ID为G001,该物品的单价为10Q点,数量为1,则payitem为:G001*10*1。
注:一个礼包中若包含多种物品,物品是分开发放的,不支持批量发放,即一个请求只发放一种物品,所以,payitem里始终只有一种物品的信息。因此如果是多个物品,建议在申请活动的配置礼包环节,将多个物品放在一起配置一个ID。

discountid string 赠送道具/物品的营销活动ID。

登录op.open.qq.com后进入管理中心,选择进入1个应用后,在“支付结算”tab下的“营销接入”中提交活动申请,即可获取活动批号信息。

token string (1)开通包月送礼包活动中,该token为应用调用v3/pay/get_token接口获取的领取道具/物品的token。

(2)抽奖送礼包和单笔消耗送礼包活动中,该token为应用调用v3/pay/buy_goods接口获取的领取道具/物品的token。
该token有效期为72小时。必须在获取到token后的72小时内传递该token,否则将会返回token不存在的错误。

billno string 赠送道具流水号(64个字符长度。该字段和openid合起来是唯一的)。
version string 协议版本号,由于基于V3版OpenAPI,这里一定返回“v3”。
zoneid string 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。
回调发货的时候,根据这里填写的zoneid实现分区发货。
注:2013年后接入的寄售应用,此参数将作为分区发货的重要参数,如果因为参数传错或为空造成的收入损失,由开发商自行承担。

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

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

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

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

3 请求示例

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

第一步: 应用接收到腾讯支付后台发送过来的请求
该请求通过后台发送,因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码(这一点请开发者关注,在回调协议中这里比较特殊)。
请求示例如下:
http://ip/cgi-bin/temp.py?openid=test001&appid=33758&ts=1328855301& discountid=UM201203071185&payitem=323003*8*1&token=53227955F80B805B50FFB511E5AD51E025360&billno=-APPDJT18700-20120210-1428215572&version=v3&zoneid=1&providetype=1&sig=5jZw1DqQ6kzKyjk6mnBLM64nLRQ%3D

特别提示:
1. 示例中的IP即营销接入时配置的发货服务器IP(详见营销发货配置)。
2. 示例中的红色部分为营销发货配置时应用指定的赠送道具发货URL,供腾讯发货时调用。
3. 为了避免道具赠送接口影响正常支付接口,建议开发者另外配置道具赠送发货服务器。

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

method: GET
url_path: /cgi-bin/temp.py
假设appkey为:12345f9a47df4d1eaeb3bad9a7e54321


请求源参数以及对应的值为:(注意:请以接收到的参数为准,除sig外的所有参数都需要参与签名)
appid: 33758
billno: -APPDJT18700-20120210-1428215572  
discountid: UM201203071185
openid: test001
payitem: 323003*8*1
providetype: 1
token: 53227955F80B805B50FFB511E5AD51E025360
ts: 1328855301
version: v3
zoneid: 1


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


编码后的参数为:
appid: 33758
billno: %2DAPPDJT18700%2D20120210%2D1428215572 
discountid: UM201203071185
openid: test001
payitem: 323003*8*1
providetype: 1
token: 53227955F80B805B50FFB511E5AD51E025360
ts: 1328855301
version: v3
zoneid: 1


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


则源串为:GET&%2Fcgi-bin%2Ftemp.py&appid%3D33758%26billno%3D%252DAPPDJT18700%252D20120210%252D1428215572%26
discountid%3DUM201203071185%26openid%3Dtest001%26payitem%3D323003%2A8%2A1%26providetype%3D1%26
token%3D53227955F80B805B50FFB511E5AD51E025360%26ts%3D1328855301%26version%3Dv3%26zoneid%3D1
密钥为:12345f9a47df4d1eaeb3bad9a7e54321&


生成的签名为:5jZw1DqQ6kzKyjk6mnBLM64nLRQ=



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

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

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

4 协议返回包

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

ret: 返回码。

msg: 道具发放操作的结果,成功为“OK”,失败则表明错误原因(必须使用utf8编码)。

腾讯设置的调用第三方发货超时是2秒钟,请第三方注意超时时间设置不要超过2秒,否则腾讯后台将返回“系统繁忙”的错误消息。

5 协议错误码

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


0: 成功

1: 系统繁忙

2: token已过期

3: token不存在

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

6 返回示例

正确返回示例:

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


错误返回示例:

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

相关文档

(1)抽奖送礼包活动
上一步:fusion2.dialog.lottery

其他相关文档:抽奖送礼包


(2)开通包月送礼包活动
上一步:fusion2.dialog.openVipGift(开通黄钻弹框)|GameAPI.GameVIPAction.show(开通蓝钻弹框)

其他相关文档:开通包月送礼包


(3)单笔消耗送礼包活动

其他相关文档:单笔消耗送礼包

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部