得力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
}

  • 加密步骤

    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.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中获取考勤数据的用户工号参数