SDK服务端(国内)接入说明文档

1. 接入必读

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

2. 准备工作

3. 接口说明

  • 接口协议:HTTP POST; content-type设为application/json;
  • 交互数据格式:JSON格式(以UTF-8进行编码); 数据直接通过HTTP消息体传输(非KEY-VALUE模式); 注意单次消息体大小不能大于512K;

4. 接口

4.1 登录验证接口

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

参数父节点 参数名称 类型 限制策略 说明
- service 字符串 必填 接口标识,固定为:palm.platform.ucenter.getUserInfo
- sessionId 字符串 必填 会话ID
  • 4.1.3 返回参数
父节点 参数名称 类型 说明
- status 字符串 状态码
0:失败
1:成功
- errorCode 字符串 响应码;
10000:接收成功;
其他详见附录1
- errorDesc 字符串 描述
data userId 字符串 用户ID
data userPlatformId 字符串 用户系统ID
data userName 字符串 用户名
data palmId 字符串 掌趣号
data nickName 字符串 昵称
data phone 字符串 登录手机号
data email 字符串 用户邮箱
data returnJson 字符串 隐形登录返回的第三方数据
data loginType 字符串 登录类型
speedyLogin:快速登录
speedyRegister:快速注册
commonLogin:普通登录
commonRegister:普通注册
phoneLogin:手机登录
phoneRegister:手机注册
thirdHiddenLogin:第三方用户登录
thirdHiddenRegister : 第三方用户注册
phoneVerifyCodeLogin:手机验证码登录
phoneVerifyCodeRegister:手机验证码注册
data originalUserType 字符串 原生用户登录类型
speedy:快登用户
common:普通用户名密码用户
phone:手机号注册用户
thirdHidden:第三方隐性用户
thirdHiddenNeedBindingCommon:第三方需要绑定 官网账户
data currentUserType 字符串 当前用户登录类型
speedy:快登用户
common:普通用户名密码用户
phone:手机号注册用户
thirdHidden:第三方隐性用户
thirdHiddenNeedBindingCommon:第三方需要绑定 官网账户
参数名称 类型 说明
-identityAuth status 字符串 状态码
“1” 认证中, “2” 认证成功, “-1” 认证失败
-identityAuth isAdult 字符串 状态码
“0” 未成年, “1” 成年
  • 4.1.4 请求示例

(渠道用户):

  1. {
  2. "data": {
  3. "phone": "",
  4. "userPlatformId": "0286",
  5. "email": "",
  6. "nickName": "",
  7. "userId": "0102860000000000000000000000000022763457",
  8. "returnJson": {
  9. "sex": "",
  10. "accessToken": "1.a3e0d5b2410e2b12aa7cf25541745695.55f048d5072366f7f6c03b7cb810e450.1494315064144",
  11. "nickname": "CCNK1417056083257",
  12. "brithday": "",
  13. "highDefUrl": "",
  14. "expires_in": "7776000",
  15. "openid": "22763457",
  16. "refresh_token": "4123dnasjonrfwjkr329439wijm3ir9u328faicy78ehc8m3urc329",
  17. "rtn_code": "0",
  18. "headIconUrl": ""
  19. },
  20. "userName": "CCNK1417056083257@coolyun_10000538.com",
  21. "originalUserType": "0",
  22. "currentUserType": "0",
  23. "loginType":"thirdHiddenLogin"
  24. },
  25. "errorCode": "10000",
  26. "errorDesc": "成功",
  27. "status": "1"
  28. }

(官网用户):

  1. {
  2. "data": {
  3. "phone": "13888886666",
  4. "userPlatformId": "0001",
  5. "email": "",
  6. "nickName": "玩家001",
  7. "userId": "0100010000000000000000000000000174323454",
  8. "returnJson": {
  9. "palmId": "174323454",
  10. "nickName": "玩家001"
  11. },
  12. "userName": "ourpalmUser",
  13. "originalUserType": "1",
  14. "currentUserType": "1",
  15. "loginType":"commonLogin"
  16. },
  17. "errorCode": "10000",
  18. "errorDesc": "成功",
  19. "status": "1"
  20. }

实名相关:

  1. "status": "1" 认证中, "2" 认证成功, "-1" 认证失败
  2. "isAdult": "0" 未成年, "1" 成年

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 字符串 必填 订单号
- testOrder 字符串 必填 是否是测试订单
0:不是
1:是
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 请求示例
    1. {
    2. "serviceId":"1000053831111600000",
    3. "channelId":"3111160031111600",
    4. "deviceGroupId":"0000",
    5. "localeId":"01",
    6. "propId":"0001",
    7. "roleId":"14325",
    8. "userId":"0103400000000000000000000000000000150595",
    9. "serverId":"10",
    10. "payChannelId":"211116000014000051014300",
    11. "chargePrice":"100",
    12. "actualPrice":"100",
    13. "currencyType":"1",
    14. "orderId":"0992017101611521566000",
    15. "testOrder":"0",
    16. "extendParams":"测试-我是扩展参数",
    17. "sign":"8bccb12d3095b898accdebd895fd14c5",
    18. }
  • 4.2.6 返回示例
    1. {
    2. "common":{
    3. "deliverCode":"0001",
    4. "deliverDesc":"通知成功"
    5. }
    6. }

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 请求示例
    1. {
    2. "serviceId":"1000053831111600000",
    3. "channelId":"3111160031111600",
    4. "deviceGroupId":"0000",
    5. "localeId":"01",
    6. "roleId":"143235",
    7. "userId":"0103400000000000000000000000000000150595",
    8. "serverId":"10",
    9. "gamePackageId":"374",
    10. "gamePackageName":"测试礼包",
    11. "gamePackageDesc":"测试礼包",
    12. "gameCode":"2E2A3VPR8NNTM1",
    13. "extendParams":"",
    14. "goodsInfo":[
    15. {
    16. "goodsId":"13452",
    17. "goodsNum":"1",
    18. "goodsName":"测试商品",
    19. "goodsDesc":"测试商品",
    20. "extendInfo":""
    21. }
    22. ],
    23. "sign":"ccae56d2aed76fa2dca6b90fb0ef4e42"
    24. }
  • 4.3.6 返回示例
    1. {
    2. "common":{
    3. "deliverCode":"0001",
    4. "deliverDesc":"通知成功"
    5. }
    6. }

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

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

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

  • 4.4.2 请求参数

参数父节点 参数名称 类型 限制策略 说明
- userId 字符串 必填 掌趣的用户ID
- serverId 字符串 必填 区服ID
- timestamp 字符串 必填 时间戳
- sign 字符串 必填 必填,按照:userId+serverId+timestamp+(secretKey)约定秘钥 的格式进行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 请求示例
    1. {
    2. "userId":"0103400000000000000000000000000000150595",
    3. "serverId":"10",
    4. "timestamp":"1513222799106",
    5. "sign":"114f55ff7804311c9df08a8ee5646700"
    6. }
  • 4.4.5 返回示例
    1. {
    2. "status":"1",
    3. "errorCode":"10000",
    4. "errorDesc":"成功",
    5. "roleInfo":[
    6. {
    7. "userId":"0103400000000000000000000000000000150595",
    8. "roleId":"11235",
    9. "roleName":"zhourunfa",
    10. "serverId":"10",
    11. "serverName":"钢铁洪流",
    12. "level":"10",
    13. "vipLevel":"0",
    14. "createTime":"2017-12-10 16:12:12"
    15. }
    16. ]
    17. }

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 请求示例
    1. {
    2. "userId":"0103400000000000000000000000000000150595",
    3. "serviceId":"1000053831111600000",
    4. "timestamp":"1513222799106",
    5. "sign":"114f55ff7804311c9df08a8ee5646700"
    6. }
  • 4.5.5 返回示例
    1. {
    2. "status":"1",
    3. "errorCode":"10000",
    4. "errorDesc":"成功",
    5. "roleInfo":[
    6. {
    7. "userId":"0103400000000000000000000000000000150595",
    8. "roleId":"11235",
    9. "roleName":"zhourunfa",
    10. "serverId":"10",
    11. "serverName":"钢铁洪流",
    12. "level":"10",
    13. "vipLevel":"0",
    14. "createTime":"2017-12-10 16:12:12"
    15. }
    16. ]
    17. }

附录1

登录验证接口响应编码表

响应码 描述
10000 成功
20001 请求的service有误
20002 sessionId参数有误
20003 session失效或无效
20004 请求方式异常
20009 服务异常

附录2

充值发货 && 礼包码发货 接口响应编码表

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

附录3

角色查询接口响应编码表

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

附录四

货币类型及对应ID

货币ID 货币名称 货币单位
1 人民币
2 美元 美分
3 日元
4 港币
5 英镑 便士
6 新加坡币
7 越南盾
8 台币
9 韩元
10 泰铢 萨当

附录五

ip鉴权处理

为了保证数据安全性,建议游戏服务器对掌趣的请求IP地址做鉴权处理,需要认证的IP如下:
国内:223.202.93.168、223.202.93.144、103.235.233.11、115.159.84.84、115.159.83.43、223.202.94.171、223.202.13.15、103.235.233.66、103.235.233.67、223.202.94.93、114.118.80.21、114.118.80.22、114.118.80.94、
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
港澳台、泰国、新马地区:128.1.62.11、128.1.62.12、128.1.62.40 、128.1.62.47 、128.1.62.48 、128.1.62.49
韩国:103.6.100.131、103.6.100.140、103.6.100.135、103.6.100.136
日本:52.69.92.254、52.196.24.135、52.193.250.87、52.199.11.192
欧美:47.89.191.141、47.90.200.33、47.89.178.154、47.89.177.232