钉钉数据对接说明

API调用说明

钉钉服务端api文档 https://ding-doc.dingtalk.com/doc#/serverapi2/gh60vz
钉钉api调试工具 https://open-dev.dingtalk.com/apiExplorer#/?devType=org&api=/get_jsapi_ticket

部门

获取部门信息

1. 获取部门ID列表

   https://oapi.dingtalk.com/department/list?access_token=ACCESS_TOKEN

2. 根据部门ID获取部门详情

   https://oapi.dingtalk.com/department/get?access_token=ACCESS_TOKEN&id=123

关键字段说明

1. department_id

   部门id

2. department_name

   部门名称

3. department_parent_id

   父部门id，根部门为1

4. department_status

   部门状态：(空值表示正常) 、CHANGED(改动过)、DELETED(部门取消)

部门表

CREATE TABLE ding_department (
  department_id VARCHAR(128) NOT NULL,
  department_name VARCHAR(128),
  department_parent_id VARCHAR(128),
  department_status VARCHAR(64),
  PRIMARY KEY (department_id)
);
COMMENT ON COLUMN ding_department.department_id IS '部门id';
COMMENT ON COLUMN ding_department.department_name IS '部门名称';
COMMENT ON COLUMN ding_department.department_parent_id IS '上级部门id';
COMMENT ON COLUMN ding_department.department_status IS '可用状态';

员工

员工信息

1. 获取员工ID列表

   https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/queryonjob?access_token=ACCESS_TOKEN
   参数说明:https://ding-doc.dingtalk.com/doc#/serverapi2/rafx8t

2. 根据ID获得员工信息

   https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=zhangsan

关键字段说明

1. employee_department_ids

   用户所在部门id列表，注意，是列表。

2. employee_identity_card

   身份证号

3. employee_status

   员工状态：可用，禁用

员工表

CREATE TABLE ding_employee (
  employee_union_id VARCHAR(128),
  employee_name VARCHAR(64),
  employee_department_ids VARCHAR(255),
  employee_identity_card VARCHAR2(64),
  employee_status VARCHAR2(64),
  employee_user_id VARCHAR(128),
  PRIMARY KEY (employee_union_id)
);
COMMENT ON COLUMN ding_employee.employee_union_id IS '员工unionid';
COMMENT ON COLUMN ding_employee.employee_name IS '员工姓名';
COMMENT ON COLUMN ding_employee.employee_department_ids IS '员工部门名称';
COMMENT ON COLUMN ding_employee.employee_identity_card IS '员工身份证号码';
COMMENT ON COLUMN ding_employee.employee_status IS '员工状态：可用，禁用';
COMMENT ON COLUMN ding_employee.employee_user_id IS '员工id';

工作流

操作流程

1. 获取流程模板process_code

   process_code流程模板唯一标识，可在OA管理后台编辑审批表单部分的url中获取
   
   
   

2. 根据process_code批量获取据当前时间120天之内的任意时间段审批实例ID列表

   https://ding-doc.dingtalk.com/doc#/serverapi2/hh8lx5

3. 根据审批实例id获取审批实例详情

   https://ding-doc.dingtalk.com/doc#/serverapi2/xgqkvx

关键字段说明

1. business_id

   审批实例业务编号 一条审批流虽然会因为更新或撤销等操作新建审批流实例，但business_id仍保留一致

2. Attached_process_instance_ids

   审批附属实例列表，当已经通过的审批实例被修改或重置，会生成一个新的实例，作为继承审批实例的附属。如果想知道当前已经通过的审批实例的状态，可以依次遍历它的附属列表，查询里面每个实例的biz_action

3. biz biz_action

   审批实例业务动作，MODIFY表示该审批实例是基于原来的实例修改而来的，REVOKE表示该审批实例对原来的实例进行撤销，NONE表示正常发起

4. form_component_values

   表单详情列表,流程中表单数据的集合

5. status

   审批状态，分为NEW（新创造）RUNNING（运行中）终止（被终止）完成（完成）

重型员工请假流程表

CREATE TABLE ding_leave_approval (
  leave_id NUMBER NOT NULL,
  leave_employee_user_id NUMBER,
  leave_start VARCHAR(255),
  leave_end VARCHAR(255),
  leave_duration VARCHAR(255),
  leave_type VARCHAR(255),
  leave_reason VARCHAR(255),
  leave_title VARCHAR(255),
  leave_result VARCHAR(255),
  leave_status VARCHAR(255),
  leave_business_id NUMBER,
  leave_attached_ids VARCHAR(255),
  leave_biz_action VARCHAR(255),
  PRIMARY KEY (leave_id)
);
COMMENT ON COLUMN ding_leave_approval.leave_id IS '请假id';
COMMENT ON COLUMN ding_leave_approval.leave_employee_user_id IS '请假职员id';
COMMENT ON COLUMN ding_leave_approval.leave_start IS '请假开始时间';
COMMENT ON COLUMN ding_leave_approval.leave_end IS '请假结束时间';
COMMENT ON COLUMN ding_leave_approval.leave_duration IS '请假时长';
COMMENT ON COLUMN ding_leave_approval.leave_type IS '请假类型';
COMMENT ON COLUMN ding_leave_approval.leave_reason IS '请假原因';
COMMENT ON COLUMN ding_leave_approval.leave_title IS '标题';
COMMENT ON COLUMN ding_leave_approval.leave_result IS '结果';
COMMENT ON COLUMN ding_leave_approval.leave_status IS '状态';
COMMENT ON COLUMN ding_leave_approval.leave_business_id IS '业务流程id';
COMMENT ON COLUMN ding_leave_approval.leave_attached_ids IS '附属流程id';
COMMENT ON COLUMN ding_leave_approval.leave_biz_action IS '审批实例业务动作';

考勤

1. 根据用户ID列表获取180天内的考勤结果，一次最多50条

   https://oapi.dingtalk.com/attendance/list?access_token=ACCESS_TOKEN

2. 参数说明:

   https://ding-doc.dingtalk.com/doc#/serverapi2/ul33mm

关键字段说明

1. base_check_time

   打卡基准时间

2. user_check_time

   员工实际打卡时间

3. check_type

   打卡类型-上下班

4. time_result

   打卡的时间结果

5. locationResult

   位置结果(范围外/范围内)

考勤表

CREATE TABLE ding_attendance (
  attendance_id VARCHAR(128),
  attendance_employee_user_id VARCHAR(128),
  attendance_base_check_time VARCHAR(128),
  attendance_user_check_time VARCHAR(128),
  attendance_group_id VARCHAR(255),
  attendance_check_type VARCHAR(255),
  attendance_time_result VARCHAR(64),
  attendance_location_result VARCHAR(255),
  attendance_work_date VARCHAR(255),
  PRIMARY KEY (attendance_id)
);
COMMENT ON COLUMN ding_attendance.attendance_id IS '考勤id';
COMMENT ON COLUMN ding_attendance.attendance_employee_user_id IS '考勤员工id';
COMMENT ON COLUMN ding_attendance.attendance_base_check_time IS '打卡基准时间';
COMMENT ON COLUMN ding_attendance.attendance_user_check_time IS '员工实际打卡时间';
COMMENT ON COLUMN ding_attendance.attendance_group_id IS '考勤组id';
COMMENT ON COLUMN ding_attendance.attendance_check_type IS '打卡类型-上下班';
COMMENT ON COLUMN ding_attendance.attendance_time_result IS '时间结果';
COMMENT ON COLUMN ding_attendance.attendance_location_result IS '打卡范围结果';
COMMENT ON COLUMN ding_attendance.attendance_work_date IS '工作日';

Donate