完美页游联运接入文档V1.5.doc

V1.1完美页游联运接入文档修订记录日期修订版本修改章节修改描述作者2013-02-281.0创建linhao2013-03-081.1修复角色查询接口签名描述错误linhao2013-04-031.2添加调试信息Pangxin2013-04-091.3添加域名解析CNAME相关信息pangxin2013-04-241.4添加测试相关urlpangxin2013-05-101.5修改域名解析CANME相关信息pangxin目录目录21. 前言32. 登陆32.1. 登陆接口32.1.1. 游戏URL形式32.1.2. 接口说明33. 游戏充值划拨接口43.1. 游戏充值划拨接口43.1.1. 接口URL形式43.1.2. 接口说明54. 查询游戏角色信息接口64.1. 查询游戏角色信息接口74.1.1. 接口URL形式74.1.2. 接口说明75. 调试帮助86. 域名解析（CNAME）规则97. 完美页游正式服务器URL97.1. 登陆URL97.2. 划拨URL107.3. 角色查询108. 完美页游测试服务器URL108.1. 测试登陆URL108.2. 测试划拨URL108.3. 测试角色查询101. 前言本文档共有三个个接口的描述分别为登陆接口和充值划拨接口、角色查询接口，其中登陆接口采用浏览器重新定向的方式传递参数，采用MD5签名保证安全，充值划拨和角色查询接口使用MD5数据签名和IP地址白名单方式保证安全。2. 登陆游戏的登陆通过平台浏览器重新定向的方式向游戏传递认证参数的方式，和平台商定一个“签名密码”，安全性由这个密码来保证。具体方式是，平台使用签名密码对用户的ID、时间戳及防沉迷状态进行签名，游戏收到信息后对签名进行校验，如果校验成功后会使用服务器的时间和传递过来的时间戳进行比对，如果在有效期内则成功进入游戏。；注：由于签名的时效和双方的服务器时间有关，请保证服务器时间为正确的北京时间2.1. 登陆接口2.1.1. 游戏URL形式登录URL：/login测试登录URL：30:9090/login游戏的URL和游戏相关，不同的游戏有不同的URL，以战三国为例：/login?from=173&game=zsg&server=1&user_id=67332423&fatigue=0&t=13413245&signature=25d55ad283aa400af464c76d713c07adl 在URL中“?”之前的是游戏的URL，“?”之后是参数l 测试请使用文档后的测试登录URL2.1.2. 接口说明. 参数列表参数名必选类型及范围说明from是string用户来源，标示用户的来源，由完美提供game是string要登陆的游戏，由完美提供，例如：zsg：战三国server是string服务器编号（1,2），由完美提供user_id是string用户账户IDfatigue是int防沉迷（0为未填写信息，1为防沉迷账号，2为非防沉迷账号）servername否string页面title显示服务器名称，中文需要URLEncoding UTF-8编码，不传入默认使用以下名称：战三国- 双线X服t是long时间戳（秒）signature是string验证串（生成验证串时使用from、game、server、userid、fatigue、t这个六个参数），md5值的小写字符串生成方法见下方_debug否int调试参数，不计入签名，不可用于正式环境，值为1时，可以返回更详细的错误信息. 参数signature的生成方法将参数名和参数值拼成如下形式： from=173+game=zsg+server=1+user_id=67332423+fatigue=0+t=13413245+ login_secret_signature=xxxxxxxx，计算该值的32位md5的值说明：l 在“=”（等号，半角字符）之前是参数名称，之后是该参数的值。l 其中“+”（加号）为字符串的连接运算符，不包含在签名串内，请根据不同的计算机语言进行替换l login_secret_signature为双方商定的游戏登陆“签名秘钥”，该密钥很重要不得泄露。（注意：该秘钥和充值用的不是同一个）l 测试时签名秘钥使用:1234563. 游戏充值划拨接口充值划拨接口采用http协议，get提交数据方式，结果以json格式返回。该接口有防火墙的IP限制，开通之前需要将平台调用该接口服务器的IP通知完美。3.1. 游戏充值划拨接口3.1.1. 接口URL形式充值URL：/api/pay测试充值URL：30:9090/api/pay充值划拨接口的URL和游戏相关，不同的游戏有不同的URL，以战三国为例：/api/pay?from=173&game=zsg&server=1&user_id=67332423&amount=1000&order_number=2345235235&t=13413245&signature=25d55ad283aa400af464c76d713c07ad说明：l 在URL中“?”之前的是游戏划拨的URL，“?”之后的是参数l 测试请使用文档后的测试充值URL3.1.2. 接口说明. 参数列表参数名必选类型及范围说明from是string用户来源，标示用户的来源，由完美提供game是string目标游戏，由完美提供，例如zsg：战三国server是string服务器编号（1,2），由完美提供user_id是string用户账户IDamount是int充入的人民币数量（单位分，为10的整数倍）,大于10order_number是string交易订单号t是long时间戳（秒）signature是string验证串（生成验证串时使用from、game、server、user_id、amount 、order_number 、t这些参数），md5的小写字符串生成方法见下方_debug否int调试参数，不计入签名，不可用于正式环境，值为1时，可以返回更详细的错误信息. 参数signature的生成方法将参数名和参数值拼成如下形式：from=173+game=zsg+server=1+user_id=67332423+amount=1000+order_number=12341244+t=13413245+transfer_secret_signature=xxxxxxxx，计算该值的32位md5的值（小写字符串）。说明：l 在“=”（等号，半角字符）之前是参数名称，之后是该参数的值。l 其中“+”（加号）为字符串的连接运算符，不包含在签名串内，请根据不同的计算机语言进行替换l transfer_secret_signature为双方商定的游戏充值划拨“签名秘钥”，该密钥很重要不得泄露。（注意：该秘钥和登陆用的不是同一个）l 测试时签名秘钥使用12345. 接口返回值返回值得形式为json字符串。失败时返回的json中只包含status信息。成功返回所有变量，格式如下：参数名类型及范围说明statusint1操作成功。-1失败。-2用户有误。-3服务器有误。-4游戏id有误。-5钱数有误。-6订单号重复。-10系统错误。user_idstring用户账户IDamountint充入的人民币数量order_numberstring交易订单号示例:成功：status:1,user_id:67332423,amount:1000,order_number: 12341244失败：status:-64. 查询游戏角色信息接口采用http get方式提交查询数据，结果以json格式返回。该接口有防火墙的IP限制，开通之前需要将平台调用该接口服务器的IP通知完美。4.1. 查询游戏角色信息接口4.1.1. 接口URL形式角色查询URL：/api/role测试角色查询URL：30:9090/api/role充值划拨接口的URL和游戏相关，不同的游戏有不同的URL，以战三国为例：/api/role?from=173&game=zsg&server=1&user_id=67332423&t=13413245&signature=25d55ad283aa400af464c76d713c07ad说明：l 在URL中“?”之前的是游戏划拨的URL，“?”之后的是参数l 测试请使用文档后的测试角色查询URL4.1.2. 接口说明. 参数列表参数名必选类型及范围说明from是string用户来源，标示用户的来源，由完美提供game是string目标游戏，由完美提供，例如zsg：战三国server是string服务器编号（1,2），由完美提供user_id是string用户账户IDt是long时间戳（秒）signature是string验证串（生成验证串时使用from、game、server、user_id、t这些参数），md5的小写字符串生成方法见下方_debug否int调试参数，不计入签名，不可用于正式环境，值为1时，可以返回更详细的错误信息. 参数signature的生成方法将参数名和参数值拼成如下形式：from=173+game=173+server=1+user_id=67332423+t=13413245+transfer_secret_signature=xxxxxxxx，计算该值的32位md5的值（小写字符串）。说明：l 在“=”（等号，半角字符）之前是参数名称，之后是该参数的值。l 其中“+”（加号）为字符串的连接运算符，不包含在签名串内，请根据不同的计算机语言进行替换l transfer_secret_signature为双方商定的游戏充值划拨“签名秘钥”，该密钥很重要不得泄露。（注意：该秘钥和登陆用的不是同一个）l 测试时签名秘钥使用12345. 接口返回值返回值得形式为json字符串。失败时返回的json中只包含status信息。成功返回所有变量，格式如下：参数名类型及范围说明statusint1成功。-1失败。口on-2用户有误。-3服务器有误。-4游戏id有误。-10系统错误。roleidstring角色idrolenamestring角色名genderint角色性别。1表示男，0表示女。levelint角色等级。campint角色阵营。vocationint角色职业。5. 调试帮助接口中提供了一个特殊的参数_debug来辅助组件开发人员调试。在遇到错误签名错时，只要在调用参数里加入_debug=1，就可以输出正确的签名串顺序。如： /api/role?from=173&game=zsg&server=1&user_id=67332423&t=13413245&signature=25d55ad283aa400af464c76d713c07ad&_debug=1输出结果：“code”:-93, “message”:”签名错误”,”debug”:“signStr”:”from=173game=zsgserver=1user_id=67332423t=13413245 transfer_secret_signature=”,“sign”:”lg80344u30fdfwqrrgpgdf”参数名类型及范围说明signStrstring未包含签名密钥的签名串signstring服务器MD5签名后的字符串systemTimelong服务器系统时间6. 域名解析（CNAME）规则所有区服都是一个入口：服务器域名CANME到 ()。两种方式： 固定登录域名： CANME 登录使用地址： /login分服登录域名 ：sX. CNAME (做泛解析) 登录使用各服域名： http:/sX./login7. 完美页游正式服务器URL7.1. 登陆URL登陆URL/lo