钉钉开发文档

发起审批实例

更新时间: 2019-6-13

概述

根据是否指定审批人,分为2种模式:

  • 指定审批人模式:

(1)调用接口时,传入approvers或者approvers_v2参数,指定审批人。其中,approvers_v2支持或签和会签。

  • 复用审批后台设置的审批流程模式:

(1)调用接口时,不传入approvers或者approvers_v2参数,会自动复用在审批管理后台预设的审批人。流程设置页面见下图。
(2)可在流程设计里设置审批人的或签会签等操作。



接口调用

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/processinstance/create?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
agent_id Number 可选 41605932 企业应用标识(ISV调用必须设置)
process_code String 必须 PROC-EF6YJL35 审批流的唯一码,process_code就在审批流编辑的页面URL中
originator_user_id String 必须 manager432 审批实例发起人的userid
dept_id Number 必须 100 发起人所在的部门,如果发起人属于根部门,传-1
approvers String 可选 zhangsan, lisi 审批人userid列表,最大列表长度:20。多个审批人用逗号分隔,按传入的顺序依次审批
approvers_v2 ProcessInstanceApproverVo[] 可选 审批人列表,支持会签/或签,优先级高于approvers变量
└user_ids String[] 可选 zhangsan, lisi 审批人userid列表,会签/或签列表长度必须大于1,非会签/或签列表长度只能为1
└task_action_ty
       pe
String 可选 AND 审批类型,会签:AND;或签:OR;单人:NONE
cc_list String 可选 zhangsan, lisi 抄送人userid列表,最大列表长度:20。多个抄送人用逗号分隔
cc_position String 可选 START 抄送时间,分为(START, FINISH, START_FINISH)
form_component_values List 必须 审批流表单参数,最大列表长度:20。
└name String 必须 请假类型 表单每一栏的名称
└value String 必须 事假 表单每一栏的值
└ext_value String 可选 总天数:1 扩展值

SDK请求示例(JAVA)

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/processinstance/create");
OapiProcessinstanceCreateRequest request = new OapiProcessinstanceCreateRequest();
request.setAgentId(41605932L);
request.setProcessCode("PROC-BY6LI83V-4R8T1CHNUX58O0Z6C55M3-DTQJJGEJ-1");
// 审批流表单参数,设置各表单项值
List<OapiProcessinstanceCreateRequest.FormComponentValueVo> formComponentValues = new ArrayList<OapiProcessinstanceCreateRequest.FormComponentValueVo>();

// 单行输入框
OapiProcessinstanceCreateRequest.FormComponentValueVo vo1 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
vo1.setName("单行输入框示例");
vo1.setValue("单行输入框value");

// 多行输入框
OapiProcessinstanceCreateRequest.FormComponentValueVo vo2 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
vo2.setName("多行输入框示例");
vo2.setValue("多行输入框value");

// 图片
OapiProcessinstanceCreateRequest.FormComponentValueVo vo3 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
vo3.setName("图片示例");
vo3.setValue("[\"http://xxxxx\"]");

// 明细包含控件
// 明细-单行输入框
OapiProcessinstanceCreateRequest.FormComponentValueVo ItemName1 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
ItemName1.setName("明细-单行输入框示例");
ItemName1.setValue("明细-单行输入框value");
// 明细-多行输入框
OapiProcessinstanceCreateRequest.FormComponentValueVo ItemName2 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
ItemName2.setName("明细-多行输入框示例");
ItemName2.setValue("明细-多行输入框value");
// 明细-照片
OapiProcessinstanceCreateRequest.FormComponentValueVo ItemName3 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
ItemName3.setName("明细-图片示例");
ItemName3.setValue("[\"http://xxxxx\"]");

// 明细
OapiProcessinstanceCreateRequest.FormComponentValueVo vo4 = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
vo4.setName("明细示例");
vo4.setValue(JSON.toJSONString(Arrays.asList(Arrays.asList(ItemName1, ItemName2, ItemName3))));

// 附件
OapiProcessinstanceCreateRequest.FormComponentValueVo attachmentComponent = new OapiProcessinstanceCreateRequest.FormComponentValueVo();
JSONObject attachmentJson = new JSONObject();
attachmentJson.put("fileId", "6433971140");
attachmentJson.put("fileName", "2644.JPG");
attachmentJson.put("fileType", "jpg");
attachmentJson.put("spaceId", "1635477658");
attachmentJson.put("fileSize", "333");

JSONArray array = new JSONArray();
array.add(attachmentJson);
attachmentComponent.setValue(array.toJSONString());
attachmentComponent.setName("附件");

// 添加单行输入框、多行输入框、图片、明细、附件到表单
formComponentValues.add(vo1);
formComponentValues.add(vo2);
formComponentValues.add(vo3);
formComponentValues.add(vo4);
formComponentValues.add(attachmentComponent);

request.setFormComponentValues(formComponentValues);
request.setApprovers("userid1,userid2");
request.setOriginatorUserId("userid1");
request.setDeptId(-1L);
request.setCcList("userid1,userid2");
request.setCcPosition("START_FINISH");
OapiProcessinstanceCreateResponse response = client.execute(request,accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok",
    "process_instance_id":"12345"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
process_instance_id 审批实例id

表单参数详解

表单参数采用key/value的形式,其中key是每个控件对应的名字,value可以是普通字符串,也可以是json字符串。

输入框类型

value是普通字符串

图片类型

value是json数组,每个数组元素必须为图片的URL,举例如下:

["http://url1","http://url2","http://url3"]

明细类型

明细控件内部只能由输入框控件和图片控件组成,它的value格式如下:

[
    [
        {"name":"开始时间","value":"2018-09-01"},
        {"name":"结束时间","value":"2018-09-03"}
    ],
    [
       {"name":"开始时间","value":"2018-09-05"},
       {"name":"结束时间","value":"2018-09-07"}
    ]
]

金额/数字/计算公式类型

value是数字

单选框

value是字符串,必须是在审批模板设计时预设值的单选框的值

多选框

value是字符串数组,数组里的每个元素必须是模板里预设的值,格式如下:

{
      "name": "多选框",
      "value": "[\"a\",\"b\"]"
}

日期

value是字符串,根据日期类型来传值,分别为“yyyy-mm-dd hh:mm” 和“yyyy-mm-dd”

日期区间

name是一个数组,value也是对应数组,格式如下:

{
      "name": "[\"开始时间\",\"结束时间\"]",
      "value": "[\"2019-02-19\",\"2019-02-25\"]"
}

内部联系人

value为企业用户userid列表,格式如下:

{
      "name": "联系人",
      "value": "[\"userid1\",\"userid2\"]"
}

关联组件

value为审批实例id数组,格式如下:

{
      "name": "关联组件",
      "value": "[\"proc1\",\"proc2\"]"
}

附件

value是一个数组,可以传多个文件或图片,格式如下:

[
    {
        "spaceId":"1635477658",
        "fileName":"2644.JPG",
        "fileSize":"333",
        "fileType":"jpg",
        "fileId":"6433971140"
    }
]

开发者可通过以下步骤获取附件相关参数:
1、调用获取审批钉盘空间接口,获取spaceId
2、调用H5微应用JSAPI或者小程序JSAPI,上传文件到步骤一的spaceId对应的钉盘空间,获取fileId、fileName、fileSize及fileType参数

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!