NCHECK API

程序员可以使用NCheck API检索和更新NCheck 生物识别考勤系统数据。它可以管理以下信息。

1. 用户/员工

2. 生物特征数据

3. 出勤事件

API 认证

API用户名和密码可以由NCheck生物识别考勤服务器管理员生成，如生成API访问认证部分所述。程序员可以使用用户名和密码生成会话身份验证令牌，以便在API方法调用中使用。 身份验证令牌将在一周内过期。一旦过期，就可以使用相同的用户名和密码生成新的身份验证令牌。 有关生成身份验证令牌的详细信息，请参阅身份验证令牌一节。

认证令牌

会话认证令牌是用来认证的API请求调用。认证令牌请求调用使用C#如 图 1 所示。 代码下方的 表 1 替换为给定的值。

图 1 使用C#代码获得认证令牌

表 1 C#代码获取访问令牌使用的变量

变量	值
Server_url	NCheck生物识别考勤服务器的URL
User_name	API用户名
password	API密码

如果反馈成功，访问令牌将从access_token 变量提取。

API’s

当访问令牌已接收，API可用来管理以下数据。

1. 用户员工数据

   NCheck生物识别考勤API允许添加、更新、删除用户或员工，从系统中提取用户/员工数据。

2. 生物特征数据

   添加/删除生物识别图像（人脸、指纹、虹膜）

3. 考勤事件

   提取或删除用户或员工考勤事件。2.3.1用户员工数据

用户员工数据

NCheck 生物识别考勤提供以下API来管理用户员工数据。

1. 添加/更新用户

2. 删除用户

3. 读取用户

添加/更新用户

此API可用于添加新用户或更改用户详细信息，如表2.2 JSON对象参数所示。

1. 请求: /api/ncheck/user

2. 方法: POST

3. 主体

   用户或员工作为JSON对象有以下信息。 表 2 显示了json对象所需的参数。 图 2 显示如含参数的JSON示例。

   表 2 JSON对象参数

   参数	类型	描述	可用性
   employeeCode	string	用户的唯一码。 要更新详细信息，添加已有用户的员工代码。	必须
   firstName	string	用户的名	必须
   lastName	string	用户的姓	必须
   email	string	电子邮件地址	可选
   loginName	string	用户的登录名。登录无法在更新时修改	可选
   password	string	用户的密码。密码无法在更新时修改	可选
   status	string	用户状态： 0为活跃 1为禁用	可选

   

   图 2 添加/更新用户请求主体的JSON对象

4. Response

   Response 是一个JSON 对象，有以下信息。

   1. statusCode

      String类型参数显示请求状态。此为必填项。可用的状态码如下 表 3 显示。

      表 3 添加/更新用户的API响应状态码

      状态码	描述
      INVALID_EMAIL	电子邮件地址无效
      FIRST_NAME_EMPTY	名为空
      Last_NAME_EMPTY	姓为空
      INVALID_EMPCODE	员工码已被使用
      ERROR	系统错误（需要检查系统日志获取更多详情）
      SUCCESS	成功

   2. status描述

      String参数显示状态码描述。此为可选项。

   3. returnValue

      如果状态码如 图 4 所示为成功，已添加/修改JSON对象用户详情，JSON响应添加/更新用户。

      

      图 3 Json 响应添加/更新用户

      

      图 4 C#代码添加一个员工

删除用户

此API用于删除一个已有用户。

1. 请求: /api/ncheck/user/<employeeCode>/

2. 方法: DELETE

3. 参数

   删除用户的API参数

   表 4 删除用户的API参数

   参数	类型	描述	可用性
   employeeCode	string	用户的唯一码	必须项

4. 响应

   状态码如 表 5 所示。如果状态码为成功，JSON对象会收到删除的人员详情如 图 5 所示。

   表 5 删除用户的API响应状态码

   状态码	描述
   USER_NOT_AVAILABLE	用户未找到。
   ERROR	系统错误（需要检查服务器日志获得更多信息）
   SUCCESS	成功

   

   图 5 删除用户的 JSON 响应

图 6 显示了C#代码示例如何删除用户。

图 6 C# 代码示例删除一个员工

获取用户

现有的用户详情可以从此API获取如 表 6 所示。

1. 请求：/api/ncheck/user?code=<employeeCode>

2. 方法：GET

3. 参数

   表 6 获取户API参数

   参数	类型	描述	可用性
   employeeCode	string	用户的唯一码	必填项

4. 响应

表 7 显示了API响应的状态代码。 图 7 显示了响应中的JSON对象。

表 7 获取用户API的API响应中的状态代码

状态代码	描述
USER_NOT_AVAILABLE	找不到用户
ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
SUCCESS	成功

图 7 获取用户JSON 响应API

图 8 获取用户详情的C# 代码示例

生物特征数据

用户/员工的生物特征数据图像，如面部、指纹和虹膜图像，可以使用以下API进行管理。

1. 更新生物特征

2. 删除生物特征

更新生物特征

可以使用此API注册用户生物特征，包括面部、手指和虹膜。

1. 请求：/api/ncheck/biometric?code=<employeeCode>/

2. 方法：POST

3. 参数：

   表 8 用于更新生物特征的API参数

   参数	类型	描述	可用性
   employeeCode	String	用户的唯一标识码	必填的

4. 主体

   JSON生物识别阵列，带有参数，如 表 9 。 图 9 显示了用于更新生物特征API的JSON数组体的示例JSON体。

   表 9 参数在JSON主体中更新生物特征API

   参数	类型	描述	可用性
   modality	String	生物识别模式（面部、手指、虹膜）	必填的
   image	byte[]	生物特征原始图像。	可选
   template	byte[]	生物识别模板。Required不是图像。	可选

   

   图 9 更新生物特征API生物特征JSON数列主体

5. 响应

   JSON响应如 图 10 所示，用于添加生物特征API的JSON响应

   

   图 10 添加生物特征Json 响应API

   1. 状态码

      字符串参数，显示请求的状态。这是必填字段。状态代码如下表所示。

      表 10 更新生物特征API的API响应中的状态代码

      状态代码	描述
      INVALID_PARAMETERS	发现无效数据。
      USER_NOT_AVAILABLE	找不到用户
      FAILED_TO_EXTRACT	生物特征提取失败
      BIOMETRIC_TYPE_NOT_SUPPORTE	D生物特征未知
      ENROLLMENT_ERROR	注册生物特征失败
      ERROR System	错误（需要检查服务器日志以了解更多信息）
      SUCCESS	成功

   2. 状态

      描述作为字符串的状态详细信息。这是一个可选字段。

   3. 返回值

      单个生物特征结果数组作为Json对象，用于成功请求，并包含以下信息。

      1. 以字符串形式显示生物特征详细信息的状态。这是必填字段。状态代码如下所示。

         表 11 更新生物特征API的API响应中个人生物特征结果的状态代码

         状态代码	描述
         DUPLICATE_FOUND	生物特征已注册给不同的用户
         EXTRACTION_ERROR,	找不到用户
         BIOMETRIC_TYPE_NOT_SUPPORTE	生物特征未知
         ENROLLMENT_ERROR	注册生物特征失败
         OK	成功

图 11 显示了更新生物特征的C代码示例。

图 11 更新生物特征C# 代码示例

删除生物特征

可以使用此API删除所有用户的生物特征。

1. 请求: /api/ncheck/biometric/<employeeCode>/

2. 方法：DELETE

3. 参数：

   表 12 参数用于删除生物特征

   参数	类型	描述	可用性
   employeeCode	String	用户的唯一标识码	要求的

4. 响应：

   JSON响应如 图 12 所示，用于删除生物特征API的JSON响应

   

   图 12 删除生物特征JSON响应API

   1. 状态码

      字符串形式的请求状态。这是必填字段。可用状态代码如下所示。

      表 13 删除生物特征的API响应中的状态代码

      状态代码	描述
      USER_NOT_AVAILABLE	找不到用户
      ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
      SUCCESS	成功

   2. 状态

      描述作为字符串的状态详细信息。这是必填字段。

   3. 返回值：空

图 13 显示了删除用户生物特征的C代码示例。

图 13 删除生物特征C# 代码示例

考勤事件

可以使用以下API管理用户/员工的考勤数据

1. 获取考勤事件

2. 添加事件

3. 删除事件

获取考勤事件

获取所选用户在给定时间范围内的出勤事件详细信息。

1. 请求：/api/ncheck/event?code=<employeeCode>&from=<fromDateTime>&to=<toDateTime>

2. 方法：GET

3. 参数：

   表 14 获得考勤事件API参数

   参数	类型	描述	可用性
   employeeCode	string	用户的唯一标识码	可选的
   toDateTime	string	日期时间字符串格式为yyyy-MMdd HH:mm:ss	要求的
   toDateTime	string	日期时间字符串格式为yyyy-MMdd HH:mm:ss	要求的

4. 响应

   以Json数组的形式响应所有考勤事件。

   

   图 14 获取考勤事件API 的JSON 响应

   1. statusCode

      请求的事件详细信息的状态代码，以字符串形式显示。这是必填字段。可用状态代码如下所示。

      表 15 获取出勤事件API响应中的状态代码

      状态代码	描述
      USER_NOT_AVAILABLE	找不到用户
      INVALID_TIME_FORMAT	日期格式无效
      ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
      SUCCESS	成功

   2. 状态

      描述作为字符串的状态详细信息。这是必填字段

   3. 返回值

      如果状态代码成功，返回值请求的事件详细信息为Json数组，并显示以下信息。

      1. 状态码

         事件详细信息的状态，作为字符串。这是必填字段。状态代码如下所示

         表 16 获取出勤事件API中每个单独出勤记录的状态代码

         状态代码	描述
         USER_NOT_AVAILABLE	找不到用户
         INVALID_TIME_FORMAT	日期格式无效
         ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
         SUCCESS	成功

      2. 状态描述作为字符串的状态详细信息。这是必填字段

      3. 返回值

         如果状态代码为成功，则返回包含事件详细信息的Json对象。

         1. employeeCode

            用户的职员代码为字符串

         2. inTime

            签入时间作为日期时间字符串，格式为yyyy-MM-dd HH:MM:ss

         3. outTime

            签出时间作为日期时间字符串，格式为yyyy-MM-dd HH:MM:ss

         4. Shift

            将班次名称作为字符串。如果为空，则选择默认班次。

         5. tzOffset

            UTC时区偏移量int。默认值为0。

图 15 显示了获取用户出勤事件的C#示例

图 15 获取用户出勤事件的C#示例

添加事件

此API可用于为用户添加出勤事件。

1. 请求：/api/ncheck/event/

2. 方法：POST

3. 主体

   包含添加事件详细信息的主体JSON数组对象，如 图 16 添加事件API的JSON主体所示。

   1. employeeCode

      员工代码用户需要删除考勤事件

   2. inTime

      以日期时间字符串形式签入时间，格式为yyyy-MM-dd HH:MM:ss

   3. outTime

      以MM-dd:hyy:MM-out格式签出时间字符串

   4. Shift

      将班次名称作为字符串。如果为空，则选择默认班次。

   5. tzOffset

      UTC时区偏移量为整数。默认值为0。

      

      图 16 添加事件API JSON 主体

4. 响应

   响应JSON对象，单个出勤事件的状态为JSON对象，如 图 17 所示

   

   图 17 添加事件API JSON 响应

   1. –状态码

      字符串形式的请求状态。这是必填字段。可用状态代码如下所示。

      表 17 添加事件的API响应中的状态代码

      状态代码	描述
      INVALID_PARAMETERS	找不到匹配的事件
      USER_NOT_AVAILABLE	找不到用户
      ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
      SUCCESS	成功

   2. 状态

      状态描述为字符串。这是必填字段。

   3. 返回值

      如果响应状态代码为Success，则返回所选事件的详细信息作为Json数组。可用的详细信息包括

      1. 状态码

         已删除事件的状态（字符串形式）。这是必填字段。状态代码如下。

         表 18 个别考勤事件的状态码

         状态代码	描述
         INVALID_PARAMETERS	找不到匹配的事件
         USER_NOT_AVAILABLE	找不到用户
         ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
         SUCCESS	成功

      2. 状态

         状态描述为字符串。这是必填字段

      3. 返回值

         以JSON对象的形式添加了事件详细信息。

图 18 显示了添加事件的C代码示例

图 18 C# 添加事件代码示例

删除事件

此API可用于从用户中删除出勤事件。

1. 请求：/api/ncheck/event/

2. 方法：DELETE

3. Body

   JSON数组对象，包含删除事件的详细信息，如 图 19 所示。

   1. –employeeCode

      员工代码用户需要删除考勤事件

   2. inTime

      以日期时间字符串形式签入时间，格式为yyyy-MM-dd HH:MM:ss

   3. outTime

      签出时间作为日期时间字符串，格式为yyyy-MM-dd HH:MM:ss

   4. Shift

      将班次名称作为字符串。如果为空，则选择默认班次。

   5. tzOffset

      UTC时区偏移量为整数。默认值为0。

      

      图 19 删除事件JSON主体API

4. 响应

   考勤事件响应JSON对象，单个出勤事件的状态为JSON对象，如 图 20 所示

   

   图 20 删除事件JSON响应API

   1. 状态码

      字符串形式的请求状态。这是必填字段。可用状态代码如下所示。

      表 19 删除事件API响应中的状态代码

      状态代码	描述
      INVALID_PARAMETERS	找不到匹配的事件
      USER_NOT_AVAILABLE	找不到用户
      ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
      SUCCESS	成功

   2. –状态

      描述为字符串。这是必填字段。

   3. 返回值

      如果响应状态代码为Success，则返回所选事件的详细信息作为Json数组。可用的详细信息包括

      1. 状态代码

         已删除事件的状态（字符串形式）。这是必填字段。状态代码如下。

         表 20 个别考勤活动的状态代码

         状态代码	描述
         INVALID_PARAMETERS	找不到匹配的事件
         USER_NOT_AVAILABLE	找不到用户
         ERROR	系统错误（需要检查服务器日志以了解更多详细信息）
         SUCCESS	成功

      2. 状态

         描述为字符串。这是必填字段

      3. 返回值

         作为JSON对象的删除事件详细信息。

图 21 显示了删除事件的C代码示例

图 21 删除事件C# 代码示例