提交审批申请 - 接口文档 - 企业微信开发者中心

{
    "creator_userid": "WangXiaoMing",
    "template_id": "3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioeFXkaaa",
    "use_template_approver":0,
    "choose_department":2,
    "process": {
        "node_list": [
            {
                "type": 1, //1:审批人 2:抄送人 3:办理人
                "apv_rel": 1, //1-会签；2-或签 3-依次审批
                "userid": [
                    "abc",
                    "bcd",
                ],
            },
            {
                "type": 1, //1:审批人 2:抄送人 3:办理人
                "apv_rel": 1, //1-会签；2-或签 3-依次审批
                "userid": [
                    "abc",
                ],
            },

        ],
    },
    "apply_data": {
         "contents": [
                {
                    "control": "Text",
                    "id": "Text-15111111111",
                    "title": [
                        {
                            "text": "文本控件",
                            "lang": "zh_CN"
                        }
                    ],
                    "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	是	调用接口凭证。必须使用第三方应用accesstoken获取，获取方式参考：文档-获取access_token
creator_userid	是	申请人userid，此审批申请将以此员工身份提交，申请人需在应用可见范围内
template_id	是	模板的唯一标识id。可在“获取审批单据详情”、“审批状态变化回调通知”中获得，也可在使用“复制/更新模板到企业”接口回调中获得。注：此id为企业内模板的实例id，非服务商后台对应模板的id。暂不支持通过接口提交[打卡补卡][调班]模板审批单。
use_template_approver	是	审批人模式：0-通过接口指定审批人、抄送人（此时process参数必填）; 1-使用此模板在管理后台设置的审批流程(需要保证审批流程中没有“申请人自选”节点)，支持条件审批。默认为0
choose_department	否	提单者提单部门id，不填默认为主部门
apply_data	是	审批申请数据，可定义审批申请中各个控件的值，其中必填项必须有值，选填项可为空，数据结构同“获取审批申请详情”接口返回值中同名参数“apply_data”
└ contents	是	审批申请详情，由多个表单控件及其内容组成，其中包含需要对控件赋值的信息
└ └ control	是	控件类型：Text-文本；Textarea-多行文本；Number-数字；Money-金额；Date-日期/日期+时间；Selector-单选/多选；；Contact-成员/部门；Tips-说明文字；File-附件；Table-明细；
└ └ id	是	控件id：控件的唯一id，可通过“获取审批模板详情”接口获取
└ └ value	是	控件值，需在此为申请人在各个控件中填写内容不同控件有不同的赋值参数，具体说明详见附录。模板配置的控件属性为必填时，对应value值需要有值。当control是Text-文本和Textarea-多行文本时，该字段支持ID转译，审批引擎自动将符合条件的id转成用户名、用户别名或者部门名，转换规则请参考本文档附录中ID转译模板语法。
summary_list	是	摘要信息，用于显示在审批通知卡片、审批列表的摘要信息，最多3行
└ summary_info	是	摘要行信息，用于定义某一行摘要显示的内容
└ └ text	是	摘要行显示文字，用于记录列表和消息通知的显示，不要超过20个字符。该字段支持ID转译，审批引擎自动将符合条件的id转成用户名，用户别名或者部门名，转换规则请参考本文档附录中ID转译模板语法。
└ └ lang	是	摘要行显示语言，中文：zh_CN（注意不是zh-CN），英文：en。
process	use_template_approver = 0 时必填	新版流程列表
└ node_list	是	流程节点
└ └ type	是	节点类型 1:审批人 2:抄送人 3:办理人
└ └ apv_rel	type为1、2时必填	多人审批方式 1-会签；2-或签 3-依次审批
└ └ userid	是	用户id

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

权限说明

应用类型	权限要求
自建应用	配置到「审批 - 可调用接口的应用」中
代开发应用	具有「审批」权限
第三方应用	具有「审批」权限

注：从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响查看详情

返回结果：

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

参数说明：

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

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

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

{
    "text": "文本填写的内容"
}

参数	说明
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）

后台自动填充，无需赋值。

附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	时间展示类型：halfday-日期；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	时间展示类型：halfday-日期；hour-日期+时间
└ └ new_begin	开始时间戳，
└ └ new_end	结束时间戳
└ └ new_duration	请假时长，单位秒
└ type	假勤组件类型：1-请假；3-出差；4-外出；5-加班

错误说明

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

ID转译模版语法

$departmentName=DEPARTMENT_ID$
$userName=USERID$
$userAlias=USERID$
$userAliasOrName=USERID$

其中 DEPARTMENT_ID 是数字类型的部门id，USERID 是成员账号。
譬如，
将 $departmentName=1$ 替换成部门id为1对应的部门名，如“企业微信部”；
将 $userName=lisi007$ 替换成userid为lisi007对应的用户姓名，如“李四”；
将 $userAlias=lisi007$ 替换成userid为lisi007对应的用户别名，如“lisi”；
将 $userAliasOrName=lisi007$ 替换成userid为lisi007对应的用户别名或姓名，别名优先级高于姓名，如"lisi"；

若输入的模板不符合语法、不在权限范围内或无效的userid或者部门ID，则不替换该项内容，保留原样
转译userAlias时，如果用户没有别名，则不替换该项内容，保留原样
转译userAliasOrName时，如果用户有别名，则替换为别名；否则，将替换为姓名

获取审批模板详情

审批申请状态变化回调通知

本节内容

附录：各控件apply_data/contents/value参数介绍
附1 文本/多行文本控件（control参数为Text或Textarea）
附2 数字控件（control参数为Number）
附3 金额控件（control参数为Money）
附4 日期/日期+时间控件（control参数为Date）
附5 单选/多选控件（control参数为Selector）
附6 成员控件（control参数为Contact，且value参数为members）
附7 部门控件（control参数为Contact，且value参数为departments）
附8 说明文字控件（control参数为Tips）
附9 附件控件（control参数为File，且value参数为files）
附10 明细控件（control参数为Table）
附11 假勤组件-请假组件（control参数为Vacation）
附12 假勤组件-出差/外出/加班组件（control参数为Attendance）
错误说明
ID转译模版语法