接口说明

以下所描述的接口都是由游戏开发方开发并提供给平台的接口，平台通过调用相应的接口地址，并传送文档所描述的参数至接口，以完成相应的功能。
接口对应的密钥在正式接入时再由双方约定，在本文档中测试所用的密钥默认设置为："SecretApiTest"
(注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）。
为方便描述，以下接口假设接口域名为：http://api.gameurl.com。（具体域名由游戏开发商自行决定）。

登录接口

1.1 URL 接口例子

http://api.gameurl.com/agentlogin.php?username=1&time=123412341&flag=md5字串&cm=1&site=smzt&serverid=1
登录接口无论任何错误,均跳转回官网地址,主要错误类型有：登录链接超时、 url手动篡改

1.2 参数说明

参数	说明	备注
username	平台帐号	用户在平台的uid。作为该用户在平台的唯一标识。数字格式 （int unsigned 必须设置成int 无符号类型 已超过21亿）
time	UNIX时间戳	发送请求的当前时间，需对该时间作超时验证。（建议超时超过5分钟的，即判定为登录超时。）
cm	防沉迷状态	可能的值包括： 0: 已经登记信息但没有满18岁（未通过防沉迷） 1: 已经登记信息并且已经满18岁（已通过防沉迷） 2: 没有登录信息（未通过防沉迷，应该提醒用户填写）
site	站点	跳转的站点，本参数只为某些有特别需求的游戏设定，如果没有特别规定，则参数值为空。
flag	加密签名	计算方法为：md5(username + time + 密钥 + cm + site + serverid)
serverid	服务器id	要进入的游戏服务器id 特别注意：新接游戏首服若为对外测试服，则首服serverid为999，具体对外正式服从1开始

1.3 测试

测试默认密钥	"SecretApiTest" (注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）

点击测试

充值接口

2.1 URL 接口例子

http://api.gameurl.com/pay.php?p=2011121510471152443002|301362655|10|1323917231|e89f29e5d0b811195c52832269d0e22b|1|0&charge=0.999

必须设置ip限制，限制充值请求的来源ip为： 115.182.52.* ip段 及 113.107.149.212

正式上线前请务必更换密钥 切勿使用测试密钥，防止充值金额正式充值到玩家账号中!!!

提交的时候,p的值是按照以下规则组装(具体参数说明参见2.2）：
PayNum| PayToUser| PayGold| time| flag| PayRMB| channel

2.2 参数说明(仔细查看以下说明！！！特别是手续费问题处理！！！)

以下参数麻烦存储一份，以便对账时可能需要使用

参数	说明	备注
PayNum	充值订单号	平台自行组装（不得重复）
PayToUser	充值用户	该值是urlencode之后的。 （int unsigned 必须设置成int 无符号类型 已超过21亿）
PayGold	游戏币数量	为整形数字，该值通过人民币金额和兑换比例及对应渠道手续费得到,给玩家发放的游戏币应按照这个值发放。。（由于某些充值渠道涉及手续费，以及对不同渠道的不同策略。这里的金额与人民币的比率不一定完全等于兑换比率）
PayRMB	人民币数量	float类型，平台实际收到的人民币数。（即：玩家实际充值的人民币数 - 渠道手续费）
time	UNIX时间戳	时间戳。要做超时验证，同时加密的验证里面要该参数
flag	加密串	md5(PayNum + PayToUser + PayGold +PayRMB+ time + 密钥)密钥 我们另外协定！
channel	渠道	用户充值时，使用的渠道。敬请记录该参数，对账时可能会有需要（以数字代替具体的渠道，例如：20 表示 4399一卡通。）
charge	手续费选项	表示渠道充值时，实际充值金额比率， 取值范围为：0~0.999。当应用需要确认用户实际充值金额时，可以由此参数换算得到。具体说明如下： 1.charge值为0时，表示游币直接兑换游戏币，不存在手续费 2.charge值为0.999时，表示充值渠道不收取手续费（这里可以将0.999视为1） 3.其他小数值，表示平台收到的充值金额（PayRMB)与用户实际充值金额的比率。例如：假设渠道手续费是12%， 用户充值100元，则平台实际收到88元（既参数PayRMB所传的参数）。charge的值为0.88（既88/100 = 0.88)
serverid	服务器id	该参数表示对应的服务器ID... 此参数为非所有游戏必须.如有需要.请知晓技术人员。 http://api.gameurl.com/pay.php?p=xxx&charge=0.999&serverid=1

2.3 返回值

返回值	备注
1	成功
2	订单重复
-1	提交参数不全
-2	验证失败
-3	用户不存在
-4	请求超时(一般可不作超时限制)
-5	充值比例异常( 游戏币 / 人民币 > 对换比率 / 0.5)
-6	请求ip验证失败。（请限制充值请求的来源ip为： 115.182.52.* ip段 及 113.107.149.212）
-7	要充值的服务器不存在
-99	其他原因导致的充值失败

2.4 测试

测试默认密钥	"SecretApiTest" (注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）

点击测试

防沉迷接口

此接口是提供给玩家在游戏中填写防沉迷的设置，只针对有可能在游戏中填写防沉迷信息的游戏。如需要玩家在平台填写防沉迷信息的游戏可忽略此接口，而直接在游戏中提供平台编辑防沉迷信息的链接地址: http://u.4399.com/user/realname

3.1 URL 接口例子

http://my.4399.com/?ct=api&ac=fcm&appid=800102&account=chen&truename=abc&card=440101119986450111&sign=

3.2 参数说明

参数	说明	备注
appid	游戏编号	表示游戏在平台的编号，每款游戏有唯一的编号，接入游戏时可向平台接口负责人询问游戏编号的值
account	玩家账号	该值是urlencode之后的。
truename	真实名字	该值是urlencode之后的。
card	身份证号码	身份证号码
sign	加密串	md5($truename.$account.$key.$card) 密钥 我们另外协定！ 此处truname, account,均为urlencode之前的值

防沉迷密钥一般由平台提供,此密钥为初步定义密钥，若需更改，请立即通知双方技术人员

3.3 返回值

返回值	备注
1	成功登记并且年龄超过18岁
2	成功登记但年龄没有超过18岁
-1	提交参数不全
-2	验证失败
-3	身份证号码无效
-7	真实姓名验证无效
-4	不允许重复登记
-5	登记失败
-6	用户不存在

在线数据接口

提供平台查询在线信息，包括：当前在线人数，当日最高在线人数，当天最低在线人数

游戏合服后，请确保原有请求一样可以获取到在线数据
（如 2、3 服 合并到1服..请保证原来取2、3 服的链接一样可以获得合服后的数据,平台方不修改请求地址。)

4.1 URL 接口例子

http://xxx/today_online.php?time=1312256449&serverid=1&flag=***

4.2 参数说明

参数	说明	备注
time	UNIX时间戳	要做超时验证，同时加密的验证里面要该参数
flag	加密串	md5(time + 密钥)密钥 我们另外协定！
serverid	服务器id	若没有服务器id，则取回所有服务器对应在线数据。若有传serverid则取对应服务器在线人数

4.3 返回值

有传serverid参数时 返回：当前在线人数|当日最高在线人数|当天最低在线人数 例：1000|1200|400

没有传serverid参数时 返回json格式数据：[{"serverid":"对应服务器id","online":"当前在线人数|当日最高在线人数|当天最低在线人数"}]

例：[{"serverid":"1","online":"1000|1200|400"},{"serverid":"2","online":"1000|1200|400"}]

返回值	备注
-1	提交参数不全
-2	验证失败

4.3 测试

测试默认密钥	"SecretApiTest" (注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）

点击测试

获取玩家信息

玩家信息接口说明

5.1 URL 接口例子

http://xxx/api/get_player_info.php?username=forever&serverid=1&time=130674873&flag=

5.2 参数说明

参数	说明	备注
username	平台id
serverid	服务器id	对应的服务器id，如果没有服务器id，则为空
time	UNIX时间戳	加密的验证里面要该参数
flag	加密串	md5(username + serverid + time + 密钥) 密钥 我们另外协定！ 此处username为urlencode前的值

5.3 返回值

返回值	备注
玩家数据	成功( 成功返回 (1).userid即平台id 参数说明中的username; (2).nickname即用户在游戏的昵称,返回格式为JSON; (3).level即用户在游戏中的等级 (4).money即用户在游戏中的游戏币库存     游戏币（即类似元宝等）库存，即游戏币剩余的数量，如果有绑定的游戏币，需要做区分     'money' => array('bind'=>100, 'normal' => 20) bind:绑定游戏币 normal:游戏币充值获得     如果没有区分绑定游戏币 则bind的值为0 (5).如果有多个角色，则返回多个角色信息。 返回数据例子： 单角色：     [{"userid":1234,"nickname":"abcd","level":"13","money":{"bind":1,"normal":100}}] 多角色：     [{"userid":1234,"nickname":"abcd","level":"13","money":{"bind":1,"normal":100}},{"userid":1234,"nickname":"hijk","level":"10","money":{"bind":0,"normal":100}}] )
0	未知错误
2	用户不存在
3	ip限制(若不需要限制ip，则不会返回此值)
4	参数错误
5	验证错误

玩家数据格式：json格式。
例子：
单角色：     [{"userid":1234,"nickname":"abcd","level":"13","money":{"bind":1,"normal":100}}] 多角色：     [{"userid":1234,"nickname":"abcd","level":"13","money":{"bind":1,"normal":100}},{"userid":1234,"nickname":"hijk","level":"10","money":{"bind":0,"normal":100}}]

5.4 测试

测试默认密钥	"SecretApiTest" (注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）

点击测试

订单信息接口

订单接口说明

6.1 URL 接口例子

http://xxx/api/get_order_info.php?order=1313164&time=130674873&flag=*****&serverid=1

6.2 参数说明

参数	说明	备注
order	订单号	订单格式为3到20个数字。
time	UNIX时间戳	加密的验证里面要该参数
flag	加密串	md5(order + time + 密钥) 密钥 我们另外协定！
serverid	充值的服务器id	如果不需要该参数或无服务器概念，可无视

6.3 返回值

返回值	备注
订单数据	成功 订单数据包括： order : 订单号 username :平台id money:人民币 gamemoney:游戏币 time:时间 nickname:角色名 serve_id:服务器id status:订单状态（1:表示成功。 -1:表示失败）
-1	订单号信息不存在
0	未知错误
3	ip限制(若不需要限制ip，则不会返回此值)
4	参数错误
5	验证错误

订单详细数据格式：json格式。
例子：
{"order":"1313164","username":"\u6ef4\u6ef4","money":"2234","gamemoney":"1234","time":"2012-12-25 07:59:59","nickname":"\u6ef4\u6ef4","serve_id":"1","status":"1"}

6.4 测试

测试默认密钥	"SecretApiTest" (注：不同的接口密钥可能不一致，开发时请勿设定为统一配置）

点击测试

排行榜接口

排行榜说明:返回游戏内的各种排行

游戏合服后，请确保原有请求一样可以获取到排行数据
（如 2、3 服 合并到1服..请保证原来取2、3 服的链接一样可以获得合服后的数据,平台方不修改请求地址。)

9.1 URL 接口例子

http://xxx/api/get_rank_info.php?kind=level&time=130674873&serverid=1&flag=****

9.2 参数说明

参数	说明	备注
kind	排行类别	例如 等级=>level 金币=>money (最好提供两种以上排行...具体kind的值 由游戏方提供.)
time	UNIX时间戳	加密的验证里面要该参数
flag	加密串	md5(kind + time + 密钥 + serverid) 密钥 我们另外协定！
serverid	游戏服务器id	如果不需要该参数或无服务器概念，可无视

9.3 返回值

返回值	备注
排行榜数据	成功（至少返回 10条数据） 排行数据包括： rank : 排行 name : 角色名称 对应kind : kind的值（例如 level ： 80）
-1	未知错误
-3	参数错误
-4	验证错误

订单详细数据格式：json格式。
例子：
[{"rank":"1","name":"\u6b66\u70ab\u660e","level":"80"},{"rank":"2","name":"\u6b66\u70ab\u660e","level":"80"}]

单服每日游戏币日志接口

获取一个游戏服每天的游戏币增加/消耗流水日志，平台每天会主动读取游戏方前一天的游戏币增加/消耗流水日志，也可能每个小时去读取上一个小时游戏方的游戏币增加/消耗流水。 定义：游戏币 － 仅仅表示充值后兑换到的游戏内部货币，不包含游戏自身普通货币，比如大部分游戏的铜钱

10.1 URL 接口例子

http://xxx/api/get_money_byserver_info.php?date=20140630&minhour=0&maxhour=23&time=1386087697&flag=****&serverid=1

10.2 参数说明

参数	说明	备注
date	格式：20140630	要查询的日期 (必须)
minhour	非必须 int	要返回在线开始的小时数 如果不传，取默认值0，表示从0点开始
maxhour	非必须 int	要返回在线结束的小时 如果不传，取默认值23 注意该值对应的是每个小时的59分59秒
time	UNIX时间戳	(平台发起访问的时间戳，用来做超时验证，建议超时时间120秒。) 加密的验证里面要该参数
flag	加密串	md5(date + time + 密钥 ) 密钥 我们另外协定！
serverid	游戏服务器id	如果不需要该参数或无服务器概念，可无视

10.3 返回值

返回值	备注
正确返回： 游戏币数据	返回参数内需要的数据（没数据的情况返回错误状态码） 格式： utf8编码的txt文档 角色名称A    用户平台账号A    游戏币变化    剩余游戏币    交易类型    交易说明    unix时间    绑定币变化    绑定币剩余 userRoleB    usernameB    count    remain_count    type    type_desc    time    bind_count    bind_remain_count userRoleC    usernameC    count    remain_count    type    type_desc    time    bind_count    bind_remain_count userRoleD    usernameD    count    remain_count    type    type_desc    time    bind_count    bind_remain_count 例子： 孩子 c5568218 -28 0 2 商场购买物品 1386087697 0 0 孩子 c5568218 -28 0 2 商场购买物品 1386087859 0 0 孩子 c5568218 -9 0 2 商场购买物品 1386114936 0 0 1.count表明本次日志中游戏币的变化数量，正表示用户自身游戏币增加，负表示用户消耗游戏币。 2.remain_count表示本次交易发生后，玩家帐号上的游戏币剩余量。 3.type表示日志类型暂时约定：0:充值 1:游戏内部发放 2:自己购买物品 3：和其他玩家交易 4:其他 4.type_desc为交易详情的说明，如：购买1级红宝石 5.bind_count为绑定元宝消耗数量(没有则为0) 6.bind_remain_count为绑定元宝剩余量(没有则为0) 7.返回值里面的时间表示该日志产生的时间，为标准时间戳格式，单位：秒。 8.如果成功，直接返回数据列表 9.分隔符定义，所有的字段用制表符“\t”分隔，行间用换行符"\n"分隔 10.用户平台账号（username） 登录接口的username, 即4399平台uid
错误返回:	返回数据格式为json格式： {"status":-1,"remark":"\u5907\u6ce8"} status的值为： -1 ： 参数缺失 -2 ：验证失败 -3 ：时间验证超时，链接已经失效 -4 ：数据为空

游戏币库存接口

获取一个游戏服某一天所有用户拥有的游戏币库存。平台每天凌晨左右会主动读取游戏方前一天的统计数据 定义：游戏币 － 仅仅表示充值后兑换到的游戏内部货币，不包含游戏自身普通货币，比如大部分游戏的铜钱

11.1 URL 接口例子

http://xxx/api/get_money_info.php?date=20140630&time=1386087697&flag=****&serverid=1

11.2 参数说明

参数	说明	备注
date	格式：20140630	要查询的日期 (必须)
time	UNIX时间戳	(平台发起访问的时间戳，用来做超时验证，建议超时时间120秒。) 加密的验证里面要该参数
flag	加密串	md5(date + time + 密钥 ) 密钥 我们另外协定！
serverid	游戏服务器id	如果不需要该参数或无服务器概念，可无视

11.3 返回值

返回值	备注
正确返回：	返回参数内需要的数据 status : 1 data : 包含以下数组内容array(    'pay_count' => '当天总充值游戏币数目',     'given_count' => '当天系统产出或赠送游戏币数目',     'used_count' => '当天玩家消耗游戏币数目',     'remain_count' => '当天服中剩余的游戏币总数',     'given_count_bind' => '当天系统产出或赠送绑定游戏币数目',     'used_count_bind' => '当天玩家消耗绑定游戏币数目',) remark : remark 示例：返回数据格式为json格式（注意使用utf8编码）： {"status":1,"data": {"pay_count":"\u5f53\u5929\u603b\u5145\u503c\u6e38\u620f\u5e01\u6570\u76ee", "given_count":"\u5f53\u5929\u7cfb\u7edf\u4ea7\u51fa\u6216\u8d60\u9001\u6e38\u620f\u5e01\u6570\u76ee", "used_count":"\u5f53\u5929\u73a9\u5bb6\u6d88\u8017\u6e38\u620f\u5e01\u6570\u76ee", "remain_count":"\u5f53\u5929\u670d\u4e2d\u5269\u4f59\u7684\u6e38\u620f\u5e01\u603b\u6570", "given_count_bind":"\u5f53\u5929\u7cfb\u7edf\u4ea7\u51fa\u6216\u8d60\u9001\u7ed1\u5b9a\u6e38\u620f\u5e01\u6570\u76ee", "used_count_bind":"\u5f53\u5929\u73a9\u5bb6\u6d88\u8017\u7ed1\u5b9a\u6e38\u620f\u5e01\u6570\u76ee"} "remark":"remark"}
错误返回:	返回数据格式为json格式： {"status":-1,"remark":"\u5907\u6ce8"} status的值为： -1 ： 参数缺失 -2 ：验证失败 -3 ：时间验证超时，链接已经失效

单服每日道具日志接口

获取一个游戏服每天的道具增加/消耗流水日志，平台每天会主动读取游戏方前一天的道具增加/消耗流水日志，也可能每个小时去读取上一个小时游戏方的道具增加/消耗流水。
道具类型说明：非商城购买的全部归为即时型，商城购买的才细分即时、时长、永久三种。商城购买的，即时型道具是指使用完就没了的，如药水等；时长型是有明确时间的，如月卡，7天有效等；永久型则是除上述两种以外的。

12.1 URL 接口例子

http://xxx/api/get_props_byserver_info.php?date=20140630&minhour=0&maxhour=23&time=1386087697&flag=****&serverid=1

12.2 参数说明

参数	说明	备注
date	格式：20140630	要查询的日期 (必须)
minhour	非必须 int	要返回在线开始的小时数 如果不传，取默认值0，表示从0点开始
maxhour	非必须 int	要返回在线结束的小时 如果不传，取默认值23 注意该值对应的是每个小时的59分59秒
time	UNIX时间戳	(平台发起访问的时间戳，用来做超时验证，建议超时时间120秒。) 加密的验证里面要该参数
flag	加密串	md5(date + time + 密钥 ) 密钥 我们另外协定！
serverid	游戏服务器id	如果不需要该参数或无服务器概念，可无视

12.3 返回值

返回值	备注
正确返回： 游戏币数据	返回参数内需要的数据（没数据的情况返回错误状态码） 格式： utf8编码的txt文档 道具ID（游戏方所属）     道具类型     有效时间     4399帐号ID     角色名     单价     1.获得/2.消耗     数量     时间     所在分服     说明 propIdA     propTypeA     propTime     userId     userRoleA     price     type     count     datetime     server     remain     propIdB     propTypeB     propTime     userId     userRoleB     price     type     count     datetime     server     remain     propIdC     propTypeC     propTime     userId     userRoleC     price     type     count     datetime     server     remain     例子： 17 1 0 1234 欧阳奇 10 2 1 1386087697 2 使用补血丹 17 1 0 1234 欧阳奇 10 2 1 1386087697 2 使用补血丹 17 1 0 1234 欧阳奇 10 2 1 1386087697 2 使用补血丹 1.道具类型暂定为3中类型：1.即时型道具 ，2，时长型道具，3永久性道具 。详见接口说明处的红字说明 2.返回值里面的时间表示该日志产生的时间，为标准时间戳格式，单位：秒。 3.有效时间表示道具的有效时长，单位：秒。若是即时型或永久型的道具，返回0 4.4399帐号ID即 登录接口的username
错误返回:	返回数据格式为json格式： {"status":-1,"remark":"\u5907\u6ce8"} status的值为： -1 ： 参数缺失 -2 ：验证失败 -3 ：时间验证超时，链接已经失效 -4 ：数据为空

道具清单接口

获取一个游戏里的道具清单列表，本接口可能每天请求一次以确保同步游戏道具系统的调整
道具类型说明：非商城购买的全部归为即时型，商城购买的才细分即时、时长、永久三种。商城购买的，即时型道具是指使用完就没了的，如药水等；时长型是有明确时间的，如月卡，7天有效等；永久型则是除上述两种以外的。

13.1 URL 接口例子

http://xxx/api/get_prop_list.php?time=1386087697&flag=****

13.2 参数说明

参数	说明	备注
time	UNIX时间戳	(平台发起访问的时间戳，用来做超时验证，建议超时时间120秒。) 加密的验证里面要该参数
flag	加密串	md5(time + 密钥 ) 密钥 我们另外协定！

13.3 返回值

返回值	备注
正确返回：	返回游戏最新的道具列表清单，以如下所示的格式返回 返回格式：utf8编码的txt文档 道具ID     道具名     价格     道具类型     有效周期     购买比例     说明 propIdA     propNameA     propMoneyA     propTypeA     time     propProA     remain     propIdB     propNameB     propMoneyB     propTypeB     time     propProB     remain     propIdC     propNameC     propMoneyC     propTypeC     time     propProC     remain     示例 1 屠龙刀 10000 3 0 0.0001 屠龙刀说明 2 回城卷 500 1 0 99 返回城里 3 加速升级 6000 2 80 600 使用后10分钟内升级加速 1.道具类型暂定为3中类型：1.即时型道具 ，2，时长型道具，3永久性道具 。详见接口说明处的红字说明 2.有效周期指的是道具使用的有效时间，单位：秒。 3.价格表示购买道具需要的是多少游戏币。 4.兑换比率，表示购买道具的比例
错误返回:	返回数据格式为json格式： {"status":-1,"remark":"\u5907\u6ce8"} status的值为： -1 ： 参数缺失 -2 ：验证失败 -3 ：时间验证超时，链接已经失效

用户库存接口

获取一个游戏里的充值用户当前的游戏币及道具库存列表，本接口定时请求（每日或者每月）。
若能直接返回充值用户的游戏币及道具接口，则直接返回充值用户的数据，否则需要返回所有用户的数据。

14.1 URL 接口例子

http://xxx/api/get_money_and_prop_by_user.php?time=1386087697&flag=****

14.2 参数说明

参数	说明	备注
time	UNIX时间戳	(平台发起访问的时间戳，用来做超时验证，建议超时时间120秒。) 加密的验证里面要该参数
flag	加密串	md5(date + time + 密钥 ) 密钥 我们另外协定！

14.3 返回值

返回值	备注
正确返回：	返回游戏里当前所有充值用户的游戏币及道具库存列表清单，以如下所示的格式返回 返回格式：utf8编码的txt文档 uid     角色名     服务器ID     道具id     道具单价     道具类型     道具有效时间     道具获得时间     说明 uid     nickname     serverid     propid     propmoney     proptype     proptime     propbegin     示例 1 独孤求败 2 1 480000 3 0 1427605970 1。uid 表示4399用户帐号，即登录接口所传递的username 2。道具类型暂定为3中类型：1.即时型道具 ，2，时长型道具，3永久性道具 3。道具有效时间指的是道具使用的有效时间，单位：秒。若为即时型道具或时长型道具则值为0 4。道具获得时间使用时间戳表示
错误返回:	返回数据格式为json格式： {"status":-1,"remark":"\u5907\u6ce8"} status的值为： -1 ： 参数缺失 -2 ：验证失败 -3 ：时间验证超时，链接已经失效