考勤数据对接协议

您所在的位置：网站首页 › 接口id的唯一性是什么 › 考勤数据对接协议

考勤数据对接协议

2024-06-13 06:20| 来源: 网络整理| 查看: 265

# 协议介绍

本文档将向您介绍第三方OA或类似系统如何与得力e+系统进行考勤数据对接。

# 系统对接前说明 # API访问域名信息

https://v2-api.delicloud.com

# API请求方式

所有的API进入都使用post的http请求进行，请求参数均为json格式，

请求头中需指定：Content-Type:application/json;

例如请求中有两个参数，key分别为k1，k2，value分别为字符串v1，数字v2，则请求的request body如下：

{ "k1": "v1", "k2": "v2" } 1234# 请求加密

请求数据都需要进行加密，加密相关名词说明如下：

参数参数说明 App-Key 为接入的外部应用分配的key，用来标识接入者的身份 App-Secret 为接入的外部系统分配的密钥，用来对请求数据进行验证加密 App-Timestamp 每次请求带有的当前时间戳，13位，精确到毫秒级别 Api-Module 请求业务API时指明需要调用的API所在的模块，以key-value的形式放在headers中 Api-Cmd 请求业务API时指明需要调用的API的具体指令，以key-value的形式放在headers中

加密步骤如下：

获取此次请求的相对路径path，不包括路径中带有的请求参数

获取当前的13位时间戳timestamp

获取此次请求的app对应的key和密钥secret

将path timestamp key secret依次拼接成字符串

对步骤4生成的字符串进行32位md5计算，并将计算结果转换为全小写，获得最终的加密签名sig

在请求的headers里面加入key为App-Key，值为当前请求的app对应的key的键值对

在请求的headers里面加入key为App-Timestamp，值为步骤3中时间戳timestamp的键值对

在请求的headers里面加入key为App-Sig，值为步骤5中生成的sig的键值对

举例：

假设当前存在一个外部应用接入，分配给此应用的App-Key为3c5ee48d0b7d48c5，App-Secret为65ded5353c5ee48d0b7d48c591b8f430。当前此外部应用需要请求地址为 http://v2-api.delicloud.com/v2.0/employee (opens new window) 的接口，请求的时间戳为1532315906364，请求的参数如下：

{ "k1": "v1", "k2": "v2" } 1234

则生成的加密签名为:

{App-Sig} = md5({Path}{App-Timestamp}{App-Key}{App-Secret})，即： md5(/v2.0/employee15323159063643c5ee48d0b7d48c565ded5353c5ee48d0b7d48c591b8f430)=d380db98703c351c83600aa853786055 12

需要在请求的headers中加入：App-Key=3c5ee48d0b7d48c5，App-Timestamp=1532315906364，App-Sig=d380db98703c351c83600aa853786055共三组键值对。

对接过程中如遇到签名错误可前往以下地址检查：

调试签名 (opens new window)

# 请求响应

响应以json对象的形式返回，包括code，msg和data三部分，分别是：

code：响应的返回码，0表示正常的返回，其他表示错误

msg：响应的消息，说明错误的情况

data：响应的实际内容，以json对象的形式返回

code值说明：

code值含义 101 用户key错误 102 用户key缺失 103 请求签名错误 104 请求签名缺失 105 请求时间戳缺失 106 post请求中请求体格式错误 107 App-Module 参数错误 108 组织异常 109 接口请求超时 110 调用次数超限 # API目录

系统对接

序号接口名称描述支持型号 1 初始化组织内根部门外部id 设置得力e+系统平台根部门的外部id；所有得力云考勤机 2 查询部门分页拉取得力系统中所有部门信息（已存在部门时使用），获取后可以统一设置外部id；所有得力云考勤机 3 为部门设置外部id 更新部门分组外部id；所有得力云考勤机 4 添加或修改部门信息在得力系统中创建或更新部门信息，可以设置部门间的层级关系（也可通过得力系统完成通过批量导入功能完成）；所有得力云考勤机 5 删除部门删除得力系统中已创建的部门分组及分组中人员所有得力云考勤机 6 添加或修改员工信息在得力系统中创建、更新人员，将员工关联到得力系统中的部门（也可通过得力系统完成通过批量导入功能完成）；所有得力云考勤机 7 批量获取员工信息分页批量地获取得力系统中人员信息；所有得力云考勤机 8 为员工设置外部id 设置得力系统员工的外部id；所有得力云考勤机 9 删除员工删除得力系统中人员信息，删除后人员打卡记录全部删除；所有得力云考勤机 10 批量获取设备信息分页批量地获取得力系统中设备信息,包括设备在线状态、设备名称、设备数量等；所有得力云考勤机

考勤对接

综合签到API支持的设备型号：设备类型型号考勤机 13750CS, 13888CS, 14050CS, 33800CS, 34521CS, 3759CS, 3765CN, 3765CS, 3960-4G, 3960CSE, D901, D902, DL-D2, DL-D3, DL-D4, DL-D5F, DL-D5FN, DL-D5FS, DL-D5S, DL-D5SN, DL-D6S, DL-D6SN, DL-D7, DL-D7E, DL-D7S, DL-D8, DL-D8PRO, DL-D8PRON, T906, T906N等门禁机 13753C, 13753CW, 13753CWN, 13800, 3768CW-ID, ACS301, ACS302, ACS501P, ACS502-W, ACS701, ACS702-W, ACS703-W, ACS801-W, ACS803-TW, ACS804-TW, D3IR-SSD, D3VR-SSD, DL-ACS501, DL-ACS501P, DL-V2 等接口说明：云系统接口名称描述支持情况综合签到考勤数据初始化初始化校验，可获取完成初始化校验后新产生的打卡记录数据；综合签到考勤数据同步获取的是人员打卡的原始记录，例如：xxx人员在xxx设备上xxx时间的打卡记录；综合签到门禁数据获取分页查询获取门禁通行人员在云门禁机上通行的记录；综合签到人员特征更新可将base64格式的照片作为人员人脸打卡依据，仅支持可见光人脸识别设备； DL-D4,D902,D901,DL-D2,3765CS,13750CS,3765CN,14050CS,3759CS,34521CS,13888CS,33800CS等红外设备不支持综合签到人员特征查询查询同步下发的人脸照片是否正常，查询录入成功的人脸照片； DL-D4,D902,D901,DL-D2,3765CS,13750CS,3765CN,14050CS,3759CS,34521CS,13888CS,33800CS等红外设备不支持 # 系统对接 # 部门管理API # 初始化组织内根部门外部id 访问地址

POST /v2.0/department/init

接口说明

初始化组织内根部门外部id。

关于根部门外部ID

接入方系统中根部门的id，即为得力e+系统平台的外部id。在得力e+中新建的组织的根部门默认外部id为0，调用此接口可以更新组织的根部门的外部id。

请求示例 { "department_ext_id":"1" } 123请求参数描述数据类型 department_ext_id 组织根部门在外部接入系统中的id，不可超过32个字符；字符串响应示例 { "code":0, "msg":"", "data":{ "ext_id":"1", "name":"得力集团" } } 12345678响应参数描述数据类型 ext_id 此部门在外部接入系统中的id；字符串 name 此部门的名称；字符串

调试接口 (opens new window)

# 查询部门访问地址

POST /v2.0/department/query

接口说明

分页拉取平台中所有部门信息，调用此接口将返回E+中所有的部门信息。

注意

请开发者注意: 没有ext_id的部门信息也会被返回。

请求示例 { "limit":20, "offset":0 } 1234请求参数描述数据类型 limit 分页大小，必须在1～100之间；整型 offset 偏移量，默认从0开始；整型响应示例 { "code":0, "msg":"", "data":{ "total":"1", "rows":[ { "id":"123", "pid":"321", "name":"设计部", "department_ext_id":"2" } ] } } 123456789101112131415响应参数描述数据类型 total 组织总部门数量；整型 rows 本次分页查询部门结果信息列表； id 部门id；字符串 pid 父级部门id；字符串 name 部门名称；字符串 department_ext_id 此部门在外部接入系统中的id；字符串

调试接口 (opens new window)

# 为部门设置外部id 访问地址

POST /v2.0/department/ext

接口说明

调用此接口将修改部门的外部id字段ext_id。

注意请调用者保证外部id的唯一性，如果违反唯一性该接口会抛出错误。

请求示例 { "id": "3244", "ext_id": "需要设置的id" } 1234请求参数描述数据类型 id 部门id；字符串 ext_id 此部门在外部接入系统中的id；字符串响应示例 { "code":0, "msg":"" } 1234

调试接口 (opens new window)

# 添加或修改部门信息访问地址

POST /v2.0/department

接口说明

利用该接口可以新建或者更新部门信息。

提示

以部门在外部接入系统中的ext_id作为部门的唯一标识。当此标识在得力E+中不存在时，即可新建一个对应的部门；当此标识在得力E+中存在时，可按照请求的参数值更新此部门在得力E+中的数据。

请求参数 { "department_ext_id":"2", "name":"设计部", "p_ext_id":"1" } 12345请求参数描述数据类型 department_ext_id 此部门在外部接入系统中的id；字符串 name 此部门的名称；字符串 p_ext_id 选填。此部门在外部接入系统中的上级部门id，不填时表示此部门没有上级部门；字符串响应示例 { "code":0, "msg":"", "data":{ "ext_id":"2", "name":"设计部" } } 12345678响应参数描述数据类型 ext_id 此部门在外部接入系统中的id；字符串 name 此部门的名称；字符串

调试接口 (opens new window)

# 删除部门访问地址

POST /v2.0/department/delete

接口说明

利用该接口可以删除部门。以部门在外部接入系统中的ext_id作为部门的唯一标识，根据这个标识删除对应的部门。

注意

当此部门或此部门的下级部门中还有员工时，不能删除此部门，需要先调用删除员工的接口，先将部门下的员工删除。

请求示例 { "department_ext_id":"2" } 123请求参数描述数据类型 department_ext_id 此部门在外部接入系统中的id；字符串响应示例 { "code":0, "msg":"" } 1234

调试接口 (opens new window)

# 员工管理API # 添加或修改员工信息访问地址

POST /v2.0/employee

接口说明

利用该接口可以新建或者编辑员工信息。

关于员工外部ID

外部接入系统中员工需要有唯一标识的id，相对于得力e+系统平台，就是人员的外部id，以员工在外部接入系统中的ext_id作为员工的唯一标识。

如需对接考勤数据，请务必给所有员工设置外部id作为关联条件

当此标识在得力E+中不存在时，新建一个对应的员工；当此标识在得力E+中存在时，按照请求的参数值修改此员工在得力E+中的数据。

另外，如果外部接入系统中人员没有手机号这个字段，可以自行给员工创建手机号，该手机号不必是真实存在的，满足中国大陆手机号位数即可，但如果需要人员在E+注册账户查看自己的考勤记录，请填写真实的手机号码。

请求示例 { "employee_ext_id":"2", "name":"张三", "mobile":"18600000000", "employee_num":"001", "department_infos":[ { "ext_id":"2", "title":"经理" } ] } 123456789101112请求参数描述数据类型 employee_ext_id 此员工在外部接入系统中的id，不可超过32个字符；字符串 name 此员工的名称，不可超过64个字符；字符串 mobile 此员工在外部接入系统中的手机号，不可超过64个字符；字符串 employee_num 此员工在外部接入系统中的工号，不可超过128个字符；字符串 department_infos 员工所属的部门信息数组，当前员工只可属于一个部门 ext_id 员工所属部门在外部接入系统中的id，不可超过32个字符；字符串 title 员工在所属部门中的职位，不可超过32个字符；字符串响应示例 { "code":0, "msg":"", "data":{ "ext_id":"2", "name":"张三", "mobile":"18600000000", "employee_num":"001" } } 12345678910响应参数描述数据类型 ext_id 此员工在外部接入系统中的id；字符串 name 此员工的名称；字符串 mobile 此员工在外部接入系统中的手机号；字符串 employee_num 此员工在外部接入系统中的工号；字符串

调试接口 (opens new window)

# 批量获取员工信息访问地址

POST /v2.0/employee/query

接口说明

分页获取得力e+系统平台内的员工信息。

请求示例 { "limit":20, "offset":0 } 1234请求参数描述数据类型 limit 分页大小，必须在1～100之间；整型 offset 偏移量，默认从0开始；整型响应示例 { "code":0, "msg":"", "data":{ "total":"1", "rows":[ { "id":"123", "ext_id":"2", "name":"张三", "mobile":"18600000000", "employee_num":"001", "department_infos":[ { "id":"321" } ] } ] } } 123456789101112131415161718192021响应参数描述数据类型 total 组织总的员工数目；整型 rows 本次分页查询的员工信息列表； id 得力E+中的员工id；字符串 ext_id 此员工在外部接入系统中的id；字符串 name 此员工的名称；字符串 mobile 此员工在外部接入系统中的手机号；字符串 employee_num 此员工在外部接入系统中的工号；字符串 department_infos 员工所属的部门信息数组，当前员工只可属于一个部门； id 得力E+的部门ID；字符串

调试接口 (opens new window)

# 为员工设置外部id 访问地址

POST /v2.0/employee/ext

接口说明

为得力e+系统平台中已存在的员工设置外部id字段ext_id。

注意请调用者保证外部id的唯一性，如果违反唯一性该接口会抛出错误。

请求示例 { "id":"3244", "ext_id":"2" } 1234请求参数描述数据类型 id 得力e+中的员工id；字符串 ext_id 此员工在外部接入系统中的id；字符串响应示例 { "code":0, "msg":"" } 1234

调试接口 (opens new window)

# 删除员工访问地址

POST /v2.0/employee/delete

接口说明

利用该接口可以删除员工信息。

提示

以员工在外部接入系统中的ext_id作为员工的唯一标识，根据此标识在得力e+系统平台组织内删除此员工。

请求示例 { "employee_ext_id":"2" } 123请求参数描述数据类型 employee_ext_id 得力e+此员工在外部接入系统中的id；字符串响应示例 { "code":0, "msg":"" } 1234

调试接口 (opens new window)

# 设备管理API # 批量获取设备信息访问地址

POST /v2.0/org/device/query

接口说明

分页获取得力e+系统平台内的设备信息。

请求示例 { "limit":20, "offset":0 } 1234请求参数描述数据类型 limit 分页大小，必须在1～100之间；整型 offset 偏移量，默认从0开始；整型响应示例 { "code": 0, "msg": "", "data": { "total": "9", "rows": [ { "sn": "ACS701_26159033", "name": "人脸门禁机701", "online": false }, { "sn": "DL-D7_03325418", "name": "人脸考勤机D7", "online": true } ] } } 12345678910111213141516171819响应参数描述数据类型 sn 设备SN；字符串 name 设备名称；字符串 online 是否在线；布尔

调试接口 (opens new window)

# 考勤接口对接

访问地址

POST/v2.0/cloudappapi

注意事项

不同设备型号支持的考勤接口略有不同，请参照Api目录确定可用的接口范围；以下接口uri固定(签名中的Path固定为“/v2.0/cloudappapi”)，需通过HTTP请求headers中的Api-Module和Api-Cmd键来指定接口； # 综合签到应用API

以下接口用于获取综合签到应用的数据：

在HTTP请求的headers中加入key为 Api-Module，值为 CHECKIN 的键值对，用于标识请求目标为综合签到应用系统。

# 考勤数据初始化

接口说明

该API用于综合签到应用考勤数据的初始化，在成功调用该API一次后的考勤数据可以通过考勤数据同步API进行同步，该API仅需调用一次。

自定义headers

在HTTP请求的headers中加入key为 Api-Cmd，值为 checkin_query_init 的键值对。

请求示例

空

响应示例

{ "code": 0, "msg": "错误描述" } 1234

调试接口 (opens new window)

# 考勤数据同步

接口说明

利用该接口可以同步考勤人员在云考勤机，设置为考勤点的其他签到设备（云门禁机等），以及综合签到应用中的打卡数据，包括：手机wifi识别打卡、手机GPS定位打卡、外勤打卡数据等等。

同步数据根据设备上报时间排序，与打卡时间无关

自定义headers

在HTTP请求的headers中加入key为 Api-Cmd，值为 checkin_query 的键值对。

请求示例

{ "next_id": 0, "page_size": 50 } 1234请求参数描述数据格式 next_id 本次查询的开始记录ID，从0开始，下次请求取上次返回记录中的next_id；整型 page_size 本次查询的最大记录数，可设置最大值500；整型

提示

初次请求next_id请设置为0，后续每次请求请使用上次查询结果中的next_id(id非连续，不可自行计算)，持续查询直到返回结果集为空；同步结束后请务必保存好最新的next_id作为下次同步的参数，避免数据重复和遗漏；只有在考勤数据初始化接口调用后，本接口才会返回数据；本接口只会返回初始化后新产生的考勤数据，无法查询历史数据；响应示例 { "code": 0, "msg": "", "data": { "next_id": 1000, "data": [ { "id": 123, "user_id": "用户ID", "ext_id": "12345", "terminal_id": "DL-D7_0000001", "check_type": "fp", "check_time": 1503025335, "check_data": "打卡数据" } ] } } 123456789101112131415161718响应参数描述数据格式 next_id 本次增量查询结果的最大偏移量值，下次以此偏移量为请求继续进行增量查询；整型 data 本次增量查询到的打卡记录列表； id 打卡记录ID 字符串 user_id 打卡人员ID(与e+应用中的user_id不一致，关联用户请设置ext_id) 字符串 ext_id 打卡人员在外部系统的id；字符串 terminal_id 打卡数据的终端id。包括；设备打卡: 设备的SN；手机打卡(包括 wifi/gps/外勤打卡方式)：打卡手机的唯一设备id；补卡: 固定值 "apply"；字符串 check_type 打卡方式。包括：fa: 人脸；fp: 指纹；pass: 密码；card: 刷卡；app_scan: APP扫码；gps: gps位置打卡；wifi: wifi打卡；out_work: 外勤打卡；reissue: 补签申请；flexible: 自动补的灵活卡；字符串 check_time 打卡时间戳，精确到秒；整型 check_data 打卡补充数据，不同的打卡类型则返回不同的数据。示例如下

check_data注释，打卡示例：

打卡方式例子 fa/fp {"device_name":"人脸考勤机D7","employee_num":"","dept_name":"","cmd":"checkin","member_name":"唐学武","dept_id":""} gps {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4,"lat":"位置所在纬度","lgt":"位置所在经度","name":"所在名称","location":"所在位置","phone_model":"rmx2111"} wifi {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4,"name":"wifi名称","mac_address":"wifi的mac地址","ssid":"ssid","phone_model":"iPhone 11"} 外勤打卡 {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4,"photo":"拍照","comment":"外勤打卡的备注","lat":"位置所在纬度","lgt":"位置所在经度","name":"所在名称","location":"所在位置","phone_model":"rmx2111"} 补卡 {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4} 自动补的灵活卡 {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4}

调试接口 (opens new window)

# 门禁数据同步

接口说明

利用该接口可以同步门禁通行人员在云门禁机上通行的记录。

同步数据根据设备上报时间排序，与打卡时间无关

自定义headers

在HTTP请求的headers中加入key为 Api-Cmd，值为 checkin_acs_query 的键值对。

请求示例

{ "next_id": 0, "page_size": 50, "pass_only": true } 12345请求参数描述数据类型 next_id 本次查询的开始记录id，从0开始，下次请求取上次返回记录中的next_id；整型 page_size 本次查询的最大记录数，可设置最大值500；返回数据过大时可能导致查询失败，如果查询的考勤记录中存在打卡照片，建议查询记录数不超过50 整型 pass_only 可选，是否仅返回通行成功的记录，默认是true，否则返回所有通行记录，包括陌生人和无权限通行的识别记录；布尔

提示

初次请求next_id请设置为0，后续每次请求请使用上次查询结果中的next_id(id非连续，不可自行计算)，持续查询直到返回结果集为空；同步结束后请务必保存好最新的next_id作为下次同步的参数，避免数据重复和遗漏；响应示例 { "code": 0, "msg": "错误描述", "data": { "next_id": 1000, "data": [ { "id": 123, "door_id": "门ID", "user_id": "用户ID", "ext_id": "12345", "check_type": "fp", "check_time": 1503025335, "check_data": "通行数据", "check_result": 0, "capture_img": "/9j/4AAQSkZJRgABAQAAAQABAAD/2......." } ] } } 1234567891011121314151617181920响应参数描述数据类型 next_id 本次增量查询结果的最大偏移量值，下次以此偏移量为请求继续进行增量查询；整型 data 本次增量查询到的门禁通行记录列表； id 记录id; 整型 user_id 通行人员id;(与e+应用中的user_id不一致，关联用户请设置ext_id) 字符串 ext_id 通行人员在外部系统的id；字符串 check_type 通行方式。包括：fa: 人脸；fp: 指纹；pass: 密码；card: 刷卡；整型 check_time 通行时间戳，精确到秒；整型 check_data 通行补充数据，不同的通行类型则返回不同的数据； check_result 通行结果。包括：0: 通行成功；1: 无通行权限，开门拒绝；2: 未识别的陌生人；8: 门禁已锁定，无法控制；9: 设备系统异常，开门失败；整型 capture_img 可选，抓拍图像，通过base64编码的字符串，不包含字符串前面标记格式的部分字符。例：不包含data:image/png;base64；字符串

注意

如果设备支持返回人脸照片，请注意控制每次增量分页查询的条目数，避免因为响应结果太大导致请求失败。

调试接口 (opens new window)

# 人员特征更新

接口说明

利用该接口，可以将人员图片作为人脸打卡识别的依据下同步到综合人员签到应用。

本接口更新的数据只可下发到支持可见光人脸识别的设备，部分红外识别设备无法使用

自定义headers

在HTTP请求的headers中加入key为 Api-Cmd，值为 feature_update 的键值对。

业务说明

使用该接口后，企业可自行收集考勤人员人脸数据，无需依赖设备采集，提高人脸特征采集的效率。

照片要求人脸特征清晰，具体要求可参考人脸规范说明

请求示例

{ "users": [ { "ext_id": "12345", "feature_type": "fa", "feature_alg": "base64", "feature_value": [ "v1", "v2" ] } ] } 12345678910111213请求参数描述数据格式 users 人员列表 ext_id 用户外部系统ID，不可超过32个字符；字符串 feature_type 人员特征类型。包括:fa: 人脸； fp: 指纹；pass: 密码；card: 员工卡；identity: 身份证；字符串 feature_alg 特征算法标识，用于区分不同的特征值解析算法字符串 feature_value 批量更新的多个人员特征值信息字符串列表其中base64算法数据，不得包含数据外的标识("data:image/png;base64"、换行符等）；响应数据 { "code": 0, "msg": "", "data": { "error_ext_ids": [ "12345" ] } } 123456789响应参数描述数据格式 error_ext_ids 更新失败的用户id列表；字符串列表

调试接口 (opens new window)

# 人员特征查询

接口说明

利用该接口可以查询指定人员的特征值。

自定义headers

在HTTP请求的headers中加入key为 Api-Cmd，值为 checkin_feature_query 的键值对。

请求示例

{ "user_ext_id": "12345", "feature_type": "fa", "feature_alg": "base64" } 12345请求参数描述数据类型 user_ext_id 用户外部系统id，不可超过32个字符字符串 feature_type 人员特征类型。包括:fa: 人脸； fp: 指纹；pass: 密码；card: 员工卡；identity: 身份证；字符串 feature_alg 特征算法标识，用于区分不同的特征值解析算法；字符串响应示例 { "code": 0, "data": { "features": [ { "value": "MTIzNDU2Nzg5MA==", "is_abnormal": false }, { "value": "OTg3NjU0MzIxMA==", "is_abnormal": true } ] } } 123456789101112131415响应参数描述数据类型 features 特征值列表，顺序同后台页面展示顺序 value 特征值内容字符串 is_abnormal 特征值是否异常，有设备无法识别该特征值时即为异常布尔

调试接口 (opens new window)

# 结语

感谢您的阅读，至此对接已完成，对接及后续使用过程中如有疑问，请反馈给服务人员。

【本文地址】

考勤数据对接协议

考勤数据对接协议

今日新闻

推荐新闻