SDK服务端(海外)接入说明
1. 接入必读
2. 准备工作
3. 接口说明
4. 接口
附录1
- 登录验证接口响应编码表
附录2
- 充值发货接口响应编码表
附录3
- 角色查询接口响应编码表
附录4
- 货币类型及对应ID
附录五
- ip鉴权处理

SDK服务端(海外)接入说明

1. 接入必读

该文档主要包含用户鉴权接口定义、游戏发货接口定义；

2. 准备工作

3. 接口说明

接口协议:HTTP POST; content-type设为application/x-www-form-urlencoded;
交互数据格式:Key Value格式（以UTF-8进行编码）; 数据直接通过HTTP消息体传输; 注意单次消息体大小不能大于512K。
如：
```
jsonStr={"interfaceId":"0002","tokenId":"254af9e9-9455-4bd1-83ee-00f50defdc79"}
```

4. 接口

4.1 登录验证接口

该接口由掌趣技术平台提供，负责对用户信息进行验证，该接口可以避免客户端随意修改信息的漏洞；
需要游戏服务端进行调用；

4.1.1 接口地址（旧版）
港澳台地址： https://authhk.gamesbean.net/ucenter/uMember/userLoginMgr.do
韩国地址：https://auth.fingertips.kr/ucenter/uMember/userLoginMgr.do
日本地址：https://authjp.gamesbean.net/ucenter/uMember/userLoginMgr.do
欧美地址： https://auth-us.gamesbean.net/ucenter/uMember/userLoginMgr.do
4.1.1 接口地址（新版海外整合SDK）
新版：
港澳台地址： https://authhk.gamesbean.net/v2/ucenter/account
欧美地址： https://auth-us.gamesbean.net/v2/ucenter/account
4.1.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	interfaceId	字符串	必填	接口号，固定填写0002即可
-	tokenId	字符串	必填	用户中心返回的tokenId

4.1.3 返回参数（旧版）

父节点	参数名称	类型	说明
-	status	字符串	返回状态 0：成功 1：失败
-	reset	字符串	状态内码； `1000`：接收成功；其他详见附录1
-	desc	字符串	状态描述
-	bindingMode	字符串	0为手机方式绑定；1为邮箱方式绑定
-	loginType	字符串	用户登录标识：（ 0：是第三方平台注册 1：为官网注册 2：为快速注册 9：为其它平台登录 10：为官网登录 11：为快速登录）
-	originalUserType	字符串	用户类型 0：第三方用户 1：普通官网用户 2：快登用户
-	currentUserType	字符串	用户类型 0：第三方用户 1：普通官网用户 2：快登用户
-	userPlatformId	字符串	用户系统ID 0001：官网用户 0231：Facebook用户
userInfo	id	字符串	用户id
userInfo	userName	字符串	用户名
userInfo	email	字符串	邮箱
userInfo	returnJson	字符串	该信息为第三方登录系统验证返回的信息
product	isRegister	字符串	是否是新登用户 0：不是 1：是

4.1.4 响应示例（旧版）

 {
 "status":"0",
 "reset":"1000",
 "desc":"成功",
 "bindingMode":"0",
 "loginType":"10",
 "tokenId":"254af9e9-9455-4bd1-83ee-00f50defdc79",
 "currentUserType":"1",
 "originalUserType":"1",
 "userInfo":{
 "id":"用户id",
 "userName":"用户昵称",
 "email":"Tyy@163.com",
 "returnJson":{"该信息为第三方返回的信息"}
 }
 "userPlatformId":"0001",
 "product":{"isRegister":"0"}
 }

4.1.3 返回参数（新版海外整合SDK）

父节点	参数名称	类型	说明
-	status	字符串	返回状态 0：成功 1：失败
-	reset	字符串	状态内码； `1000`：接收成功；其他详见附录1
-	desc	字符串	状态描述
userInfo	loginType	字符串	用户登录标识：（ 0：是第三方平台注册 1：为官网注册 2：为快速注册 9：为其它平台登录 10：为官网登录 11：为快速登录）
userInfo	id	字符串	用户id
userInfo	name	字符串	用户名
userInfo	isBindEmail	布尔	是否绑定邮箱
userInfo	thirdList	数组	绑定的第三方渠道的id列表

4.1.4 响应示例（新版海外整合SDK）

{
    "userInfo": {
        "id": "0800020000000000000000000000000000000440",
        "name":""
        "isBindEmail": false,
        "thirdList": [
            "0330",
            "0231"
        ]
    },
    "reset": "1000",
    "status": "0",
    "desc": "成功"
}

4.2 充值发货接口

该接口由游戏按规范提供，掌趣平台通过该接口实现游戏发货功能；

4.2.1 安全验证
1.游戏需验证订单金额(chargePrice)和实际支付金额(actualPrice)是否相等，如果不相等，则按照实际支付金额(actualPrice)进行处理。

2.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。

4.2.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	serviceId	字符串	必填	业务ID
-	channelId	字符串	必填	推广渠道ID
-	deviceGroupId	字符串	必填	机型组ID
-	localeId	字符串	必填	语言ID
-	propId	字符串	必填	商品ID
-	roleId	字符串	必填	游戏角色ID
-	userId	字符串	必填	游戏用户ID
-	serverId	字符串	必填	逻辑服ID
-	payChannelId	字符串	必填	支付方式ID
-	chargePrice	字符串	必填	订单金额，详见附录4货币类型及对应ID
-	actualPrice	字符串	必填	实际支付金额，详见附录4货币类型及对应ID
-	currencyType	字符串	必填	货币类型，详见附录4货币类型及对应ID
-	orderId	字符串	必填	订单号
-	cpOrderId	字符串	选填	第三方订单号，不参于签名
-	subParams	字符串	选填	订阅参数（只有订阅才会传），不参于签名
-	testOrder	字符串	必填	是否是测试订单 0：不是 1：是
-	payCurrency	字符串	必填	支付货币类型，不参于签名
-	payCurrencyAmount	字符串	必填	支付货币金额，不参于签名
-	payCountry	字符串	必填	支付国家，不参于签名
strategy{rebate}	price	字符串	可选	返利金额(为整数，如果有小数则进1)
strategy{rebate}	goodId	字符串	可选	返利商品ID
strategy{rebate}	rebateType	字符串	可选	返利类型 GOODID：按照商品ID返利 PRICE：按照充值金额进行返利
-	extendParams	字符串	可选	自定义扩展字段
-	sign	字符串	必填	签名 Md5(serviceId +channelId +deviceGroupId +localeId +propId +roleId +userId +serverId +payChannelId +chargePrice +actualPrice +currencyType +orderId +testOrder +strategy.rebate.price +strategy.rebate.goodId +strategy.rebate.rebateType +extendParams +secretKey(约定秘钥)) 不存在的字段则“”（空串）代替。

4.2.3 返回参数

父节点	参数名称	类型	说明
common	deliverCode	字符串	响应码； `0001`：接收成功；失败详见附录2
common	deliverDesc	字符串	通知结果描述(需要做UrlEncode，编码方式UTF-8)

4.2.4 请求示例

{
"serviceId":"1000053831111600000",
"channelId":"3111160031111600",
"deviceGroupId":"0000",
"localeId":"01",
"propId":"0001",
"roleId":"14325",
"userId":"0103400000000000000000000000000000150595",
"serverId":"10",
"payChannelId":"211116000014000051014300",
"chargePrice":"100",
"actualPrice":"100",
"currencyType":"1",
"orderId":"0992017101611521566000",
"cpOrderId":"1203902009",
"testOrder":"0",
"extendParams":"测试-我是扩展参数",
"subParams":"{\"payType\":\"subscribe\",\"startTime\":\"1692787155000\",\"endTime\":\"1692787335000\"}",
"sign":"8bccb12d3095b898accdebd895fd14c5",
}

4.2.6 返回示例

{
  "common":{
      "deliverCode":"0001",
      "deliverDesc":"通知成功"
  }
}

4.3 礼包码发货接口

该接口由游戏按规范提供，掌趣平台通过该接口实现礼包码发货功能；
注意：
由于网络抖动、服务器维护等网络原因，可能会在玩家触发第一次兑换请求的时候，游戏返回的请求平台这边没有收到或者请求超时、非成功状态，平台会定时补发请求，直到返回成功或者礼包已经领取的状态码为止。此时如果游戏已经给玩家发放过了礼包，就需要给平台返回对应的状态，已经领取并且不能再给此玩家再次发放礼包。所以需要游戏方面对礼包发放进行判断。同一个角色+同一个礼包码，只能发放一次。不能重复发。否则在特殊情况下可能会给玩家重复发礼包。

4.3.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
4.3.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	serviceId	字符串	必填	业务ID
-	channelId	字符串	必填	推广渠道ID
-	deviceGroupId	字符串	必填	机型组ID
-	localeId	字符串	必填	语言ID
-	roleId	字符串	必填	游戏角色ID
-	userId	字符串	必填	游戏用户ID
-	serverId	字符串	必填	逻辑服ID
-	gamePackageId	字符串	可选	礼包ID，即游戏内的物品包ID。（该字段已过时。）
-	gamePackageName	字符串	必填	礼包名称，需要做urlencoding
-	gamePackageDesc	字符串	必填	礼包描述，需要做urlencoding
-	gameCode	字符串	必填	礼包码（用户输入的码号）
-	extendParams	字符串	必填	自定义字段，多个参数之间以“\|” 分隔
-	goodsInfo	字符串	可选	道具信息，数组
goodsInfo	goodsId	字符串	可选	商品ID
goodsInfo	goodsNum	字符串	可选	商品数量
goodsInfo	goodsName	字符串	可选	商品名称，需要做urlencoding
goodsInfo	goodsDesc	字符串	可选	商品描述，需要做urlencoding
goodsInfo	extendInfo	字符串	可选	物品扩展信息
-	sign	字符串	必填	签名 Md5(serviceId +channelId +deviceGroupId +localeId +roleId +userId +serverId +gamePackageId +gamePackageName +gamePackageDesc +gameCode +extendParams +goodsInfo[0].goodsId +goodsInfo[0].goodsNum +goodsInfo[0].goodsName +goodsInfo[0].goodsDesc +goodsInfo[0].extendInfo +…+goodInfos[n].goodsId +goodsInfo[n].goodsNum +goodsInfo[n].goodsName +goodsInfo[n].goodsDesc +goodsInfo[n].extendInfo +secretKey(约定秘钥)) 注：goodsInfo数组中的数据要循环依次加到字符串中，然后算取sign值，不存在的字段则“”（空串）代替。

4.3.3 返回参数

父节点	参数名称	类型	说明
common	deliverCode	字符串	响应码； `0001`：接收成功；失败详见附录2
common	deliverDesc	字符串	通知结果描述(需要做UrlEncode，编码方式UTF-8)

4.3.4 请求示例

{
"serviceId":"1000053831111600000",
"channelId":"3111160031111600",
"deviceGroupId":"0000",
"localeId":"01",
"roleId":"143235",
"userId":"0103400000000000000000000000000000150595",
"serverId":"10",
"gamePackageId":"374",
"gamePackageName":"测试礼包",
"gamePackageDesc":"测试礼包",
"gameCode":"2E2A3VPR8NNTM1",
"extendParams":"",
"goodsInfo":[
    {
        "goodsId":"13452",
        "goodsNum":"1",
        "goodsName":"测试商品",
        "goodsDesc":"测试商品",
        "extendInfo":""
    }
],
"sign":"ccae56d2aed76fa2dca6b90fb0ef4e42"
}

4.3.6 返回示例

{
  "common":{
      "deliverCode":"0001",
      "deliverDesc":"通知成功"
  }
}

4.4 查询区服下某个用户角色接口

该接口由游戏按规范提供，掌趣平台通过该接口实现角色查询功能；

4.4.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
4.4.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	userId	字符串	必填	掌趣的用户ID
-	serverId	字符串	必填	区服ID
-	timestamp	字符串	必填	时间戳
-	sign	字符串	必填	必填,按照：userId+serverId+timestamp+约定秘钥的格式进行MD5加密，不存在的字段则“”（空串）代替。

4.4.3 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	errorCode	字符串	响应码； `10000`：成功；失败详见附录3
-	errorDesc	字符串	状态描述
-	roleInfo	字符串	该数据为数组，如果只为一个角色，则数组里面只放一个数据即可
roleInfo	userId	字符串	用户ID
roleInfo	roleId	字符串	角色ID
roleInfo	roleName	字符串	角色名
roleInfo	serverId	字符串	游戏服ID
roleInfo	serverName	字符串	游戏区服名称
roleInfo	level	字符串	角色等级
roleInfo	vipLevel	字符串	角色VIP等级
roleInfo	createTime	字符串	格式：yyyy-MM-dd (24小时进制)HH:mm:ss

4.4.4 请求示例

{
"userId":"0103400000000000000000000000000000150595",
"serverId":"10",
"timestamp":"1513222799106",
"sign":"114f55ff7804311c9df08a8ee5646700"
}

4.4.5 返回示例

{
  "status":"1",
  "errorCode":"10000",
  "errorDesc":"成功",
  "roleInfo":[
      {
          "userId":"0103400000000000000000000000000000150595",
          "roleId":"11235",
          "roleName":"zhourunfa",
          "serverId":"10",
          "serverName":"钢铁洪流",
          "level":"10",
          "vipLevel":"0",
          "createTime":"2017-12-10 16:12:12"
      }
  ]
}

4.5 查询渠道下某个用户角色接口

该接口由游戏按规范提供，掌趣平台通过该接口实现角色查询功能；

4.5.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
4.5.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	userId	字符串	必填	掌趣的用户ID
-	serviceId	字符串	必填	渠道ID
-	timestamp	字符串	必填	时间戳
-	sign	字符串	必填	必填,按照：userId+serviceId+timestamp+（secretKey）约定秘钥的格式进行MD5加密，不存在的字段则“”（空串）代替。

4.5.3 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	errorCode	字符串	响应码； `10000`：成功；失败详见附录3
-	errorDesc	字符串	状态描述
-	roleInfo	字符串	该数据为数组，如果只为一个角色，则数组里面只放一个数据即可
roleInfo	userId	字符串	用户ID
roleInfo	roleId	字符串	角色ID
roleInfo	roleName	字符串	角色名
roleInfo	serverId	字符串	游戏服ID
roleInfo	serverName	字符串	游戏区服名称
roleInfo	level	字符串	角色等级
roleInfo	vipLevel	字符串	角色VIP等级
roleInfo	createTime	字符串	格式：yyyy-MM-dd (24小时进制)HH:mm:ss

4.5.4 请求示例

{
"userId":"0103400000000000000000000000000000150595",
"serviceId":"1000053831111600000",
"timestamp":"1513222799106",
"sign":"114f55ff7804311c9df08a8ee5646700"
}

4.5.5 返回示例

{
    "status":"1",
    "errorCode":"10000",
    "errorDesc":"成功",
    "roleInfo":[
        {
            "userId":"0103400000000000000000000000000000150595",
            "roleId":"11235",
            "roleName":"zhourunfa",
            "serverId":"10",
            "serverName":"钢铁洪流",
            "level":"10",
            "vipLevel":"0",
            "createTime":"2017-12-10 16:12:12"
        }
    ]
}

4.6 查询某个用户角色接口(三方支付和网页账号删除使用)

该接口由游戏按规范提供，掌趣平台通过该接口实现角色查询功能；

4.6.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
4.6.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	roleId	字符串	必填	角色ID
-	serverId	字符串	必填	区服ID
-	timestamp	字符串	必填	时间戳
-	sign	字符串	必填	必填,按照：roleId+serverId+timestamp+约定秘钥的格式进行MD5加密，不存在的字段则“”（空串）代替。

4.6.3 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	errorCode	字符串	响应码； `10000`：成功；失败详见附录3
-	errorDesc	字符串	状态描述
-	roleInfo	字符串	该数据为数组，如果只为一个角色，则数组里面只放一个数据即可
roleInfo	userId	字符串	用户ID
roleInfo	roleId	字符串	角色ID
roleInfo	roleName	字符串	角色名
roleInfo	serverId	字符串	游戏服ID
roleInfo	serverName	字符串	游戏区服名称
roleInfo	level	字符串	角色等级
roleInfo	vipLevel	字符串	角色VIP等级
roleInfo	createTime	字符串	格式：yyyy-MM-dd (24小时进制)HH:mm:ss

4.6.4 请求示例
http://XXXX?roleId=XX&serverId=XX&timestamp=XX&sign=XXX
4.6.5 返回示例

{
    "status":"1",
    "errorCode":"10000",
    "errorDesc":"成功",
    "roleInfo":[
        {
            "userId":"0103400000000000000000000000000000150595",
            "roleId":"11235",
            "roleName":"zhourunfa",
            "serverId":"10",
            "serverName":"钢铁洪流",
            "level":"10",
            "vipLevel":"0",
            "createTime":"2017-12-10 16:12:12"
        }
    ]
}

4.7 ios订阅查询接口

该接口由掌趣技术平台提供，负责查询appstore的订阅状态；

4.7.1 请求地址
https://{域名}/billingcenter2.0/appstore/{产品Id}/queryXDState.do
4.7.1 请求地址(海外SDK新版地址)
https://{域名}/billingcenter2.0/appstore/V2/{产品Id}/queryXDState.do
4.7.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	userId	字符串	必填	用户ID
-	roleId	字符串	必填	角色ID
-	serverId	字符串	必填	区服ID
-	sign	字符串	必填	参照签名说明

4.7.3 签名说明
sign=MD5(userId=XXX&roleId=XXXID&serverId=XXX|app_secret),app_secret为签名KEY
4.7.4 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	desc	字符串	描述信息
-	reset	字符串	状态内码，默认为空
-	data	字符串	该数据为数组，如果只有一条订阅记录，则数组里面只放一个数据即可
data	productId	字符串	订阅商品ID
data	subTime	字符串	订阅初始时间（时间戳格式）
data	endTime	字符串	订阅过期时间（时间戳格式）
data	status	字符串	订阅状态 0：订阅中 1：取消订阅（具体以订阅时间为准）

4.7.5 请求示例
http://{域名}/billingcenter2.0/appstore/{产品ID}/queryXDState.do?userId=XXX&roleId=XXX&serverId=XXX&sign=XXX
4.7.6 返回示例

{
    "data": [{
        "endTime": "1589611538000",
        "productId": "Sub_18",
        "status": "0",
        "subTime": "1587019538000"
    }],
    "desc": "查询成功",
    "reset": "",
    "status": "1"
}

4.8 google订阅查询接口

该接口由掌趣技术平台提供，负责查询google订阅的相关信息，游戏可以根据自己的发放策略去定时访问该接口，获取到账号的订阅状态信息。

4.8.1 请求地址
https://{域名}/billingcenter2.0/google/{产品Id}/queryXDState.do
4.8.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	userId	字符串	必填	用户ID
-	roleId	字符串	必填	角色ID
-	serverId	字符串	必填	区服ID
-	sign	字符串	必填	参照签名说明

4.8.3 签名说明
sign=MD5(userId=XXX&roleId=XXXID&serverId=XXX|app_secret),app_secret为签名KEY
4.8.4 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	desc	字符串	描述信息
-	reset	字符串	状态内码，默认为空
-	data	字符串	该数据为数组，如果只有一条订阅记录，则数组里面只放一个数据即可
data	productId	字符串	订阅商品ID
data	subTime	字符串	订阅初始时间（时间戳格式）
data	endTime	字符串	订阅过期时间（时间戳格式）
data	subStatus	字符串	订阅状态 0：订阅中 1：订阅失效
data	cancelTime	字符串	取消订阅时间（时间戳格式），用户未取消，默认为空“”(字符串)

4.8.5 请求示例
http://{域名}/billingcenter2.0/google/{产品ID}/queryXDState.do?userId=XXX&roleId=XXX&serverId=XXX&sign=XXX
4.8.6 返回示例

{
    "data": [{
        "productId": "Sub_18",
        "subTime": "1587019538000",
        "endTime": "1589611538000",
        "subStatus": "1",
        "cancelTime": "1589611438000"
    }],
    "desc": "查询成功",
    "reset": "",
    "status": "1"
}

4.9 google订阅状态推送接口（订阅选接）

该接口由游戏平台提供，负责接收google的订阅相关状态，主要用来监听google订阅账号保留、恢复、宽限期等功能，这些功能只有在google后台启用才生效。

4.9.1 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	rid	字符串	必填	角色ID
-	sec	字符串	必填	区服ID
-	notificationType	字符串	必填	google的通知状态
-	endTime	字符串	必填	过期时间，时间戳
-	sign	字符串	必填	参照签名说明

4.9.2 签名说明
sign = md5(rid+sec+endTime+signKey)
4.9.3 返回参数

父节点	参数名称	类型	说明
common	deliverCode	字符串	响应码； `0001`：接收成功；失败详见附录2
common	deliverDesc	字符串	通知结果描述(需要做UrlEncode，编码方式UTF-8)

4.9.4 返回示例

{
    "common":{
        "deliverCode":"0001",
        "deliverDesc":"通知成功"
    }
}

5.0 google和ios促销码发货接口

该接口由游戏按规范提供，掌趣平台通过该接口实现ios和google促销码、google预注册、google积分兑换、googleEap等发货功能；

5.0.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
5.0.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	serviceId	字符串	必填	业务ID
-	channelId	字符串	必填	推广渠道ID
-	deviceGroupId	字符串	必填	机型组ID
-	localeId	字符串	必填	语言ID
-	orderId	字符串	必填	订单ID
-	propId	字符串	必填	商品ID
-	roleId	字符串	必填	游戏角色ID
-	userId	字符串	必填	用户ID
-	serverId	字符串	必填	逻辑服ID
-	extendParams	字符串	可选	游戏自定义扩展字段
-	sign	字符串	必填	签名 Md5(serviceId +channelId +deviceGroupId +localeId +orderId +propId +roleId +userId +serverId +extendParams +secretKey(约定秘钥))不存在的字段则“”（空串）代替

5.0.3 返回参数

父节点	参数名称	类型	说明
common	deliverCode	字符串	响应码； `0001`：接收成功；失败详见附录2
common	deliverDesc	字符串	通知结果描述(需要做UrlEncode，编码方式UTF-8)

5.0.4 请求示例

{
    "serviceId":"1000053831111600000",
    "channelId":"3111160031111600",
    "deviceGroupId":"0000",
    "localeId":"01",
    "propId":"0001",
    "roleId":"14325",
    "userId":"0103400000000000000000000000000000150595",
    "serverId":"10",
    "extendParams":"测试-我是扩展参数",
    "sign":"8bccb12d3095b898accdebd895fd14c5",
}

5.0.5 返回示例

{
      "common":{
          "deliverCode":"0001",
          "deliverDesc":"通知成功"
      }
}

5.1 账号销毁通知游戏接口

该接口由游戏按规范提供，掌趣平台通过该接口将已经过冷静期的账号发送游戏端功能；

5.1.1 安全验证
1.为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五。
5.1.2 请求参数

参数父节点	参数名称	类型	限制策略	说明
-	userId	字符串	必填	用户ID
-	roleId	字符串	非必填	角色ID
-	serverId	字符串	非必填	区服ID
-	timestamp	字符串	必填	时间戳
-	sign	字符串	必填	必填,按照：userId+roleId+serverId+timestamp+约定秘钥的格式进行MD5加密，不存在的字段则“”（空串）代替。

5.1.3 返回参数

父节点	参数名称	类型	说明
-	status	字符串	状态码 0：失败 1：成功
-	errorDesc	字符串	状态描述

5.1.4 请求示例
https://XXXX?userId=XX&roleId=XX&serverId=XX&timestamp=XX&sign=XXX
5.1.5 返回示例

{
    "status":"1",
    "errorDesc":"成功"
}

5.2 Google、Appstore 退款通知游戏接口

该接口由游戏按规范提供，掌趣平台通过该接口将三方退款订单信息发送给游戏端

5.2.1请求参数

接口协议:HTTP POST; content-type设为 application/json;

参数名称	类型	限制策略	说明
cpOrderId	字符串	必填	三方订单号
orderId	字符串	必填	平台订单号
userId	字符串	必填	平台用户ID
roleId	字符串	必填	游戏角色ID
amount	数字	必填	金额
currencyType	字符串	必填	货币类型
serverId	字符串	必填	区服ID, 不存在则””(空串)代替
refundTime	数字	必填	退款时间戳

5.2.2 签名说明

无签名，但是为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP详见附录五

5.2.3返回参数

参数名称	类型	说明
errorCode	字符串	状态码, `0000`代表成功，其他值认为失败
errorDesc	字符串	状态描述

5.2.4请求示例

    {
        "cpOrderId": "GPA.3319-1502-8448-27427",
        "orderId": "0612024050913015476800",
        "userId": "1100020000000000000000000000000000209526",
        "roleId": "705803324170830848",
        "amount": 99,
        "currencyType": "USD",
        "serverId": "1",
        "refundTime": 1720769380
    }

5.2.5 返回示例

    {
      "errorCode": "0000",
      "errorDesc": "success"
    }

附录1

登录验证接口响应编码表

响应码	描述
1000	成功
1117	token过期或已失效
1099	其它错误

附录2

充值发货接口响应编码表

响应码	描述
0001	成功
1000	订单异常（该订单已经发货）
1001	用户异常
1002	角色异常
1003	逻辑服异常
1004	商品异常
1005	发货失败
1100	预留扩展(该扩展由游戏方定义，定义后请反馈计费中心)

附录3

角色查询接口响应编码表

响应码	描述
10000	成功
20001	角色异常
20002	区服异常

附录4

货币类型及对应ID

货币ID是没有限定位数的纯自增值，详情：货币类型详情列表

货币ID	货币名	货币单位
1	人民币	分
2	美元	美分
3	日元	円
4	港币	分
5	英镑	便士
6	新加坡币	分
7	越南盾	盾
8	台币	元
9	韩元	分
10	泰铢	萨当
14	马来西亚林令吉	分
17	菲律宾币	仙
19	印尼卢比	卢比
21	柬埔寨瑞尔	瑞尔
22	加拿大元	分
28	巴西雷亚尔	分
29	智利比索	分
32	欧元	分
67	墨西哥比索	分
70	秘鲁新索尔	分
93	哥斯达黎加科朗	分
95	俄罗斯卢布	戈比
110	巴拉圭瓜尼	分
122	缅甸元	分
125	哥伦比亚比索	分

附录五

ip鉴权处理

为了保证数据安全性，建议游戏服务器对掌趣的请求IP地址做鉴权处理，需要认证的IP如下：
国内：123.59.201.40、123.59.201.41、123.59.201.42、120.132.83.31、120.132.83.32、120.132.83.33、120.92.126.236、120.92.126.237、120.92.126.238、120.92.126.151、120.92.126.80、120.92.126.35、120.132.83.104
港澳台、泰国、新马地区：129.227.148.196、129.227.148.202、129.227.148.209、129.227.148.218、129.227.148.219
韩国：103.6.100.131、103.6.100.140、103.6.100.135、103.6.100.136、103.6.100.132
日本：150.109.193.59、150.109.193.235、150.109.195.246
欧美：34.150.160.243、34.85.152.140、35.188.244.120、43.131.33.210、43.131.61.193、43.131.32.13 （ 2022-11-14新增）

Table of Contents

SDK服务端(海外)接入说明

1. 接入必读

2. 准备工作

3. 接口说明

4. 接口

4.1 登录验证接口

4.2 充值发货接口

4.3 礼包码发货接口

4.4 查询区服下某个用户角色接口

4.5 查询渠道下某个用户角色接口

4.6 查询某个用户角色接口(三方支付和网页账号删除使用)

4.7 ios订阅查询接口

4.8 google订阅查询接口

4.9 google订阅状态推送接口（订阅选接）

5.0 google和ios促销码发货接口

5.1 账号销毁通知游戏接口

5.2 Google、Appstore 退款通知游戏接口

附录1

登录验证接口响应编码表

附录2

充值发货接口响应编码表

附录3

角色查询接口响应编码表

附录4

货币类型及对应ID

附录五

ip鉴权处理