前言

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=3c5ee48d0b7d48c5App-Timestamp=1532315906364App-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