标准版/尊享版专享

前言

开放接口的主要使用场景包括如下：

定时将数据拉回到自建系统中进行精加工或归档。
将表单提交、流程发起操作的入口集成到现有平台上。

如果你有类似上述需求的使用场景，可以考虑使用宜搭的开放接口能力。

一、准备工作

特别说明

网关接口的使用，需要秘钥ak和sk的信息，请先提交申请提交申请，审批通过后向宜搭的技术支持同学获取对应的秘钥信息。

1.1 Java调用方式

1.1.1 引入依赖

<dependency>
    <groupId>com.alibaba.platform.shared</groupId>
    <artifactId>xxpt.gateway.shared.client</artifactId>
    <version>1.1.0</version>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.2</version>
</dependency>
<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.9.4</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.4</version>
</dependency>

xxpt.gateway.shared.client.zip

说明：
上述需要引入的maven配置是网关调用的依赖项，如果和您本地的jar包版本冲突，请进行排包处理

1.1.2 参数配置

例自定义配置文件：aecpgateway.properties
xxpt.gateway.protocal=https
xxpt.gateway.domainName=s-api.alibaba-inc.com
xxpt.gateway.accessKey=自己的accessKey
xxpt.gateway.secretKey=自己的secretKey

通过xml定义bean

<?xml version="1.0" encoding="UTF-8" ?><beans xmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:context="http://www.springframework.org/schema/context"xmlns:tx="http://www.springframework.org/schema/tx"xmlns:util="http://www.springframework.org/schema/util"xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsdhttp://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsdhttp://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsdhttp://www.springframework.org/schema/util http://localhost:8080/schema/www.springframework.org/schema/util/spring-util-2.0.xsd "default-autowire="byName">
<bean id="propertyConfigurer" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
  <property name="locations">
    <list>
      <value>classpath:aecpgateway.properties</value>
    </list>
  </property> 
</bean>
<bean id="executableClient" class="com.alibaba.xxpt.gateway.shared.client.http.ExecutableClient" factory-method="getInstance" init-method="init" destroy-method="destroy">
  <property name="protocal" value="${xxpt.gateway.protocal}"/>
  <property name="domainName" value="${xxpt.gateway.domainName}"/>
  <property name="accessKey" value="${xxpt.gateway.accessKey}"/>
  <property name="secretKey" value="${xxpt.gateway.secretKey}"/>
</bean>
</beans>

出于安全性考虑，上文中的${accessKey}和${secretKey}请联系宜搭开发人员获取。

说明：

上述需要配置的xml需要自行通过spring进行加载，文件名没有要求，sdk中不会自动加载
配置bean后，通过ExecutableClient.getInstance()获取的对象是单例，请知晓
如果项目框架不是spring，可以自行通过new ExecutableClient()的方式创建对象，对象有设置上述属性的set方法，属性设置完成后，请务必调用该对象的init方法初始化对象内部的其他属性

1.1.3 调用示例

简单的单元测试：

@Test
public void postYidaOutTest() {
    String api = "/yida_vpc/form/searchFormDatas.json";
    PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
    postClient.addParameter("appType", "APP_XXX");
    postClient.addParameter("systemToken", "XXX");
    postClient.addParameter("formUuid", "XXX");
    postClient.addParameter("userId", "yida_pub_account");
    String apiResult = postClient.post();
    Assert.notNull(apiResult);
}

工程中实际使用：

import com.alibaba.fastjson.JSON;
import com.alibaba.xxpt.gateway.shared.client.http.ExecutableClient;
import com.alibaba.xxpt.gateway.shared.client.http.PostClient;
import org.springframework.util.CollectionUtils;
import java.util.HashMap;
import java.util.Map;
/*
* aecp网关服务请求工具
* @Author: weimeng(shanyu)
* @Date: 2019/2/28 下午2:50
*/
public class AecpGatewayRequestUtil {
 /**    
* 请求aecp网关    
* @param param 请求参数    
* @param url 网关地址, 在aecp网关服务（https://epaas.alibaba-inc.com）查看    
* @return 请求结果    
*/    
public static AecpGatewayResult baseRequest(Map<String, String> param, String url) {
        try {
            PostClient postClient = ExecutableClient.getInstance().newPostClient(url);
            if (!CollectionUtils.isEmpty(param)) {
                for (Map.Entry<String, String> entry : param.entrySet()) {
                    postClient.addParameter(entry.getKey(), entry.getValue());
                }
            }
            String result = postClient.post();
            return JSON.parseObject(result, AecpGatewayResult.class);
        }catch(Throwable e){
            AecpGatewayResult result= new AecpGatewayResult();
            result.setSuccess(false);
            result.setResult("false");
            return result;
        }
    }
}

/**
* aecp网关服务请求的返回结果类
* @Author: weimeng(shanyu)
* @Date: 2019/2/28 下午2:52
*/
public class AecpGatewayResult {
    private boolean success;
    private String result;
    private String errorCode;
    private String errorMsg;
    public boolean isSuccess() {
        return success;
    }
    public void setSuccess(boolean success) {
        this.success = success;
    }
    public String getResult() {
        return result;
    }
    public void setResult(String result) {
        this.result = result;
    }
    public String getErrorCode() {
        return errorCode;
    }
    public void setErrorCode(String errorCode) {
        this.errorCode = errorCode;
    }
    public String getErrorMsg() {
        return errorMsg;
    }
    public void setErrorMsg(String errorMsg) {
        this.errorMsg = errorMsg;
    }
    @Override    
    public String toString() {
        return "AecpGatewayResult{" +
                "success=" + success +
                ", result='" + result + '\'' +
                ", errorCode='" + errorCode + '\'' +
                ", errorMsg='" + errorMsg + '\'' +
                '}';
    }
}

/**    
* 获取授权用户账号列表    
*/    
public static final String GET_USER_LIST = "/yida_vpc/corp/getAliyunAuthInfo.json";
try {
    Map<String, String> param = new HashMap<String, String>();
    param.put(AecpHsfConstants.CURRENT_PAGE, request.getCurrentPage()+"");
    param.put(AecpHsfConstants.PAGE_SIZE, request.getPageSize()+"");
    param.put(AecpHsfConstants.ACCOUNT_NAME, request.getAccountName());
    // 调用注册在aecp网关服务上的宜搭接口    
    AecpGatewayResult result = AecpGatewayRequestUtil.baseRequest(param, GET_USER_LIST);
    // 请求成功    
    if(result.isSuccess()){
     // 解析数据，用户列表        
    response = JSON.parseObject(result.getResult(), ConsoleUserListResponse.class);
        if(response.getEmployee() != null && response.getEmployee().getTotalCount() != null){
            response.setTotal(response.getEmployee().getTotalCount().longValue());
        }
        return response;
    }
} catch (Exception e) {
    // TODO
}

二、表单接口

1. 新增表单实例

接口：/yida_vpc/form/saveFormData.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formUuid | 表单ID | 是 | FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB | | | appType | 应用ID | 是 | APP_DR4OK27ZKL5N22B907E8 | | | formDataJson | 表单数据 | 是 | {“textField_jcpm6agt”: “单行”,”employeeField_jcos0sar”: [“workno”]} | 参考：附录1保存/更新表单数据格式说明 |

返回值：
- success: 请求是否成功
- result：实例ID
- errorMsg: 错误信息
- errorCode：错误码
返回值demo：{“result”:”FINST-EF6Y93URN2UZ1SBPLIP9NAV6HR2GEO1Z4ZCHSCJ0”,”success”:true}

2. 更新表单中指定组件值

接口：/yida_vpc/form/updateFormData.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | helxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formInstId | 要更新的表单数据ID | 是 | FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9 | | | updateFormDataJson | 要更新的表单组件值，必填 | 是 | {“employeeField_jcpm5gy2”: [“workno”]} | 参考：附录1保存/更新表单数据格式说明。参数有的组件更新，没有的组件保持不变。明细的值只能统一更新，无法只更新明细下某个组件的值 |

返回值：
- success: 请求是否成功
- errorMsg: 错误信息
- errorCode：错误码
返回值demo：{“success”:true}

3. 删除表单实例

接口：/yida_vpc/form/deleteFormData.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | helxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formInstId | 要删除的表单数据ID | 是 | FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9 | |

返回值：
- success: 请求是否成功
- errorMsg: 错误信息
- errorCode：错误码
返回值demo：{“success”:true}

4. 根据表单ID查询实例详情

接口：/yida_vpc/form/getFormDataById.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | helxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formInstId | 要查询的实例的实例ID | 是 | FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9 | |

返回值
- success:请求是否成功
- errorMsg: 错误信息
- errorCode：错误码
- result：单据实例详情。参见附录5. 单据实例详情对象格式说明

5. 根据条件搜索表单实例ID列表

接口：/yida_vpc/form/searchFormDataIds.json
说明：只有应用管理员才能使用这个接口
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formUuid | 表单ID | 是 | FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3 | | | searchFieldJson | 根据表单内组件值查询 | 否 | | 格式见附录2：根据组件值进行条件搜索，组件值格式说明 | | currentPage | 当前页 | 否 | 1 | 必须大于0
默认1 | | pageSize | 每页记录数 | 否 | 10 | 必须大于0
默认10
不能大于100 | | originatorId | 根据数据提交人工号查询 | 否 | | | | createFrom | createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表 | 否 | 2018-01-01 | 字符串格式，且为yyyy-MM-DD格式 | | createTo | createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。 | 否 | 2018-02-01 | 字符串格式，且为yyyy-MM-DD格式。
和createFrom一起，相当于查询在
2018-01-01到2018-01-31之间(包含01和31号)创建的数据。 | | modifiedFrom | modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表 | 否 | 2018-01-01 | 字符串格式，且为yyyy-MM-DD格式 | | modifiedTo | modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表。 | 否 | 2018-02-01 | 字符串格式，且为yyyy-MM-DD格式。和modifiedFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。 |

返回值
- success : 请求是否成功;
- errorCode : 错误码;
- errorMsg : 错误信息;
- result :
  - currentPage : 当前页
  - totalCount : 符合条件的实例总数
  - data : 实例ID列表
返回值demo：{“result”:{“data”:[“FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0”],”totalCount”:1,”currentPage”:1},”success”:true}

6. 根据条件搜索表单实例详情列表

接口：/yida_vpc/form/searchFormDatas.json
说明：只有应用管理员才能使用这个接口
参数
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hellxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formUuid | 表单ID | 是 | FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3 | | | searchFieldJson | 根据表单内组件值查询 | 否 | | 格式见附录2：根据组件值进行条件搜索，组件值格式说明 | | currentPage | 当前页 | 否 | 1 | 必须大于0，默认1 | | pageSize | 每页记录数 | 否 | 10 | 必须大于0
默认10
不能大于100 | | originatorId | 根据数据提交人工号查询 | 否 | | | | createFrom | createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表 | 否 | 2018-01-01 | 字符串格式，且为yyyy-MM-DD格式
（或者精确到秒
yyyy-MM-DD HH:mm:ss） | | createTo | createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。 | 否 | 2018-02-01 | 字符串格式，且为yyyy-MM-DD格式（或者精确到秒
yyyy-MM-DD HH:mm:ss）
和createFrom一起，相当于查询在
2018-01-01到2018-01-31之间(包含01和31号)创建的数据。 | | modifiedFrom | modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表 | 否 | 2018-01-01 | 字符串格式，且为yyyy-MM-DD格式（或者精确到秒
yyyy-MM-DD HH:mm:ss） | | modifiedTo | modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表。 | 否 | 2018-02-01 | 字符串格式，且为yyyy-MM-DD格式。（或者精确到秒
yyyy-MM-DD HH:mm:ss）和modifiedFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。 | | dynamicOrder | 指定排序字段 | 否 | {“numberField_1ac”:”+”} | 表示按照字段numberField_1ac升序排列 |

返回值
- success : 请求是否成功;
- errorCode : 错误码;
- errorMsg : 错误信息;
- result :
  - currentPage : 当前页
  - totalCount : 符合条件的实例总数
  - data : 实例详情列表。每个实例详情格式参见附录4 作为返回值的表单数据的格式说明

7. 获取表单定义

接口：/yida_vpc/formDesign/getFormComponentDefinationList.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formUuid | 表单ID | 是 | FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB | | | version | 表单版本 | 否 | 1 | 可以传入formData中的version字段。
为空时返回最新的版本定义 |

返回值：
- success: 请求是否成功
- result：[]
- errorMsg: 错误信息
- errorCode：错误码

返回格式

{
  "success":true,
  "content":[
      {
          "label":"{"en_US":"CheckBox Field","zh_CN":"多选","type":"i18n"}",
          "key":"checkboxField_jiwvhkdi"
      },
      {
          "label":"{"en_US":"Textarea Field","zh_CN":"多行输入框","type":"i18n"}",
          "key":"textareaField_jiwvhkdh"
      },
      {
          "label":"{"en_US":"Select Field","zh_CN":"下拉单选","type":"i18n"}",
          "key":"selectField_jiwvhkdg"
      }
  ]
}

三、流程接口

1. 发起新的流程实例

接口: /yida_vpc/process/startInstance.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processCode	流程code	是	TPROC—EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4	单独发起页链接上可查
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3	单独发起页链接上可查
formDataJson	表单数据	是		参考：附录1保存/更新表单数据格式说明
deptId	发起人所在部门号	否	18295	不填，默认发起人主职部门

返回值：
- result : 实例ID;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
返回值demo： {“result”:”f30233fb-72e1-4af4-8cb8-c7e0ea9ee530”,”success”:true}

2. 根据条件搜索流程实例ID

接口：/yida_vpc/process/getInstanceIds.json
说明：只有应用管理员才能使用这个接口
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录2：根据组件值进行条件搜索，组件值格式说明
taskId	任务ID	否	2199132092	一般用不到。
instanceStatus	实例状态	否	RUNNING	可选值为：RUNNING,TERMINATED,COMPLETED,ERROR。分别代表：运行中，已终止，已完成，异常。
approvedResult	流程审批结果	否	agree	可选值为：agree, disagree。分别表示：同意，拒绝。
currentPage	当前页	否	1	必须大于0 默认1
pageSize	每页记录数	否	10	必须大于0 默认10 不能大于100
originatorId	根据流程发起人工号查询	否
createFrom	createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表	否	2018-01-01	字符串格式，且为yyyy-MM-DD格式 yyyy-MM-DD
createTo	createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。	否	2018-02-01	字符串格式，且为yyyy-MM-DD格式。和createFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)创建的数据。
modifiedFrom	modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表	否	2018-01-01	字符串格式，且为yyyy-MM-DD格式
modifiedTo	modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表。	否	2018-02-01	字符串格式，且为yyyy-MM-DD格式。和modifiedFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。

返回
- result : 实例ID列表;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
返回值 demo： {“result”:{“data”:[“f30233fb-72e1-4af4-8cb8-c7e0ea9ee530”,”bc0950a3-fe1b-459c-b6ba-282be38523ab”,”f540cbd7-43eb-40de-b915-6716578a2802”],”totalCount”:3,”currentPage”:1},”success”:true}

3. 根据搜索条件获取实例详情

接口： /yida_vpc/process/getInstances.json
说明：只有应用管理员才能使用这个接口
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	helxxxy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录2：根据组件值进行条件搜索，组件值格式说明
taskId	任务ID	否	2199132092	一般用不到。
instanceStatus	实例状态	否	RUNNING	可选值为：RUNNING,TERMINATED,COMPLETED,ERROR。分别代表：运行中，已终止，已完成，异常。
approvedResult	流程审批结果	否	agree	可选值为：agree, disagree。分别表示：同意，拒绝。
currentPage	当前页	否	1	必须大于0 默认1
pageSize	每页记录数	否	10	必须大于0 默认10 不能大于100
originatorId	根据流程发起人工号查询	否
createFrom	createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表	否	2018-01-01	字符串格式，且为yyyy-MM-DD格式
createTo	createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。	否	2018-02-01	字符串格式，且为yyyy-MM-DD格式。和createFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)创建的数据。
modifiedFrom	modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表	否	2018-01-01	字符串格式，且为yyyy-MM-DD格式
modifiedTo	modifiedFrom和modifiedTo构成一个时间段，查询在该时间段有修改的数据列表。	否	2018-02-01	字符串格式，且为yyyy-MM-DD格式。和modifiedFrom一起，相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。

返回值
- errorCode : 错误码;
- success : 请求是否成功;
- errorMsg : 错误信息;
- result :
  - currentPage : 当前页
  - totalCount : 符合条件的实例总数
  - data : 实例详情列表，实例详情格式参见附录3-流程实例详情对象格式说明

4. 根据实例ID获取流程实例详情

接口：/yida_vpc/process/getInstanceById.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

返回值
- result : 实例详情，参见附录3-流程实例详情对象格式说明
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

5. 根据实例ID列表批量获取流程实例详情

接口：/yida_vpc/process/getInstancesByIds.json
参数
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxyy | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | processInstanceIds | 流程实例ID列表，多个用,分割 | 是 | f30233fb-72e1-4af4-8cb8-c7e0ea9ee530,d230233fb-72e1-4af4-8cb8-c7e0ea9ee530 | |

返回值
- result : 实例详情列表，参见附录3-流程实例详情对象格式说明
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

6. 更新流程实例

接口: /yida_vpc/process/updateInstance.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hello1234	在应用数据中获取。
userId	钉钉的userId	是		会校验userId是否有流程发起权限
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processInstanceId	实例ID	是
updateFormDataJson	更新的表单数据	是		参考：附录1保存/更新表单数据格式说明

返回值：
- success : 是否成功
- errorMsg : 错误信息;
- errorCode : 错误码;
返回值demo： {“success”:true}

7. 删除流程实例

接口：/yida_vpc/process/deleteInstance.json
说明：只有应用管理员才能使用这个接口
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

返回值
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

8. 终止流程实例

接口：/yida_vpc/process/terminateInstance.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

返回值
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

9. 执行审批任务

接口：/yida_vpc/task/executeTask.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
taskId	任务ID	是	12002575
procInstId	实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530
outResult	审批结果	是	AGREE	AGREE(同意)、DISAGREE(不同意)
remark	审批意见	是	确认同意
formDataJson	更新的表单值	否		参考：附录1保存/更新表单数据格式说明。参数有的组件更新，没有的组件保持不变。明细的值只能统一更新，无法只更新明细下某个组件的值
noExecuteExpressions	是否不执行校验&关联操作	否	y	本任务节点有绑定校验规则或者关联操作时， y -> 不执行校验规则&关联操作 n -> 执行校验规则&关联操作不传默认为n，即会执行校验规则&关联操作

返回值
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

10. 执行转交任务

接口: /yida_vpc/task/redirectTask.json
参数 | 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP |
| | systemToken | 验权token | 是 | | 在应用数据中获取。 | | language | 语言环境 | 否 | zh_CN | 可选值：zh_CN/en_US | | processInstanceId | 实例ID | 是 | | | | byManager | 是否应用管理员进行转交 | 否 | y |
- 可选项 : y/n
- y,则userId必须传应用管理员工号，或者yida_pub_account
- n, userId必须传任务的当前执行人
| | userId | 钉钉的userId | 是 | | | | nowActionerId | 新的任务处理人工号 | 是 | |
| | remark | 转交备注 | 是 |
| | | taskId | 任务ID | 是 |
| |

返回值：
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
- errorLevel : 错误级别;
返回格式

成功：

{
  "success":true
}

11. 执行宜搭平台的审批任务

接口: /yida_vpc/process/executePlatformTask.json
参数
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP |
| | systemToken | 应用秘钥 | 是 | hexxyyddd | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | yida_pub_account | 写死 yida_pub_account | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | procInstId | 流程实例ID | 是 | f30233fb-72e1-4af4-8cb8-c7e0ea9ee530 |
| | outResult | 审批结果 | 是 |
- agree
- disagree
| | | formDataJson | 更新的表单数据 | 否 | | 参考：附录1保存/更新表单数据格式说明。
参数有的组件更新，没有的组件保持不变。
明细的值只能统一更新，无法只更新明细下某个组件的值
| | remark | 审批意见 | 是 | 确认同意 | | | noExecuteExpressions | 是否不执行校验&关联操作 | 否 | y | 本任务节点有绑定校验规则或者关联操作时，
y -> 不执行校验规则&关联操作
n -> 执行校验规则&关联操作
不传默认为n，即会执行校验规则&关联操作 |

下面举一个具体的使用示例：

新建一个流程

前置审批人根据用户需求设置，需要程序回调执行的审批人需要选择使用角色中的虚拟角色“宜搭平台”，选择完成之后点击“保存”按钮，保存当前最新添加的流程节点。

回到流程设置的最外层，点击“保存并发布”按钮，将整个流程发布。

发起流程之后，一路处理，直到审批流到达“宜搭平台”，此时整个流程会卡主，等待这一虚拟角色的审批。

可以调用宜搭暴露的“执行虚拟节点任务”的接口“/yida/process/executePlatformTask.json”来更新该审批节点的处理结果。

相关参数调用Demo如下：

这里重点介绍一下其中的流程实例Id参数proInstId，它表示的是一个审批流的实例，获取方式之一为根据“根据条件搜索流程实例Id”的接口“/yida/process/getInstanceIds.json”接口，设置查询字段instanceStatus为RUNNING以及searchFieldJson中某个字段值来搜索到达“宜搭平台”处理的审批节点。

使用虚拟节点而不是某一个真实存在的审批人是保证该审批处理一定是接口侧发起的，系统中的登录人是无法直接执行该审批，提供一个安全性的保障。

12. 获取审批记录

接口：/yida_vpc/process/getOperationRecords.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

返回值
- result :
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;

返回格式

{
"success": true,
"content": [
  {
    "operateTime": "2018-06-22 14:35:40",
    "remark": "",
    "taskHoldTime": 0,
    "type": "HISTORY",
    "operatorName": "王许川",
    "operator": "WB260752",
    "activityId": "sid-restartevent",
    "action": "提交申请",
    "actionExt": "submit",
    "id": 2846866118,
    "operatorPhotoUrl": "//work.alibaba-inc.com/photo/WB260752.128x128.jpg",
    "processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
    "showName": "提交申请",
    "operateType": "NEW_PROCESS",
    "domains": [],
    "operatorStatus": "A",
    "operatorAgentIds": [],
    "size": 1,
    "operatorDisplayName": "王许川",
    "taskId": "null"
  },
  {
    "taskHoldTime": 531398377,
    "type": "TODO",
    "operatorName": "王许川",
    "operator": "WB260752",
    "activityId": "sidJIOB2P2J1JW3RPMDOS28",
    "taskType": "COMMON_ALL_AT_ONCE",
    "actionExt": "doing",
    "operatorPhotoUrl": "//work.alibaba-inc.com/photo/WB260752.128x128.jpg",
    "processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
    "showName": "执行人",
    "activeTime": "2018-06-22 14:35:41",
    "domains": [],
    "operatorStatus": "A",
    "operatorAgentIds": [],
    "size": 1,
    "operatorDisplayName": "王许川",
    "taskId": "2846866145"
  }
]
}

13.获取流程实例可操作功能列表

接口: /yida_vpc/process/getActivityButtonVOs.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hello1234	在应用数据中获取。
userId	钉钉的userId	是		会校验userId是否有流程发起权限
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processCode
流程编码	是	TPROC—X1G*42ZMGA31OYELIWJ1
activityId
节点ID	是

返回值：
- success : 是否成功
- errorMsg : 错误信息;
- errorCode : 错误码;
返回值demo：

{
  "result": [
    {
      "aliasEn": "Forward",
      "alias": "转交",
    },
    {
      "aliasEn": "Append",
      "alias": "加签",
    },
    {
      "aliasEn": "Return",
      "alias": "退回",
    }
  ],
  "success": true,
  "errorCode": null,
  "content": null,
  "errorMsg": null
}

四、任务中心

1. 查询已提交任务列表

接口: /yida_vpc/process/getMySubmmitInCorp.json
参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	[“APP_xxx”,”APP_xxx”]
processCodes	流程code列表	否	[“xx”,”xxx”]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：
- content : 返回内容;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
- errorLevel : 错误级别;
返回格式

成功：

{
    "result": {
        "data": [{
            "modifiedTime": "2018-04-12 19:44:14",
            "formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
            "title": "单据",
            "instValue": [{"componentId":"node_jfwgghbo","componentName":"TextField","fieldId":"textField_jfwggg8e","label":"姓名","validation":[],"fieldData":{"complexType":"custom","dataType":"CHANGED","pass":true,"value":"jack"},"errorMsg":null,"hasError":false}],
            "processId": 0,
            "appType": "APP_R8MYLKYXXXXXX",
            "dataMap": {
                "textField_jfXXXXXX": "XXXXXX"
            },
            "originatorId": "XXXXXX",
            "formUuid": "FORM-0G7KPV3WZL0U3AHTOA9BFVXXXXXX",
            "dataType": "finst",
            "originatorAvatar": "http://static.dingtalk.com/media/lADPBbCc1R7VwSHNXXXXXX.jpg",
            "version": 0,
            "createTime": "2018-04-12 19:44:14"
        }],
        "totalCount": 1,
        "currentPage": 1
    },
    "success": true
}

失败：

{"errorCode":"TIANSHU_000006","success":false,"errorMsg":"没有权限"}

Tips:instValue返回的是字符串，内容格式是json数组

示例请求代码：

 @Test
    public void postYidaOutTaskTest() {
        String api = "/yida_vpc/process/getMySubmmitInCorp.json";
        String corpId = "ding5d17e3add038d44535c2f4657eb63711";
        String userId = "141940523222800011";
        String corpToken = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";
        PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
        postClient.addParameter("page", "1");
        postClient.addParameter("limit", "10");
        postClient.addParameter("corpId", corpId);
//        postClient.addParameter("appTypes", "[\"APP_I3D2FD2ZQB75KLLKL48Y\"]");
        postClient.addParameter("userId", userId);
        String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);
        String apiResult = postClient.post();
        Assert.notNull(apiResult);
    }

2. 查询待办任务列表

接口: /yida_vpc/process/getTodoTasksInCorp.json
参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	[“APP_xxx”,”APP_xxx”]
processCodes	流程code列表	否	[“xx”,”xxx”]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：
- content : 返回内容;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
- errorLevel : 错误级别;
返回格式

成功：

{
    "result": {
        "data": [{
            "processInstanceId": "XXXXXX",
            "originatorName": "XXX",
            "title": "XXX发起的流程",
            "originatorPhoto": "http://static.dingtalk.com/media/lADPdfafafsAXXXXXX.jpg",
            "titleEn": "XXX发起的流程",
            "createTime": "2018-04-13 13:35:58",
            "appType": "APP_R8MdfadfXXXXXX",
            "originatorNameEn": "XXXXXX",
            "originatorId": "XXXXXX",
            "taskId": "XXXXXX",
            "status": "NEW"
        }],
        "totalCount": 1,
        "currentPage": 1
    },
    "success": true
}

失败：

{"errorCode":"TIANSHU_000006","success":false,"errorMsg":"没有权限"}

示例请求代码：

 @Test
    public void postYidaOutTaskTest() {
        String api = "/yida_vpc/process/getTodoTasksInCorp.json";
        String corpId = "ding5d17e3add038d44535c2f4657eb63711";
        String userId = "141940523222800011";
        String corpToken = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";
        PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
        postClient.addParameter("page", "1");
        postClient.addParameter("limit", "10");
        postClient.addParameter("corpId", corpId);
//        postClient.addParameter("appTypes", "[\"APP_I3D2FD2ZQB75KLLKL48Y\"]");
        postClient.addParameter("userId", userId);
        String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);
        String apiResult = postClient.post();
        Assert.notNull(apiResult);
    }

3. 查询已完成任务列表

接口: /yida_vpc/process/getDoneTasksInCorp.json
参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	[“APP_xxx”,”APP_xxx”]
processCodes	流程code列表	否	[“xx”,”xxx”]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：
- content : 返回内容;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
- errorLevel : 错误级别;
返回格式

成功：

{
    "result": {
        "data": [{
            "processInstanceId": "abc434rfds23XXXXXX",
            "finishTime": "2018-03-28 17:46:14",
            "originatorName": "",
            "title": "XXX发起的流程页面",
            "originatorPhoto": "//img.alicdn.com/tfs/TB1msdfsXXXXXX.jpg",
            "titleEn": "XXX发起的流程页面",
            "createTime": "2018-03-28 17:45:43",
            "appType": "XXXXXX",
            "originatorNameEn": "XXXXXX",
            "originatorId": "XXXXXX",
            "taskId": "XXXXXX",
            "status": "COMPLETED"
        }],
        "totalCount": 1,
        "currentPage": 1
    },
    "success": true
}

失败：

{"errorCode":"TIANSHU_000006","success":false,"errorMsg":"没有权限"}

示例请求代码：

 @Test
    public void postYidaOutTaskTest() {
        String api = "/yida_vpc/process/getDoneTasksInCorp.json";
        String corpId = "ding5d17e3add038d44535c2f4657eb63711";
        String userId = "141940523222800011";
        String corpToken = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";
        PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
        postClient.addParameter("page", "1");
        postClient.addParameter("limit", "10");
        postClient.addParameter("corpId", corpId);
//        postClient.addParameter("appTypes", "[\"APP_I3D2FD2ZQB75KLLKL48Y\"]");
        postClient.addParameter("userId", userId);
        String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);
        String apiResult = postClient.post();
        Assert.notNull(apiResult);
    }

4. 查询抄送我的任务列表（应用维度）

接口: /yida_vpc/process/getNotifyMeTasksInApp.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	验权token	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
userId	钉钉的userId	是
processCodes	流程code列表	否	[“xx”,”xxx”]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
instStatus	实例状态	否		枚举值

返回值：
- content : 返回内容;
- success : 请求是否成功;
- errorMsg : 错误信息;
- errorCode : 错误码;
- errorLevel : 错误级别;
返回格式

成功：

{
    "result": {
        "data": [{
            "modifiedTime": "2018-04-12 19:44:14",
            "formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
            "title": "单据",
            "instValue": [{"componentId":"node_jfwgghbo","componentName":"TextField","fieldId":"textField_jfwggg8e","label":"姓名","validation":[],"fieldData":{"complexType":"custom","dataType":"CHANGED","pass":true,"value":"jack"},"errorMsg":null,"hasError":false}],
            "processId": 0,
            "appType": "APP_R8MYLKYXXXXXX",
            "dataMap": {
                "textField_jfXXXXXX": "XXXXXX"
            },
            "originatorId": "XXXXXX",
            "formUuid": "FORM-0G7KPV3WZL0U3AHTOA9BFVXXXXXX",
            "dataType": "finst",
            "originatorAvatar": "http://static.dingtalk.com/media/lADPBbCc1R7VwSHNXXXXXX.jpg",
            "version": 0,
            "createTime": "2018-04-12 19:44:14"
        }],
        "totalCount": 1,
        "currentPage": 1
    },
    "success": true
}

失败：

{
    "errorCode":"TIANSHU_000006",
     "success":false,
     "errorMsg":"没有权限"
}

Tips:instValue返回的是字符串，内容格式是json数组

5. 查询抄送我的任务列表（企业维度）

接口:/yida_vpc/process/getNotifyMeInCorp.json
参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
token	验权token	是		md5(corpId + userId + code)，每个企业有自己的唯一code md5取32位大写值
userId	钉钉的userId	是
page	当前页	是	1	必须大于0 默认1
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
keyword	表单中组件数据模糊搜	否
appTypes	应用标识列表	否	[“APP_xxx”,”APP_xxx”]
processCodes	流程code列表	否	[“xx”,”xxx”]
instanceCreateFrom	数据提交时间开始	否		时间戳
instanceCreateTo	数据提交时间结束	否		时间戳
createFrom	抄送到达时间开始	否		时间戳
createTo	抄送到达时间结束	否		时间戳

返回结果

{
  "result": {
    "data": [
      {
        "gmtModified": "2019-01-24 19:25:23",
        "creator": "manager55",
        "corpId": "ding5d17e3add038d44535c2f4657eb6378f",
        "title": "小蔡发起的流程",
        "gmtCreate": "2019-01-24 19:25:23",
        "url": "https://www.aliwork.com/alibaba/web/APP_VN7I6HVKUTXES7XX4OI8/inst/carbonDetail.html?formInstId=33f6d221-17f8-42b7-836a-682b95a046c2&activityId=sidJRAJ56IZ2JOFOOPZ2MI7",
        "activityId": "sidJRAJ56IZ2JOFOOPZ2MI7",
        "titleEn": "小蔡（小蔡）发起的流程",
        "processCode": "TPROC--S5VKBWKVB4UVLG1BT5NS6229RVSD2MACIA4IJ7",
        "appType": "APP_VN7I6HVKUTXES7XX4OI8",
        "formInstId": "33f6d221-17f8-42b7-836a-682b95a046c2",
        "mobileUrl": "https://www.aliwork.com/alibaba/mobile/APP_VN7I6HVKUTXES7XX4OI8/inst/detail/carbonDetail?formInstId=33f6d221-17f8-42b7-836a-682b95a046c2&activityId=sidJRAJ56IZ2JOFOOPZ2MI7"
      }
    ],
    "currentPage": 1,
    "totalCount": 1
  },
  "success": true
}

五、其他接口

1. 附件地址转临时免登地址

接口：/yida_vpc/file/getOpenUrl.json
参数：
| 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxxx | 在应用数据中获取。 | | userId | 钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | fileUrl | 宜搭附件地址 | 是 | https://www.aliwork.com/fileHandle?appType=APP_VN7I6HVKUTXES7XX4OI8&fileName=2a4103a6-44d5-4114-990d-4147a2d53811.xlsx&instId=&type=download | | | timeout | 临时地址多久失效,单位毫秒，最大 32400000 毫秒（9小时）。 | 是 | 60000 | 60000表示一分钟后临时地址失效 |

返回值：
- success: 请求是否成功
- result：[]
- errorMsg: 错误信息
- errorCode：错误码

返回格式

{
"result": "免登的附件地址",
"success": true
}

2. 提交表单/流程实例下的评论

接口：/yida_vpc/remark/save.json
参数： | 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxxx | 在应用数据中获取。 | | userId | 评论人钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formInstId | 实例ID | 是 | | | | replyId | 对评论进行回复 | 否 | 12 | | | atUserId | 将评论内容通过钉钉发给指定用户 | 否 | 多个工号,用英文逗号分隔 | | | content | 评论内容 | 是 | | |

返回值：
- success: 请求是否成功
- result：评论ID
- errorMsg: 错误信息
- errorCode：错误码
返回格式
```
{"result":14,"success":true}
```

3. 获取应用下的页面列表

接口：/yida_vpc/app/listNavigationByFormType.json
参数： | 参数名 | 描述 | 是否必填 | 示例 | 备注 | | —- | —- | —- | —- | —- | | appType | 应用ID | 是 | APP_PBKT0MFBEBTDO8T7SLVP | | | systemToken | 应用秘钥 | 是 | hexxxx | 在应用数据中获取。 | | userId | 评论人钉钉的userId | 是 | | | | language | 语言 | 否 | zh_CN | 可选值：zh_CN/en_US
默认：zh_CN | | formType | 页面类型 | 是 | | receipt,单据页面process,流程页面report，报表页面 |

返回值：
- success: 请求是否成功
- result：页面列表
- errorMsg: 错误信息
- errorCode：错误码

返回格式

{
"result": [
  {
    "formUuid": "FORM-92GKRGIVZ5xxJZ6XB7WU3G4XNHV1YXYNELXJ0",
    "processCode": "TPROC--92GKRGIxx5V6LJZ6XB7WU3G4XNHV15YYNELXJ1",
    "title": {
      "pureEn_US": "普通流程01",
      "en_US": "普通流程01",
      "zh_CN": "普通流程01",
      "type": "i18n"
    },
  },
  {
    "formUuid": "FORM-92GKRGIV63X6K8X8ZH432CWBEGFN1DZ9V3OXJ0",
    "processCode": "TPROC--92GKRGIV63X6K8X8ZH432CWBEGFN1G3AV3OXJ1",
    "title": {
      "pureEn_US": "普通流程01(carbon)",
      "en_US": "普通流程01(carbon)",
      "zh_CN": "普通流程01-01-抄送人",
      "type": "i18n"
    }
  }
],
"success": true,
"errorCode": null,
"content": null,
"errorMsg": null
}

附录

1. 保存/更新表单数据格式说明

表单中每个组件都有唯一ID，每个组件中填写的数据都有自己的固定格式。目前支持的表单组件有：单行，多行，数字，单选，下拉单选，多选，下拉多选，日期，日期区间，人员搜索框，地区选择，部门选择，级联选择，明细组件。
保存/更新表单数据时，用Map的jsonString格式来作为参数传递表单中的数据。key为组件ID，Object为组件的值。每个组件的值格式如下：

组件类型	数据格式	demo	备注
单行输入框	字符串	“danhang”
多行输入框	字符串	“duohang”
数字输入框	数字	1
单选	字符串	“选项一”
下拉单选	字符串	“选项一”
多选	字符串数组	[“选项一”,”选项二”]
下拉多选	字符串数组	[“选项一”,”选项二”]
日期组件	时间戳	1516204800000
级联日期	字符串数组	[“1514736000000”,”1517328000000”]。假如只有结束时间，[“”,”1517328000000”]	第一个为开始时间的时间戳字符串，第二给结束时间的时间戳字符串
人员搜索框	字符串数组	[“xxxxx”,”yyyyy”]
城市选择	字符串数组	[“110000”,”110100”,”110101”]	第一个必须为省份ID，第二个为城市ID，第三个为区ID。
部门选择	数字	1123456
级联选择	字符串数据	[“part”,”part_b”]	必须按照级联顺序，依次放到数组中
附件组件	字符串数组	[ { “downloadUrl”: “文件下载地址”, “name”: “文件名”, “previewUrl”: “文件预览地址”, “url”: “文件下载地址”, “ext”: “docx” } ]
超链接组件	字符串数组	[ { “link”:”http://www.aliwork.com“, “text”:”宜搭” } ]
明细	JSONARRAY	[{“textField_jcr0069m”: “danhang1”},{“textField_jcr0069m”: “danhang2”}] (textField_jcr0069m为明细下单行的组件ID)	由于明细下有多条记录，所以用JSONARRAY。由于每条记录都是很多组件的值，因此用JSONObject来存每个组件对应的值

完整的表单数据格式如下：

{
  "textField_jcr0069m": "danhang",
  "textareaField_jcr0069n": "duohang",
  "numberField_jcr0069o": 1,
  "radioField_jcr0069p": "选项一",
  "selectField_jcr0069q": "选项一",
  "checkboxField_jcr0069r": [
    "选项二",
    "选项三"
  ],
  "multiSelectField_jcr0069s": [
    "选项二",
    "选项三"
  ],
  "dateField_jcr0069t": 1516636800000,
  "cascadeDate_jcr0069u": [
    "1514736000000",
    "1517328000000"
  ],
  "employeeField_jcr0069x": [
    "xxxxx"
  ],
  "citySelectField_jcr0069y": [
    "110000",
    "110100",
    "110101"
  ],
  "departmentField_jcr0069z": 1123456,
  "cascadeSelectField_jcr006a0": [
    "part",
    "part_b"
  ],
  {
  "attachmentField_jna1lvyb": [
    {
      "downloadUrl": "https://www.aliwork.com/fileHandle?appType=default_tianshu_app&fileName=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt&instId=&type=download",
      "name": "test.txt",
      "previewUrl": "https://www.aliwork.com/inst/preview?appType=default_tianshu_app&fileName=test.txt&fileSize=4&downloadUrl=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt",
      "url": "https://www.aliwork.com/fileHandle?appType=default_tianshu_app&fileName=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt&instId=&type=download",
      "ext": "txt"
    }
  ]
},  
  "tableField_jcr006a1": [
    {
      "cascadeDate_jcr006aa": [
        "1514736000000",
        "1517328000000"
      ],
      "cascadeSelectField_jcr006ae": [
        "product",
        "product_a"
      ],
      "checkboxField_jcr006a7": [
        "选项一",
        "选项二",
        "选项三"
      ],
      "citySelectField_jcr006ac": [
        "120000",
        "120100",
        "120102"
      ],
      "dateField_jcr006a9": 1517328000000,
      "departmentField_jcr006ad": 1123456,
      "employeeField_jcr006ab": [
        "yyyyy",
        "xxxxx"
      ],
      "multiSelectField_jcr006a8": [
        "选项一",
        "选项二",
        "选项三"
      ],
      "numberField_jcr006a4": 2,
      "radioField_jcr006a5": "选项二",
      "selectField_jcr006a6": "选项三",
      "textField_jcr006a2": "明细下单行",
      "textareaField_jcr006a3": "明细下多行"
    }
  ]
}

2. 根据组件值进行条件搜索，组件值格式说明

表单中每个组件都有唯一ID，每个组件的搜索格式不一样。目前支持搜索的表单组件有：单行，多行，数字，单选，下拉单选，多选，下拉多选，日期，日期区间，人员搜索框，地区选择，部门选择，级联选择，明细组件。
搜索时，用Map 格式来表示每个组件的搜索条件。key为组件ID，Object为组件的搜索值。各个组件的搜索类型和值格式如下

组件类型	数据格式	demo	备注
单行输入框	字符串	“danhang”	模糊搜索
多行输入框	字符串	“duohang”	模糊搜索
数字输入框	字符串数组	[“1”,”10”]	范围搜索。第一个为最小值，第二个为最大值
单选	字符串	“选项二”	精确搜索
下拉单选	字符串	“选项二”	精确搜索
多选	字符串数组	[“选项二”]	数组搜索。搜索值必须是多选值的子集
下拉多选	字符串数组	[“选项二”]	数组搜索。搜索值必须是多选值的子集
日期组件	字符串数组	[“1514736000000”,”1517414399000”]	范围搜索。第一个为日期开始的时间戳，第二个为日期结束的时间戳。
日期区间	数组	[[“1514736000000”,”1517414399000”],[“1514736000000”,”1517414399000”]]	范围搜索。第一个数组是日期区间开始的搜索范围。第二个数组是日期区间结束的搜索范围。
人员搜索框	字符串数组	[“xxxxx”,”yyyyyy”]	精确匹配。值必须完全匹配，工号顺序也需要一致。
城市选择	字符串数组	[“110000”,”110100”,”110101”]	数组搜索。搜索值必须是城市值的子集。另外，有市ID，就必须有省ID。有区ID，就必须有省ID和市ID。
部门选择	数字	1123456	精确匹配
级联选择	字符串数组	[“part”,”part_b”]	数组搜索。和城市选择限制条件一致。
明细组件	字符串	danhang	模糊搜索。明细下的值为一个大text，搜索用模糊搜索。

完整例子

{
  "textField_jcr0069m": "danhang",
  "textareaField_jcr0069n": "duohang",
  "numberField_jcr0069o": [
    "1",
    "10"
  ],
  "radioField_jcr0069p": "选项一",
  "selectField_jcr0069q": "选项一",
  "checkboxField_jcr0069r": [
    "选项二"
  ],
  "multiSelectField_jcr0069s": [
    "选项二",
    "选项三"
  ],
  "dateField_jcr0069t": [
    1514736000000,
    1517414399000
  ],
  "cascadeDate_jcr0069u":[
      [
        1514736000000,
        1517414399000
      ],
      [
        1514736000000,
        1517414399000
      ]
    ],
  "employeeField_jcr0069x": [
    "xxxxx"
  ],
  "citySelectField_jcr0069y": [
    "110000",
    "110100",
    "110101"
  ],
  "departmentField_jcr0069z": 1123456,
  "cascadeSelectField_jcr006a0": [
    "part",
    "part_b"
  ],
  "tableField_jcr006a1": "明细数据"
}

3. 流程实例详情对象格式说明

字段	描述	示例	备注
actioners	流程实例当前任务执行人	[ { “name”: { “en_US”: “user_en_name”, “zh_CN”: “user_zh_name”, “type”: “i18n” }, “userId”: “workno” } ]	如果流程已完成，没有执行人时，该字段为空
processInstanceId	实例ID	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530	唯一
formUuid	流程表单ID	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
processCode	流程Code	TPROC—EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4
title	实例标题	xxxx 发起的流程	根据你的语言环境，返回对应的标题
instanceStatus	实例状态	RUNNING
approvedResult	流程结束时的审批结论	agree	agree -> 通过 disagree -> 拒绝
originator	发起人信息	[ { “name”: { “en_US”: “user_en_name”, “zh_CN”: “user_zh_name”, “type”: “i18n” }, “userId”: “workno” } ]
data	表单数据		参加附录4- 作为返回值的表单数据的格式说明

完整的数据格式demo

{
  "result": {
    "data": 
      {
        "actioners": [
          {
            "name": {
              "pureEn_US": "xxx",
              "en_US": "xxx",
              "zh_CN": "xxx",
              "type": "i18n"
            },
            "userId": "xxx"
          }
        ],
        "processInstanceId": "f30233fb-72e1-4af4-8cb8-c7e0ea9ee530",
        "formUuid": "FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3",
        "data": {
          "numberField_jcr0069o": 1,
          "multiSelectField_jcr0069s": [
            "选项三",
            "选项二"
          ],
          "textareaField_jcr0069n": "duohang",
          "employeeField_jcr0069x": [
            "xxxx"
          ],
          "departmentField_jcr0069z": "信息xxx平台",
          "cascadeDate_jcr0069u": [
            "1514736000000",
            "1517328000000"
          ],
          "cascadeSelectField_jcr006a0": [
            "part",
            "part_b"
          ],
          "tableField_jcr006a1": [
            {
              "departmentField_jcr006ad": "信息xxx",
              "cascadeDate_jcr006aa": [
                "1514736000000",
                "1517328000000"
              ],
              "selectField_jcr006a6": "选项三",
              "citySelectField_jcr006ac": [
                "天津",
                "天津市",
                "河东区"
              ],
              "radioField_jcr006a5": "选项二",
              "employeeField_jcr006ab": [
                "yyyyy",
                "xxxxxx"
              ],
              "dateField_jcr006a9": 1517328000000,
              "textField_jcr006a2": "明细下单行",
              "textareaField_jcr006a3": "明细下多行",
              "cascadeSelectField_jcr006ae": [
                "product",
                "product_a"
              ],
              "numberField_jcr006a4": 2,
              "checkboxField_jcr006a7": [
                "选项一",
                "选项三",
                "选项二"
              ],
              "multiSelectField_jcr006a8": [
                "选项一",
                "选项三",
                "选项二"
              ]
            }
          ],
          "selectField_jcr0069q": "选项一",
          "citySelectField_jcr0069y": [
            "北京",
            "北京市",
            "东城区"
          ],
          "checkboxField_jcr0069r": [
            "选项三",
            "选项二"
          ],
          "textField_jcr0069m": "danhang",
          "radioField_jcr0069p": "选项一",
          "dateField_jcr0069t": 1516636800000
        },
        "processCode": "TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4",
        "originator": {
          "name": {
            "pureEn_US": "xxx",
            "en_US": "xxxx",
            "zh_CN": "xxx",
            "type": "i18n"
          },
          "userId": "xxxx"
        },
        "title": "xxx发起的流程",
        "instanceStatus": "RUNNING"
      },
    "totalCount": 1,
    "currentPage": 1
  },
  "success": true
}

4. 作为返回值的表单数据的格式说明

作为返回值的表单数据格式和 “附录1-保存/更新表单数据格式说明”基本一致。区别在于：

录入时，地区组件值为[“省份ID”, “市ID”, “区ID”]。作为返回值时，是[“省名称”,”城市名称”,”地区名称”]。
单选，下拉单选，多选，下拉多选是有国际化的。返回值时，会根据传的language参数，返回对应的数据值。

5. 单据实例详情对象格式说明

字段	描述	示例	备注
gmtModified	最后修改时间	2018-01-24 11:22:01
formUuid	表单ID	FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1
formInstId	实例ID	FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0
originator	发起人详情	[{“name”: {“en_US”: “user_en_name”,”zh_CN”: “user_zh_name”,”type”: “i18n”},”userId”: “workno”}]
formData	表单数据详情		参加附录4- 作为返回值的表单数据的格式说明

完整的demo如下

{
  "result": {
    "gmtModified": "2018-01-24 11:22:01",
    "formUuid": "FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1",
    "formInstId": "FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0",
    "formData": {
      "numberField_jcr0069o": 1,
      "multiSelectField_jcr0069s": [
        "选项三",
        "选项二"
      ],
      "textareaField_jcr0069n": "duohang",
      "employeeField_jcr0069x": [
        "xxxx"
      ],
      "departmentField_jcr0069z": "xxxx",
      "cascadeDate_jcr0069u": [
        "1514736000000",
        "1517328000000"
      ],
      "cascadeSelectField_jcr006a0": [
        "part",
        "part_b"
      ],
      "tableField_jcr006a1": [
        {
          "departmentField_jcr006ad": "xxxx",
          "cascadeDate_jcr006aa": [
            "1514736000000",
            "1517328000000"
          ],
          "selectField_jcr006a6": "选项三",
          "citySelectField_jcr006ac": [
            "天津",
            "天津市",
            "河东区"
          ],
          "radioField_jcr006a5": "选项二",
          "employeeField_jcr006ab": [
            "xxxxxx",
            "yyyyyy"
          ],
          "dateField_jcr006a9": 1517328000000,
          "textField_jcr006a2": "明细下单行",
          "textareaField_jcr006a3": "明细下多行",
          "cascadeSelectField_jcr006ae": [
            "product",
            "product_a"
          ],
          "numberField_jcr006a4": 2,
          "checkboxField_jcr006a7": [
            "选项一",
            "选项三",
            "选项二"
          ],
          "multiSelectField_jcr006a8": [
            "选项一",
            "选项三",
            "选项二"
          ]
        }
      ],
      "selectField_jcr0069q": "选项一",
      "citySelectField_jcr0069y": [
        "北京",
        "北京市",
        "东城区"
      ],
      "checkboxField_jcr0069r": [
        "选项三",
        "选项二"
      ],
      "textField_jcr0069m": "danhang",
      "radioField_jcr0069p": "选项一",
      "dateField_jcr0069t": 1516636800000
    },
    "originator": {
      "name": {
        "pureEn_US": "userEnglishName",
        "en_US": "userEnglishName",
        "zh_CN": "userName",
        "type": "i18n"
      },
      "userId": "xxxx"
    }
  },
  "success": true
}

6. corpId和corpToken如何获取？

点击首页右上角的小螺丝的图标，进入平台管理配置页面

有侧边栏点击企业基本信息，在展示页面的租户信息中可以分别查询到Corp ID和Corp Token的数据，分别对应常用参数里面的corpId和corpToken。

五、常见问题

除了文档中提及的JAVA SDK，是否支持其他语言调用？

回答：支持，除了Java语言之外，还支持go/php等语言，具体内容可以参考文档。

接口调用产生如下的报错

sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

【原因分析】
网关服务的https证书配置存在问题。

【解决方案】
一方面可以将 xxpt.gateway.protocal=https 修改为xxpt.gateway.protocal=http 临时解决这个问题，
另一方面，向官方值班人员报错，建议官方尽快修复这个https证书的问题。

已经订阅服务了，在进行接口调用时还是产生了如下的报错：
```
User not authorized to operate on the specified resource
```
【解决方案】
订阅未生效，联系技术支持同学重新进行接口订阅。

接口返回：”The Api Key ‘test_201xxx1-LxQQO1xxxZBNn22’ is invalid” ？

【解决方案】
请检查参domainName是否正确，正确值应该为：s-api.alibaba-inc.com**。
**

（高级功能）宜搭公有云版开放接口文档

前言

一、准备工作

1.1 Java调用方式

1.1.1 引入依赖

1.1.2 参数配置

1.1.3 调用示例

二、表单接口

1. 新增表单实例

2. 更新表单中指定组件值

3. 删除表单实例

4. 根据表单ID查询实例详情

5. 根据条件搜索表单实例ID列表

6. 根据条件搜索表单实例详情列表

7. 获取表单定义

三、流程接口

1. 发起新的流程实例

2. 根据条件搜索流程实例ID

3. 根据搜索条件获取实例详情

4. 根据实例ID获取流程实例详情

5. 根据实例ID列表批量获取流程实例详情

6. 更新流程实例

7. 删除流程实例

8. 终止流程实例

9. 执行审批任务

10. 执行转交任务

11. 执行宜搭平台的审批任务

12. 获取审批记录

13.获取流程实例可操作功能列表

四、任务中心

1. 查询已提交任务列表

2. 查询待办任务列表

3. 查询已完成任务列表

4. 查询抄送我的任务列表（应用维度）

5. 查询抄送我的任务列表（企业维度）

五、其他接口

1. 附件地址转临时免登地址

2. 提交表单/流程实例下的评论

3. 获取应用下的页面列表

附录

1. 保存/更新 表单数据格式说明

2. 根据组件值进行条件搜索，组件值格式说明

3. 流程实例详情对象格式说明

4. 作为返回值的表单数据的格式说明

5. 单据实例详情对象格式说明

6. corpId和corpToken如何获取？

五、常见问题

1. 保存/更新表单数据格式说明