提交审批申请

企业可通过审批应用或自建应用Secret调用本接口,代应用可见范围内员工在企业微信“审批应用”内提交指定类型的审批申请。

请求方式:POST(HTTPS
请求地址: https://qyapi.weixin.qq.com/cgi-bin/oa/applyevent?access_token=ACCESS_TOKEN

请求示例:

{
    "creator_userid": "WangXiaoMing",
    "template_id": "3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioeFXkaaa",
    "use_template_approver":0,
    "approver": [
        {
            "attr": 2,
            "userid": ["WuJunJie","WangXiaoMing"]
        },
        {
            "attr": 1,
            "userid": ["LiuXiaoGang"]
        }
    ],
    "notifyer":[ "WuJunJie","WangXiaoMing" ],
    "notify_type" : 1,
    "apply_data": {
         "contents": [
                {
                    "control": "Text",
                    "id": "Text-15111111111",
                    "value": {
                        "text": "文本填写的内容"
                    }
                }
            ]
    },
    "summary_list": [
        {
            "summary_info": [{
                "text": "摘要第1行",
                "lang": "zh_CN"
            }]
        },
        {
            "summary_info": [{
                "text": "摘要第2行",
                "lang": "zh_CN"
            }]
        },
        {
            "summary_info": [{
                "text": "摘要第3行",
                "lang": "zh_CN"
            }]
        }
    ]
}

参数说明:

参数 必须 说明
access_token 调用接口凭证。必须使用审批应用或企业内自建应用的secret获取,获取方式参考:文档-获取access_token
creator_userid 申请人userid,此审批申请将以此员工身份提交,申请人需在应用可见范围内
template_id 模板id。可在“获取审批申请详情”、“审批状态变化回调通知”中获得,也可在审批模板的模板编辑页面链接中获得。暂不支持通过接口提交[打卡补卡][调班]模板审批单。
use_template_approver 审批人模式:0-通过接口指定审批人、抄送人(此时approver、notifyer等参数可用); 1-使用此模板在管理后台设置的审批流程,支持条件审批。默认为0
approver 审批流程信息,用于指定审批申请的审批流程,支持单人审批、多人会签、多人或签,可能有多个审批节点,仅use_template_approver为0时生效。
└ userid 审批节点审批人userid列表,若为多人会签、多人或签,需填写每个人的userid
└ attr 节点审批方式:1-或签;2-会签,仅在节点为多人审批时有效
notifyer 抄送人节点userid列表,仅use_template_approver为0时生效。
notify_type 抄送方式:1-提单时抄送(默认值); 2-单据通过后抄送;3-提单和单据通过后抄送。仅use_template_approver为0时生效。
apply_data 审批申请数据,可定义审批申请中各个控件的值,其中必填项必须有值,选填项可为空,数据结构同“获取审批申请详情”接口返回值中同名参数“apply_data”
└ contents 审批申请详情,由多个表单控件及其内容组成,其中包含需要对控件赋值的信息
└ └ control 控件类型:Text-文本;Textarea-多行文本;Number-数字;Money-金额;Date-日期/日期+时间;Selector-单选/多选;;Contact-成员/部门;Tips-说明文字;File-附件;Table-明细;
└ └ id 控件id:控件的唯一id,可通过“获取审批模板详情”接口获取
└ └ value 控件值 ,需在此为申请人在各个控件中填写内容不同控件有不同的赋值参数,具体说明详见附录。模板配置的控件属性为必填时,对应value值需要有值。
summary_list 摘要信息,用于显示在审批通知卡片、审批列表的摘要信息,最多3行
└ summary_info 摘要行信息,用于定义某一行摘要显示的内容
└ └ text 摘要行显示文字,用于记录列表和消息通知的显示,不要超过20个字符
└ └ lang 摘要行显示语言

接口频率限制 600次/分钟
当模板的控件为必填属性时,表单中对应的控件必须有值。


返回结果:

{
   "errcode": 0,
   "errmsg": "ok",
   "sp_no": "202001010001"
}

参数说明:

参数 说明
errcode 错误码,详情见错误码说明
errmsg 错误码对应的错误信息提示
sp_no 表单提交成功后,返回的表单编号

错误码说明

错误码 说明
301055 无审批应用权限,或者提单者不在审批应用/自建应用的可见范围
301056 审批应用已停用
301025 提交审批单请求参数错误
301057 通用错误码,提交审批单内部接口失败

附录:各控件apply_data/contents/value参数介绍

附1 文本/多行文本控件(control参数为Text或Textarea)

{
    "text": "文本填写的内容"
}
参数 说明
text 文本内容,在此填写文本/多行文本控件的输入值

附2 数字控件(control参数为Number)

{
    "new_number": "700"
}
参数 说明
new_number 数字内容,在此填写数字控件的输入值

附3 金额控件(control参数为Money)

{
    "new_money": "700"
}
参数 说明
new_money 金额内容,在此填写金额控件的输入值

附4 日期/日期+时间控件(control参数为Date)

{
    "date": {
        "type": "day",
        "s_timestamp": "1569859200"
    }
}
参数 说明
date 日期/日期+时间内容
└ type 时间展示类型:day-日期;hour-日期+时间 ,和对应模板控件属性一致
└ s_timestamp 时间戳-字符串类型,在此填写日期/日期+时间控件的选择值,以此为准

附5 单选/多选控件(control参数为Selector)

{
    "selector": {
        "type": "multi",
        "options": [
            {
                "key": "option-15111111111",
            },
            {
                "key": "option-15222222222",
            }
        ]
    }
}
参数 说明
selector 选择控件内容,即申请人在此控件选择的选项内容
└ type 选择方式:single-单选;multi-多选
└ options 多选选项,多选属性的选择控件允许输入多个
└ └ key 选项key,可通过“获取审批模板详情”接口获得

附6 成员控件(control参数为Contact,且value参数为members)

{
    "members": [
        {
            "userid": "WuJunJie",
            "name": "Jackie"
        },
        {
            "userid": "WangXiaoMing"
            "name": "Tom"
        }
    ]
}
参数 说明
members 所选成员内容,即申请人在此控件选择的成员,多选模式下可以有多个
└ userid 所选成员的userid
└ name 成员名

附7 部门控件(control参数为Contact,且value参数为departments)

{
    "departments": [
        {
            "openapi_id": "2",
            "name": "销售部",
        },
        {
            "openapi_id": "3",
            "name": "生产部",
        }
    ]
}
参数 说明
departments 所选部门内容,即申请人在此控件选择的部门,多选模式下可能有多个
└ openapi_id 所选部门id
└ name 所选部门名

附8 说明文字控件(control参数为Tips)
此控件不显示在审批详情中,故value为空

附9 附件控件(control参数为File,且value参数为files)

{
    "files": [
        {
            "file_id": "1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K1aaa"
        }
    ]
}
参数 说明
files 附件列表
└ file_id 文件id,该id为临时素材上传接口返回的的media_id,注:提单后将作为单据内容转换为长期文件存储;目前一个审批申请单,全局仅支持上传6个附件,否则将失败。

附10 明细控件(control参数为Table)

{
    "children": [
        {
            "list": [
                {
                    "control": "Text",
                    "id": "Text-15111111111",
                    "title": [
                        {
                            "text": "明细内文本控件",
                            "lang": "zh_CN"
                        }
                    ],
                    "value": {
                        "text": "明细文本"
                    }
                }
            ]
        }
    ]
}
参数 说明
children 明细内容,一个明细控件可能包含多个子明细
└ list 子明细列表,在此填写子明细的所有子控件的值,子控件的数据结构同一般控件

附11 假勤组件-请假组件(control参数为Vacation)

{
    "vacation": {
        "selector": {
            "type": "single",
            "options": [
                {
                    "key": "3",
                    "value": [
                        {
                            "text": "病假",
                            "lang": "zh_CN"
                        }
                    ]
                }
            ],
            "exp_type": 0
        },
        "attendance": {
            "date_range": {
                "type": "hour",
                "new_begin": 1568077200,
                "new_end": 1568368800,
                "new_duration": 291600
            },
            "type": 1
        }
    }
}
参数 说明
vacation 请假内容,即申请人在此组件内选择的请假信息
└ selector 请假类型,所选选项与假期管理关联,为假期管理中的假期类型
└ └ type 选择方式:single-单选;multi-多选,在假勤控件中固定为单选
└ └ options 用户所选选项
└ └ └ key 选项key,选项的唯一id,可通过“获取审批模板详情”接口获得vacation_list中item的id值
└ └ └ value 选项值,若配置了多语言则会包含中英文的选项值
└ attendance 假勤组件
└ └ date_range 假勤组件时间选择范围
└ └ └ type 时间展示类型:day-日期;hour-日期+时间
└ └ └ new_begin 开始时间戳
└ └ └ new_end 结束时间戳
└ └ └ new_duration 请假时长,单位秒
└ └ type 假勤组件类型:1-请假;3-出差;4-外出;5-加班

附12 假勤组件-出差/外出/加班组件(control参数为Attendance)

{
    "attendance": {
        "date_range": {
            "type": "halfday",
            "new_begin": 1570550400,
            "new_end": 1570593600,
            "new_duration": 86400
        },
        "type": 4
    }
}
参数 说明
attendance 假勤内容,即申请人在此组件内选择的假勤信息
└ date_range 假勤组件时间选择范围
└ └ type 时间展示类型:day-日期;hour-日期+时间
└ └ new_begin 开始时间戳,
└ └ new_end 结束时间戳
└ └ new_duration 请假时长,单位秒
└ type 假勤组件类型:1-请假;3-出差;4-外出;5-加班

错误说明

错误码 说明
301055 无审批应用权限,或者提单者不在审批应用/自建应用的可见范围
301056 审批应用已停用
301025 提交审批单请求参数错误
301057 通用错误码,提交审批单内部接口失败
© 1998 - 2020 Tencent Inc. All Rights Reserved