前言

Hello！欢迎阅读此文档，该文档将向您介绍如何与得力e+系统进行考勤对接。

对接流程

四步搞定考勤对接：

1、阅读了解对接文档，判断是否满足对接需求，订购API接口。（订购渠道：天猫、京东得力云考勤机售卖的店铺）

2、下载得力e+App，注册登录，绑定云考勤机并创建组织；

3、提供对接需求方对接人微信；提供客户号、得力e+ App的注册手机号，授权开通 App-Key 和 App-Secret；

4、邀请进入企业微信服务群，进行对接。

考勤对接必读

您所使用的系统与得力e+平台进行考勤对接，开启对接前必须知道的事情

注意: demo 中的提供的仅为示例代码，请不要直接用于生产环境!

对接业务逻辑说明

对接业务围绕部门管理、员工管理、获取考勤数据展开，以下一一说明：

考勤的基础是部门架构及其中的人，所以考勤对接的第一步需要将双边系统中的架构和人关联起来，得力e+平台提供了部门和员工管理API，利用该API，可以将外部接入系统中的部门架构、人员推送到得力e+平台。

得力e+平台已接收到外部接入系统推送的人员，下一步需要通过得力e+系统的自有功能将这些人员放置到考勤机，并给他们录入生物特征用于打卡识别。

打卡人员打卡匹配上已录入的生物特征成功即打卡成功，产生的打卡数据会实时传输到得力e+平台。得力e+平台提供了考勤数据API，利用该API，外部接入系统可以获取到打卡人员在云考勤机上的打卡数据；还可以获取人员在得力e+系统上手机打卡产生的数据。

系统对接前说明

API访问域名信息

https://v2-api.delicloud.com

API请求方式

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

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

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

请求加密

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

举例：

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

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

则生成的加密签名为:

md5(/v2.0/user15323159063643c5ee48d0b7d48c565ded5353c5ee48d0b7d48c591b8f430)=fdc9cbdb08ff823a2e095680d3925d2a

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

加密请求响应

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

​

系统对接

部门管理API

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

/v2.0/department/init

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

{
    "department_ext_id":"1"
}
请求参数 描述
department_ext_id 组织根部门在外部接入系统中的id； 
{
    "code":0,
    "msg":"",
    "data":{
        "ext_id":"1",
        "name":"得力集团"
    }
}
响应参数 描述
ext_id 此部门在外部接入系统中的id；
name 此部门的名称；

查询部门

/v2.0/department/query

分页拉取平台中所有部门信息，调用此接口将返回E+中所有的部门信息。请开发者注意: 没有ext_id的部门信息也会被返回。

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

为部门设置外部ID

/v2.0/department/ext

为部门设置ext_id。
调用此接口将修改部门的外部ID字段，注意：请调用者保证外部ID的唯一性，如果违反唯一性该接口会抛出错误。

{
    "id":"3244",       
    "ext_id":"需要设置的ID"       
}
请求参数 描述
id 部门ID；
ext_id 此部门在外部接入系统中的id； 
{
    "code":0,
    "msg":""
}

添加/修改部门信息

/v2.0/department

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

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

删除部门

/v2.0/department/delete

利用该接口可以删除部门。
以部门在外部接入系统中的ext_id作为部门的唯一标识，根据这个标识删除对应的部门。注意：当此部门或此部门的下级部门中还有员工时，不能删除此部门，需要先调用删除员工的接口，先将部门下的员工删除。

{
    "department_ext_id":"2"
}
请求参数 描述
department_ext_id 此部门在外部接入系统中的id； 
{
  "code":0,
  "msg":""
}

员工管理API

添加/修改员工信息

/v2.0/employee

利用该接口可以新建或者编辑员工信息。
外部接入系统中员工需要有唯一标识的id，相对于得力e+系统平台，就是人员的外部id。以员工在外部接入系统中的ext_id作为员工的唯一标识。 当此标识在得力E+中不存在时，新建一个对应的员工；当此标识在得力E+中存在时，按照请求的参数值修改此员工在得力E+中的数据。
如果外部接入系统中人员没有手机号这个字段，可以自行给员工创建手机号，该手机号不必是真实存在的，满足中国大陆手机号位数即可。 因为员工的手机号不是真实所有，所以员工通过自有手机号注册加入得力e+中的组织，查看个人考勤记录。

{
    "employee_ext_id":"2",
    "name":"张三",
    "mobile":"18600000000",
    "employee_num":"001",
    "department_infos":[
        {
            "ext_id":"2",
            "title":"经理"
        }
    ]
}
请求参数 描述
employee_ext_id 此员工在外部接入系统中的id；
name 此员工的名称；
mobile 此员工在外部接入系统中的手机号；
employee_num 此员工在外部接入系统中的工号；
department_infos 员工所属的部门信息数组，员工可能属于多个部门；
    ext_id 员工所属部门在外部接入系统中的id；
    title 员工在所属部门中的职位； 
{
    "code":0,
    "msg":"",
    "data":{
        "ext_id":"2",
        "name":"张三",
        "mobile":"18600000000",
        "employee_num":"001"
    }
}
响应参数 描述
ext_id 此员工在外部接入系统中的id；
name 此员工的名称；
mobile 此员工在外部接入系统中的手机号；
employee_num 此员工在外部接入系统中的工号；

批量获取员工信息

/v2.0/employee/query

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

{
    "limit":20,
    "offset":0
}
请求参数 描述
limit 分页大小，必须在1～100之间；
offset 偏移量，默认从0开始； 
{
    "code":0,
    "msg":"",
    "data":{
        "total":"1",
        "rows":[
            {
                "id":"123",
                "ext_id":"2",
                "ext_extra_info": {},
                "name":"张三",
                "mobile":"18600000000",
                "employee_num":"001",
                "department_infos":[
                    {
                        "id":"321"
                    }
                ]
            }
        ]
    }
}
响应参数 描述
total 组织总的员工数目；
rows 本次分页查询的员工信息列表；
    id 得力E+中的员工ID；
    ext_id 此员工在外部接入系统中的id；
    ext_extra_info 此员工在外部接入系统中的其他自定义业务信息；
    name 此员工的名称；
    mobile 此员工在外部接入系统中的手机号；
    employee_num 此员工在外部接入系统中的工号；
    department_infos 员工所属的部门信息数组，员工可能属于多个部门；
        id 得力E+的部门ID；

为员工设置外部ID

/v2.0/employee/ext

为得力e+系统平台中已存在的员工设置ext_id。
调用此接口将修改员工的外部ID字段，注意：请调用者保证外部ID的唯一性，如果违反唯一性该接口会抛出错误。

{
    "id":"3244",       
    "ext_id":"2"       
}
请求参数 描述
id 得力e+中的员工ID；
ext_id 此员工在外部接入系统中的id； 
{
    "code":0,
    "msg":""
}

为员工设置自定义业务信息

/v2.0/employee/extra

为得力e+系统平台中已同步外部ID的员工设置其他自定义的业务信息。自定义业务信息的字段内容不限，但长度不能超过1024个字节。

{
    "ext_id":"2",
    "ext_extra_info": {
        "location_id":"1224",
        "name":"办公大楼"
    }
}
请求参数 描述
ext_id 此员工在外部接入系统中的id；
ext_extra_info 此员工在外部接入系统中的其他自定义业务信息，请使用JSON格式的kv结构上报； 
{
    "code":0,
    "msg":""
}

删除员工

/v2.0/employee/delete

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

{
  "employee_ext_id":"2"
}
请求参数 描述
employee_ext_id 得力e+此员工在外部接入系统中的id； 
{
  "code":0,
  "msg":""
}

考勤接口对接

云考勤应用接口

以下接口用于获取云考勤应用的数据。 请在HTTP请求的headers中统一加入key为 Api-Module，值为 KQ 的键值对，用于标示请求目标为云考勤应用系统。

人员特征更新API

响应参数 描述
error_ext_ids 更新失败的用户ID列表；

考勤数据获取API

响应参数 描述
next_id 本次增量查询结果的最大偏移量值，下次以此偏移量为请求继续进行增量查询；
data 本次增量查询到的打卡记录列表；
    id 打卡记录ID
    user_id 打卡人员ID
    ext_id 打卡人员在外部系统的id；
    check_type 打卡方式。包括：
fa: 人脸；
fp: 指纹；
pass: 密码；
card: 刷卡；
app_scan: APP扫码；
gps: gps位置打卡；
wifi: wifi打卡；
outside: 外勤打卡；
other: 补签异常申请；
    check_time 打卡时间戳，精确到秒；
    check_data 打卡补充数据，不同的打卡类型则返回不同的数据。其中：
fa/fp/pass/card: sn|打卡方式；
gps打卡: 经纬度；
wifi打卡: 路由器mac；
补签异常申请：原因；
外勤打卡: 经纬度|地址标题|地址内容|外勤描述；

综合签到应用接口

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

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

考勤数据初始化API

人员特征更新API

响应参数 描述
error_ext_ids 更新失败的用户ID列表；

考勤数据获取API

响应参数 描述
next_id 本次增量查询结果的最大偏移量值，下次以此偏移量为请求继续进行增量查询；
data 本次增量查询到的打卡记录列表；
    id 打卡记录ID
    user_id 打卡人员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 打卡补充数据，不同的打卡类型则返回不同的数据。示例如下：
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"}
补卡: reissue
 {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4}
自动补的灵活卡: {"employee_num":"","dept_name":"B超室","member_name":"刘有会","dept_id":4}

门禁数据获取API

办公地点更新API

结语

感谢您的阅读，至此对接已完成，对接及后续使用过程中如有疑问，请与技术服务人员联系！
邮箱地址： cloud_bd@nbdeli.com

demo下载地址：

java：https://img.delicloud.com/2b/apidemo-java.zip

php：https://img.delicloud.com/2b/apidemo-php.zip

c#： https://img.delicloud.com/2b/apidemo-c#.zip