本文档用于描述得力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}
假设当前存在一个外部应用接入,分配给此应用的App-Key
为3c5ee48d0b7d48c5,App-Secret
为65ded5353c5ee48d0b7d48c591b8f430。当前此外部应用需要请求地址为的接口,请求的时间戳为1532315906364,请求的参数如下:
{ 'k1':'v1', 'k2':v2}
则生成的加密签名为:
md5(/v2.0/user15323159063643c5ee48d0b7d48c565ded5353c5ee48d0b7d48c591b8f430)=fdc9cbdb08ff823a2e095680d3925d2a
需要在请求的headers中加入App-Key=65ded5353c5ee48d0b7d48c591b8f430,App-Timestamp=1532315906364,App-Sig=50320c79b40786983c39d0745b047f40共三组键值对。
响应以json对象的形式返回,包括code,msg和data三部分。
code值 | 含义 |
---|---|
101 | 用户key错误 |
102 | 用户key缺失 |
103 | 请求签名错误 |
104 | 请求签名缺失 |
105 | 请求时间戳缺失 |
106 | post请求中请求体格式错误 |
/v2.0/department/init
初始化组织内根部门外部id。在得力E+中新建的组织的根部门默认外部id为0,调用此接口可以更新组织的根部门的外部id。
{ 'department_ext_id':'1' //组织根部门在外部接入系统中的id,必填}
{ 'code':0, 'msg':'', 'data':{ 'ext_id':'1', // 此部门在外部接入系统中的id 'name':'得力集团' // 此部门的名称 }}
/v2.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':'设计部' // 此部门的名称 }}
/v2.0/department/delete
删除部门。以部门在外部接入系统中的ext_id作为部门的唯一标识,根据这个标识删除对应的部门,当此部门或此部门的下级部门中还有员工时,不能删除此部门。。
{ 'department_ext_id':'2' // 此部门在外部接入系统中的id,必填}
{ 'code':0, 'msg':''}
/v2.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' // 此员工在外部接入系统中的工号,必填 }}
/v2.0/employee/delete
删除员工信息。以员工在外部接入系统中的ext_id作为员工的唯一标识,根据此标识在组织内删除此员工。
{ 'employee_ext_id':'2' // 此员工在外部接入系统中的id,必填}
{ 'code':0, 'msg':''}
更新考勤人员的特征数据,用于机器识别。
/v2.0/cloudappapi
{ 'users': [{ 'ext_id': '12345', 'feature_type': 'fa', 'feature_alg': 'base64', 'feature_value': [] }]}
可配置参数 | 描述 |
---|---|
ext_id | 用户外部系统ID |
feature_type | 人员特征类型 |
feature_alg | 特征算法标示,用于区分不同的特征值解析算法 |
feature_value | 批量更新的多个人员特征值信息 |
{ 'code': 0,//0表示成功 'msg': '错误描述', 'data': { 'error_ext_ids': ['12345'] } }
响应结果各参数说明如下:
参数 | 类型 | 描述 |
---|---|---|
code | 整型 | 结果错误码。0表示成功 |
msg | 字符串 | 错误描述 |
error_ext_ids | 数组 | 更新失败的人员列表。一般外部人员未同步到系统时产生,请确保录入特征之前完成组织人员的同步操作 |
获取考勤数据。
/v2.0/cloudappapi
{ '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' 'check_type': 'fp', 'check_time': 1503025335, 'check_data': '打卡数据' } ] } }
响应结果各参数说明如下:
参数 | 类型 | 描述 |
---|---|---|
code | 整型 | 结果错误码。0表示成功 |
msg | 字符串 | 错误描述 |
next_id | 整型 | 下次查询的记录id |
data | 数组 | 打卡记录,以数组形式返回。各属性说明如下: user_id:用户ID, ext_id:可选,用户外部系统ID,如果不存在则不返回; 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接口 |
2020-4-14 | 徐超国 | 修改版本,增加考勤人员特征更新api接口 |
2020-4-16 | 胡超 | 修改版本,修订2.0版本接口的地址 |
联系客服