Interface Reference

  • 关于签名 URL中的参数,需要验证签名,签名方式如下:
    1)将参数名排序,包括AuthPwd进行md5加密后的字符串
    2)将参数名和参数值(url编码)依次连接起来做一次md5加密得到Sign。
  • 关于加密 BODY里的数据需要加密,这里使用AES&CBC加密,密钥是256位,多个需要加密的数据,使用&连起来。例如:
    单个参数: { "Token": "ddddddddddd" }
    多个参数,参数值需要进行url编码: Token=aaaaaa&L1=57494E55494Dxxxx&L2=57494E55494Dxxxx&L3=&L4=57494E55494Dxxxx 加密后保存到Data字段中 { "Data": "ddddddddddd" }
  • 关于时间戳的使用说明:
    1)加密数据时需要使用时间戳,时间戳是服务器的Unix时间值;
    2)通过server接口返回一个当前服务器时间戳server_ts,同时请保存一个本地时间戳local_ts1,当调用接口加密时,需要使用服务器实时时间,如果传入的时间戳和服务器当前时间戳相差过大,服务器将忽略该请求;
    3)计算服务器实时时间,需要得到一个当前本地时间戳local_ts2,公式如下: now_server_ts = local_ts2 - local_ts1 + server_ts
  • Get
    • 功能描述 :获取服务器信息
    • 地址 : http://host:port/server
    • 方法 :GET
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • TimStm:当前服务器unix时间戳
      • Forwards:可用的服务器列表
    • 请求实例 :GET http://www.winuim.com:12101/server
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "TimStm": 1462244306, "Forwards": [{"Addr":"http://www.winuim.com:12101"}] }
  • GET
    • 功能描述 :查询用户指位信息
    • 地址 : http://host:port/user
    • 方法 :GET
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • FpIdx:已经注册的指位
      • Ts:用户指纹最近修改的Unix时间戳
    • 请求实例 : GET http://www.winuim.com:12101/user?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "FpIdx": "L1L2L3L4L5R1", "Ts": 1465639207 }
  • POST
    • 功能描述 :注册更新删除指纹
    • 地址 : http://host:port/user
    • 方法 :POST
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • Token:操作凭证
      • L1:左手拇指,为空为删除,不为空为新增或者更新
      • L2:左手食指,为空为删除,不为空为新增或者更新
      • L3:左手中指,为空为删除,不为空为新增或者更新
      • L4:左手环指,为空为删除,不为空为新增或者更新
      • L5:左手小指,为空为删除,不为空为新增或者更新
      • R1:右手拇指,为空为删除,不为空为新增或者更新
      • R2:右手食指,为空为删除,不为空为新增或者更新
      • R3:右手中指,为空为删除,不为空为新增或者更新
      • R4:右手环指,为空为删除,不为空为新增或者更新
      • R5:右手小指,为空为删除,不为空为新增或者更新
      • SN:设备编号
      • Dev:设备型号
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • POST http://www.winuim.com:12101/user?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
      • { "Data":”加密后的标签列表数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }
  • DELETE
    • 功能描述 :删除用户
    • 地址 : http://host:port/user
    • 方法 :DELETE
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Token:操作凭证
      • Sign:参数签名
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • DELETE http://www.winuim.com:12101/user?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554&Token=ddddd
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }
  • POST
    • 功能描述 :指纹验证(1:1)
    • 地址 : http://host:port/verify
    • 方法 :POST
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • Feature:指纹特征数据
      • SN:设备编号
      • Dev:设备型号
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • FpIdx:认证成功后得到的指位
      • Token:认证成功后得到的操作凭证
      • Score:比对分数
      • Ts:加密Token使用的Unix时间戳
    • 请求实例 :
      • POST http://www.winuim.com:12101/verify?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
      • { " Data ":”加密后的数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "FpIdx": "L1", "Token": "AAAAAAAAAAAA", "Score": 1098, "Ts": 123123123 }
  • POST
    • 功能描述 :指纹识别(1:N)
    • 地址 : http://host:port/identify
    • 方法 :POST
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • Feature:指纹特征数据
      • SN:设备编号
      • Dev:设备型号
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • UsrNam:认证成功后得到的用户名
      • FpIdx:认证成功后得到的指位
      • Token:认证成功后得到的操作凭证
      • Score:比对分数
      • Ts:加密Token使用的unix时间戳
    • 请求实例 :
      • POST http://www.winuim.com:12101/identify?AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
      • { " Data ":”加密后的数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "UsrNam": "admin", "FpIdx": "L1", "Token": "AAAAAAAAAAAA", "Score": 1098, "Ts": 123123123 }
  • GET
    • 功能描述 :导出用户指纹数据
    • 地址 : http://host:port/feature
    • 方法 :GET
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • Token:加密后的操作凭证
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • Data:保存所有所有指纹数据,格式类似注册协议,L1=AAAA&L2=BBBB
      • Ts:加密Data使用的Unix时间戳
    • 请求实例 : GET http://www.winuim.com:12101/feature?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554&Token=AAAAAAA
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "Data": "aaaaaaaaaaaa", "Ts": 1465639207 }
  • GET
    • 功能描述 :获取自定义数据
    • 地址 : http://host:port/data
    • 方法 :GET
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • Token:加密后的操作凭证
      • Keys:需要获取数据的键组合,用分号“;”连接,如为空则获取所有数据
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • Data:返回的自定义数据
      • Ts:加密Data使用的Unix时间戳
    • 请求实例 : GET http://www.winuim.com:12101/data?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554&Token=AAA&Keys=A1;B2
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "Data": "aaaaaaaaaaaaa", "Ts": 1465639207 }
  • POST
    • 功能描述 :保存自定义数据
    • 地址 : http://host:port/data
    • 方法 :POST
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • Token:操作凭证
      • KeyValue:需要保存的数据,json格式
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • POST http://www.winuim.com:12101/data?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
      • Body加密前数据格式:Token=c10d61a91a25c24bffe44a2d5c758c20&KeyValues={"key1":"value1","key2":"value2"}
      • { "Data":”加密后的数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }

Pwd

  • GET
    • 功能描述 :密码验证
    • 地址 : http://host:port/pwd
    • 方法 :GET
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • Pwd:加密后的待验证的密码*
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • Token:认证成功后得到的操作凭证,Token值为密文,需要解密使用
      • Ts:加密Token使用的Unix时间戳
    • 请求实例 : GET http://www.winuim.com:12101/pwd?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554&Pwd=AAAA
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "Token": "aaaaaaaaaaaaa", "Ts": 1465639207 }
  • POST
    • 功能描述 :密码更新
    • 地址 : http://host:port/pwd
    • 方法 :POST
    • URL参数 :
      • UsrNam:需要查询的用户名
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • NewPwd:新密码
      • Token:操作凭证
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • POST http://www.winuim.com:12101/pwd?UsrNam=administrator&AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
      • { "Data":”加密后的数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }
  • GET
    • 功能描述 :获取短信验证码
    • 地址 : http://host:port/phone
    • 方法 :GET
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • Phone:待获取短信验证码的手机号*
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 : GET http://www.winuim.com:12101/phone?AppId=10001&AuthId=1&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554&Phone=18928406157
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }
  • POST
    • 功能描述 :短信码验证
    • 地址 : http://host:port/phone
    • 方法 :POST
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • Code:手机收到的6位短信验证码
      • Phone:手机号码
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • Token:认证成功后得到的操作凭证
      • UsrNam:手机短信验证成功后得到的用户名
      • Ts:验证成功后返回的Unix时间戳
    • 请求实例 :
      • POST http://www.winuim.com:12101/phone?AppId=10001&AuthId=1&Code=933257&Phone=18928406157&TimStm=123123123&Sign=75f2c1c2ff37302bfc632970dcd55554
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "Token": "aaaaaaaaaaaaa", "UsrNam": "winuim", "Ts": 1465639207 }
  • GET
    • 功能描述 :查询应用日志
    • 地址 : http://host:port/applog
    • 方法 :GET
    • 说明 :查询有两种模式,提供logid参数,则直接查询到日志内容;提供日志属性,则查询到日志id
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • LogId:日志id列表,用符号“;”连接起来,需要转义
      • UsrNam:日志查询属性-用户名
      • Ts1:日志查询属性-起始时间,和Ts2一起使用
      • Ts2:日志查询属性-结束时间,和Ts1一起使用
      • Lable1:日志查询属性-自定义标签1
      • Lable2:日志查询属性-自定义标签2
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
      • Logs:日志列表,使用日志id查询时返回,有内容加密返回
      • LogIds:日志id列表,使用日志属性查询时返回,有内容加密返回
      • Ts:加密使用的Unix时间戳
    • 请求实例 : GET http://www.winuim.com:12101/applog?AppId=10001&AuthId=1&TimStm=1476431833&Sign=8c9fe6e9dc15e431899811997807fdda&LogId=&UsrNam=winuim&Label1=&Label2=&Ts1=1476431823&Ts2=1476431833
    • 响应实例 :{ "Ret": 0, "Desc": "OK", "Logs": null, "LogIds": "7;8;6;5;9" }
  • POST
    • 功能描述 :新增应用日志
    • 地址 : http://host:port/applog
    • 方法 :POST
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
    • Body参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • UsrNam:日志用户名
      • ClientTs:客户端时间
      • Lable1:日志定义标签1
      • Lable2:日志自定义标签2
      • Content: 日志内容
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • POST http://www.winuim.com:12101/applog?AppId=10001&AuthId=1&TimStm=1476429240&Sign=0354bd2aac8923f35e17d1f6f4828715
      • { "Data":”加密后的数据”,"TimStm":"123123123" }
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }
  • DELETE
    • 功能描述 :删除应用日志
    • 地址 : http://host:port/applog
    • 方法 :DELETE
    • URL参数 :
      • AppId:授权应用ID
      • AuthId:授权应用用户ID
      • TimStm:当前相对的服务器时间戳
      • Sign:参数签名
      • LogIds:日志id列表,需要转义
    • 返回值 :
      • Ret:返回值
      • Desc:返回值描述
    • 请求实例 :
      • DELETE http://www.winuim.com:12101/applog?AppId=10001&AuthId=1&TimStm=1476432870&Sign=f0dce9ceb433077a2d0bab4f97f64c55&LogIds=8;9
    • 响应实例 :{ "Ret": 0, "Desc": "OK" }

Error Code List

  • 错误码 错误文字 错误描述
  • 0 OK 操作成功
  • 1 Fail 操作失败,原因未知
  • 2 UsernameRepeat 用户名重复
  • 3 FingerRepeat 指纹重复
  • 4 UserNotExists 用户名不存在
  • 5 FingerNotExists 指纹不存在
  • 6 VerifyFailure 一比一失败
  • 7 IdentifyFailure 一比N失败
  • 8 ServiceStop 服务正在维护
  • 9 AppNotExists App不存在
  • 10 AppPwdError App密码错误
  • 11 LicenseError 引擎授权错误
  • 12 UsernameEmpty 用户名为空
  • 13 TokenExpire Token时间过期
  • 14 Unauthorized 操作未经过授权
  • 21 UsernameFormatError 用户名格式错误
  • 22 FingerDataError 指纹数据格式错误
  • 23 SignError http签名错误
  • 24 AppExpire App授权过期
  • 25 LicenseTimeExpire 引擎授权时间过期
  • 26 LicenseUserCountLimit 引擎授权用户数不足
  • 27 LicenseServerMacAddrError 引擎授权服务器Mac地址错误
  • 28 TimeStampExpire 操作时间戳过期
  • 29 PermissionDenied 操作不允许