第三方系统集成接入

文档目标

本文档用于描述得力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}

加密步骤

1. 获取此次请求的相对路径path，不包括路径中带有的请求参数
2. 获取当前的13位时间戳timestamp
3. 获取此次请求的app对应的key和密钥secret
4. 将path timestamp key secret依次拼接成字符串
5. 对步骤4生成的字符串进行32位md计算，并将计算结果转换为全小写，获得最终的加密签名sig
6. 在请求的headers里面加入key为App-Key，值为当前请求的app对应的key的键值对
7. 在请求的headers里面加入key为App-Timestamp，值为步骤3中时间戳timestamp的键值对
8. 在请求的headers里面加入key为App-Sig，值为步骤5中生成的sig的键值对

加密举例

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

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

则生成的加密签名为:

md5(/v2.0/user15323159063643c5ee48d0b7d48c565ded5353c5ee48d0b7d48c591b8f430)=fdc9cbdb08ff823a2e095680d3925d2a

需要在请求的headers中加入App-Key=65ded5353c5ee48d0b7d48c591b8f430，App-Timestamp=1532315906364，App-Sig=50320c79b40786983c39d0745b047f40共三组键值对。

响应格式

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

1. code：响应的返回码，0表示正常的返回，其他表示错误
2. msg：响应的消息，说明错误的情况
3. data：响应的实际内容，以json对象的形式返回

code值说明

code值	含义
101	用户key错误
102	用户key缺失
103	请求签名错误
104	请求签名缺失
105	请求时间戳缺失
106	post请求中请求体格式错误

域名信息

• 测试环境域名：http://api.
• 生产环境域名：http://api.

部门管理api

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

访问地址

/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':''}

员工管理api

添加/修改员工信息

访问地址

/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':''}

业务api

人员特征更新api

接口说明

更新考勤人员的特征数据，用于机器识别。

访问地址

/v2.0/cloudappapi

自定义headers

• Api-Module：KQ。在请求的headers中加入key为Api-Module，值为KQ的键值对。
• Api-Cmd：feature_update。在请求的headers中加入key为Api-Cmd，值为feature_update的键值对。

请求参数

{ '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	数组	更新失败的人员列表。一般外部人员未同步到系统时产生，请确保录入特征之前完成组织人员的同步操作

获取考勤数据api

接口说明

获取考勤数据。

访问地址

/v2.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'                '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版本接口的地址