SDK服务端接入说明文档

1 接入必读

• 接口协议:HTTP
• HTTP method:POST
• content-type:application/json;
• 数据格式:JSON格式（UTF-8编码）

2 校验码规则

• 未特殊说明时，所有接口都需要按照如下校验码规则进行相关Header预置和校验

• 校验码 Header 介绍
  注意：platform-auth-version和content-encrypt-type都需要写

  platform-auth-version:固定写死 v3  (旧版标识)
  content-encrypt-type:固定写死 v3 （新版标识）
  platform-auth-timestamp:服务器时间戳，毫秒数
  platform-auth-key-id:秘钥keyId，第三方平台由GSC平台统一进行分配； 游戏产品接入以平台的productId+localeId进行替代（如GMT接入、登录校验及充值发货等）；
  platform-auth-checksum:请求数据计算后的校验码

• 校验码原理及作用
  校验码即 platform-auth-checksum 是为了防止双方通信过程中交换的数据被篡改的一种通用校验方式。 由交换数据双方按照某种规则组装生成请求明文数据， 然后追加上当前时间戳和双方协商好的秘钥[需要线下获取] ，生成校验码明文， 再通过对明文进行散列值计算获取到数据指纹即校验码， 请求方把时间戳、校验码版本号、秘钥ID以及校验码放到Header头中发送给服务方，服务方获取后再次按照相同进行计算数据指纹， 通过比较自己生成和请求方传递过来得数据指纹是否一致来确定数据是否合法。
• 校验码明文
  本次请求body体中的数据
• 散列值计算
  校验码散列值算法：MD5， 注意取32位md5，并转小写。
• 示例
  请求body中的json如下

{"productId":"20000099","localeId":"01"}

假设平台分配的产品和发行地域为20000099和01， 当前的毫秒时间戳为:1600422195516, key(秘钥)为:eea2e42511c3294d47b4d2deaf4ea33c
组装后的校验码明文串如下（注意原始数据和时间戳以及密码key之间通过&符号连接）：

{"productId":"20000099","localeId":"01"}&1600422195516&eea2e42511c3294d47b4d2deaf4ea33c

生成校验码如下

203a8da1b841c19673518b5cc3419ab6

注意：此时该请求的header头的四个校验码相关的header值如下

platform-auth-version:v3
content-encrypt-type:v3
platform-auth-timestamp:1600422195516
platform-auth-key-id:2000009901
platform-auth-checksum:203a8da1b841c19673518b5cc3419ab6

3 登录

3.1 登录验证接口

基本信息

Path： /api/v2/server/user/auth
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

游戏服务端登录验证，注意：header中需要增加platform-auth-token

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/auth

响应内码介绍：

请求参数

Headers

Body

返回数据

返回示例：

3.2 获取当前登录用户绑定列表接口

基本信息

Path： /api/v2/server/user/bind/list
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

游戏服务端登录验证，注意：header中需要增加platform-auth-token

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/bind/list

响应内码介绍：

请求参数

Headers

Body

返回数据

返回示例：

4 发货

4.1 充值发货接口

基本信息

• Path: 游戏服发货地址?service=recharge.notify&server=游戏服ID
  Method： POST
  接口描述：
  SDK平台服务端 -> 游戏服务端
  该接口由游戏按规范提供，王牌运营技术平台通过该接口实现游戏充值发货功能

• 安全验证
  游戏需验证订单金额(chargePrice)和游戏内该商品价格是否相等，如果不相等，应该不予发货，返回“商品异常”即可；
  为了保证数据安全性，建议游戏服务器对平台的请求IP地址做鉴权处理，需要认证的IP详见附录；
  游戏发货时要判断下单价格和商品ID相匹配，才能发货，否则不发货。比如6480钻石的价格是648元人民币，商品ID是com.shangpin.rmb648，当通知游戏发货的价格变为1元，商品ID不变的时候，应拒绝发货返回“商品异常”，不能仅判断商品ID去发货。
  游戏发货时需要判断用户ID[userId]和角色ID[roleId]是否匹配（即判断该角色ID是否属于该用户ID），防止出现跨平台作弊充值的情况；若出现该情况请返回指定的响应码（1006）

• 重试机制
  因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知，需要运营人员手动在GSC上进行手动“通知发货”；因涉及重新通知，因此需要研发确保相同平台侧的订单号(orderId)若已经正常发货则不可重复发货，此时返回0002即可。

• actualPrice 实际支付金额，默认和下单金额相同，当在王牌计费平台进行打折时，才会与下单金额不同；

• callbackPrice 计费商回调计费金额，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的金额； 可能为空，如无特殊需求，研发侧可以忽略该字段。
• callbackCurrencyType 计费商回调计费货币，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的货币； 可能为空，如无特殊需求，研发侧可以忽略该字段。

响应内码介绍：

请求参数

Headers

Body

返回数据

请求示例：

{
"orderId": "0992023100811105979700",
"orderType": "1",
"orderSource": "1",
"testOrder": "0",
"serviceId": "2000003431014300000",
"channelId": "3101430031014300",
"deviceGroupId": "0000",
"localeId": "01",
"userId": "90099910335DD23341995A944A112D5ACAA329E2",
"serverId": "10002",
"roleId": "1",
"propId": "1001",
"payChannelId": "210339000014000051014300",
"chargePrice": "64800",
"actualPrice": "64800",
"currencyType": "1",
"extendParams": "{\"innerOrder\":\"ddddddd\",\"GGGGG\":\"ggggg\"}",
"rechargeRebate": null
}

4.2 退费通知接口

基本信息

• Path: 游戏服发货地址?service=refund.notify&server=游戏服ID
  Method： POST
  接口描述：
  SDK平台服务端 -> 游戏服务端
  该接口由游戏按规范提供，王牌运营技术平台通过该接口实现游戏退费通知

• 重试机制
  因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知，需要运营人员手动在GSC上进行手动“通知发货”；因涉及重新通知，因此需要研发确保相同平台侧的订单号(orderId)若已经正常发货则不可重复发货，此时返回0002即可。

• actualPrice 实际支付金额，默认和下单金额相同，当在王牌计费平台进行打折时，才会与下单金额不同；

• callbackPrice 计费商回调计费金额，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的金额； 可能为空，如无特殊需求，研发侧可以忽略该字段。
• callbackCurrencyType 计费商回调计费货币，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的货币； 可能为空，如无特殊需求，研发侧可以忽略该字段。

响应内码介绍：

请求参数

Headers

Body

返回数据

请求示例：

{
"orderId": "0992023100811105979700",
"orderType": "1",
"orderSource": "1",
"testOrder": "0",
"serviceId": "2000003431014300000",
"channelId": "3101430031014300",
"deviceGroupId": "0000",
"localeId": "01",
"userId": "90099910335DD23341995A944A112D5ACAA329E2",
"serverId": "10002",
"roleId": "1",
"propId": "1001",
"payChannelId": "210339000014000051014300",
"chargePrice": "64800",
"actualPrice": "64800",
"currencyType": "1",
"extendParams": "{\"innerOrder\":\"ddddddd\",\"GGGGG\":\"ggggg\"}",
"rechargeRebate": null
}

4.3 礼包码发货接口

基本信息

• Path: 游戏服发货地址?service=giftcode.notify&server=游戏服ID
  Method： POST
  接口描述：
  SDK平台服务端 -> 游戏服务端
  该接口由游戏按规范提供，王牌运营技术平台通过该接口实现礼包兑换发货功能；
• 安全验证
  游戏需验证每个角色每个礼包码24小时内最多只能发一次货，防止重试机制导致多次发货；
  为了保证数据安全性，建议游戏服务器对平台的请求IP地址做鉴权处理，需要认证的IP详见附录；
  游戏发货时需要判断用户ID[userId]和角色ID[roleId]是否匹配（即判断该角色ID是否属于该用户ID），防止出现跨平台作弊充值的情况；若出现该情况请返回指定的响应码（1006）
• 重试机制
  因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知；因涉及重新通知，有可能研发侧已经给玩家发过该礼包，需要给平台返回对应的状态码0002。 注意：需要游戏方面对礼包发放进行判断。同一个角色+同一个礼包码，24小时内最多能领取一次，不能重复发。避免在特殊情况下可能会给玩家重复发礼包。

响应内码介绍：

请求参数

Headers

Body

返回数据

返回示例：

5 预约

5.1 预约渠道查询

基本信息

Path： /api/v2/server/user/appintment/query
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

若游戏需要用户是否是预约用户，以及为预约用户发奖，需要调用该接口；
是否是预约用户的状态，平台侧从OB开始默认保留45天，45天后预约状态将返回空数组，若45天后还需要获取用户预约状态需要线下联系平台技术支持进行数据导出；

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/appintment/query

响应内码介绍：

请求参数

Headers

Body

返回数据

返回示例：

5.2 预约用户发奖

基本信息

Path： /api/v2/server/user/appintment/deliver
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

该接口由王牌运营技术平台提供，游戏服务端进行调用， 目的是实现对预约用户发放预约礼包；
注意：该接口在完成发送前校验后，会调用礼包码发货接口进行发货，请确认已经接入了平台的礼包码发货接口

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/appintment/deliver

响应内码介绍：

请求参数

Headers

Body

返回数据

返回示例：

附录一 货币类型

附录二 IP鉴权

为了保证数据安全性，游戏服务器必须要对平台的请求IP地址做鉴权处理，需要认证的IP请联系技术支持获取