Skip to content

写入审批结果

由于部分企业使用的是自己的审批系统,而不是飞书审批系统,因此员工的请假、加班等数据无法流入到飞书考勤系统中,导致员工在请假时间段内依然收到打卡提醒,并且被记为缺卡。 对于这些只使用飞书考勤系统,而未使用飞书审批系统的企业,可以通过考勤开放接口的形式,将三方审批结果数据回写到飞书考勤系统中。(请注意,如果在飞书审批、自助服务或假勤应用中发起加班,请勿使用该接口写入和系统同一天生成的加班数据,否则写入的数据不计入)

Tip: 1. 目前支持写入加班、请假、出差和外出这四种审批结果,写入只会追加(insert),不会覆盖(update)(开放接口导入的加班假期记录,在管理后台的假期加班里查不到,可以在考勤统计报表查看,或者通过获取审批通过数据来查询) 2. 离职人员没有考勤组,所以写入和返回的时间会有差异

请求

项目
HTTP URLhttps://open.feishu.cn/open-apis/attendance/v1/user_approvals
HTTP MethodPOST
接口频率限制50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用attendance:task 写入打卡数据

请求头

名称类型必填描述
Authorizationstringtenant_access_token 值格式:"Bearer access_token" 示例值:"Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多:如何选择与获取 access token
Content-Typestring固定值:"application/json; charset=utf-8"

查询参数

名称类型必填描述
employee_typestring请求体和响应体中的 user_id 的员工ID类型。如果没有后台管理权限,可使用通过手机号或邮箱获取用户 ID
示例值:employee_id
可选值有
- employee_id: 员工 employee ID,即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID - employee_no: 员工工号,即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号 - open_id: 用户在某个应用中的身份,可以参考如何获取不同的用户 ID

请求体

名称类型必填描述
user_approvaluser_approval审批信息
  └ user_idstring审批提交人 ID。传入的ID类型需要与employee_type的取值一致
示例值:"abd754f7"
  └ datestring审批作用日期,格式为yyyyMMdd
示例值:"20210104"
  └ outsuser_out\[\]外出信息
    └ uniq_idstring外出类型唯一 ID,代表一种外出类型,长度小于 14
* 如何获取?可以选择填入三方的外出类型id。如市内外出、市外外出的id
示例值:"9496E43696967658A512969523E89870"
    └ unitint外出时长单位
示例值:1
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
    └ intervalint关联审批单外出时长,单位为秒,与unit无关
示例值:3600
    └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 09:00:00"
    └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 19:00:00"
    └ i18n_namesi18n_names外出多语言展示,格式为 map,key 为 ["ch"、"en"、"ja"],其中 ch 代表中文、en 代表英语、ja 代表日语
      └ chstring中文描述
示例值:"中文描述"
      └ enstring英语描述
示例值:"English description"
      └ jastring日语描述
示例值:"日本語の説明"
    └ default_localestring默认语言类型,由于飞书客户端支持中、英、日三种语言,当用户切换语言时,如果假期名称没有所对应的语言,会使用默认语言的名称
示例值:"ch"
    └ reasonstring外出理由
示例值:"外出办事"
    └ idempotent_idstring外出记录的唯一幂等键,用于避免外出记录重复创建,可以填入三方的外出记录id
示例值:"1233432312"
    └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
  └ leavesuser_leave\[\]请假信息
    └ uniq_idstring假期类型唯一ID,代表一种假期类型
示例值:"6852582717813440527"
    └ unitint假期时长单位。假期时长单位若传3,不足半天按照半天计算,以此类推
示例值:1
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
    └ intervalint无效字段,暂时不支持
示例值:3600
    └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 09:00:00"
    └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 19:00:00"
    └ i18n_namesi18n_names假期多语言展示,格式为 map,key 为 ["ch"、"en"、"ja"],其中 ch 代表中文、en 代表英语、ja 代表日语
      └ chstring中文描述
示例值:"中文描述"
      └ enstring英语描述
示例值:"English description"
      └ jastring日语描述
示例值:"日本語の説明"
    └ default_localestring默认语言类型,由于飞书客户端支持中、英、日三种语言,当用户切换语言时,如果假期名称没有所对应的语言,会使用默认语言的名称
示例值:"ch"
可选值有
- ch: 中文 - en: 英文 - ja: 日文
    └ reasonstring请假理由,必选字段
示例值:"家里有事"
    └ idempotent_idstring请假记录的唯一幂等键,用于避免请假记录重复创建,可以填入三方的请假记录id
示例值:"1233432312"
    └ leave_detail_range_objstime_range_list\[\]根据班次计算出来的请假具体时间,格式为list<br>数据校验规则
- 长度范围:030
      └ dayint日期day
示例值:20220501
数据校验规则
- 取值范围:1700010120990101
      └ time_rangestime_range\[\]时间范围,是一个list<br>数据校验规则
- 长度范围:020
        └ start_time_stampint开始时间
示例值:1751385600
数据校验规则
- 取值范围:09223372036
        └ end_time_stampint结束时间
示例值:1751385600
数据校验规则
- 取值范围:09223372036
  └ overtime_worksuser_overtime_work\[\]加班信息
    └ durationnumber(float)加班时长,如需使用此字段进行加班时长计算,请联系技术支持开通。默认采用start_time和end_time计算
示例值:1.5
    └ unitint加班时长单位
示例值:1
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
    └ categoryint加班日期类型
示例值:2
可选值有
- 1: 工作日 - 2: 休息日 - 3: 节假日
    └ typeint加班规则类型
示例值:1
可选值有
- 0: 仅记录 - 1: 调休 - 2: 加班费 - 3: 【该可选值已废弃】
    └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-09 09:00:00"
    └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-10 13:00:00"
    └ reasonstring加班事由
示例值:"推进项目进度"
    └ idempotent_idstring加班记录的唯一幂等键,用于避免加班记录重复创建,可以填入三方的加班记录id
示例值:"1233432312"
    └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
  └ tripsuser_trip\[\]出差信息。
目前仅支持全天出差(未满全天则按全天计入)。如果你需要支持半天出差,请咨询技术支持
    └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 09:00:00"
    └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 19:00:00"
    └ reasonstring出差理由
示例值:"培训"
    └ approve_pass_timestring审批通过时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 12:00:00"
    └ approve_apply_timestring审批申请时间,时间格式为 yyyy-MM-dd HH:mm:ss
示例值:"2021-01-04 11:00:00"
    └ idempotent_idstring出差记录的唯一幂等键,用于避免出差记录重复创建,可以填入三方的出差记录id
示例值:"1233432312"
    └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
示例值:["7304865941202929196"]
    └ departureregion_place出发地(只有一个)
      └ region_levelstring地理等级(国家|省|市|区) l1:国家级; l2:省级; l3:市级; l4:区/县级
示例值:"l1"
      └ region_idstring地理id可以通过查询区/县信息查询城市信息获取(仅支持飞书人事企业版使用)
示例值:"6863333418483058189"
    └ destinationsregion_place\[\]目的地(可写多个)
      └ region_levelstring地理等级(国家|省|市|区) l1:国家级; l2:省级; l3:市级; l4:区/县级
示例值:"l1"
      └ region_idstring地理id可以通过查询区/县信息查询城市信息获取(仅支持飞书人事企业版使用)
示例值:"6863333418483058189"
    └ transportationint\[\]交通工具(1 飞机,2 火车,3 汽车,4 高铁/动车,5 船,6 其他)
示例值:[1]
    └ trip_typeint出差类型(1:单程 2:往返)
示例值:1
    └ remarksstring出差备注
示例值:"出差备注"
  └ time_zonestring此字段不再使用,以用户匹配的考勤组时区为准
示例值:"0"

请求体示例

json
{
    "user_approval": {
        "user_id": "abd754f7",
        "date": "20210104",
        "outs": [
            {
                "uniq_id": "9496E43696967658A512969523E89870",
                "unit": 1,
                "interval": 3600,
                "start_time": "2021-01-04 09:00:00",
                "end_time": "2021-01-04 19:00:00",
                "i18n_names": {
                    "ch": "中文描述",
                    "en": "English description",
                    "ja": "日本語の説明"
                },
                "default_locale": "ch",
                "reason": "外出办事",
                "idempotent_id": "1233432312",
                "correct_process_id": [
                    "7304865941202929196"
                ],
                "cancel_process_id": [
                    "7304865941202929196"
                ],
                "process_id": [
                    "7304865941202929196"
                ]
            }
        ],
        "leaves": [
            {
                "uniq_id": "6852582717813440527",
                "unit": 1,
                "interval": 3600,
                "start_time": "2021-01-04 09:00:00",
                "end_time": "2021-01-04 19:00:00",
                "i18n_names": {
                    "ch": "中文描述",
                    "en": "English description",
                    "ja": "日本語の説明"
                },
                "default_locale": "ch",
                "reason": "家里有事",
                "idempotent_id": "1233432312",
                "leave_detail_range_objs": [
                    {
                        "day": 20220501,
                        "time_ranges": [
                            {
                                "start_time_stamp": 1751385600,
                                "end_time_stamp": 1751385600
                            }
                        ]
                    }
                ]
            }
        ],
        "overtime_works": [
            {
                "duration": 1.5,
                "unit": 1,
                "category": 2,
                "type": 1,
                "start_time": "2021-01-09 09:00:00",
                "end_time": "2021-01-10 13:00:00",
                "reason": "推进项目进度",
                "idempotent_id": "1233432312",
                "correct_process_id": [
                    "7304865941202929196"
                ],
                "cancel_process_id": [
                    "7304865941202929196"
                ],
                "process_id": [
                    "7304865941202929196"
                ]
            }
        ],
        "trips": [
            {
                "start_time": "2021-01-04 09:00:00",
                "end_time": "2021-01-04 19:00:00",
                "reason": "培训",
                "approve_pass_time": "2021-01-04 12:00:00",
                "approve_apply_time": "2021-01-04 11:00:00",
                "idempotent_id": "1233432312",
                "correct_process_id": [
                    "7304865941202929196"
                ],
                "cancel_process_id": [
                    "7304865941202929196"
                ],
                "process_id": [
                    "7304865941202929196"
                ],
                "departure": {
                    "region_level": "l1",
                    "region_id": "6863333418483058189"
                },
                "destinations": [
                    {
                        "region_level": "l1",
                        "region_id": "6863333418483058189"
                    }
                ],
                "transportation": [
                    1
                ],
                "trip_type": 1,
                "remarks": "出差备注"
            }
        ],
        "time_zone": "0"
    }
}

响应

响应体

名称类型描述
codeint错误码,非 0 表示失败
msgstring错误描述
data\--
  └ user_approvaluser_approval审批信息
    └ user_idstring审批提交人 ID
    └ datestring审批作用日期,格式为yyyyMMdd
    └ outsuser_out\[\]外出信息
      └ approval_idstring审批实例id 创建的时候无效字段无需传入
      └ uniq_idstring外出类型唯一 ID,代表一种假期类型,长度小于 14
* 此ID对应外出类型(即: i18n_names),因此需要保证唯一
      └ unitint外出时长单位
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
      └ intervalint关联审批单外出时长,单位为秒,与unit无关
      └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ i18n_namesi18n_names外出多语言展示,格式为 map,key 为 ["ch"、"en"、"ja"],其中 ch 代表中文、en 代表英语、ja 代表日语
        └ chstring中文描述
        └ enstring英语描述
        └ jastring日语描述
      └ default_localestring默认语言类型,由于飞书客户端支持中、英、日三种语言,当用户切换语言时,如果假期名称没有所对应的语言,会使用默认语言的名称
      └ reasonstring外出理由
      └ approve_pass_timestring审批通过时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ approve_apply_timestring审批申请时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ idempotent_idstring外出记录的唯一幂等键,响应体中无需关注
      └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
    └ leavesuser_leave\[\]请假信息
      └ approval_idstring审批实例 ID
      └ uniq_idstring假期类型唯一 ID,代表一种假期类型,长度小于 14
* 此ID对应假期类型(即: i18n_names),因此需要保证唯一
      └ unitint假期时长单位
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
      └ intervalint关联审批单假期时长,单位为秒,与unit无关
      └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ i18n_namesi18n_names假期多语言展示,格式为 map,key 为 ["ch"、"en"、"ja"],其中 ch 代表中文、en 代表英语、ja 代表日语
        └ chstring中文描述
        └ enstring英语描述
        └ jastring日语描述
      └ default_localestring默认语言类型,由于飞书客户端支持中、英、日三种语言,当用户切换语言时,如果假期名称没有所对应的语言,会使用默认语言的名称
可选值有
- ch: 中文 - en: 英文 - ja: 日文
      └ reasonstring请假理由,必选字段
      └ approve_pass_timestring审批通过时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ approve_apply_timestring审批申请时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ idempotent_idstring请假记录的唯一幂等键,响应体中无需关注
      └ leave_detail_range_objstime_range_list\[\]根据班次计算出来的请假具体时间,格式为list
        └ dayint日期day
        └ time_rangestime_range\[\]时间范围,是一个list
          └ start_time_stampint开始时间
          └ end_time_stampint结束时间
    └ overtime_worksuser_overtime_work\[\]加班信息
      └ approval_idstring审批实例 ID
      └ durationnumber(float)加班时长
      └ unitint加班时长单位
可选值有
- 1: 天 - 2: 小时 - 3: 半天 - 4: 半小时
      └ categoryint加班日期类型
可选值有
- 1: 工作日 - 2: 休息日 - 3: 节假日
      └ typeint加班规则类型
可选值有
- 0: 仅记录 - 1: 调休 - 2: 加班费 - 3: 关联加班规则,没有调休或加班费
      └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ reasonstring加班事由
      └ idempotent_idstring加班记录的唯一幂等键,响应体中无需关注
      └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
    └ tripsuser_trip\[\]出差信息
      └ approval_idstring审批实例id
      └ start_timestring开始时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ end_timestring结束时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ reasonstring出差理由
      └ approve_pass_timestring审批通过时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ approve_apply_timestring审批申请时间,时间格式为 yyyy-MM-dd HH:mm:ss
      └ idempotent_idstring出差记录的唯一幂等键,响应体中无需关注
      └ correct_process_idstring\[\]更正流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ cancel_process_idstring\[\]撤销流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ process_idstring\[\]发起流程实例 ID。该字段由系统自动生成,在写入审批结果时,无需传入该参数。
      └ departureregion_place出发地(只有一个)
        └ region_levelstring地理等级(国家|省|市|区) l1:国家级; l2:省级; l3:市级; l4:区/县级
        └ region_idstring地理id
      └ destinationsregion_place\[\]目的地(可写多个)
        └ region_levelstring地理等级(国家|省|市|区) l1:国家级; l2:省级; l3:市级; l4:区/县级
        └ region_idstring地理id
      └ transportationint\[\]交通工具(1 飞机,2 火车,3 汽车,4 高铁/动车,5 船,6 其他)
      └ trip_typeint出差类型(1:单程 2:往返)
      └ remarksstring出差备注
    └ time_zonestring计算时间所用的时区信息

响应体示例

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "user_approval": {
            "user_id": "abd754f7",
            "date": "20210104",
            "outs": [
                {
                    "approval_id": "6737202939523236113",
                    "uniq_id": "9496E43696967658A512969523E89870",
                    "unit": 1,
                    "interval": 3600,
                    "start_time": "2021-01-04 09:00:00",
                    "end_time": "2021-01-04 19:00:00",
                    "i18n_names": {
                        "ch": "中文描述",
                        "en": "English description",
                        "ja": "日本語の説明"
                    },
                    "default_locale": "ch",
                    "reason": "外出办事",
                    "approve_pass_time": "2021-01-04 12:00:00",
                    "approve_apply_time": "2021-01-04 11:00:00",
                    "idempotent_id": "1233432312",
                    "correct_process_id": [
                        "7304865941202929196"
                    ],
                    "cancel_process_id": [
                        "7304865941202929196"
                    ],
                    "process_id": [
                        "7304865941202929196"
                    ]
                }
            ],
            "leaves": [
                {
                    "approval_id": "6737202939523236113",
                    "uniq_id": "6852582717813440527",
                    "unit": 1,
                    "interval": 3600,
                    "start_time": "2021-01-04 09:00:00",
                    "end_time": "2021-01-04 19:00:00",
                    "i18n_names": {
                        "ch": "中文描述",
                        "en": "English description",
                        "ja": "日本語の説明"
                    },
                    "default_locale": "ch",
                    "reason": "家里有事",
                    "approve_pass_time": "2021-01-04 12:00:00",
                    "approve_apply_time": "2021-01-04 11:00:00",
                    "idempotent_id": "1233432312",
                    "leave_detail_range_objs": [
                        {
                            "day": 20220501,
                            "time_ranges": [
                                {
                                    "start_time_stamp": 1751385600,
                                    "end_time_stamp": 1751385600
                                }
                            ]
                        }
                    ]
                }
            ],
            "overtime_works": [
                {
                    "approval_id": "6737202939523236113",
                    "duration": 1.5,
                    "unit": 1,
                    "category": 2,
                    "type": 1,
                    "start_time": "2021-01-09 09:00:00",
                    "end_time": "2021-01-10 13:00:00",
                    "reason": "推进项目进度",
                    "idempotent_id": "1233432312",
                    "correct_process_id": [
                        "7304865941202929196"
                    ],
                    "cancel_process_id": [
                        "7304865941202929196"
                    ],
                    "process_id": [
                        "7304865941202929196"
                    ]
                }
            ],
            "trips": [
                {
                    "approval_id": "6737202939523236113",
                    "start_time": "2021-01-04 09:00:00",
                    "end_time": "2021-01-04 19:00:00",
                    "reason": "培训",
                    "approve_pass_time": "2021-01-04 12:00:00",
                    "approve_apply_time": "2021-01-04 11:00:00",
                    "idempotent_id": "1233432312",
                    "correct_process_id": [
                        "7304865941202929196"
                    ],
                    "cancel_process_id": [
                        "7304865941202929196"
                    ],
                    "process_id": [
                        "7304865941202929196"
                    ],
                    "departure": {
                        "region_level": "l1",
                        "region_id": "6863333418483058189"
                    },
                    "destinations": [
                        {
                            "region_level": "l1",
                            "region_id": "6863333418483058189"
                        }
                    ],
                    "transportation": [
                        1
                    ],
                    "trip_type": 1,
                    "remarks": "出差备注"
                }
            ],
            "time_zone": "Asia/Shanghai"
        }
    }
}

错误码

HTTP状态码错误码描述排查建议
4001220001param is invalid入参校验失败,请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 技术支持
4001220002tenant_id is empty请检查入参中的 tenant_access_token是否正确
4001220004param is invalid请参考实际返回的错误信息排查问题。例如“user_id is not exist or does not have permission”代表入参传入的用户id不存在或者没有权限。如仍无法解决可联系 技术支持
4001220005permission denied请前往考勤管理后台检查数据权限范围
5001225000param is invalid请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
4001225001param is invalid请参考实际返回的错误信息排查问题。返回错误格式为导入的审批数据,格式为:{"TripErrorRecords":"","OvertimeWorkErrorRecords":"","LeaveErrorRecords":"","OutErrorRecords":""}。如仍无法解决可联系 技术支持
4001220600general error information通用错误信息包含多条,详细的错误信息以及处理建议可参见错误信息

内容来源:飞书开放平台 · 自动爬取整理