沃土开放平台

API文档 > 接口说明 > 接口规范
接口根地址: http://gs-api.uface.uni-ubi.com/{versionNo}/{appId}/
接口形式: 接口采用 Restful 的 Web API 实现方案,通过 HTTP 请求的方式对外提供服务。
回调说明:当有人员被设备识别出后,云端服务器会向回调URL地址POST字段deviceKey、personGuid、showTime、photoUrl、type和data。回调有补发机制,若即时回传消息给回调URL未成功,会重试五次发送,间隔为65秒,70秒,5分钟,30分钟,1小时,3小时,6小时,12小时,24小时。
回调格式: ContentType:application/x-www-form-urlencoded
回调数据示例
{
	"personGuid": "STRANGERBABY",//人员guid,陌生人为STRANGERBABY,人证比对为IDCARDBABY
	"deviceKey": "84E0F420013300B4",//设备序列号
	"photoUrl": "http://uniubi-device-test.oss-cn-hangzhou.aliyuncs.com/device/spot/photo/84E0F420013300B4/2017-11-16/STRANGERBABY_20171116153434.jpg",//现场照url
	"showTime": "1510817674000",//识别记录时间
	"data": "{\"name\":\"宇泛测试\",\"idNo\":\"88888\",\"height\":\"211\",\"width\":\"211\",\"xAxis\":\"474\",\"yAxis\":\"243\"}",//人脸附属信息。若data数据json解析不正确,可使用data.replace("\\\"","\"")再进行解析
	"type": 2,//识别出的人员类型,0:时间段内,1:时间段外,2:陌生人
	"recMode": 1,//识别模式,1:刷脸,2:刷卡,3:双重认证, 4:人证比对
	"idCardInfo": {
			"name":"宇泛",//姓名
			"sex":"男",//性别
			"nation":"汉",//民族
			"birthday":"2018-01-01",//出生年月日
			"idNum":"330326201801010818",//公民身份号码
			"address":"浙江省杭州市西湖区文一路",//住址
			"issuingOrgan":"西湖区公安局",//签发机关
			"photoPath":"http://uniubi-device-test.oss-cn-hangzhou.aliyuncs.com/device/spot/photo/84E0F4200D4202FA/2018-04-12/STRANGERBABY_20180412193059_idCardImg.jpg",//身份证照
			"usefulLife":"2008.09.16-2018.09.16"//有效期限
			"compareResult":false,//比对结果
			"id":0,//卡编号,部分身份证阅读器不支持读取
			"createTime":1514822399999,//比对时间
			"deviceKey":"84E0F4200D4202FA",//比对设备序列号
			}//人证比对详细
}
回调数据说明
字段 描述 类型 说明
deviceKey 设备序列号 String
personGuid 人员id String 人员录入接口调用成功后,由云端服务器生成并返回;陌生人为STRANGERBABY
showTime 识别时间 String yyyy-MM-dd HH:mm:ss
photoUrl 现场照url String 回调photoUrl要求设备为v2.7及以上版本
type 识别出的人员分类 String 0:时间段内,1:时间段外,2:陌生人
data 其他数据 String name:人员姓名
idNo:IC卡/身份证卡号
height:人脸框高度(单位:px)
width:人脸框宽度(单位:px)
xAxis:人脸框左上角顶点坐标(单位:px)
yAxis:人脸框左上角顶点坐标(单位:px)
recMode 识别模式 String 1:刷脸,2:刷卡,3:双重认证, 4:人证比对
idCardInfo 人证比对详细 String name : 姓名
sex : 性别
nation : 民族
birthday : 出生年月日
idNum : 公民身份号码
address : 住址
issuingOrgan : 签发机关
photoPath : 身份证照
usefulLife : 有效期限
compareResult : 比对结果
id : 卡编号(部分身份证阅读器无法读取)
createTime : 比对时间
deviceKey : 比对设备序列号
接口请求参数:所有业务接口调用时请求字段必须带上versionNo、appId和token。
字段 描述 类型 必传 说明
versionNo 沃土接口版本号 String Y 接口的功能、传输的数据模型会因版本不同而改变。通过在根地址中(接口URL前)写入版本号以使用该版本对应的接口功能。版本升级时将发送业务公告,第一版为v1
appId 添加新应用时生成 String Y 沃土平台网站添加新应用后会生成一个属于该应用的appId,以此区别不同的应用项目
token 鉴权token,接口调用凭证 String Y 沃土云端服务器需要鉴定用户是否有权调用业务接口,用户调用鉴权接口:/auth,POST,可获取token(有效期为一天,过期后需再次获取),之后每一次调用业务接口的请求都需要写入此token(建议在URL中)作为校验。

鉴权接口所需参数:appKey,timestamp(毫秒),sign,其中appKey和appSecret都是沃土平台添加创建新应用时生成,sign的算法为:MD5-32(appKey+timestamp+appSecret)
接口返回: 所有接口返回的数据,都包含三个字段,即 result、 code、 msg,分别表示处理结果( 1 成功, 0 失败)、返回码(接口统一定义)、返回信息。 result、code 和 msg 称为基本字段。
字段 描述 类型 必传 说明
result 处理结果 Int Y 1 成功, 0 失败
code 返回码 String Y 接口定义成功和错误类型码
msg 返回信息 String N 接口返回的信息,通常是错误信息
除返回基本字段,大部分接口会返回业务数据,返回的字段统一为 data, 称为业务字段。
字段 描述 类型 必传 说明
data 返回数据 Int/String/Object/List 等 Y 返回的数据,数值、字符串、对象或集合