安诚盾-API接口规范文档C#版本(1.0.0).docx

安诚盾-API接口规范文档C#版本(1.0.0)安诚盾-API接口规范文档C#版本(1.0.0)系统名称安诚盾-API接口规范文档C#版本(1.0.0)项目负责人作者王龙文档提交日期2013-1-16深圳华科远讯科技有限公司(版权所有,翻版必究)深圳华科远讯科技有限公司 - 1 -修改记录No修改后版本号修改内容简介修改日期修改人11.02013-01-16王龙21.0.1目 录1背景52规范适用对象说明53名词解释54错误码定义55站流量统计65.1功能描述65.2嵌入JS脚本样例66安全控件下载配置76.1功能76.2配置样例77API接口细则87.1公用部分87.1.1请求基类87.1.2构造函数87.1.3响应基类（接口返回值）87.2单点登录接口HK.WebShieldSys.APIForWebSite. LoginAPI87.2.1功能87.2.2数据交互流程97.2.3构造参数97.2.4Invoke参数97.2.5返回值97.2.6Invoke Demo：107.3用户检测接口HK.WebShieldSys. APIForWebSite. CheckUserApi107.3.1功能107.3.2数据交互流程107.3.3构造参数117.3.4Invoke参数117.3.5返回值117.3.6Invoke Demo：117.4用户注册限制接口HK.WebShieldSys.APIForWebSite. UserRegisterAPI127.4.1功能127.4.2数据交互流程127.4.3构造参数137.4.4Invoke参数137.4.5返回值147.4.6Invoke Demo：147.5用户注册完成后回调接口HK.WebShieldSys.APIForWebSite. UserRegisterFeedbackAPI147.5.1功能147.5.2数据交互流程147.5.3构造参数157.5.4Invoke参数157.5.5返回值157.5.6Invoke Demo：157.6区域限制接口HK.WebShieldSys.APIForWebSite. RegionRestrictAPI167.6.1功能167.6.2数据交互流程167.6.3构造参数177.6.4Invoke参数177.6.5返回值177.6.6Invoke Demo：177.7提款限制接口HK.WebShieldSys.APIForWebSite. DrawingsRestrictAPI187.7.1功能187.7.2数据交互流程187.7.3构造参数197.7.4Invoke参数197.7.5返回值197.7.6Invoke Demo：197.8交易限制接口HK.WebShieldSys.APIForWebSite. TradeRestrictAPI207.8.1功能207.8.2数据交互流程207.8.3构造参数217.8.4Invoke参数217.8.5返回值217.8.6Invoke Demo：217.9实名验证接口HK.WebShieldSys.APIForWebSite. IDCardVerificationApi227.9.1功能227.9.2数据交互流程227.9.3构造参数237.9.4Invoke参数237.9.5返回值237.9.6Invoke Demo：238附件及参考资料24 深圳华科远讯科技有限公司 - 4 -安诚盾-API接口规范文档C#版本(1.0.0)1 背景本文旨在为第三方合作站点应用访问安诚盾服务提供统一的HTTP接口调用与交互规范。本文中描述的规范包括登录限制,区域限制,提款限制,交易限制,设备关联账号限制,账号关联设备限制。2 规范适用对象说明本规范仅适用于由客户网站（服务器端）发起的调用请求、POST提交数据请求文本数据结果的 API。3 名词解释l 安诚盾：安诚盾的网址为：/api/。所有的API的调用请求的域名地址。l 商业密钥：平台分配的应用密钥，用于平台与合作站点之间通信时的参数签名l 站点编号: 平台分配的网站唯一标示,用于平台与合作站点之间通信标示4 错误码定义安诚盾API调用过程中可能会返回的错误码定义如下表所示：所有接口调用都首先返回一个返回码ResultID（0，1），0：表示不限制直接通过，1：表示有限制，具体限制类型通过RestrictType返回的结果查看，例如，2：区域限制。实名验证类型，是指调用身份证实名验证接口时返回的结果。类型错误码Description返回码(ResultID)0不限制1限制限制的类型(RestrictType)1站点统计2区域限制4注册限制8单点登录16提款限制32交易限制64账号关联设备128设备关联账号256注册成功反馈512未知类型1024设备被禁止2048审查用户4096用户锁定实名验证类型(VerificationResult)500库中无此号，请到户籍所在地进行核实501查询真实姓名和身份证号码都一致502姓名一致，身份证号码不一致503姓名不一致，身份证号码一致510转递XML格式错误511DES解密错误，密钥不正确512数据传输中，传递数据内容被篡改513输入身份证格式不正确514传参必填项为空（包括XML中用户名和身份证号码为空515系统异常516商户账号不存在5 站流量统计5.1 功能描述在添加网站流量统计应用以后，在商户网站的每一页面添加用来采集用户访问的统计脚本，商户可以在安诚盾网站查看自己网站用户访问情况及相关统计报表，类似的下图所示功能。5.2 嵌入JS脚本样例嵌入脚本的内容如下:其中81的网站编号,每个网站都不一样,不能为空。商户在安诚盾注册以后，在“我的账户站点信息”下添加并开通站点以后，可以通过点击“获取代码”得到上述JS代码，请复制该代码并拷贝到需要进行的统计的每个页面中去。6 安全控件下载配置6.1 功能通过强制要求用户注册或登录时下载安全控件，通过安全控件来收集网站防欺诈的基础数据。用户在下载安装安全控件之前是无法使用网站的注册、登录功能。6.2 配置样例第一步：在网站注册及登录页面嵌入JS脚本。脚本内容如下：注意，这段脚本跟网站流量统计脚本是完全一致的，脚本获取的方法也完全一致，具体请参考网站流量统计中描述，如果已经在注册及登录页面添加过，可以跳过此步骤，直接进行第二步。第二步：在注册及登录页面修改用户名输入框，建议修改密码输入框，在输入框中添加属性HKYXUSERNAME=”Login”或属性HKYXUSERNAME=”Reg”。例如：A. 在登录页面的用户名输入框中加入属性HKYXUSERNAME=”Login”如: B. 在注册页面的用户名输入框中加入属性HKYXUSERNAME=”Reg” 如: 可以参考如下MVC3 Demo：7 API接口细则以下接口返回数据均是以实体模式。7.1 公用部分7.1.1 请求基类所有API请求基类都继承于ApiPostParameterBase参数名类型描述示例WebSiteIDInt64站点编号81UserNameString用户姓名张三ServerDateTimeDateTime服务器时间格式为yyyy-MM-dd HH:mm:ss2013-01-11 19:12:44ClientIPString用户端IP, C#API自动获取MachineIDString用户端设备号*(备用,目前没用)7.1.2 构造函数所有 API 调用的构造函数参数都如下:参数名类型描述示例websiteIDInt64站点编号81skeyString商业密钥FDDGF-DGFDH-DGFHS-HDurlString接口入口,每个接口的入口 都不一样/api/UserLogin.asp7.1.3 响应基类（接口返回值）所有API 响应基类都继承于ApiResponseBase，参数名类型描述示例ResultIDInt32返回码，详情参考:错误码定义1 (不通过)RestrictTypeInt32限制类型,详情参考:错误码定义2 (限制的具体类型)RestrictTypeNameString限制类型中文名, 详情参考错误码定义区域限制MessageString响应的消息限制了*地区的登录7.2 单点登录接口HK.WebShieldSys.APIForWebSite. LoginAPI7.2.1 功能单点登录，获取当前用户是否满足检测功能点检测的功能点包括：单点登录，设备被禁止，设备关联账号，账号关联设备前提条件： 站点登录成功，后才调用这个接口7.2.2 数据交互流程7.2.3 构造参数查看公共构造函数url参数为: /api/UserLogin.aspx7.2.4 Invoke参数参数名类型描述示例UsernameString用户名MczbhuLoginTimeOutInt32用户登录超时的分钟数,默认20分钟207.2.5 返回值查看响应基类7.2.6 Invoke Demo：7.3 用户检测接口HK.WebShieldSys. APIForWebSite. CheckUserApi7.3.1 功能用户审查，审查用户违规状态。检测的功能点包括：设备被禁止，设备关联账号， 账号关联设备前提条件：站点登录成功后才调用这个接口7.3.2 数据交互流程7.3.3 构造参数查看公共构造函数url参数: /api/CheckUser.aspx7.3.4 Invoke参数参数名类型描述示例UsernameString用户名Zetee7.3.5 返回值查看响应基类7.3.6 Invoke Demo：7.4 用户注册限制接口HK.WebShieldSys.APIForWebSite. UserRegisterAPI7.4.1 功能检测用户是否能注册账号(如果开启实名验证功能，则检测功能点将包括实名验证)检测的功能点包括:设备被禁止，设备关联账号，账号关联设备前提条件：用户注册时，立即调用7.4.2 数据交互流程7.4.3 构造参数查看公共构造函数url参数为: /api/UserRegister.aspx7.4.4 Invoke参数参数名类型描述示例UsernameString用户名Zhangs213SexString性别(可选)男AgeInt32岁数(可选)21EMAILString邮箱(可选)RealNameString真实姓名(开启实名验证时,必填,不开启就可选)张三TelphoneString电话(可选ddressString地址(可选)深圳*IDCardNoString身份证号(开启实名验证时,必填,不开启就可选)44*7.4.5 返回值继承响应基类,参数如下:参数名类型描述示例RegisterCountInt32已注册的次数07.4.6 Invoke Demo：7.5 用户注册完成后回调接口HK.WebShieldSys.APIForWebSite. UserRegisterFeedbackAPI7.5.1 功能注册成功反馈,用户注册成功后,调用的反馈信息，用来更新安诚盾后台数据，标注该用户已经注册成功。前提条件:必须是注册成功后才调用该API7.5.2 数据交互流程 7.5.3 构造参数查看公共构造函数url参数为: /api/UserRegisterFeedback.aspx7.5.4 Invoke参数参数名类型描述示例UsernameString用户名Zhangsan123IsRegisterSucceedbool是否注册成功True7.5.5 返回值查看响应基类7.5.6 Invoke Demo：7.6 区域限制接口HK.WebShieldSys.APIForWebSite. RegionRestrictAPI7.6.1 功能获取用户是否被区域限制前提条件：用户刚刚登录，或者刚刚注册的时候。7.6.2 数据交互流程7.6.3 构造参数查看公共构造函数url参数为: /api/ RegionRestrict.aspx7.6.4 Invoke参数参数名类型描述示例UsernameString用户名Zetee7.6.5 返回值查看响应基类7.6.6 Invoke Demo：7.7 提款限制接口HK.WebShieldSys.APIForWebSite. DrawingsRestrictAPI7.7.1 功能提款限制，获取客户是否满足提款限制要求前提条件：用户刚开始提款时7.7.2 数据交互流程7.7.3 构造参数查看公共构造函数url参数为: /api/ DrawingsRestrict.aspx7.7.4 Invoke参数参数名类型描述示例UsernameString用户名MczbhuAmountdecimal提款的金额32.32DescriptionString提款描述(可选)缴费OtherTraderString交易方(可选)Zetee7.7.5 返回值查看响应基类7.7.6 Invoke Demo：7.8 交易限制接口HK.WebShieldSys.APIForWebSite. TradeRestrictAPI7.8.1 功能交易限制，获取客户是否满足交易限制要求前提条件：用户刚开始交易时7.8.