预置接口

文章目录

修订记录
全局说明
请求参数说明
返回结果说明
GM接口列表
回调接口列表
- 说明
- 1. 游戏服变更回调
2. 发送全服邮件回调
3. 发送角色邮件回调
4. 获取渠道列表
App Key签名规则
App Secret签名规则

修订记录

文档版本	更新日期	更新内容
1.1.8	2024.12.17	新增“获取抖音用户已就绪场景列表”接口
1.1.7	2024.12.09	发送角色邮件参数source新增类型：4-支付宝小游戏礼包
1.1.6	2024.10.23	增加“推送全服礼包”、“推送角色礼包”、“撤回礼包”接口
1.1.5	2024.06.21	发送角色邮件接口，新增服务器id字段
1.1.4	2024.06.17	发送角色邮件接口，字段source新增类型 3微信礼包，字段exchange_id 由int类型改为string类型
1.1.3	2024.03.26	增加“获取游戏服准入白名单”接口
1.1.2	2024.01.31	1 “发送富文本公告”接口支持分批发送功能，增加is_del参数 2 “发送跑马灯公告”接口支持分批发送功能，增加is_del参数 3 “发送全服邮件”接口支持分批发送功能，增加渠道channel_id_list、end_time和batch_id参数，同步返回字段和异步“发送全服邮件回调”把sid修改为item_id，表示游戏服ID或者渠道ID 4 “发送角色邮件”接口支持分批发送功能，增加end_time和batch_id参数 5 对请求参数说明进行补充
1.1.1	2023.12.11	增加“网页直充创建订单”接口
1.1.0	2023.11.21	1 增加“获取游戏服变更信息”、“获取道具名称列表”、“道具删除”、“发送富文本公告”、“发送跑马灯公告”、“删除公告”、“发送全服邮件”、“发送角色邮件”和“撤回邮件”预置接口 2 获取角色信息接口增加返回server_id、channel_id和vip_level参数
1.0.2	2021.10.29	GM接口参数说明
1.0.0	2020.01.01	初始化

全局说明

系统使用手册，了解功能的使用和配置，了解某个功能依赖哪些GM接口
GM接口是接入方需要按照此文档开发出对应的接口，并在“对接中心->GM接口管理”将接口配置好，便可在“GM系统”使用标准化的GM工具
接口IP白名单限制：前往“对接中心-GM接口管理”查看来源IP列表，在使用GM接口时，会从这些服务器发起请求到接入方服务器，请把以下IP加入到接入方IP白名单，以确保收到合法请求
所有的GM接口（星云调用接入方）使用App Key签名规则
- 所有GM接口请求时会带上ts和sig这2个签名参数，get请求放在url中，post放在body中，需要对sig参数进行校验，ts也可自行进行校验，比如设置有效期为5分钟内等策略。后面请求参数就不再赘述这2个参数。这2个参数也不需要在“对接中心-GM接口管理”的请求参数中进行配置
- 参数名类型长度说明是否必传
  
  ts int 11 时间戳是
  
  sig string 32 签名是
- 示例
游戏服、渠道、道具等通用接口若完成配置并上线，在对其余"未配置"状态的接口配置编辑时，会默认把游戏服、渠道、道具接口的url进行填充。注：仅针对"未配置"状态的接口生效

参数名	类型	长度	说明	是否必传
ts	int	11	时间戳	是
sig	string	32	签名	是

请求参数说明

接口参数控件类型为下拉框的说明
- 需要填写下拉框数据源获取地址，HTTP 请求方式为GET，返回的参数为固定的id和name，表示id和名称。
- 请求参数名类型长度说明是否必传
  
  ts int 11 时间戳是
  
  sig string 32 签名是
- 返回参数名类型长度说明是否必传
  
  id string 32 id 是
  
  name string 50 名称是

请求参数名	类型	长度	说明	是否必传
ts	int	11	时间戳	是
sig	string	32	签名	是

返回参数名	类型	长度	说明	是否必传
id	string	32	id	是
name	string	50	名称	是

获取下拉框请求示例：
http://{HOST}:{PORT}/serverList?ts=1535198961&sig=0bebc8ef5313b9f9b73194e138a6ee50

响应示例：

{
"status":1,
"msg":"success",
"data":[
    {
        "id":"1",
        "name":"区服1"
    },
    {
        "id":"2",
        "name":"区服2"
    }
]
}

"per_page"和"page"用于支持查询结果的分页
"ts"和"sig"字段会在请求gm接口时带上，用于签名校验
如需要增加请求参数，通用命名尽量统一，使用以下参数例：
- 请求参数命名
  
  当前分页 page
  
  每页展示数 per_page
  
  用户账号唯一标识OpenID open_id
  
  服务器id sid
  
  玩家id pid
  
  渠道id channel_id
若新增参数需设置游戏服字段，枚举获取地址可填入__NEBULA_SERVER__，即可使用“GM系统-操作工具-游戏服管理”维护的游戏服信息
若新增参数需设置渠道字段，枚举获取地址可填入__NEBULA_CHANNEL__，即可使用“对接中心-渠道打包-渠道配置”的配置完成和启用的渠道

请求参数	命名
当前分页	page
每页展示数	per_page
用户账号唯一标识OpenID	open_id
服务器id	sid
玩家id	pid
渠道id	channel_id

富文本字段说明：统一json格式，insert插入内容，attributes对插入内容配置加粗、链接、颜色等。发送富文本公告、发送全服邮件和发送角色邮件会使用到富文本。注：换行符都是单独一行，不会在文本中

{
"version": "v1",
"ops": [
{ "insert": "普通文本"},
{ "insert": "文本加粗", "attributes": { "bold": true } },
{ "insert": "文本颜色", "attributes": { "color": "#e60000" } },
{ "insert": "超链接", "attributes": { "link": "url地址" } },
{ 
    "insert": "超链接文本加粗和颜色设置组合使用",
    "attributes": { "bold": true, "color": "#e60000","copy":true, "link": "https://nebula.737.com/home3" } 
},
{ "insert": "\n" },
{ "insert": {"image": "https://nebula.737.com/home3/favicon.ico" } }]
}

富文本效果示例

由于目前暂不支持在“对接中心-GM接口”的请求参数中配置固定参数，如果需要增加固定的请求参数，可以在接口地址URL?后进行配置。（注：不要添加和请求参数一样的参数，或者ts、sig、page、per_page这些系统参数）
- GET请求时，合并url固定的请求参数+配置请求参数作为整合请求参数，对整合请求参数进行签名处理，整合请求参数作为最后请求参数
  
  发起的请求是：curl 'https://baidu.com/v1/gm/channelList?type=1&sid=s1&ts=1535198961&sig=0bebc8ef5313b9f9b73194e138a6ee50'
- POST请求时，合并url固定的请求参数+配置Body请求参数作为整合Body请求参数，然后对整合Body请求参数进行签名处理，整合Body请求参数作为最后Body请求参数，去除请求地址URL?后的固定参数作为最后请求地址
  
  发起的请求是：curl -X POST -d 'type=1&sid=s1&pid=p1&day=1&ts=1535198961&sig=0bebc8ef5313b9f9b73194e138a6ee50' https://baidu.com/v1/gm/forbiddenWords

返回结果说明

所有接口都以json格式返回，包含以下字段

参数名	说明	是否必传
status	状态，成功填1 ，失败填其他数字	是
msg	信息，成功填ok，失败填写具体原因	是
errno	错误码（失败时为必填项（填写0以外的数字），成功可传可不传（传填0））	否
data	数据	否

响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"区服1"
        },
        {
            "id":"2",
            "name":"区服2"
        }
    ]
}

GM接口列表

1. 获取游戏服变更信息

1.1 说明

运用于 GM系统-操作工具-游戏服管理，游戏研发可通过此接口获取于星云管理的游戏服信息
若此接口已配置上线，则GM系统中的所有功能，若需使用游戏服信息，将自动使用 “游戏服管理”中的游戏服信息
此接口与“获取游戏当前可用的游戏服列表”接口二选一即可，若已配置上线后者，则无需配置此接口

1.2 请求方式

POST

1.3 请求参数

  {
    "list":[
        {
            "is_del":0,
            "sid":"aaaaaa",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
              },
        {
            "is_del":0,
            "sid":"bbbb",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":"新服",
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"  
          }
    ],
}

参数名	类型	长度	说明	是否必传
list	string，json格式	-	服务器列表	是
list.is_del	int	1	默认0，1表示删除	是
list.sid	string	32	游戏服id	是
list.name	string	50	游戏服名称	是
list.server_char	string	32	集群标识	是
list.display_time	string	-	对外展示时间，格式YYYY-MM-DD hh:mm:ss	是
list.open_time	string	-	开服时间，格式YYYY-MM-DD hh:mm:ss	是
list.channel_id_list	array	-	渠道id列表	是
list.tag	int	1	标签，1正常 2新服 3爆满 4推荐	是
list.use_status	int	1	使用状态，1启用 2停新 3停用	是
list.maintain_status	int	1	维护状态，1正常 2维护	是
list.deploy_status	int	1	部署状态，1未部署 2变更中 3已部署	是
list.create_time	string	-	创建时间，格式YYYY-MM-DD hh:mm:ss	是
list.update_time	string	-	更新时间，格式YYYY-MM-DD hh:mm:ss	是

1.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

2. 获取游戏当前可用的游戏服列表

2.1 说明

此接口与“获取游戏服变更信息”接口二选一即可，若已对接 GM系统-操作工具-游戏服管理，则无需配置此接口
若此接口已配置上线，则玩家于SDK登录后进入游戏前访问C端客服中心时，可通过此接口选择游戏服
GM系统-操作工具中的所有功能，若需使用游戏服信息，将自动同步此接口信息

2.2 请求方式

2.3 请求参数

2.4 返回参数

参数名	类型	长度	说明	是否必传
id	string	32	游戏服id	是
name	string	50	游戏服名称	是

响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

3. 获取游戏当前可用的渠道列表

3.1 说明

若已对接聚合渠道SDK、已进行对接中心-渠道打包-渠道配置，则无需配置此接口
若此接口已配置上线，则GM系统-操作工具中的所有功能，若需使用渠道信息，将自动同步此接口信息

3.2 请求方式

3.3 请求参数

3.4 返回参数

参数名	类型	长度	说明	是否必传
id	string	32	渠道id	是
name	string	50	渠道名称	是

响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

4. 获取角色信息（按创角时间降序）

4.1 说明

运用于 GM系统-信息查询-角色信息查询

4.2 请求方式

4.3 请求参数

参数名	类型	长度	说明	是否必传
per_page	int	11	每页显示条数	是
page	int	11	页码	是
pname	string	50	角色名称，支持模糊搜索	否
pid	string	50	角色ID	否
open_id	string	50	用户OpenID	否
did	string	32	创角设备id	否
ip	string	32	创角ip	否

4.4 返回参数

参数名	类型	长度	说明	是否必传
data.total	int	11	总记录数	是
data.list	array	1000	玩家信息列表	是
data.list.server_id	string	32	游戏服ID	是
data.list.server_name	string	50	游戏服名称	是
data.list.channel_id	string	32	渠道ID	是
data.list.channel_name	string	50	渠道名称	是
data.list.open_id	string	32	用户OpenID	是
data.list.pid	string	32	角色id	是
data.list.pname	string	50	角色名称	是
data.list.level	int	11	角色等级	是
data.list.vip_level	int	11	角色vip等级	是
data.list.register_time	string	50	创角时间，格式YYYY-MM-DD hh:mm:ss	是
data.list.did	string	32	创角设备id	是
data.list.ip	string	32	创角ip	是
data.list.amount	float	32	累计充值金额（单位为元或美元）	是
data.list.recharge_num	int	11	累计充值笔数	是
data.list.last_login_time	string	32	最后登录时间，格式YYYY-MM-DD hh:mm:ss	是

响应示例：

{"status":1,"msg":"success","data":{"total":"2","list":[{"server_name":"游戏服名称1","channel_name":"渠道名称1","server_id":"1","channel_id":"1","open_id":"413bea7eafa0dafe8f76a4544546ae3b","pid":"3245dgh","pname":"角色名1","level":"13","vip_level":"13","register_time":"2019-02-07 14:28:15","did":"3ab0854691d6870bfcfe6c501c3bd78e","ip":"123.207.66.53","amount":"100","recharge_num":"13","last_login_time":"2019-02-07 14:38:15"},{"server_name":"游戏服名称2","channel_name":"渠道名称2","server_id":"2","channel_id":"2","open_id":"413bea7eafa0dafe8f76a4544546ae3b","pid":"3345dgh","pname":"角色名2","level":"11","vip_level":"12","register_time":"2019-02-07 14:28:15","did":"3ab0854691d6870bfcfe6c501c3bd78e","ip":"123.207.66.53","amount":"333","recharge_num":"13","last_login_time":"2019-02-07 14:38:15"}]}}

5. 获取游戏服准入白名单

5.1 说明

游戏研发可通过此接口获取于 GM系统-操作工具-游戏服管理-准入白名单配置的准入白名单
注意：星云会异步把准入白名单数据全量推送到该GM接口，研发需自行处理准入白名单用户进入游戏逻辑

5.2 请求方式

POST

5.3 请求参数

参数名	类型	长度	说明	是否必传
whitelist	string	20000	聚合OpenID列表，用英文逗号进行分割，最大20000个	是

5.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

6. 获取客服工单处理通知

6.1 说明

玩家于C端SDK登录后客服中心（含“SDK登录后进入游戏前”+“SDK进入游戏后”）“联系客服”提交的问题，在B端客服工单系统被客服人员回复后，游戏研发可通过此接口获取进度提醒，用于在游戏内向玩家推送已处理通知
注意
- 游戏向玩家的具体推送形式，需由游戏研发自行处理（如红点、邮件等）
- 此接口暂不支持 WEB客服及 SDK登录前客服的工单处理进度通知，其余通知方式说明，详见客服中心介绍

6.2 请求方式

POST

6.3 请求参数

参数名	类型	长度	说明	是否必传
open_id	string	32	用户OpenID	是
sid	string	32	服务器id	否
channel_id	string	32	渠道id	否
pid	string	32	角色id	否

6.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

7. 获取道具名称列表

7.1 说明

若此接口已配置上线，则GM系统中的所有功能，若需使用道具信息，将自动同步此接口信息

7.2 请求方式

7.3 请求参数

7.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

8. 获取道具变更明细

运用于 GM系统-信息查询-道具变更明细

8.1 获取道具变更明细（按变更时间降序）

HTTP 请求方式：
GET

参数说明：

参数名	类型	长度	说明	是否必传
per_page	int	11	每页显示条数	是
page	int	11	页码	是
pid	string	50	角色id	是
prop_id	int	11	道具id	否，和变更原因id必传一个
change_reason_id	int	11	变更原因id	否，和道具id必传一个
change_start_time	string	32	变更开始时间，格式YYYY-MM-DD hh:mm:ss	是
change_end_time	string	32	变更结束时间，格式YYYY-MM-DD hh:mm:ss	是

请求示例：
http://{HOST}:{PORT}/propChangeList?ts=1535195226&sig=1c9f83680d579d182b02b81efad18523&per_page=10&page=1pid=111&prop_id=11&change_start_time=2019-06-11 11:11:09&change_end_time=2019-06-11 11:16:11
响应示例：

{"status":1,"msg":"success","data":{"total":"2","list":[{"change_time":"2020-07-18 00:01:57","prop_name":"道具名称1","change_num":"+10","account_num":"100","change_reason":"变更原因1"},{"change_time":"2020-07-18 00:02:57","prop_name":"道具名称2","change_num":"-10","account_num":"80","change_reason":"变更原因2"}]}}

返回参数说明：

参数名	类型	长度	说明	是否必传
data.total	int	11	总记录数	是
data.list	array	1000	道具变更明细列表	是
data.list.change_time	string	32	变更时间，格式YYYY-MM-DD hh:mm:ss	是
data.list.prop_name	string	50	道具名称	是
data.list.change_num	string	11	变更数量，如果是增加，数量前面需加上+，如果是减少，数量前面需加上-，例如+10或-20	是
data.list.account_num	int	11	变更后数量	是
data.list.change_reason	string	50	变更原因	是

8.2 获取道具变更原因列表

HTTP 请求方式：
GET
参数说明：

请求示例：
http://{HOST}:{PORT}/propChangeReasonList?ts=1535195226&sig=1c9f83680d579d182b02b81efad18523
响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"变更原因1"
        },
        {
            "id":"2",
            "name":"变更原因2"
        }
    ]
}

返回参数说明：

参数名	类型	长度	说明	是否必传
id	string	11	变更原因id	是
name	string	50	变更原因	是

9. 道具删除

9.1 说明

运用于 GM系统-操作工具-道具操作-道具删除

9.2 请求方式

POST

9.3 请求参数

{
    "pid": "syusfjfjs",
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "reason":"xxxx"
}

参数名	类型	长度	说明	是否必传
pid	string	50	角色id	是
prop_list	string，json格式	-	道具列表	是
prop_list.id	string	50	道具id	是
prop_list.num	int	11	道具数量	是
reason	string	50	删除原因	是

9.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

10. 发送富文本公告（分批）

10.1 说明

运用于 GM系统-操作工具-公告管理-添加&修改富文本公告
该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
有渠道或游戏服追加时，会增量请求
注：在添加&修改富文本公告时就会调用此接口，公告的显示需要由接入方自行处理

10.2 请求方式

POST

10.3 请求参数

{
    "anc_id": "100",
    "anc_type": 1,
    "title": "礼包兑换成功",
    "list_title":"公告列表标题",
    "content": {},
    "sid_list":["a111","a222"],
    "channel_id_list":["1","2"],
    "img_list":[
        {"img":"http://img1","link":"link1"},
        {"img":"http://img2","link":"link2"}
    ],
    "start_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-10 00:00:00",
    "create_time":"2023-10-01 10:00:00",
    "update_time":"2023-10-01 10:00:00"
    "sort":-1,
    "is_del":0
}

参数名	类型	长度	说明	是否必传
anc_id	string	11	公告ID，唯一	是
anc_type	int	1	公告类型，固定为1，表示富文本	是
title	string	50	公告标题	是
list_title	string	50	公告列表标题，可选	否
content	string，json格式	-	公告内容，富文本json，参见“请求参数说明”关于富文本的说明	是
channel_id_list	string，json格式	-	多个渠道id，和游戏服id二选一	否
sid_list	string，json格式	-	多个游戏服id，和渠道id二选一	否
start_time	string	-	开始生效时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	-	生效结束时间，格式YYYY-MM-DD hh:mm:ss	是
create_time	string	-	创建时间，格式YYYY-MM-DD hh:mm:ss	是
update_time	string	-	更新时间，格式YYYY-MM-DD hh:mm:ss	是
sort	int	11	优先级，0置顶、-1置底，＞0值越大越优先	是
tag	string	32	标签，可选	否
img_list	string，json格式	-	轮播图，可选	否
img_list.img	string	-	图片url	是
img_list.link	string	-	图片跳转链接，选填	否
is_del	int	1	默认0，1表示这一批次的数据都要删除	是

10.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

11. 发送跑马灯公告（分批）

11.1 说明

运用于 GM系统-操作工具-公告管理-添加&修改跑马灯公告
该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
注：在添加&修改跑马灯公告时就会调用此接口，公告的显示需要由接入方自行处理

11.2 请求方式

POST

11.3 请求参数

{
    "anc_id": "11.",
    "anc_type": 2,
    "content": "亲爱的玩家：\n 礼包奖励兑换成功，请及时领取，祝您游戏愉快^_^",
    "channel_id_list":["1","2"],
    "sid_list":["a111","a222"],
    "start_time":"2023-11.01 00:00:00",
    "end_time":"2023-11.11.00:00:00",
    "create_time":"2023-11.01 11.00:00",
    "update_time":"2023-11.01 11.00:00"
    "sort":-1,
    "interval":11,
    "is_del":0
}

参数名	类型	长度	说明	是否必传
anc_id	string	11	公告ID，唯一	是
anc_type	int	1	公告类型，固定为2，表示跑马灯	是
content	string	-	公告内容，纯文本	是
channel_id_list	string，json格式	-	多个渠道id，和游戏服id二选一	否
sid_list	string，json格式	-	多个游戏服id，和渠道id二选一	否
start_time	string	-	开始生效时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	-	生效结束时间，格式YYYY-MM-DD hh:mm:ss	是
create_time	string	-	创建时间，格式YYYY-MM-DD hh:mm:ss	是
update_time	string	-	更新时间，格式YYYY-MM-DD hh:mm:ss	是
sort	int	11	优先级，0置顶、-1置底，＞0值越大越优先	是
interval	int	11	播放间隔，分钟	是
is_del	int	1	默认0，1表示这一批次的数据都要删除	是

11.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

12. 删除公告

12.1 说明

运用于 GM系统-操作工具-公告管理-删除富文本公告&跑马灯公告
注：在删除富文本公告&跑马灯公告时就会调用此接口，公告的显示需要由接入方自行处理

12.2 请求方式

POST

12.3 请求参数

{
    "anc_id": "100",
    "anc_type": 1
}

参数名	类型	长度	说明	是否必传
anc_id	string	11	公告ID，唯一	是
anc_type	int	1	公告类型，1富文本 2跑马灯	是

12.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

13. 发送全服邮件（分批）

13.1 说明

运用于 GM系统-操作工具-邮件管理-添加&修改全服邮件
该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
有渠道或游戏服追加时，会增量请求
注：在到达设定时间时才会调用此接口

13.2 请求方式

POST

13.3 请求参数

{
    "email_id":"100",
    "email_type":1,
    "title": "礼包兑换成功",
    "sender": "福利官",
    "content": {},
    "pid_deny_list": ["syusfjfjs"],
    "channel_id_list":["1","2"],
    "sid_list":["a111","a222"],
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "send_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-07 00:00:00",
    "batch_id":"2d02e669731cbade6a64b58d602cf2a4",
}

参数名	类型	长度	说明	是否必传
email_id	string	64	邮件ID，最长64位，唯一	是
email_type	int	1	邮件类型，固定为1，表示全服邮件	是
title	string	50	邮件标题	是
sender	string	50	发件人	否
content	string，json格式	-	邮件内容，富文本json，参见“请求参数说明”关于富文本的说明	是
pid_deny_list	string，json格式	-	角色id黑名单	否
channel_id_list	string，json格式	-	多个渠道id，和游戏服id二选一	否
sid_list	string，json格式	-	多个游戏服id，和渠道id二选一	否
prop_list	string，json格式	-	可选，发送道具	否
prop_list.id	string	50	道具id	是
prop_list.num	int	11	道具数量	是
batch_id	string	64	批次id，唯一	是
send_time	string	-	发送时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	-	失效时间，格式YYYY-MM-DD hh:mm:ss	否

13.4 返回参数

响应示例：

a 异步通知邮件发送结果，需要调用发送全服邮件回调接口（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

b 同步通知邮件发送结果（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{
         "list":[
            {"item_id":"aaaa","result":1,"note":""},
            {"item_id":"bbb","result":2,"note":"ID不存在"}
        ]
    }
}

参数名	类型	注释	是否必填
list	string，json格式	发送结果列表，可选	是
list.item_id	string	游戏服ID或者渠道ID	是
list.result	int	发送情况，1成功 2失败	是
list.note	string	备注，可为空	是

14. 发送角色邮件（分批）

14.1 说明

运用于 GM系统-操作工具-邮件管理-添加&修改角色邮件
该接口是分批请求接口，当角色数量大于1000，会以每批1000条进行发送
注：在到达设定时间时才会调用此接口

14.2 请求方式

POST

14.3 请求参数

{
    "email_id":"100",
    "email_type":2,
    "source":1,
    "exchange_id":23,
    "title": "礼包兑换成功",
    "sender": "福利官",
    "content": {},
    "pid_list": ["syusfjfjs"],
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "send_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-07 00:00:00",
    "batch_id":"2d02e669731cbade6a64b58d602cf2a4",
}

参数名	类型	长度	说明	是否必传
email_id	string	64	邮件ID，最长64位，唯一	是
email_type	int	1	邮件类型，固定为2，表示角色邮件	是
source	int	1	来源，1-后台 2-礼包码 3-微信小游戏礼包 4-支付宝小游戏礼包	是
exchange_id	string	255	礼包码兑换记录id，source=2平台礼包回调接口需要传回，其它类型不需要。有传入时需要根据exchange_id做幂等，避免一次兑换多次发送邮件。	否
title	string	50	邮件标题	是
sender	string	50	发件人	否
content	string，json格式	-	邮件内容，富文本json，参见“请求参数说明”关于富文本的说明，注意：微信小游戏礼包（source=3）、支付宝小游戏礼包（source=4），不使用富文本方式解析，直接进行内容展示	是
sid	string	32	服务器id，1、字段为可选参数，星云开放平台不进行预置，有需要自行新增自定义参数。2、微信礼包码下发道具邮件该字段有值，需要进行校验	否
pid_list	string，json格式	-	角色id列表	是
prop_list	string，json格式	-	可选，发送道具列表	否
prop_list.id	string	50	道具id	是
prop_list.num	int	11	道具数量	是
batch_id	string	64	批次id，唯一	是
send_time	string	-	发送时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	-	失效时间，格式YYYY-MM-DD hh:mm:ss	否

14.4 返回参数

响应示例：

a 异步通知邮件发送结果，需要调用发送角色邮件回调接口（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

b 同步通知邮件发送结果（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{
         "list":[
            {"pid":"aaaa","result":1,"note":""},
            {"pid":"bbb","result":2,"note":"ID不存在"}
        ]
    }
}

参数名	类型	注释	是否必填
list	string，json格式	发送结果列表，可选	是
list.pid	string	角色id	是
list.result	int	发送情况，1成功 2失败	是
list.note	string	备注，可为空	是

15. 撤回邮件

15.1 说明

运用于 GM系统-操作工具-邮件管理-撤回全服邮件&角色邮件
注：在-撤回全服邮件&角色邮件调用此接口，道具是否撤回由接入方自行处理

15.2 请求方式
POST

15.3 请求参数

{
    "email_id": "100",
    "email_type": 1
}

参数名	类型	长度	说明	是否必传
email_id	string	64	邮件ID，最长64位，唯一	是
email_type	int	1	邮件类型，1全服邮件 2角色邮件	是

15.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

16. 获取玩家聊天内容

16.1 说明

GM系统-操作工具-聊天监控中，可通过此接口查询玩家聊天内容

16.2 请求方式

POST

16.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id，多个通过 “;” 符号拼接	是
channel_id	string	11	频道id，多个通过 “;” 符号拼接	是
start_time	string	32	聊天内容开始时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	32	聊天内容结束时间，格式YYYY-MM-DD hh:mm:ss	是
min_level	int	11	角色最小等级	否
max_level	int	11	角色最大等级	否

16.4 返回参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
server_name	string	50	游戏服名称	是
content	string	512	聊天内容	是
create_time	string	50	聊天时间，格式YYYY-MM-DD hh:mm:ss	是
pname	string	50	角色名称	是
pid	string	32	角色id	是
channel_name	string	50	频道	是

响应示例：

{"status":1,"msg":"success","data":[{"sid":"1","server_name":"服务器1","content":"聊天内容1","create_time":"2020-06-23 15:57:25","pname":"角色名称1","pid":"dfhe23233","channel_name":"频道名称1"},{"sid":"2","server_name":"服务器1","content":"聊天内容2","create_time":"2020-06-2315:57:26","pname":"角色名称2","pid":"fg345fg4","channel_name":"频道名称2"}]}

17. 获取游戏聊天频道列表

17.1 说明

GM系统-操作工具-聊天监控中，可通过此接口选择聊天频道

17.2 请求方式

17.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	否，多个通过 “;” 符号拼接

17.4 返回参数

参数名	类型	长度	说明	是否必传
id	int	11	频道id	是
name	string	50	频道名称	是

响应示例：

{"status":1,"msg":"success","data":[{"id":"1","name":"频道1"},{"id":"2","name":"频道2"}]}

18. 角色禁言

18.1 说明

GM系统-操作工具-违规封禁-封禁中，可通过此接口角色禁言
GM系统-操作工具-聊天监控中，可通过此接口角色禁言

18.2 请求方式

POST

18.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
pid	string	32	角色id	是
day	int	11	封禁天数	是

18.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

19. 解除角色禁言

19.1 说明

GM系统-操作工具-违规封禁-解除封禁中，可通过此接口解除角色禁言
GM系统-操作工具-聊天监控中，可通过此接口解除角色禁言

19.2 请求方式

POST

19.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
pid	string	32	角色id	是

19.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

20. 角色封停

20.1 说明

GM系统-操作工具-违规封禁-封禁中，可通过此接口角色封停
GM系统-操作工具-聊天监控中，可通过此接口角色封停

20.2 请求方式

POST

20.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
pid	string	32	角色id	是
day	int	11	封禁天数	是

20.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

21. 角色解封

21.1 说明

GM系统-操作工具-违规封禁-解除封禁中，可通过此接口角色解封
GM系统-操作工具-聊天监控中，可通过此接口角色解封

21.3 请求方式

POST

21.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
pid	string	32	角色id	是

21.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

22. ip封停

22.1 说明

GM系统-操作工具-违规封禁-封禁中，可通过此接口IP封停

22.2 请求方式

POST

22.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
ip	string	32	ip	是
day	int	11	封禁天数	是

22.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

23. ip解封

23.1 说明

GM系统-操作工具-违规封禁-解除封禁中，可通过此接口IP解封

23.2 请求方式

POST

23.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
ip	string	32	ip	是

23.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

24. 设备封停

24.1 说明

GM系统-操作工具-违规封禁-封禁中，可通过此接口设备封停

24.2 请求方式

POST

24.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
did	string	32	设备id	是
day	int	11	封禁天数	是

24.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

25. 设备解封

25.1 说明

GM系统-操作工具-违规封禁-解除封禁中，可通过此接口设备解封

25.2 请求方式

POST

25.3 请求参数

参数名	类型	长度	说明	是否必传
sid	string	11	游戏服id	是
did	string	32	设备id	是

25.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

26. 网页直充创建订单

26.1 说明

玩家网页直充时，中台通过此接口直接向游戏服务端创建订单
需对传入参数需要做基本校验，例如：商品ID和金额是否一致、是否停服
注意：针对网页直充支付回调扩展参数额外新增两个参数goods_ext（商品扩展参数）、callback_ext（创建游戏订单扩展参数）
{"pay_sign_type":"md5","os":"windows","callback_ext":"","goods_ext":""}

26.2 请求方式

POST

26.3 请求参数

参数名	类型	长度	说明	是否必传
server_id	string	32	区服ID	是
channel_id	string	32	渠道ID	是
goods_id	string	50	商品ID	是
pay_amount	int	11	支付金额（单位：分）	是
open_id	string	32	用户OpenID	是
pid	string	32	角色ID	是
level	int	11	角色等级	是
vip_level	int	11	vip等级	是

26.4 返回参数

字段名	类型	说明
game_order_id	string	游戏订单ID
callback_ext	string	游戏透传参数，支付回调游戏服务端会合并到notify_ext参数里回传，例如：{"notify_ext":{"callback_ext":""}}

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{
        "game_order_id":"2023111011124011111",
        "callback_ext":""
    }
}

27. 推送全服礼包（分批）

27.1 说明

运用于 GM系统-操作工具-定制礼包管理-添加&修改全服礼包
该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
有渠道或游戏服追加时，会增量请求
注：在到达设定时间时才会调用此接口

27.2 请求方式

POST

27.3 请求参数

参数名	类型	长度	说明	是否必传
gift_id	int	11	礼包ID	是
gift_title	string	18	礼包标题	是
gift_amount	int	11	礼包价格（单位：分）	是
gift_banner	string	255	礼包背景	是
start_time	string	32	开始时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	32	结束时间，格式YYYY-MM-DD hh:mm:ss	是
duration	int	11	持续时长（单位：秒）	是
sid_list	string	-	多个服务器ID，和渠道ID二选一，以JSON格式表示	否
channel_id_list	string	-	多个渠道ID，和服务器ID二选一，以JSON格式表示	否
prop_list	string	-	发送道具	是
prop_list.id	string	50	道具ID	是
prop_list.num	int	11	道具数量	是

27.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

28. 推送角色礼包（分批）

28.1 说明

运用于 GM系统-操作工具-定制礼包管理-添加&修改角色礼包
该接口是分批请求接口，当角色数量大于1000，会以每批1000条进行发送
注：在到达设定时间时才会调用此接口

28.2 请求方式

POST

28.3 请求参数

参数名	类型	长度	说明	是否必传
gift_id	int	11	礼包ID	是
gift_title	string	18	礼包标题	是
gift_amount	int	11	礼包价格（单位：分）	是
gift_banner	string	255	礼物背景	是
start_time	string	32	开始时间，格式YYYY-MM-DD hh:mm:ss	是
end_time	string	32	结束时间，格式YYYY-MM-DD hh:mm:ss	是
duration	int	11	持续时长（单位：秒）	是
pid_list	string	-	多个角色ID，以JSON格式表示	是
prop_list	string	-	发送道具	是
prop_list.id	string	50	道具ID	是
prop_list.num	int	11	道具数量	是

28.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

29. 撤回礼包

29.1 说明

运用于 GM系统-操作工具-定制礼包管理-撤回全服礼包&角色礼包
注：在-撤回全服礼包&角色礼包调用此接口，礼包是否撤回由接入方自行处理

29.2 请求方式

POST

29.3 请求参数

参数名	类型	长度	说明	是否必传
gift_id	int	11	礼包ID	是
gift_type	int	1	礼包类型，1全服定制礼包 2角色定制礼包	是

29.4 返回参数

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

30. 获取抖音用户已就绪场景列表

30.1 说明

抖音服务端接入文档：https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/server/feed-game/open-api

30.2 请求方式

30.3 请求参数

参数名	类型	长度	说明	是否必传
open_id	string	32	聚合OpenID	是

30.4 返回参数

字段名	类型	说明
data.list	array	用户就绪场景列表
data.list.scene	int	就绪的场景值：1：离线收益场景2：体力恢复场景3：重要事件掉落
data.list.content_ids	array	就绪场景对应自定义文案ID列表，例如：["CONTENT27648287"]
data.list.extra	string	开发者可为每个场景携带额外的信息，长度需要<100字符

响应示例：

{
    "status":1,
    "msg":"success",
    "data":{
        "list":[
          {
            "scene": 1,
            "content_ids": ["CONTENT27648287"],
            "extra": ""
         },
          {
            "scene": 2,
            "content_ids": ["CONTENT27648031"],
            "extra": ""
          }
        ]
    }
}

回调接口列表

说明

1 下列接口是接入方调用星云的接口，非必接
2 签名使用App Secret签名规则
3 入参的公共参数有

参数名	类型	注释	是否必填
app_id	string	星云AppID	是
timestamp	int	时间戳	是
sign	string	签名	是
sign_type	string	签名类型(默认：md5)	是
sign_nonce	string	签名随机数(随机数字+字符串共8位)	是
sign_version	string	签名版本,默认1.0	是

4 以json格式返回，包含以下字段

参数名	说明	是否必传
status	状态，成功未0 ，失败为非0	是
message	信息	是
trace_id	追踪id，排查问题用	否
data	数据	否

响应示例：

{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

1. 游戏服变更回调

1.1 描述

当游戏服务端有服务器变更时，将服务器变更信息通知到星云
根据server_id来识别，如果存在，会更新记录，不存在则插入记录
如果记录is_del为0，便会删掉对应server_id的记录
单次调用接口最多限制1000条服务器信息

1.2 接口地址

https://nebula.737.com/gmapi/open/server/sync

1.3 请求方式

POST

1.4 请求参数

{
    "list":[
        {
            "is_del":0,
            "sid":"aaaaaa",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
                 },
        {
            "is_del":0,
            "sid":"bbbb",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
             }
    ],
    "app_id":"30035",
    "timestamp": 1535198961,
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}

参数名	类型	注释	是否必填
app_id	string	星云AppID	是
list	string	服务器列表，单次最多限制1000条数据	是
list.is_del	int	默认0，1表示删除	否
list.sid	string	游戏服id	是
list.name	string	服务器名称	是
list.server_char	string	集群标识	是
list.display_time	string	对外展示时间，格式YYYY-MM-DD hh:mm:ss	是
list.open_time	string	开服时间，格式YYYY-MM-DD hh:mm:ss	是
list.auto_add_channel	int	新增官方渠道时自动追加，0否 1是	是
list.channel_id_list	array	渠道id列表	是
list.tag	int	标签，1正常 2新服 3爆满 4推荐	是
list.use_status	int	使用状态，1启用 2停新 3停用	是
list.maintain_status	int	维护状态，1正常 2维护	是
list.deploy_status	int	部署状态，1未部署 2变更中 3已部署	是
list.create_time	string	创建时间，格式YYYY-MM-DD hh:mm:ss	是
list.update_time	string	更新时间，格式YYYY-MM-DD hh:mm:ss	是
timestamp	int	时间戳	是
sign	string	签名	是
sign_type	string	签名类型(默认：md5)	是
sign_nonce	string	签名随机数(随机数字+字符串共8位)	是
sign_version	string	签名版本,默认1.0	是

1.5 请求成功返回：

{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

2. 发送全服邮件回调

2.1 描述

当发送全服邮件后，将具体发送结果变更信息回调

2.2 接口地址

https://nebula.737.com/gmapi/open/email/notify

2.3 请求方式

POST

2.4 请求参数

{
    "app_id": "30035",
    "email_id": "100",
    "email_type": 1,
    "timestamp": 1535198961,
    "list":[
        {"item_id":"aaaa","result":1,"note":""},
        {"item_id":"aaaa","result":2,"note":"服务器ID不存在"}
    ],
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}

参数名	类型	注释	是否必填
app_id	string	星云AppID	是
email_id	string	邮件id	是
email_type	int	邮件类型，固定为1，表示全服邮件	是
timestamp	int	时间戳	是
list	string	发送结果列表	是
list.item_id	string	游戏服ID或者渠道ID	是
list.result	int	角色发送情况，1成功 2失败	是
list.note	string	备注	是
sign	string	签名	是
sign_type	string	签名类型(默认：md5)	是
sign_nonce	string	签名随机数(随机数字+字符串共8位)	是
sign_version	string	签名版本,默认1.0	是

2.5 请求成功返回：

{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

3. 发送角色邮件回调

3.1 描述

当发送角色邮件后，将具体发送结果变更信息回调

3.2 接口地址

https://nebula.737.com/gmapi/open/email/notify

3.3 请求方式

POST

3.4 请求参数

{
    "app_id": "30035",
    "email_id": "100",
    "email_type": 2,
    "timestamp": 1535198961,
    "list":[
        {"pid":"aaaa","result":1,"note":""},
        {"pid":"aaaa","result":2,"note":"角色ID不存在"}
    ],
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}

参数名	类型	注释	是否必填
app_id	string	星云AppID	是
email_id	string	邮件id	是
email_type	int	邮件类型，固定为2，表示角色邮件	是
timestamp	int	时间戳	是
list	string	发送结果列表	是
list.pid	string	角色id	是
list.result	int	角色发送情况，1成功 2失败	是
list.note	string	备注	是
sign	string	签名	是
sign_type	string	签名类型(默认：md5)	是
sign_nonce	string	签名随机数(随机数字+字符串共8位)	是
sign_version	string	签名版本,默认1.0	是

3.5 请求成功返回：

{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

4. 获取渠道列表

4.1 描述

获取对接中心-渠道配置的渠道列表

4.2 接口地址

https://nebula.737.com/gmapi/open/channel/lists

4.3 请求方式

POST

4.4 请求参数

{
    "app_id": "30035",
    "timestamp": 1535198961,
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}

参数名	类型	注释	是否必填
app_id	string	星云AppID	是
timestamp	int	时间戳	是
sign	string	签名	是
sign_type	string	签名类型(默认：md5)	是
sign_nonce	string	签名随机数(随机数字+字符串共8位)	是
sign_version	string	签名版本,默认1.0	是

4.5 请求成功返回：

{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": [
        {"channel_id":1,"channel_name":"xxxx","is_official":1},
        {"channel_id":2,"channel_name":"xxxx","is_official":0}
    ]
}

参数名	类型	注释	是否必填
status	int	状态码	是
message	string	消息	是
data	array	数据	是
data.channel_id	int	渠道id	是
data.channel_name	string	渠道名称	是
data.is_official	int	是否官方，1官方 0三方	是

App Key签名规则

1 说明

所有星云方请求接入方的GM接口都使用该签名规则

2 获取基础接入参数

在【对接中心->SDK对接->SDK列表】，App ID（请求参数app_id）和App Key（签名密钥）
file

3 签名文档

鉴权指南

App Secret签名规则