目录
服务商可通过第三方应用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,
"choose_department":2,
"process": {
"node_list": [
{
"type": 1,
"apv_rel": 1,
"userid": [
"abc",
"bcd"
]
},
{
"type": 1,
"apv_rel": 1,
"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 | 表单提交成功后,返回的表单编号 |
{
"text": "文本填写的内容"
}
参数 | 说明 |
---|---|
text | 文本内容,在此填写文本/多行文本控件的输入值。文本控件Text内容不支持包含换行符。 |
{
"new_number": "700"
}
参数 | 说明 |
---|---|
new_number | 数字内容,在此填写数字控件的输入值 |
{
"new_money": "700"
}
参数 | 说明 |
---|---|
new_money | 金额内容,在此填写金额控件的输入值 |
{
"date": {
"type": "day",
"s_timestamp": "1569859200"
}
}
参数 | 说明 |
---|---|
date | 日期/日期+时间内容 |
└ type | 时间展示类型:day-日期;hour-日期+时间 ,和对应模板控件属性一致 |
└ s_timestamp | 时间戳-字符串类型,在此填写日期/日期+时间控件的选择值,以此为准 |
{
"selector": {
"type": "multi",
"options": [
{
"key": "option-15111111111"
},
{
"key": "option-15222222222"
}
]
}
}
参数 | 说明 |
---|---|
selector | 选择控件内容,即申请人在此控件选择的选项内容 |
└ type | 选择方式:single-单选;multi-多选 |
└ options | 多选选项,多选属性的选择控件允许输入多个 |
└ └ key | 选项key,可通过“获取审批模板详情”接口获得 |
{
"members": [
{
"userid": "WuJunJie",
"name": "Jackie"
},
{
"userid": "WangXiaoMing",
"name": "Tom"
}
]
}
参数 | 说明 |
---|---|
members | 所选成员内容,即申请人在此控件选择的成员,多选模式下可以有多个 |
└ userid | 所选成员的userid |
└ name | 成员名 |
{
"departments": [
{
"openapi_id": "2",
"name": "销售部"
},
{
"openapi_id": "3",
"name": "生产部"
}
]
}
参数 | 说明 |
---|---|
departments | 所选部门内容,即申请人在此控件选择的部门,多选模式下可能有多个 |
└ openapi_id | 所选部门id |
└ name | 所选部门名 |
后台自动填充,无需赋值。
{
"files": [
{
"file_id": "1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K1aaa"
}
]
}
参数 | 说明 |
---|---|
files | 附件列表 |
└ file_id | 文件id,该id为临时素材上传接口返回的的media_id,注:提单后将作为单据内容转换为长期文件存储;目前一个审批申请单,全局仅支持上传6个附件,否则将失败。 |
{
"children": [
{
"list": [
{
"control": "Text",
"id": "Text-15111111111",
"title": [
{
"text": "明细内文本控件",
"lang": "zh_CN"
}
],
"value": {
"text": "明细文本"
}
}
]
}
]
}
参数 | 说明 |
---|---|
children | 明细内容,一个明细控件可能包含多个子明细 |
└ list | 子明细列表,在此填写子明细的所有子控件的值,子控件的数据结构同一般控件 |
{
"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 | 假勤组件,参考附12中的attenance |
{
"attendance": {
"date_range": {
"type": "halfday",
"new_begin": 1570550400,
"new_end": 1570593600,
"new_duration": 86400
},
"type": 4,
"slice_info": {
"day_items": [
{
"daytime": 1713801600,
"duration": 84400
},
{
"daytime": 1713888000,
"duration": 86400
}
]
}
}
}
参数 | 说明 |
---|---|
attendance | 假勤内容,即申请人在此组件内选择的假勤信息 |
└ date_range | 假勤组件时间选择范围 |
└ └ type | 时间展示类型:halfday-日期;hour-日期+时间 |
└ └ new_begin | 开始时间戳, |
└ └ new_end | 结束时间戳 |
└ └ new_duration | 请假时长,单位秒 当slice_info有值时,无需填写,系统会根据slice_info 计算总时长 |
└ type | 假勤组件类型:1-请假;3-出差;4-外出;5-加班 |
└ slice_info | 非必填。时长分片信息 |
└ └ day_items | 某一天的分片 |
└ └ └ daytime | 当天零点时间戳 (当天的东八区的零点时间戳) |
└ └ └ duration | 某一天的时长,秒数,可以为0,(type为halfday时:加班:需为8640整倍数,其他:需为43200的整倍数,type为hour时需为360的整倍数) |
注意:加班的时间跨度不能超过七天
错误码 | 说明 |
---|---|
301055 | 无审批应用权限,或者提单者不在审批应用/自建应用的可见范围 |
301056 | 审批应用已停用 |
301025 | 提交审批单请求参数错误 |
301057 | 通用错误码,提交审批单内部接口失败 |
$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时,如果用户有别名,则替换为别名;否则,将替换为姓名