NCheck 生物识别考勤 API¶
NCheck 生物识别考勤 API提供接口来管理以下实体中的信息。
用户/员工
用户生物特征数据
事件日志
身份验证令牌¶
所有API调用都使用OAuth2身份验证令牌进行身份验证。可以使用OAuth2资源所有者密码授予流检索身份验证令牌。身份验证请求可以准备为 Listing 2 。
serverUrl =”https://localhost:8443” key=”1ZNIOZOYOY”;
secret=”JYUH5K368YNIP5LXAS1Z”;
req =Request(serverUrl + "/oauth/token");
req.Method = "POST";
req.Headers["Authorization"] = "Basic " + Base64String(("ncheck:");
req.ContentType = "application/x-www-form-urlencoded";
var body = "grant_type=password&username=" + key + "&password=" + secret;
req.ContentLength = body.Length;
响应将是一个json对象，具有成功调用的access_token值。应使用接收到的访问令牌对API调用进行身份验证。
访问限制¶
为了防止数据编辑和丢失，可以应用API访问限制。可以分配两个角色来限制对API的访问，如下所示，
管理员
管理员 角色有权用于所有API。
管理员审核
管理员审核 角色有权查看所有数据。管理员审核 无权编辑或删除数据。
API的¶
添加/更新用户¶
Request: /api/ncheck/user
Method : 发送
Body : 用户/员工 作为一个 json 对象 包含以下信息。
表 65 API主体中添加/更新用户所需的参数¶ 参数
类型
描述
可用性
员工代码
字符串
用户的唯一标识码
要求的
名
字符串
用户的名
要求的
姓
字符串
用户的姓
要求的
电子邮件
字符串
电子邮件地址
可选的
登录名
字符串
用户的登录名。更新时无法更改登录名
可选的
密码
字符串
用户的密码。更新时无法更改密码
可选的
状态
字符串
用户状态 0 为活跃，1 为禁用
可选的
示例用户对象为 Listing 3.
{ "employeeCode":"13312", "firstName":"Peter", "lastName":"Hanzward", "loginName":"peter", "password":"hasnsward", "email":"peter@hanzward.com", "status":0 }
Response : 响应是一个 JSON 对象 ，包含以下信息.
statusCode : 字符串 类型参数显示请求的状态。可用状态代码为
表 66 添加/更新用户的API响应中可能的状态代码¶ 状态码
描述
无效的电子邮件
电子邮件地址是无效的
名字为空
名字为空
姓氏为空
姓氏为空
无效的员工代码
员工代码已经被使用
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription : 字符串 参数用于显示状态代码的描述。
returnValue : 已添加/修改用户详细信息 json 对象 如果状态码为 成功 显示为 Listing 4.
{ "statusCode":"SUCCESS", "statusDescription":"Successfully updated the person", "returnValue": { "employeeCode":"13312", "firstName":"Peter", "lastName":"Hanzward", "email":"peter@hanzward.com", "status":0, "loginName":"peter", "password":"hasnsward" } }
删除用户¶
获取用户¶
Request: /api/ncheck/user?code=<employeeCode>
方法 : 获取
参数
表 69 API参数用来获取用户¶ 参数
类型
描述
可用性
员工代码
字符串
用户的唯一标识码
要求的
Response : 请求的用户详细信息包括以下信息。
statusCode : 字符串 类型参数显示请求的状态。可用的状态码为
表 70 获取用户的API响应中可能的状态码¶ 状态码
描述
用户不可用
没有找到用户
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription : 字符串 参数用于显示状态代码的描述。
returnValue : 请求用户详细信息为 json 对象 如果状态码为 成功 .
更新生物特征¶
Request: /api/ncheck/biometric/<employeeCode>/
Method : 发送
参数 :
表 71 API 参数用来更新生物特征¶ 参数
类型
描述
可用性
员工代码
字符串
用户的唯一标识码
要求的
Body : 生物特征详细信息为 JSON 数组 .
Response : 响应是一个 JSON 对象 包含以下信息.
statusCode : 字符串 参数显示请求状态。状态码为
表 73 更新生物特征API响应中可能的状态码¶ 状态码
描述
无效的参数
找到无效数据。
用户不可用
没有找到用户
提取失败
生物特征提取失败
不支持生物特征类型
未知生物特征类型
登记失败
生物特征登记失败
错误系统
错误（需要检查服务器日志获得更多信息）
成功
成功
statusDescription : 状态的详细信息作为一个 字符串 .
returnValue : 单独的生物特征结果数组作为一个 Json 对象 作为成功的请求包含以下信息。
"statusCode : 生物特征详细信息的状态为 字符串 . 状态码为
表 74 每次更新生物特征的API响应中可能的状态代码¶ 状态码
描述
无效的参数
找到无效数据。
用户不可用
没有找到用户
提取失败
生物特征提取失败
不支持生物特征类型
未知生物特征类型
登记失败
生物特征登记失败
错误系统
错误（需要检查服务器日志获得更多信息）
成功
成功
statusDescription : 状态的详细信息为字符串
returnValue : Null
Example response as Listing 6
{ "statusCode":"SUCCESS", "statusDescription":"Successfully enrolled biometrics", "returnValue": [ { "statusCode":"SUCCESS", "statusDescription":"Successfully enrolled biometrics", "returnValue":null }, { "statusCode":"SUCCESS", "statusDescription":"Successfully enrolled biometrics", "returnValue":null } ] }
删除生物特征¶
Request: /api/ncheck/biometric/<employeeCode>/
Method : 删除
参数 :
表 75 用于删除生物特征的api参数¶ 参数
类型
描述
可用性
员工代码
字符串
用户的唯一标识码
要求的
Response : Json object 及以下信息.
添加/更新事件¶
Request: /api/ncheck/event
Method : POST
Body : 考勤事件需要更新为 Json Array 及以下信息
表 77 api主体中添加/更新事件所需的参数¶ 参数
类型
描述
可用性
员工代码
字符串
生物特征模态（人脸、指纹、虹膜）
要求的
inTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
可选的
outTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
如果inTime可用则可选
班次
字符串
班次名称。如果为空，则选择默认班次
可选的
tzOffset
整数
UTC时区偏移
默认为0
Json 数组应该类似 Listing 8.
[ { "employeeCode":"13312", "inTime":"2019-06-17 08:30:50", "outTime":"2019-06-17 16:37:24", "shiftName":"Day Shift", "tzOffset":0 }, { "employeeCode":"13312", "inTime":"2019-06-18 08:38:20", "outTime":"2019-06-18 17:12:20", "shiftName":"Day Shift", "tzOffset":0 } ]
Response : 添加/更新考勤事件为 Json object，如下所示。
statusCode : 请求状态在 String . 有效的状态码为
表 78 添加/更新事件的api响应中可能的状态代码¶ 状态码
描述
无效的参数
找不到匹配事件
用户不可用
没有找到用户
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription :状态描述为一个 String .
returnValue : 请求考勤事件详细信息如 Json array 如果请求状态为 成功 . 可用的详细信息为
statusCode : 添加/更新事件的状态为 String 。状态代码将是
表 79 每个添加/更新事件的api响应中可能的状态代码¶ 状态码
描述
无效的参数
找不到匹配事件
用户不可用
没有找到用户
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription :状态描述为一个 String .
returnValue : 考勤事件详情为 Json object ，详情如下。
employeeCode : 生物特征模态（面部、手指、虹膜）为 String
inTime : 格式化日期时间字符串为
yyyy-MMdd HH:mm:ss为 StringoutTime : 格式化日期时间字符串为
yyyy-MMdd HH:mm:ss为 String 如果inTime 不可用，则可选。shift : 班次名称如 String . 如果为空，则选择默认班次
tzOffset : UTC 时区偏移量 int . 默认是 0.
示例响应为 Listing 9
{ "statusCode":"SUCCESS", "statusDescription":"Successfully updated event logs", "returnValue": [ { "statusCode":"SUCCESS", "statusDescription":"Successfully updated checkin checkout events", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-17 08:30:50", "outTime":"2019-06-17 16:37:24", "shiftName":"Day Shift", "tzOffset":0 } }, { "statusCode":"SUCCESS", "statusDescription":"Successfully updated checkin checkout events", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-18 08:38:20", "outTime":"2019-06-18 17:12:10", "shiftName":"Day Shift", "tzOffset":0 } } ] }
删除事件¶
Request: /api/ncheck/event/<employeeCode>/
Method : 删除
Body : 所有事件都需要作为一个 Json array 删除，具体如下。
表 80 api主体中删除事件所需的参数¶ 参数
类型
描述
可用性
员工代码
字符串
生物特征模态（人脸、指纹、虹膜）
要求的
inTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
可选的
outTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
如果inTime可用则可选
班次
字符串
班次名称。如果为空，则选择默认班次
可选的
tzOffset
整数
UTC时区偏移
默认0
示例类似于 Listing 10.
[ { "employeeCode":"13312", "inTime":"2019-06-17 08:30:50", "outTime":"2019-06-17 16:37:24", "shiftName":"Day Shift", "tzOffset":0 }, { "employeeCode":"13312", "inTime":"2019-06-18 08:38:20", "outTime":"2019-06-18 17:12:20", "shiftName":"Day Shift", "tzOffset":0 } ]
Response : 删除的考勤事件详细信息为 Json array，详细信息如下。
statusCode : 请求状态在 String . 有效的状态码为
表 81 删除事件的api响应中可能的状态代码¶ 状态码
描述
无效的参数
找不到匹配事件
用户不可用
没有找到用户
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription :状态描述为一个 String .
returnValue : 选定事件的详细信息为 Json array 。可用的详细信息是
statusCode : 已删除事件的状态为 String 。状态代码是
表 82 每个删除事件的api响应中可能的状态代码¶ 状态码
描述
无效的参数
找不到匹配事件
用户不可用
没有找到用户
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription :状态描述为一个 String .
returnValue : 事件详细信息为一个 Json object ，包含以下详细信息。
employeeCode : 生物特征模态（面部、手指、虹膜）为 String
inTime : 格式化日期时间字符串为 yyyy-MMdd HH:mm:ss 为 String
outTime : 格式化日期时间字符串为 yyyy-MMdd HH:mm:ss 为 String. 如果inTime不可用，则可选。
shift : 班次名称如 String . 如果为空，则选择默认班次
tzOffset : UTC 时区偏移量 int . 默认为 0.
示例响应为 Listing 11.
{ "statusCode":"SUCCESS", "statusDescription":" Deleting events successful", "returnValue":[ { "statusCode":"SUCCESS", "statusDescription":" Successfully deleted the attendance event ", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-17 08:30:50", "outTime":"2019-06-17 16:37:24", "shiftName":"Day Shift", "tzOffset":0 } }, { "statusCode":"SUCCESS", "statusDescription":" Successfully deleted the attendance event", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-18 08:38:20", "outTime":"2019-06-18 17:12:10", "shiftName":"Day Shift", "tzOffset":0 } } ] }
获取出勤事件¶
Request: /api/ncheck/event?code=<employeeCode>&from=<fromDateTime>&to=<toDateTime>
方法 : 获取
参数 :
表 83 获取出勤事件的api参数¶ 参数
类型
描述
可用性
员工代码
字符串
用户的唯一标识码
可选的
toDateTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
要求的
toDateTime
字符串
格式化日期时间字符串为 yyyy-MMdd HH:mm:ss
要求的
Response : 所有的出勤事件如 Json array 及以下参数.
statusCode : 请求的事件详细信息的状态为 String 。可用状态代码为
表 84 获取出席事件的api响应中可能的状态代码¶ 状态码
描述
用户不可用
没有找到用户
INVALID_TIME_FORMAT
日期格式无效
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription : 状态详细信息如 String .
returnValue : 如果状态代码为 成功 ，则请求的事件详细信息为 Json array ，并提供以下信息。
statusCode : 事件详细信息的状态为 String 。可能的状态代码是
表 85 每个出席事件的API响应中可能的状态代码¶ 状态码
描述
用户不可用
没有找到用户
INVALID_TIME_FORMAT
日期格式无效
错误
系统错误（需要检查服务器日志获得更多详细信息）
成功
成功
statusDescription : 状态详细信息如 String .
returnValue : Json object 包含事件详细信息。
employeeCode : 生物特征模态（面部、手指、虹膜）为 String
inTime : 日期时间格式为
yyyy-MMdd HH:mm:ss为 String. 这是可选的outTime : 日期时间格式为
yyyy-MMdd HH:mm:ss为 String . 如果inTime 不可用，则可选。shift : 班次名称如 String . 如果为空，则选择默认班次
tzOffset : UTC 时区偏移量 int . 默认是 0.
示例响应显示在 Listing 12.
{ "statusCode":"SUCCESS", "statusDescription":"Successfully updated event logs", "returnValue":[ { "statusCode":"SUCCESS", "statusDescription":"Successfully updated checkin checkout events", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-17 08:30:50", "outTime":"2019-06-17 16:37:24", "shiftName":"Day Shift", "tzOffset":0 } }, { "statusCode":"SUCCESS", "statusDescription":"Successfully updated checkin checkout events", "returnValue":{ "employeeCode":"13312", "inTime":"2019-06-18 08:38:20", "outTime":"2019-06-18 17:12:10", "shiftName":"Day Shift", "tzOffset":0 } } ] }