接口列表

测试环境：https://sg-oauth.upliveapp.com/
正式环境：https://gameopenapi.schirst.com/

一、通用接口

1、获取用户信息

• path：/getUserInfo

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识

• 返回参数

参数	描述
open_id	用户的唯一标识
username	用户名
gender	用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
avatar	用户头像
country_code	用户所属国家的二字代码
uplive_code	用户upliveCode，唯一
language	用户客户端语言码，例如：zh-CN

• 请求实例

https://sg-oauth.upliveapp.com/getUserInfo?access_token=ACCESS_TOKEN&open_id=OPENID

• 返回结果：

  • 请求成功：

    {
      avatar: "http://p.cdn.upliveapps.com/uplive/p/u/2018/9/11/5038085.jpg",
      country_code: "CN",
      gender: 1,
      language: "",
      open_id: "101015150d5e4e40445b755f5445",
      uplive_code: "zt2a92l6",
      username: "USERNAME"
    }

    
    

  • 请求失败或处理错误

    {
      "errno":"000002",
      "errmsg":"params error"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

2、防盗刷

• path：/getUserIsPay

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
platform	是	平台 1是安卓 2是ios

• 返回参数

参数	描述
userIsPay	是否充值过
isShow	是否显示充值

• 请求实例

https://sg-oauth.upliveapp.com/getUserIsPay?access_token=ACCESS_TOKEN&open_id=OPENID&platform=1

• 返回结果：

  • 请求成功：

    {
        "userIsPay": true,
        "isShow": true
    },

    
    

3、游戏兑换礼物

• path：/sendActivityGift

• 请求方式：POST

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
game_id	是	用于区分游戏唯一标识，由Uplive分配
order_id	是	本地订单id
giftIdList	是	奖励礼物id集合 [1,2,3]
sign	是	access_token=&client_secret=&game_id=&open_id=&order_id= 以上字段及值md5加密

• 返回参数

参数	描述
limitGiftIdList	达到上限的礼物列表

• 请求实例

https://sg-oauth.upliveapp.com/sendActivityGift?access_token=ACCESS_TOKEN&open_id=OPENID&game_id=GAMEID&order_id=ORDERID&giftIdList=[1]&sign=SIGN

• 返回结果：

  • 请求成功：

    {
        "limitGiftIdList": [2,4]
    },

    
    

4、游戏兑换礼物列表

• path：/getActivityGiftList

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
game_id	是	用于区分游戏唯一标识，由Uplive分配
language	是	语言

• 返回参数

参数	描述
redeemGiftList	礼物列表

• 请求实例

https://sg-oauth.upliveapp.com/getActivityGiftList?access_token=ACCESS_TOKEN&open_id=OPENID&game_id=GAMEID&language=LANGUAGE

• 返回结果：

  • 请求成功：

    {
        "redeemGiftList": [
            {
                "exchangeAllLimit": 0,
                "exchangeSingleLimit": 0,
                "giftCount": 1, //礼物发送个数
                "giftExp": 1, //礼物有效期 天
                "giftId": 9, //礼物id
                "giftName": "蓝色妖姬CN", //礼物多语言名称
                "giftWorth": 10, //礼物价值
                "smallUrl": "https://g-cdn.upliveapp.com/oauthgame/9_1_1634885492_small.png" //礼物图片
            },
        ]
    }

    
    

U钻版本

1、获取用户当前U钻数量

• path：/getDiamond

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识

• 返回参数

参数	描述
diamond	U钻数量

• 请求实例 *

  https://sg-oauth.upliveapp.com/getDiamond?access_token=ACCESS_TOKEN&open_id=OPENID

• 返回结果：

  • 请求成功：

    {
      "diamond" : 300
    }

    
    

  • 请求失败或处理错误

    {
      "errno":"000002",
      "errmsg":"params error"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

2、加钻、扣钻

• path：/changeDiamond

• 请求方式：POST

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
order_id	是	订单号（调用方生成，必须保证唯一），交易的唯一标志
amount	是	本次加钻／扣钻数量
op_type	是	加钻／扣钻 1为加钻，2为扣钻
game_id	是	游戏id
sign	是	交易签名（字母用小写，签名方法见下方示例）
constitute	否	加钻时如果有因使用道具(游戏抵用券)中注而加钻的构成参数 (见下方示例)

• 签名方法

  用client_secret对交易做签名，目的是为了增强接口的安全性，防止access_token泄露导致发生伪造交易

  签名的方法是将请求里的所有参数及其值，按参数名排序后，转换成url格式，再用md5加密

  PHP代码示例：

  $data["access_token"]="REPQYHEHP0GNP1WCLOS4BQ";
  $data["open_id"]="4f4f57524d0607011e1931164c47494345785c4c";
  $data["order_id"] = "5bee7c70ef716";
  $data["amount"]=20;
  $data["op_type"]=1;
  $data["game_id"]=1;
  $data["client_secret"] ="qv5pz3289lgpcqlwho3accb";
  //sort param keys
  ksort($data);
  //form key/value to url format
  $url_param = http_build_query($data); 
  //result: $url_param = access_token=REPQYHEHP0GNP1WCLOS4BQ&amount=20&client_secret=qv5pz3289lgpcqlwho3accb&game_id=1&op_type=1&open_id=4f4f57524d0607011e1931164c47494345785c4c&order_id=5bee7c70ef716
  return md5($url_param);
  

• constitute示例
  flowType 31 为使用抵用券中注加钻
  flowType 1 为扣钻中注加钻

  [{"flowType":"31","amount":50},{"flowType":"1","amount":50}]

• 返回参数

参数	描述
diamond	u钻余额

• 请求实例

• 返回结果：

  • 请求成功：

    {
    ​   "diamond" : 300
    }

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
    "errno":"000003",
    "errmsg":"order no exist"
    }

    {
    "errno":"000004",
    "errmsg":"insufficient money"
    }

    {
    "errno":"000005",
    "errmsg":"user frozen"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

3、查询钻订单（确定订单是否执行成功）

• path：/checkOrder

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
order_id	是	订单号（调用方生成，必须保证唯一），交易的唯一标志
op_type	是	1加钻订单 2扣钻订单

• 返回参数

参数	描述
success	表示订单执行成功

• 请求实例

• 返回结果：

  • 请求成功：

    {
        "success" : true
    }

    
    

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
    "errno":"000008",
    "errmsg":"order not exist"
    }

4、使用游戏抵用券

• path：/packDescProp

• 请求方式：POST

• 请求参数

参数名称	是否必须	描述
open_id	是	用户在第三方应用中的标识
order_id	是	订单号（调用方生成，必须保证唯一），交易的唯一标志
game_id	是	游戏id
sign	是	签名
gifts	是	礼物/商品

• gifts示例
  道具只能有一个，amount只能传1

  [{"giftId":道具ID,"amount":1}]

• 返回参数

参数	描述
success	表示执行成功

• 请求实例

• 返回结果：

  • 请求成功：

    {
        "success" : true
    }

    
    

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
    "errno":"000008",
    "errmsg":"order not exist"
    }

5、用户游戏抵用券列表

• path：/packQueryProp

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
open_id	是	用户在第三方应用中的标识
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token

• 返回参数

参数	描述
success	表示执行成功
data	返回的列表

• 请求实例

• 返回结果：

  • 请求成功：

    {
           "data": [{
               "amount": 500,
               "beginTime": null,
               "code": 0,
               "createTime": 1668047861,
               "expValue": 1,
               "expireTime": 1682325542,
               "goodsId": 2211101,
               "gridId": null,
               "intro": "游戏抵扣券（描述英文）",
               "name": "游戏抵扣券（英文）",
               "privateJson": null,
               "propId": 2211101,
               "resources": null,
               "type": 6,
               "updateTime": 1669174626,
               "valuable": null,
               "valuableDiamond": 100
           }],
           "success": true
       }

    
    

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
    "errno":"000008",
    "errmsg":"order not exist"
    }

金币版本

从玩家层面看,只有一种“金币”的概念
但从平台和游戏开发者的角度看, 金币分为有效金币和免费金币
(就是说 [用户金币余额=有效金币+免费金币],但这中区别对用户是无感知的,)

• 免费金币 通过 领取金币/系统赠送免费金币活动 等方式获取的金币, 以及投注免费金币赢取的金币

• 有效金币 通过 u钻兑换金币 和 投注有效金币赢取的金币

• 投注时优先消耗免费金币,免费金币不足时,消耗有效金币
• 结算时,按照 该局游戏该玩家 投注的 有效金币 和 免费金币 的比例 , 自动计算 应得的 免费金币 和 有效金币
• 每个玩家每天可以领取一次免费金币,每次可以领1000免费金币

1、获取用户当前金币数量

• path：/gold/getBalance

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识

• 返回参数

用户金币余额 = gold + goldFree

参数	描述
gold	有效金币数量
goldFree	免费金币数量

• 请求实例

https://sg-oauth.upliveapp.com/gold/getBalance?access_token=ACCESS_TOKEN&open_id=OPENID

• 返回结果：

  • 请求成功：

    {
      "gold" : 300
    }

    
    

  • 请求失败或处理错误

    {
      "errno":"000002",
      "errmsg":"params error"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

2、投注(追加投注)(扣金币)、结算(加金币/发奖)、赠免费金币(特殊奖励/活动赠送/任务赠送等)

• path：

  • 投注 /gold/betting
  • 结算 /gold/settlement
  • 赠免费金币 /gold/gift

• 请求方式：POST

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
order_id	是	订单号（调用方生成，必须保证唯一），交易的唯一标志
amount	是	本次扣除金币（下注）数量
game_id	是	游戏id
sign	是	交易签名（字母用小写，签名方法见下方示例）
round	是	游戏局次(回合)编号

• 局次(回合)编号
  增加局次round的概念, 用以表示’一局’游戏,

  • 一局游戏可以有一个或者多个玩家, 同局的多个玩家暂时没有强制关系(比如投注结算时间/输赢/等)
  • 一局游戏表示:
    其中 每个玩家的 一次或多次投注 加 零次或一次结算
    每个玩家必须先下注后结算 , 结算后不能再次下注(结算后即应是新的一局)
  • 一局游戏最大时长(从第一笔投注起)为 1小时

  • 结算 有效金币 和免费金币

    投注时优先消耗免费金币,免费金币不足时 才消耗有效金币
    结算时,按照 该局游戏该玩家 投注的 有效金币 和 免费金币 的比例 , 自动计算 应得的 免费金币 和 有效金币

  • 赠送金币
    游戏活动 / 游戏任务 / 特殊关卡 等 场景下 , 可能需要不跳过下注过程直接赠送用户金币, 可以调用赠送金币接口
    赠送金币接口 不受下注/结算等流程限制,即:未下注/未结算/已下注/局时时长超过限制 等情况下都该局(round)皆可赠送

• 签名方法

  用client_secret对交易做签名，目的是为了增强接口的安全性，防止access_token泄露导致发生伪造交易

  签名的方法是将请求里的所有参数及其值，按参数名排序后，转换成url格式，再用md5加密

  PHP代码示例：

  $data["access_token"]="REPQYHEHP0GNP1WCLOS4BQ";
  $data["open_id"]="4f4f57524d0607011e1931164c47494345785c4c";
  $data["order_id"] = "5bee7c70ef716";
  $data["amount"]=20;
  $data["game_id"]=1;
  $data["client_secret"] ="qv5pz3289lgpcqlwho3accb";
  $data["round"] ="fp-123456";
  
  //sort param keys
  ksort($data);
  //form key/value to url format
  $url_param = http_build_query($data); 
  //result: $url_param = access_token=REPQYHEHP0GNP1WCLOS4BQ&amount=20&client_secret=qv5pz3289lgpcqlwho3accb&game_id=1&open_id=4f4f57524d0607011e1931164c47494345785c4c&order_id=5bee7c70ef716&round=fp-123456
  return md5($url_param);
  

• 返回参数

参数	描述
amount	减少(下注) / 增加(结算)的有效金币数
amountFree	减少(下注) / 增加(结算)的免费金币数
gold	有效金币数量
goldFree	免费金币数量

• 请求实例

• 返回结果：

  • 请求成功：

    {
        "amount":20,
        "amountFree":0,
        "gold":20,
        "goldFree":99999998
    }

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

    {
      "errno":"000009",
      "errmsg":"order_id already exist"
    }

    {
      "errno":"000001",
      "errmsg":"server error"
    }

    {
      "errno":"000011",
      "errmsg":"game round overtime"
    }

    {
      "errno":"000012",
      "errmsg":"game round Settled"
    }

    {
    "errno":"000003",
    "errmsg":"order_id already exist"
    }

    {
    "errno":"000004",
    "errmsg":"insufficient money"
    }

    {
    "errno":"000005",
    "errmsg":"user frozen"
    }

3、查询金币订单（确定订单是否执行成功）

• path： /gold/checkOrder

• 请求方式：GET

• 请求参数

参数名称	是否必须	描述
access_token	是	通过OAuth获取access_token接口或是刷新access_token获取的token
open_id	是	用户在第三方应用中的标识
order_id	是	订单号（调用方生成，必须保证唯一），交易的唯一标志

• 返回参数

参数	描述
success	交易成功标识,异常情况不返回该字段
errno	错误编码,异常情况才会返回此字段
errmsg	错误简述,异常情况才会返回此字段

• 请求实例

• 返回结果：

  • 请求成功：

    {
    "success":true
    }

    
    

  • 请求失败

    {
    "errno":"000002",
    "errmsg":"params error"
    }

    {
      "errno":"000006",
      "errmsg":"access_token invalid"
    }

    {
      "errno":"000001",
      "errmsg":"server error"
    }

    {
    "errno":"000008",
    "errmsg":"order not exist"
    }

附件

1、 统一错误码

错误码	说明
000001	服务器内部错误
000002	参数传递错误
000003	订单号重复
000004	U钻/金币 余额不足
000005	用户被冻结，不能扣钻／加钻
000006	access_token无效或已过期
000007	code无效
000008	订单号不存在
000009	游戏接口已关闭
000010	超过U钻限额
000011	round超时(局时超长)
000012	round已结算(重复结算)

2、 返回结果格式

{
  "errno": " [错误码] ", 
  "errmsg": "[错误信息]"
}