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