得力E+开发模式接口说明
文档目标
本文档用于描述得力E+中的组织开启开发模式后提供的自定义开发api。
适用范围
本文档用于说明得力E+中的组织开启开发模式后对外提供的自定以开发接入方式,帮助和指导外部应用接入开发人员正确接入得力E+的数据。
相关术语
术语 | 解释 |
---|---|
部门 | 组织结构中的人员集合,和现实企业中的部门概念对应 |
员工 | 组织结构中的人员,不同员工的手机号/组织内的id/组织内的工号需要不同,此三者都是员工的唯一标识 |
App-Key | 为接入的外部应用分配的key,用来标识接入者的身份 |
App-Secret | 为接入的外部应用分配的密钥,用来对请求数据进行验证加密 |
App-Timestamp | 每次请求带有的当前时间戳,13位,精确到毫秒级别 |
Api-Module | 请求业务api时指明需要调用的api所在的模块,以key-value的形式放在headers中 |
Api-Cmd | 请求业务api时指明需要调用的api的具体指令,以key-value的形式放在headers中 |
请求方式
所有的api进入都使用post的http请求进行,请求数据都需要进行加密.
-
参数传递方式
所有的api请求都以post请求的方式进行,请求中的参数以json格式的request body进行传递。例如请求中有两个参数,key分别为k1,k2,value分别为字符串v1,数字v2,则请求的request body如下:
{
"k1":"v1",
"k2":v2
}
-
加密步骤
- 获取此次请求的相对路径path,不包括路径中带有的请求参数
- 获取当前的13位时间戳timestamp
- 获取此次请求的app对应的key和密钥secret
- 将path timestamp key secret依次拼接成字符串
- 对步骤4生成的字符串进行32位md计算,并将计算结果转换为全小写,获得最终的加密签名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://devapi.delicloud.com/v1.0/user的接口,请求时的时间戳为1532315906364,请求的参数如下:
{
"k1":"v1",
"k2":v2
}
则生成的加密签名为md5(/v1.0/user15323159063643c5ee48d0b7d48c565ded5353c5ee48d0b7d48c591b8f430)=fdc9cbdb08ff823a2e095680d3925d2a。 需要在请求的headers中加入App-Key=65ded5353c5ee48d0b7d48c591b8f430,App-Timestamp=1532315906364,App-Sig=fdc9cbdb08ff823a2e095680d3925d2a共三组键值对。
响应格式
响应以json对象的形式返回,包括code,msg和data三部分。
1. code:响应的返回码,0表示正常的返回,其他表示错误
2. msg:响应的消息,说明错误的情况
3. data:响应的实际内容,以json对象的形式返回
-
code值说明
code值 | 含义 |
---|---|
101 | 用户key错误 |
102 | 用户key缺失 |
103 | 请求签名错误 |
104 | 请求签名缺失 |
105 | 请求时间戳缺失 |
106 | post请求中请求体格式错误 |
域名信息
1. 测试环境域名:http://api.delicloud.xin
2. 生产环境域名:
部门管理api
-
初始化组织内根部门外部id
-
访问地址
/v1.0/department/init
-
接口说明
初始化组织内根部门外部id。 在得力E+中新建的组织的根部门默认外部id为0,调用此接口可以更新组织的根部门的外部id。
-
请求参数
{
"department_ext_id":"1" // 组织根部门在外部接入系统中的id,必填
}
-
响应数据
{
"code":0,
"msg":"",
"data":{
"ext_id":"1", // 此部门在外部接入系统中的id
"name":"得力集团" // 此部门的名称
}
}
-
添加/修改部门信息
-
访问地址
/v1.0/department
-
接口说明
新建或者编辑部门信息。 以部门在外部接入系统中的ext_id作为部门的唯一标识。当此标识在得力E+中不存在时,新建一个对应的部门;当此标识在得力E+中存在时,按照请求的参数值修改此部门在得力E+中的数据。
-
请求参数
{
"department_ext_id":"2", // 此部门在外部接入系统中的id,必填
"name":"设计部", // 此部门的名称,必填
"p_ext_id":"1" // 此部门在外部接入系统中的上级部门id,选填,不填时表示此部门没有上级部门
}
-
响应数据
{
"code":0,
"msg":"",
"data":{
"ext_id":"2", // 此部门在外部接入系统中的id
"name":"设计部" // 此部门的名称
}
}
-
删除部门
-
访问地址
/v1.0/department/delete
-
接口说明
删除部门。 以部门在外部接入系统中的ext_id作为部门的唯一标识,根据这个标识删除对应的部门,当此部门或此部门的下级部门中还有员工时,不能删除此部门。。
-
请求参数
{
"department_ext_id":"2" // 此部门在外部接入系统中的id,必填
}
-
响应数据
{
"code":0,
"msg":""
}
员工管理api
-
添加/修改员工信息
-
访问地址
/v1.0/employee
-
接口说明
新建或者编辑员工信息。 以员工在外部接入系统中的ext_id作为员工的唯一标识。当此标识在得力E+中不存在时,新建一个对应的员工;当此标识在得力E+中存在时,按照请求的参数值修改此员工在得力E+中的数据。
-
请求参数
{
"employee_ext_id":"2", // 此员工在外部接入系统中的id,必填
"name":"张三", // 此员工的名称,必填
"mobile":"18600000000", // 此员工在外部接入系统中的手机号,必填
"employee_num":"001", // 此员工在外部接入系统中的工号,必填
"department_infos":[ // 员工所属的部门信息数组,员工可能属于多个部门,必填
{
"ext_id":"2", // 员工所属部门在外部接入系统中的id
"title":"经理" // 员工在所属部门中的职位
}
]
}
-
响应数据
{
"code":0,
"msg":"",
"data":{
"ext_id":"2", // 此员工在外部接入系统中的id
"name":"张三", // 此员工的名称,必填
"mobile":"18600000000", // 此员工在外部接入系统中的手机号,必填
"employee_num":"001" // 此员工在外部接入系统中的工号,必填
}
}
-
删除员工
-
访问地址
/v1.0/employee/delete
-
接口说明
删除员工信息。 以员工在外部接入系统中的ext_id作为员工的唯一标识,根据此标识在组织内删除此员工。
-
请求参数
{
"employee_ext_id":"2" // 此员工在外部接入系统中的id,必填
}
-
响应数据
{
"code":0,
"msg":""
}
业务api
-
获取考勤数据api
-
接口说明
获取考勤数据。
-
访问地址
/v1.0/cloudappapi
-
自定义headers
Api-Module:KQ。在请求的headers中加入key为Api-Module,值为KQ的键值对。 Api-Cmd:checkin_query。在请求的headers中加入key为Api-Cmd,值为checkin_query的键值对。
-
请求参数
{
"next_id": 0,
"page_size": 50
}
可配置参数 | 描述 |
---|---|
next_id | 本次查询的开始记录ID,从0开始,下次请求取上次返回记录的最大ID; |
page_size | 可选,本次查询的最大记录数,默认50; |
-
响应数据
{
"code": 0,//0表示成功
"msg": "错误描述",
"data": {
"next_id": 1000,
"data": [
{
"id": 123,
"user_id": "用户ID",
"ext_id": "12345",
"empno": "e123",
"check_type": "fp",
"check_time": 1503025335,
"check_data": "打卡数据"
}
]
}
}
响应结果各参数说明如下:
参数 | 类型 | 描述 |
---|---|---|
code | 整型 | 结果错误码。0表示成功 |
msg | 字符串 | 错误描述 |
next_id | 整型 | 下次查询的记录id |
data | 数组 | 打卡记录,以数组形式返回。各属性说明如下: user_id:用户ID, ext_id:可选,用户外部系统ID,如果不存在则不返回; empno:用户的工号,如果不存在则不返回; check_type:打卡方式,包括fp、fa、pass、card、wifi、gps、外勤、补签等; check_time:打卡时间(精确到秒); check_data:打卡数据,不同的打卡方式数据不同。例如考勤机打卡应保存考勤机设备ID,gps打卡应保存gps坐标位置等* |
更新记录
更新时间 | 操作人 | 更新内容 |
---|---|---|
2018-7-23 | 胡超 | 初始版本,提供新增/修改部门,新增/修改员工,导出考勤数据的功能 |
2018-7-23 | 胡超 | 修改版本,修改请求加密方法,修改部分拼写错误 |
2018-7-23 | 胡超 | 修改版本,修改请求加密方法 |
2018-7-25 | 胡超 | 修改版本,修改拼写错误 |
2018-7-27 | 胡超 | 修改版本,增加测试环境域名,增加修改组织根部门外部id的api接口,根据外部id删除部门的api接口,根据外部id删除员工的api接口 |
2019-8-29 | 胡超 | 修改版本,增加业务api中获取考勤数据的用户工号参数 |