ZKBioOnline SDK For Windows


接口开发手册









熵基科技股份有限公司
http://www.zkteco.com

版权声明


  熵基科技股份有限公司版权所有©,保留一切权利。

  非经本公司书面许可,任何单位和个人不得擅自摘抄、复制本书的部分或全部,并不得以任何形式传播。

1. 目录

版权声明1. 目录2. 前言3. 技术规格3.1 平台支持3.2 浏览器支持3.3 硬件支持3.4 技术规格3.5 快速集成3.5.1 安装3.5.2 流程图5. 接口说明5.1 websocket协议5.1.1 通信数据格式定义5.1.2 获取服务信息(info 请求)5.1.3 打开指纹设备(open 请求)5.1.4 采集登记指纹 (register 请求)5.1.5 取消登记采集 (cancelregister 请求)5.1.6 关闭指纹设备(close 请求)5.1.7 1:1指纹比对(verify 请求)5.1.8 oncapture事件5.1.9 onenroll事件5.1.10 错误码5.2 http/https 协议5.2.1 返回值数据格式定义5.2.2 获取系统信息5.2.3 开始采集5.2.4 取消采集5.2.5 获取图像5.2.6 获取模板5.2.7 1:1比对指纹5.2.8 错误码5.3 后台比对库(matchdll.dll)5.3.1 Java Native API5.3.1.1 NativeToProcess5.3.1.2 NativeToSetThreshold5.3.2 C API5.3.2.1 SetThreshold5.3.2.2 Verify5.3.2.3 process

2. 前言

欢迎使用熵基科技ZKBioOnline SDK, 在使用前请仔细阅读本文档,以便于您能更快地掌握并使用。

3. 技术规格

3.1 平台支持

Windows XP SP3及以上系统

3.2 浏览器支持

高版本谷歌、火狐,IE10及以上IE浏览器等(注意:edge浏览器不支持websocket协议接口)

3.3 硬件支持

3.4 技术规格

适用于B/S系统

协议端口号
http22001
https22002
websocket22003

3.5 快速集成

3.5.1 安装

(1) 在客户端双击安装程序“setup.exe”安装sdk。

(2) 按照安装向导完成安装,即可通过http/https/websocket协议访问。

注意:不同协议不支持混合使用

3.5.2 流程图

websocket协议的调用流程:

ws登记采集流程

websocket协议 获取登记指纹的流程步骤:

http/https协议调用流程:

http登记采集流程图

http/https 协议获取登记指纹的流程步骤:

 

5. 接口说明

5.1 websocket协议

5.1.1 通信数据格式定义

通信协议采用 websocket 时,后台服务在本地 22003端口监听。

建立连接示例代码如下:

通信数据格式采用 JSON ,各字段区分大小写,定义说明如下:

请求的数据格式:

功能描述
module模块名称
msgid自定义消息id
function方法
parameter参数,具体格式参考具体接口说明
data返回消息,具体格式参考具体接口说明

应答的数据格式:

功能描述
module模块名称
msgid消息id,应答的消息id和请求的消息id一致
function方法
ret0成功,其它失败,具体请参考错误码
data存放返回的数据,具体格式参考具体接口说明

5.1.2 获取服务信息(info 请求)

请求消息的字段:

功能获取服务信息
modulecommon
msgid自定义消息id
functioninfo
parameter无参数,非必要字段

请求消息的示例如下:

应答消息的字段:

功能获取服务信息
modulecommon
msgid自定义消息id
functioninfo
ret0成功,其它失败,具体请参考错误码
data.now当前请求时间
data.server_versionsdk版本
data.startsdk服务启动的时间
data.biometric.engversion算法版本
data.biometric.enroll_count登记采集需要采集次数
data.biometric.type生物识别类型

应答消息的示例如下:

5.1.3 打开指纹设备(open 请求)

打开指纹,默认进入指纹采集状态,每次采集都会触发oncapture事件,oncapture事件具体参考5.1.8。

请求消息的字段:

功能打开指纹设备
modulefingerprint
msgid自定义消息id
functionopen
parameter无参数,非必要字段

请求消息的示例如下:

应答消息的字段:

功能打开指纹设备
modulefingerprint
msgid自定义消息id
functionopen
ret0成功,其它失败,具体请参考错误码
data.SN设备序列号

应答消息的示例如下:

5.1.4 采集登记指纹 (register 请求)

采集登记指纹需要采集三次指纹,每次采集完成触发onenroll事件,onenroll事件具体参考5.1.9。采集登记指纹完成后会进入指纹采集状态。

请求消息的字段:

功能采集登记指纹
modulefingerprint
msgid自定义消息id
functionregister
parameter无参数,非必要字段

请求消息的示例如下:

应答消息的字段:

功能采集登记指纹
modulefingerprint
msgid自定义消息id
functionregister
ret0成功,其它失败,具体请参考错误码
data没有返回数据时,返回空

应答消息的示例如下:

5.1.5 取消登记采集 (cancelregister 请求)

该方法用于取消采集登记指纹,即将onenroll事件状态重置为oncapture事件状态。

请求消息的字段:

功能取消登记采集
modulefingerprint
msgid自定义消息id
functioncancelregister
parameter无参数,非必要字段

请求消息的示例如下:

应答消息的字段:

功能取消登记采集
modulefingerprint
msgid自定义消息id
functioncancelregister
ret0成功,其它失败,具体请参考错误码
data没有返回数据时,返回空

应答消息的示例如下:

5.1.6 关闭指纹设备(close 请求)

请求消息的字段:

功能关闭指纹设备
modulefingerprint
msgid自定义消息id
functionclose
parameter无参数,非必要字段

请求消息的示例如下:

应答消息的字段:

功能关闭指纹设备
modulefingerprint
msgid自定义消息id
functionclose
ret0成功,其它失败,具体请参考错误码
data没有返回数据时,返回空

应答消息的示例如下:

5.1.7 1:1指纹比对(verify 请求)

该方法是对传入的两个指纹模板做1:1指纹比对,返回一个比对分数值(0~100), 用户可根据自己需求设置阈值,判断是否比对成功(一般默认大于35则比对成功)。

请求消息的字段:

功能1:1指纹比对
modulefingerprint
msgid自定义消息id
functionverify
parameter.template1参与比对的模板1
parameter.template2参与比对的模板2

请求消息的示例如下:

应答消息的字段:

功能1:1指纹比对
modulefingerprint
msgid自定义消息id
functionverify
ret0成功,其它失败,具体请参考错误码
data.grade比对分数值(范围:0~100,一般默认大于35则比对成功)

应答消息的示例如下:

 

5.1.8 oncapture事件

每次采集指纹,触发oncapture事件触发后,会返回2条数据,即当次采集的指纹图片数据和模板数据。

oncapture事件触发返回的 image 应答消息字段:

功能oncapture事件
modulefingerprint
datatypeimage
functiononcapture
ret0成功,其它失败,具体请参考错误码
data.biotype生物识别类型,指纹识别类型为0
data.enroll_index采集指纹图片的的序号(弃用,仅onenroll事件用于显示登记采集显示登记索引)
data.width图片宽
data.height图片高
data.quality图片质量
data.jpg_base64jpg格式指纹像数据(base64 String)
data.raw_base64原始指纹图像数据(base64 String)

示例如下:

oncapture事件触发返回的 template 应答消息字段:

功能oncapture事件
modulefingerprint
datatypetemplate
functiononcapture
ret0成功,其它失败,具体请参考错误码
data.biotype生物识别类型,指纹识别类型为0
data.template指纹模板数据(base64 string)
data.templatelen模板数据长度

示例如下:

5.1.9 onenroll事件

onenroll事件触发后,前面2次返回图片数据,第三次返回图片数据和模板数据。(注:并在触发三次后,重置为指纹采集状态)

onenroll事件触发返回的 image 应答消息字段:

功能onenroll事件
modulefingerprint
datatypeimage
functiononenroll
ret0成功,其它失败,具体请参考错误码
data.biotype生物识别类型,指纹识别类型为0
data.enroll_index登记索引(三次采集的图片数据索引对应分别为1,2,3)
data.width图片宽
data.height图片高
data.quality图片质量
data.jpg_base64jpg格式指纹图像数据(base64 String)
data.raw_base64原始指纹图像数据(base64 String)

示例如下:

onenroll事件触发返回的 template 应答消息字段:

功能onenroll事件
modulefingerprint
datatypetemplate
functiononenroll
ret0成功,其它失败,具体请参考错误码
data.biotype生物识别类型,指纹识别类型为0
data.template指纹特征模板(base64 string)
data.templatelen模板数据长度

返回指纹模板数据格式如下:

5.1.10 错误码

错误码如下表所示

错误码说明
0成功
-10001失败
-10002服务未初始化
-10003无效参数或者参数格式错误
-10004模式错误
-10005接口不支持
-10006初始化指纹库失败
-10007打开指纹采集设备失败
-10008非法指纹模板
-10009假手指
-10010继续按指纹采集
-10011指纹或者指静脉采集失败
-10012导出模板失败
-10013正在使用websocket连接
-10014未打开设备或者webs连接标识不一致
-10015异常跳出
-10016登记时与上一次指纹不同
-10017该指纹设备已绑定webs连接
-10018该指纹设备状态异常

5.2 http/https 协议

5.2.1 返回值数据格式定义

返回值数据格式:json

功能描述
ret0成功,其它失败,具体请参考错误码
error错误描述
data保存返回的数据

5.2.2 获取系统信息

请求方法:

返回的消息字段:

参数名参数类型描述
retint0成功,其它失败,具体请参考错误码
errorstring错误描述
data.nowstring当前请求时间
data.server_versionstringsdk版本
data.startstringsdk服务启动的时间
data.biometric.engversionstring算法版本
data.biometric.enroll_countint登记采集需要采集次数
data.biometric.typestring生物识别类型

返回消息示例如下:

5.2.3 开始采集

请求方法:

参数:

参数名参数类型描述
typeint1表示采集登记指纹(采集同一手指3次指纹),不是1则表示采集比对指纹

成功时返回:

5.2.4 取消采集

请求方法:

成功时返回:

5.2.5 获取图像

请求方法:

参数名参数类型描述
retint0成功,其它失败,具体请参考错误码
errorstring错误描述
data.biotypeint生物识别类型,0表示指纹
data.enroll_indexint登记索引(用于登记采集时的登记采集次数索引,当enroll_index等于enroll_count时表示登记采集完成,可以调用gettemplate获取模板)
data.widthint图片宽度
data.heightint图片高度
data.qualityint图片质量
data.jpg_base64stringjpg格式指纹图像数据(base64 String)
data.raw_base64string原始指纹图像数据(base64 String)

返回的消息示例如下:

5.2.6 获取模板

请求方法:

 

参数名参数类型描述
retint0成功,其它失败,具体请参考错误码
errorstring错误描述
data.biotypeint生物识别类型,0表示指纹
data.templatestring指纹模板数据(base64 string)
data.lengthint模板数据长度

返回的消息示例如下:

5.2.7 1:1比对指纹

请求方法:

POST 的body数据格式为json, 数据的字段说明:

参数名参数类型描述
regString登记模板(base64 String)
verString比对模板(base64 String)

POST数据格式为json字符串,示例如下:

返回的消息

参数名参数类型描述
retint0成功,其它失败,具体请参考错误码
errorString错误描述
scoreint比对分数, > 35表示匹配

返回的消息示例如下:

5.2.8 错误码

错误值 描述
0 操作成功
4 正在操作,请稍后再试
-1 操作失败
-2 不支持操作,请确认是否URL错误
-3 参数错误(暂未使用)
-5 无效数据格式
-6 无效模板
-7 比对异常
-2000 调用错误,目前仅支持HTTP Get
-2001 连接采集器失败
-2002 加载算法库失败
-2003 提取模板失败
-2004 采集图像失败
-2005 正在采集,请按手指或者取消采集
-2006 请按手指
-2007 分配内存失败(暂未使用)
-2008 取消失败(暂未使用)
-2009 疑似假指纹或者手指按太快

5.3 后台比对库(matchdll.dll)

5.3.1 Java Native API

类名:zk.jni.JavaToBiokey

备注:类名必须为 zk.jni.JavaToBiokey ,不能改成其他,否则会出现查找不到类库的情况。


5.3.1.1 NativeToProcess

功能 : 比对 9.0、10.0 算法指纹模板(Base64)

方法接口:

参数:

参数名参数类型描述
ARegTemplateString登记模板(Base64 string)
AVerTemplateString比对模板(Base64 string)

返回值:

比对成功返回 True,失败返回 False。


5.3.1.2 NativeToSetThreshold

功能 :设置比对指纹模板的阀值

方法接口:

参数:

参数名参数类型描述
AThresholdint阈值
AOneToOneThresholdint设定Biokey低速指纹1:1比对的识别阀值分数(1-100),默认为10,值越大,误判率越低同时拒绝率变大。

5.3.2 C API


5.3.2.1 SetThreshold

功能 :设置比对指纹模板的阀值

方法接口:

参数:

参数名参数类型描述
AThresholdint阈值
AOneToOneThresholdint设定Biokey低速指纹1:1比对的识别阀值分数(1-100),默认为10,值越大,误判率越低同时拒绝率变大。

返回值:

成功返回TRUE;失败返回FALSE


5.3.2.2 Verify

功能 :比对 9.0、10.0 算法指纹模板(Base64)

方法接口:

参数:

参数名参数类型描述
szRegTemplatechar*登记模板(Base64 string)
szVerTemplatechar*比对模板(Base64 string)

返回值

比对分数


5.3.2.3 process

功能 :比对 9.0、10.0 算法指纹模板(Base64)

方法接口:

参数:

参数名参数类型描述
szRegTemplatechar*登记模板(Base64 string)
szVerTemplatechar*比对模板(Base64 string)

返回值:

成功返回TRUE;失败返回FALSE