服务端接口文档

服务端接口文档

wapublisher No Comment
Uncategorized

一、简介

此文档描述了使用SDK的CP(内容提供商)用到的与WINGSDK后台交付的所有接口的详细定义。
接口分两种:
1、WINGSDK后台实现,CP后台调用。
2、CP后台实现,WINGSDK后台调用。

名词说明:

名词 说明
CP 内容提供商(Content Provider)游戏、应用等
第三方平台登录 通过第三方社交平台的OAuth authentication登录第三方帐号,并绑定WINGSDK帐号
游客登录 通过设备信息登录帐号,设备信息与WINGSDK帐号绑定
应用内登录 用户通过CP提供的帐号系统登录,然后CP通过WINGSDK提供的接口将用户绑定WINGSDK的帐号,以便CP使用SDK提供的服务

二、登录

后台-登录
注:实线表示请求的发起,虚线表示请求的返回

登录流程说明:
1)SDK客户端封装了其它不同第三方登录平台,用户登录后,SDK会返回后台验证的参数
2)客户端去WINGSDK服务端获取在线token,服务端先去第三方登录平台验证accessToken,获取第三方用户信息,并返回对应的WINGSDK用户ID和token给客户端
3)客户端通过SDK API 获取token,userId,puserId,platform等用户信息,然后向游戏后台发送登录请求
4)游戏后台调用WINGSDK提供的接口验证用户登录,请求参数见下
5)如果是应用内登录,以上登录流程图可以将第三方登录平台当成CP服务端,CP需要提供验证用户帐号的接口供WINGSDK后台调用。

2.1 CP验证用户登录接口

接口说明:

接口相关 说明
接口提供方 WINGSDK平台
接口调用方 CP
接口实现方式 HTTP/POST
接口描述 登录流程图第8步,CP验证WINGSDK token是否合法,是否与ghwUserId匹配
生产环境 https://api.wingsdk.com/cpapi/v2/user/authorize.do
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
token String(100) Y WINGSDK验证token,从客户端获取
appId String(100) Y WINGSDK应用ID
osign Stirng(100) Y MD5(
appId+
token +
secureKey
),如果有参数为空,用空字符串””替代,secureKey (登录验证key,即SDK后台对应的秘钥)由运营人员在SDK后台获取

返回格式

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照状态码说明表
msg String(32) Y 结果描述
error String(32) N 验证错误描述信息
ghwUserId Long N 验证成功后返回ghwUserId,CP通过检验客户端的ghwUser与此字段是否相等防止客户端冒充其它用户

2.2 WINGSDK后台验证CP用户登录信息接口(应用内登录)

登录验证流程图:
后台-CP验证用户登录接口

接口说明:

接口相关 说明
接口提供方 CP
接口调用方 WINGSDK平台
接口实现方式 HTTP/POST
接口描述 应用内登录,登录流程第4步,WINGSDK验证CP用户信息时调用。WINGSDK通过accessToken和extInfo 验证用户信息。accessToken由客户端完成CP帐号系统登录后获取,WINGSDK通过accessToken和extInfo去CP后台验证用户信息
生产环境 地址由CP提供给运营人员,运营人员将地址配置在SDK管理后台
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
accessToken String N CP帐号登录验证token,从客户端获取
appId String Y WINGSDK应用ID
extInfo String N CP自定义的内容,原样返回
osign Stirng Y MD5(
appId+
accessToken+
secureKey+
extInfo
),如果有参数为空,用空字符串””替代,secureKey (登录验证key,即SDK后台对应的秘钥)由运营人员在SDK后台获取

返回格式

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照状态码说明表
msg String(32) Y 结果描述
error String(32) N 验证错误描述信息
cpUserId String Y CP的用户ID。code=200时返回此字段

三、支付流程

3.1 概述

要使用Wingsdk的支付功能,首先要在SDK后台添加商品列表以及要使用的第三方支付平台信息。每个支付平台的商品列表都是可以单独配置的。
Wingsdk支付过程中,对第三方支付平台的信息都做了屏蔽,也就是说,所有第三方支付平台以及对应的配置信息对CP来说都是透明的。CP在客户端使用的商品列表是wingsdk平台独有的商品Id,和第三方支付后台的商品Id的不一样,但是有映射关系(运营人员在SDK管理后台维护),即wingsdk商品Id+支付渠道标识可以确认一个第三方商品Id,用户选择某一个商品进行购买后,需要选择第三方支付渠道(google、apple等),wingsdk首先会使用wingsdk平台的商品id下订单,之后会使用对应的第三方商品id到第三方(google,apple等)进行支付。支付成功,Wingsdk通知CP发货也是使用Wingsdk的商品Id。
后台-支付流程

3.2 CP发货通知接口

该接口由移动平台定义,CP负责实现
发货接口调用说明
1.WINGSDK服务端系统订单在支付完成之后将实时通知到 CP 发货接口。

2.WINGSDK服务端系统通知 CP 发货时,若未接收到 CP 接口成功回复,该笔订单将重复通知 3次。

3.WINGSDK服务端系统在重复 3 次通知 CP 发货的过程中,若都未收到 CP 的成功回复,订单将进入后台轮询通知发货。每次轮询将有 3 次的通知;第一次轮询为订单新建之后的 15 分钟;之后每小时轮询通知一次; 24 小时之后隔日通知一次。

4.WINGSDK服务端系统收到 CP 接口返回 code=200 时将不再对该笔订单做重复通知。

5.WINGSDK服务端系统若对某笔订单重复通知,则 CP 需自行判断是否已经发货,若已发货则接
口直接返回 code=200,当作成功处理。

6.WINGSDK回调服务器的 IP 地址为 xx.xx.xx.xx,CP 可以考虑在回调接口中做该 IP 的白名单匹
配(可选)。不过 IP 地址可能存在变更,如有变更,将在SDK管理后台上另行通知

URL:http://****/deliver.do
支持Http Method:POST
返回信息格式:Json

输入参数说明:

参数名 类型 是否必须 参数说明
appId String(32) Y WINGSDK 应用 ID
orderId String Y WINGSDK订单号
defaultAmount Double N 第三方支付后台配置的商品基准货币价格,单位(元);
如果非商品购买(如预点卡支付,短信充值、充值金额由玩家定义),此字段为0
defaultCurrency String(32) N 第三方支付后台配置的商品价格使用的基准货币
payAmount Double Y 用户支付的本地货币金额,单位(元);实际支付金额,如果商品有打折,这个金额是折后的价格,请勿根据此参数设定发货数量
currencyCode String(32) N 用户支付时候使用的本地货币币种;
如果非商品购买(如点卡支付,充值金额由玩家定义),此字段为WINGSDK后台设置的支付渠道对应的基准货币
gameAmount Int Y 游戏币数量,如钻石数,金币数
gameCurrency String(32) Y 游戏币种,如钻石,金币,元宝
dollarAmount Double Y 将本地货币金额转换成美元($)的商品金额(精确至小数点后4位),如果没有本地货币,使用基准货币替代。
productId String(32) N WINGSDK后台定义商品Id
如果非商品购买(如点卡支付,充值金额由玩家定义),此字段为
具体值:customAmountProduct,这类购买CP可以通过gameAmount给玩家发相应的游戏币
payChannel String Y 支付渠道:APPLE 、GOOGLE
userId Long Y 用户ID,WINGSDK游戏平台userId
serverId String Y 服务器ID
orderStatus Int Y 订单状态:
1:成功
2:失败
5:退款
6:争议
statusMsg String Y 订单状态说明
ots Int Y 订单创建时间戳(秒)
payDoneTime String N 支付完成时间(秒),已转成字符串,支付失败为空
extInfo String N CP 扩展信息字段,限长512,创建订单时通过客户端SDK传入,发货通知原样返回给CP。CP可以添加任意自定义的字段(JSON格式),用于检验订单信息或扩展其它功能,不超过长度限制即可。
如果CP的通知发货地址是动态变化的(比如每个服务区的地址都不一致),可以添加参数deliverUrl;
添加merId字段(选填),收款商户ID,使用场景:同一个支付渠道下有多个不同的收款验证信息(或收款帐号)。如果是APPLE支付渠道,merId使用客户端bundleId。
参考格式
{
“deliverUrl”:” http://game.com/deliver.do”,
“merId”:”payChanelMerId”
}
osign String Y 签名,MD5(
appId+
orderId+
defaultAmount+
defaultCurrency+
gameAmount+
gameCurrency+
productId+
userId+
serverId+
orderStatus+
ots +
payDoneTime +
extInfo +
paySecretKey
)
payDoneTime、extInfo参数无值则使用””(空字符串)代替参与签名
paySecretKey(支付验证key,即SDK后台对应的支付秘钥)由运营人员在SDK后台获取

返回结果说明:

参数名 类型 是否必须 参数说明
appId String(32) N 应用 ID
code Int Y 通知结果状态码,200表示通知成功
msg String(32) Y 结果描述
userId Long N 用户ID
deliverStatus Int N 订单发货状态
0:未知
1:发货成功
2:发货失败
CP在接受到发货通知后,如果能同步确定发货状态,可以返回此状态,如果不能确定发货状态,可以忽略此字段。CP也可以通过发货结果异步回调接口通知SDK发货结果

3.3 发货结果异步回调接口(可选)

接口说明:

接口相关 说明
接口提供方 WINGSDK平台
接口调用方 CP
接口实现方式 HTTP/POST
接口描述 1.CP在向用户发货成功后,将发货结果反馈给WINGSDK平台
2.CP在通知失败情况下(通知结果返回code值非200),需要重试通知
3.WINGSDK对发货成功的订单不再做修改发货状态(发货成功/发货失败),但发货失败的订单可以再修改发货状态。
4.CP对通知结果状态码code=200的订单不需要再重复通知。
生产环境 https://api.wingsdk.com/cpapi/v1/deliver_callback.do
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
appId String(32) Y 应用 ID
orderId String Y WINGSDK订单号
productId String(32) Y 商品Id
如果非商品购买(如点卡支付,充值金额由玩家定义),此字段为
具体值:customAmountProduct
userId Long Y 用户ID,WINGSDK游戏平台userId
serverId String N 服务器ID
deliverStatus Int Y 订单发货状态
1:发货成功
2:发货失败
statusMsg String N 订单状态说明
osign String Y 签名,MD5(
appId+
orderId+
productId+
userId+
serverId+
deliverStatus +
paySecretKey
)
serverId等参数无值则使用””(空字符串)代替参与签名
paySecretKey(订单验证key,即SDK后台对应的支付秘钥)由运营人员在SDK后台获取

返回结果说明:

参数名 类型 是否必须 参数说明
code Int Y 通知结果状态码,200表示通知成功
msg String(32) Y 结果描述

3.4 退款通知接口(可选)

该接口由移动平台定义,CP负责实现
退款通知接口调用说明
1.WINGSDK服务端每天定时任务查询第三方支付平台退款订单列表,目前只支持Google play

2.用于Google支付渠道的服务邮箱账号需拥有查看财务的权限。

3.WINGSDK服务端系统通知 CP退款订单时,若未接收到 CP 接口成功回复,该笔退款订单将重复通知5次。每隔30分钟通知一次

4.WINGSDK服务端系统收到 CP 接口返回 code=200 时将不再对该笔退款订单做重复通知。

5.WINGSDK服务端系统若对某笔退款订单重复通知,则 CP 需自行判断是否已经处理,若已处理则接口直接返回 code=200,当作成功处理。

6.WINGSDK回调服务器的 IP 地址为 xx.xx.xx.xx,CP可以考虑在回调接口中做该 IP 的白名单匹配(可选)。不过 IP 地址可能存在变更,如有变更,将在SDK管理后台上另行通知

URL:http://****/refund_notify.do
支持Http Method:POST
返回信息格式:Json

输入参数说明:

参数名 类型 是否必须 参数说明
appId String(32) Y WINGSDK应用 ID
orderId String Y WINGSDK订单号
defaultAmount Double N 第三方支付后台配置的商品基准货币价格,单位(元);
如果非商品购买(如预点卡支付,短信充值、充值金额由玩家定义),此字段为0
defaultCurrency String(32) N 第三方支付后台配置的商品价格使用的基准货币
payAmount Double Y 用户支付的本地货币金额,单位(元)
currencyCode String(32) N 用户支付时候使用的本地货币币种
如果非商品购买(如点卡支付,充值金额由玩家定义),此字段为WINGSDK后台设置的支付渠道对应的基准货币
gameAmount Int Y 游戏币数量,如钻石数,金币数
gameCurrency String(32) Y 游戏币种,如钻石,金币,元宝
dollarAmount Double Y 将本地货币金额转换成美元($)的商品金额(精确至小数点后4位),如果没有本地货币,使用基准货币替代。
productId String(32) N WINGSDK后台定义商品Id
如果非商品购买(如点卡支付,充值金额由玩家定义),此字段具体值:customAmountProduct,这类购买CP可以通过gameAmount给玩家发相应的游戏币
payChannel String Y 支付渠道:APPLE 、GOOGLE
userId Long Y 用户ID,WINGSDK游戏平台userId
serverId String Y 服务器ID
orderStatus Int Y 订单状态
1:成功
2:失败
statusMsg String Y| 订单状态说明
ots Long Y 订单创建时间戳(秒)
payDoneTime String N 支付完成时间(秒),已转成字符串,支付失败为空
purchaseTime Long N 第三方支付平台购买时间(秒), 若无不返回
voidedTime Long N 第三方支付平台退款时间(秒), 若无不返回
extInfo String N CP 扩展信息,CP通过客户端SDK 传入,发货通知原样返回,CP可用此字段检验订单信息。
如果CP的通知发货地址是动态变化的(比如每个服务区的地址都不一致),可以通过此字段设置:参数格式为JSON,参数名为deliverUrl,参考格式
{
“deliverUrl”:” http://game.com/deliver.do”,
“otherInfo”:”otherInfo”,
“merId”:””
}
添加merId字段(选填),收款商户ID,使用场景:同一个支付渠道下有多个不同的收款验证信息(或收款帐号)。
如果是APPLE支付渠道,merId使用客户端bundleId
osign String Y 签名,MD5(
appId+
orderId+
defaultAmount+
defaultCurrency+
gameAmount+
gameCurrency+
productId+
userId+
serverId+
orderStatus+
ots +
payDoneTime +
purchaseTime +
voidedTime +
extInfo +
paySecretKey
)
payDoneTime、extInfo参数无值则使用””(空字符串)代替参与签名
paySecretKey(支付验证key,即SDK后台对应的支付秘钥)由运营人员在SDK后台获取

返回结果说明:

参数名 类型 是否必须 参数说明
appId String(32) N 应用 ID
code Int Y 通知结果状态码,200表示通知成功
msg String(32) Y 结果描述

四、奖励通知

4.1 邀请奖励通知接口定义

接口相关 说明
接口提供方 CP后端
接口调用方 WINGSDK平台
接口实现方式 HTTP/POST
接口描述 奖励通知调用说明:
1.WINGSDK服务端系统在用户触发奖励机制后会通知CP对指定用户发送奖励,奖励规则在SDK管理后台配置。
2.WINGSDK服务端系统通知 CP 奖励通知时,若未接收到 CP 接口成功回复,该奖励通知将重复通知 3次。
3.WINGSDK服务端系统在重复 3 次奖励通知的过程中,若都未收到 CP 的成功回复,通知将进入后台轮询通知。每次轮询将有 3 次的通知;第一次轮询为通知新建之后的 15 分钟;之后每小时轮询通知一次; 24 小时之后隔日通知一次。
4.WINGSDK服务端系统收到 CP 接口返回 code=200 时将不再对该奖励做重复通知。
5.WINGSDK服务端系统若对某笔奖励重复通知,则 CP 需自行判断是否已经发货,若已发货则接口直接返回 code=200,当作成功处理。
生产环境 CP自定义
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
appId String(32) Y 应用 ID
eventName String Y 触发奖励机制的事件名称,由运营人员配置在WINGSDK后台
installTime Long Y 被邀请者应用安装时间戳
inviteePfUserId String(32) Y 被邀请者社交平台openId
inviteeUserId Long Y 被邀请者ghwUserId
inviteeGameUserId String N 被邀请者游戏ID
inviteeServerId String N 被邀请者服务区ID,安装事件可能为空可能为空
platform String Y 社交平台标识 FaceBook, VK
rewardType String Y 奖励物品标识: 钻石,元宝等
rewardAmount Int Y 奖励物品数量
rewardId String 奖励事件唯一标识Id
userId Long Y 邀请者 ghwUserId
serverId String N 邀请者服务区Id
osign String Y 签名,MD5(
appId +
eventName +
installTime +
inviteePfUserId+
inviteeUserId +
inviteeGameUserId+
inviteeServerId +
platform+
rewardAmount +
rewardId +
userId +
serverId+
secureKey )
参数无值则使用””(空字符串)代替参与签名,secureKey 服务端验证key,在SDK后台配置(即SDK后台对应的秘钥)

返回结果说明:

参数名 类型 是否必须 参数说明
appId String(32) N
code Int Y 通知结果状态码,200表示通知成功
msg String(32) Y
userId Long N
deliverStatus Int N 奖励状态
0:未知
1: 奖励成功
2: 奖励失败
CP在接受到奖励通知后,如果能同步确定奖励状态,可以返回此状态,如果不能确定奖励状态,可以忽略此字段

4.2 视频广告奖励通知接口定义

接口说明:

接口相关 说明
接口提供方 CP后台
接口调用方 WINGSDK平台
接口实现方式 HTTP/POST
接口描述 玩家观看完广告视频后,WINGSDK平台通知CP对玩家进行奖励
生产环境 CP自定义,配置到SDK后台即可。
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
appId String(32) Y 应用 ID
viewId String Y 视频观看Id,全局唯一,每次观看至奖励一次,WINGSDK平台可能会通知多次,CP需要判断去重,避免重复发放奖励
rewardType String Y 奖励物品标识:钻石,元宝等
rewardAmount Int Y 奖励物品数量
userId Long Y 玩家的WINGSDK平台用户ID
serverId String N 玩家所在的游戏服
gameUserId String Y 玩家的角色Id
extInfo String Y 扩展字段,游戏在客户端观看视频前通过API传给SDK,原样返回给CP后台
osign String Y 签名,MD5(
appId +
viewId+
rewardType+
rewardAmount +
userId +
serverId+
gameUserId+
extInfo+
secureKey )
参数无值则使用””(空字符串)代替参与签名,secureKey 服务端验证key,在SDK后台配置(即SDK后台对应的秘钥)

返回结果说明(JSON格式):
失败返回错误码,请参照附录1的状态码说明表;

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照状态码说明表
msg String Y 结果描述

五、数据查询接口

5.1 通过第三方OPEN_ID获取WINGSDK平台用户ID

接口说明:

接口相关 说明
接口提供方 WINGSDK平台
接口调用方 CP后端
接口实现方式 HTTP/POST
接口描述 通过第三方平台openId获取WINGSDK平台的userId
生产环境 https://api.wingsdk.com/cpapi/v1/get_user_info.do
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
appId String Y WINGSDK平台分配的应用id
platform String Y 第三方平台标识: FACEBOOK、APPLE、GOOGLE、GUEST等
openId String Y 第三方平台openId
osign String Y 验证用的加密串
Md5(
appId+
appKey+ //登录验证key,注意保密
platform+
openId
)

返回结果说明(JSON格式):
失败返回错误码,请参照状态码说明表

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照状态码说明表
msg String Y 结果描述
userId Long N SDK平台用户Id

5.2 查询区服角色信息

该接口由移动平台定义,CP负责实现
查询区服信息接口调用说明
1、WA服务端系统通过WA的userId来查询用户已经玩过的区服角色以及最近玩过的区服角色。
2、Url:https://****/serverinfo.do

接口说明:

接口相关 说明
接口提供方 CP后端
接口调用方 WINGSDK平台
接口实现方式 HTTP/POST
接口描述 通过WA的userId来查询用户已经玩过的区服角色
生产环境 https://****/serverinfo.do
支持Http Method POST
返回信息格式 JSON

输入参数说明:

参数名 类型 是否必须 参数说明
appId String Y WINGSDK平台分配的应用id
userId Long Y 用户ID,WA游戏平台userId
osign String Y 验证用的加密串Md5(appId+userId+secureKey) //secureKey即SDK后台对应的登录密钥, 需运营人员在SDK后台获取

返回结果说明(JSON格式):
失败返回错误码,请参照状态码说明表

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照状态码说明表
msg String Y 结果描述
currentServerId String Y 当前服务器Id,没有则是最近登录的服务器Id,没有区服时可以传空字符串
currentRoleId String Y 当前角色Id,没有则是最近使用的角色Id,没有角色时可以传空字符串
serverList object N 数组对象(当没有服务器信息时,返回空数组:[])
serverList为数组对象,包含数据如下,见示例
serverId String N 服务器Id
serverName String N 服务器名称
roleList object N 数组对象 (当没有角色信息时,返回空数组:[])
roleList为数组对象,包含数据如下,见示例
roleId String N 角色Id
roleName String N 角色名称

示例:

六、消息推送

6.1 消息推送接口

接口说明:

接口相关 说明
接口提供方 WA平台
接口调用方 CP
接口实现方式 HTTP/POST
接口描述 可通过该接口发起推送任务,需要在sdk后台配置IP白名单后,才能正常访问此接口
生产环境 https://api.wingsdk.com/cpapi/v1/user/push.do
支持Http Method POST
报文类型 application/json; charset=utf-8
返回信息格式 JSON

请求报文头:

字段 类型 必须 参数说明
appId String Y WA应用ID
sign String Y 接口调用签名, 小写MD5(appId + body + secureKey), secureKey (登录验证key)由运营人员在SDK后台生成

body说明:

参数名 类型 是否必须 参数说明
message Object Y 消息对象
message.id String N 自定义ID,当一次推送任务需要多次请求接口时,可以设置相同的ID,标识为同一任务,便于回溯推送情况(不超过64字符)
message.title String Y 消息题目(不超过64字符)
message.body String Y 消息内容(不超过200字符)
message.platform Int Y 推送平台;0-安卓 1-IOS
message.priority String Y 推送优先级;1-低;2-中;3-高;
message.pushType Int Y 推送类型;0-自定义uid推送;1-全服推送;
message.uids List N Uid列表(最多支持1000个),当pushType为”自定义uid推送”时,该参数必须要传值。[123,456,789]

返回格式:

参数名 类型 是否必须 参数说明
code Int Y 状态码,请参照附录1
msg String(32) Y 结果描述

调用实例:

附录1:返回状态码说明

通用返回状态码说明(参考了Http状态码设计):

状态码code 说明
200 成功
400 错误请求:请求参数有错,头信息有误等,导致请求无法被正确理解
401 请求未认证:访问受限资源是缺少认证信息,或者认证未通过
403 禁止访问:由于应用上下文原因或请求端上下文的原因被禁止访问资源,例如IP限制等;
404 找不到被访问资源:接口不存在、页面不存在或对应的业务实体找不到
500 服务器内部故障
501 所请求接口或页面未实现

平台自定义状态码说明

状态码code 说明
4010 无效appId: appId不存在或未开启
4011 无效osign:osign校验失败
4079 推送配置无效,APNS证书及密码(IOS推送)或Firebase(Android推送)认证 Key未配置

Leave a Reply