一、简介
此文档描述了使用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 (需要以表单的形式提交 content-type=application/x-www-form-urlencoded） |
| 返回信息格式 | 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与此字段是否相等防止客户端冒充其它用户 |
请求示例：
$ curl -s -XPOST -H ‘content-type:application/x-www-form-urlencoded’ ‘https://api.wingsdk.com/cpapi/v2/user/authorize.do’ -d ‘appId=39a59e6182b911eebb5a02c85f0429f5&osign=2df4b4da628ff9e9da8ade02d5f9bd94&token=30_o1hgud5ogc9CSlgwul4AEaFr8jS0g3sD’
2.2 WINGSDK后台验证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 | Y | 第三方支付后台配置的商品基准货币价格，单位（元）; 如果非商品购买（如预点卡支付，短信充值、充值金额由玩家定义），此字段为0 |
| defaultCurrency | String(32) | Y | 第三方支付后台配置的商品价格使用的基准货币 |
| Double | N | 即将废弃，请勿使用 用户支付的本地货币金额，单位（元）；实际支付金额，如果商品有打折，这个金额是折后的价格，请勿根据此参数设定发货数量 |
|
| String(32) | N | 即将废弃，请勿使用 用户支付时候使用的本地货币币种; 如果非商品购买（如点卡支付，充值金额由玩家定义），此字段为WINGSDK后台设置的支付渠道对应的基准货币 |
|
| gameAmount | Int | Y | 游戏币数量，如钻石数，金币数 |
| gameCurrency | String(32) | Y | 游戏币种，如钻石，金币，元宝 |
| Double | N | 即将废弃，请勿使用 将本地货币金额转换成美元（$）的商品金额（精确至小数点后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 | 结果描述 |
4.3 admob激励广告奖励通知接口定义
接口说明：
| 接口相关 | 说明 |
|---|---|
| 接口提供方 | CP后台 |
| 接口调用方 | WA平台 |
| 接口实现方式 | HTTP/POST |
| 接口描述 | 玩家观看完激励广告后，WA平台通知CP对玩家进行奖励 |
| 生产环境 | CP自定义，配置到SDK后台即可。 |
| 支持Http Method | POST |
| 请求信息格式 | application/x-www-form-urlencoded |
| 返回信息格式 | JSON |
接口调用说明
连续通知3次，都失败则不再通知。
输入参数说明：
| 参数名 | 类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| appId | String(32) | Y | 应用 ID |
| transactionId | String | Y | 广告奖励订单流水号 |
| adName | String | Y | 广告名称 |
| rewardItem | String | Y | 奖励物品标识：钻石，元宝等 |
| rewardAmount | Int | Y | 奖励物品数 |
| userId | Long | Y | 玩家的WA平台用户ID |
| serverId | String | N | 玩家所在的游戏服 |
| extInfo | String | N | 扩展字段，游戏在客户端观看视频前通过API传给SDK，原样返回给CP后台 |
| osign | String | Y | 签名，MD5( appId + transactionId + adName+ rewardItem + rewardAmount + userId + serverId+ extInfo+ secureKey ) 参数无值则使用””(空字符串)代替参与签名，secureKey 服务端验证key,在SDK后台配置 |
返回结果说明(JSON格式):
失败返回错误码，请参照附录1的状态码说明表；
| 参数名 | 类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| code | Int | Y | 状态码，请参照状态码说明表； |
| msg | String | Y | 结果描述 |
| deliverStatus | int | N | 奖励发货状态 0:未知 1:发货成功 2:发货失败 CP在接受到发货通知后，如果能同步确定发货状态，可以返回此状态，如果不能确定发货状态，可以忽略此字段。 |
4.4 礼包通知接口定义
接口说明：
| 接口相关 | 说明 |
|---|---|
| 接口提供方 | CP后台 |
| 接口调用方 | WingSDK平台 |
| 接口实现方式 | HTTP/POST |
| 接口描述 | 给玩家发放礼包 |
| 生产环境 | CP自定义，配置到WingSDK后台即可。 |
| 支持Http Method | POST |
| 请求信息格式 | application/x-www-form-urlencoded |
| 返回信息格式 | JSON |
输入参数说明：
| 参数名 | 类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| appId | String(32) | Y | 应用 ID |
| giftId | String | Y | 礼包id |
| transactionId | String | Y | 唯一流水号，可根据此字段来判断是否是重复通知。 |
| userId | Long | Y | 玩家的WingSDK平台用户ID |
| serverId | String | Y | 玩家所在的游戏服 |
| osign | String | Y | 签名，MD5( appId + giftId + transactionId+ userId + serverId+ secureKey ) 参数无值则使用 “”(空字符串)代替参与签名，secureKey 服务端验证key,由运营提供 |
返回结果说明(JSON格式):
失败返回错误码，请参照附录1的状态码说明表；
| 参数名 | 类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| code | Int | Y | 状态码，200表示通知成功；400表示通知失败 |
| 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.(游戏没有区服概念时可以传”1”) |
| currentRoleId | String | Y | 当前角色Id，没有则是最近使用的角色Id |
| serverList | object | Y | 数组对象 |
| serverList为数组对象，包含数据如下，见示例 | |||
| serverId | String | Y | 服务器Id。(游戏没有区服概念时可以传”1”) |
| serverName | String | Y | 服务器名称。(游戏没有区服概念时可以传”server1”) |
| roleList | object | Y | 数组对象 |
| roleList为数组对象，包含数据如下，见示例 | |||
| roleId | String | Y | 角色Id |
| roleName | String | Y | 角色名称 |
示例：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ "code": 200, "msg": "Successful", "currentServerId": "server1", "currentRoleId": "role1", "serverList": [ { "serverId": "server1", "serverName": "1服", "roleList": [ { "roleId": "role1", "roleName": "青铜" }, { "roleId": "role2", "roleName": "青铜2" } ] } ] } |
六、消息推送
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 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
secretKey: test_secretKey General Request URL:https://api.wingsdk.com/cpapi/v1/user/push.do Request Method:POST Request Headers Content-Type:application/json;charset=utf-8 appId=test-appId sign=210b46fa81ce1b26a69ed466c53be7b6 Request Body {"message":{"titile":"test-title","body":"test-body","platform":0,"priority":1,"pushType":0,"uids":[123,456]}} Response { "code":200, "message":"success" } 签名说明： 1) 签名待加密字符串 test-appId{"message":{"titile":"test-title","body":"test-body","platform":0,"priority":1,"pushType":0,"uids":[123,456]}}test_secretKey 2) 小写MD5加密 MD5(test-appId{"message":{"titile":"test-title","body":"test-body","platform":0,"priority":1,"pushType":0,"uids":[123,456]}}test_secretKey) = 210b46fa81ce1b26a69ed466c53be7b6 |
附录1：返回状态码说明
通用返回状态码说明（参考了Http状态码设计）：
| 状态码code | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 错误请求：请求参数有错，头信息有误等，导致请求无法被正确理解 |
| 401 | 请求未认证：访问受限资源是缺少认证信息，或者认证未通过 |
| 403 | 禁止访问：由于应用上下文原因或请求端上下文的原因被禁止访问资源，例如IP限制等； |
| 404 | 找不到被访问资源：接口不存在、页面不存在或对应的业务实体找不到 |
| 500 | 服务器内部故障 |
| 501 | 所请求接口或页面未实现 |
平台自定义状态码说明
| 状态码code | 说明 |
|---|---|
| 4010 | 无效appId: appId不存在或未开启 |
| 4011 | 无效osign：osign校验失败 |
| 4079 | 推送配置无效，APNS证书及密码(IOS推送)或Firebase(Android推送)认证 Key未配置 |