用户&流程开放文档

2438 上次更新时间：2021-02-21 19:54:33

Document

注意

Base URL

https://api.pro.surongyun.cn/

接口请求类型

本文档所涉及到的所有接口的调用方法为 POST 类型，请求参数的类型为 Json 格式

身份验证问题

所有接口需要将 openApi 生成的 AuthCode 放到 header中完成身份的验证   
请求Header中添加的Authorization字段；配置Authorization字段的值为“Bearer ＋ 半角空格 ＋AuthCode值”。
格式如下：

Authorization:Bearer AuthCode值

示例如下：

Authorization:Bearer 3F2504E04F8911D39A0C0305E82C3301

Curl示例：

curl --location --request POST 'https://xxx/openapi/form/smart/5f23be36e4b03ccc874f091a/query' \
--header 'Authorization: Bearer gqRZRzGm8Dw38IgQjabdQf2bSrjTUB4U' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone":"18710841735",
    "pageSize":1
}'

身份验证错误返回示例

{
    "timestamp": "2021-01-22T07:48:45.657+0000",
    "status": 401, //无权限
    "error": "Unauthorized",
    "message": "illegal token,access denied",
    "path": "/openapi/form/smart/5f23be36e4b03ccc874f091a/query"
}

请求接口方式错误返回示例，请求接口请使用 POST 方式

{
    "timestamp": "2021-01-27T08:38:33.613+0000",
    "status": 405,
    "error": "Method Not Allowed",
    "message": "Request method 'GET' not supported",
    "path": "/openapi/instance/flow/filter/todo"
}

服务返回

{
    "code": 0, //状态码 非 0 则为错误返回
    "msg": "success", //内容 错误时 会返回错误信息
    "result": {} //返回的结果信息 
}

节点类型说明

节点类型 节点说明
start 开始节点
approval 审批节点
provideInput 填写节点
cc 抄送节点
end 结束节点

节点状态说明

节点执行状态 状态说明
RUNNING 进行中
FINISH 已完成
REJECT 拒绝
END 结束节点已结束

表单状态说明

表单执行状态 状态说明
RUNNING 进行中
REJECT 拒绝
AGREE 已同意

按钮操作说明

originName 操作 说明
agree 同意
reject 拒绝
submit 通过/提交
forward 转交
revocation 撤回
repulse 驳回

错误码

错误码 说明
待补充

使用时间说明

在系统中返回时间的地方，返回的时间均为13位时间戳（精确到毫秒）请根据需求自行转换类型，传递给速融云的时间也请使用13位时间戳（精确到毫秒）。

名词解释

应用

在速融云中应用是最小逻辑单元，或者应用是你创建或创建的「系统」，你可以理解为手机上的一个个软件，如 微信、飞书、钉钉  等等都是应用。 一个 速融云应用通常由一个或多个有联系的表单、流程、仪表盘和数据协作组成。
应用具有唯一标识 appId，查询应用信息或者应用下表单使用 appId

表单

速融云中，承载数据收集、展示的载体就是『表单』。
在日常工作中，在纸质时代制式表单的语义与我们的表单一样。 数据的格式填写、上报、汇总都是通过表单来实现。
表单有唯一标识formId,查询表单信息，使用formId

流程

表单数据提交后流转的方式。一个表单对应一个流程。
一个表单对应一套流程，查询表单的流程信息也使用 formId 来查询

节点

流程处理的每一步就是 1 个节点。一个流程包含多个节点。节点具有自己的 nodeId

instanceId

表单提交的一条数据，就是一个数据实例，对应一个唯一标识 instanceId

一、用户对接

1.新增用户

/openapi/org/user/add

请求参数

{
    "thirdUserId":"333", //第三方用户的唯一标识 必填
    "username":"用户名", //用户名称 必填
    "userImage":"头像" //用户头像 选填 不传递头像，系统会使用系统生成的默认头像
}

响应参数

{
    "code": 0, 
    "msg": "success", 
    "result": {
       "userId":"34"  //速融云的用户 Id
    } 
}

2.删除用户

/openapi/org/user/remove

请求参数

{
    "thirdUserId":"333" //必填
}

响应参数

{
    "code": 0, 
    "msg": "success", 
    "result": null
}

3.更新用户

/openapi/org/user/update

请求参数

{
    "thirdUserId":"333", //第三方用户的唯一标识 必填
    "username":"用户名", //用户名称 必填
    "userImage":"头像" //用户头像 选填
}

响应参数

{
    "code": 0, 
    "msg": "success", 
    "result": {
       "userId":"34"  //速融云的用户 Id
    } 
}

4. 用户的列表

/openapi/org/user/list

请求参数

{}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result": [
    {
      "userId":"34",  //速融云的用户 Id
      "thirdUserId":"333", //第三方用户的唯一标识 
      "username":"用户名", //用户名称 
      "userImage":"头像" //用户头像 
    }
  ]
}

5. 用户的兑换

第三方用户兑换速融云用户 Id,返回对应的 key-value 结构，没有找到的不返回

/openapi/org/user/exchange

请求参数

{
	"thirdUserIdList":["35","46","57"] //必填 不能为空数组
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result": {
  		"35":"789",
      "46":"987",
      "57":"999"
  }
}

二、流程设计

1.获取表单流程节点信息

/openapi/flow/node/list

请求参数

{
  "formId":"5e0d67094f3e5f00071635b4" //必填 表单的 Id
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result": [
    {
    	"nodeId":"当前节点 Id",
      "nodeType":"节点类型", //参考下面的节点类型说明
      "previous":"前一个节点Id",
      "next":"下一个节点的 Id",
      "parent":"父节点的 Id",
      "nodeName":"节点名称",
      "chargePerson":{
      	"memberIdList":["34","35"], //团队成员 Id信息
        "roleIdList":["12312312"], //角色 Id信息
				"deptIdList":[33], //部门 Id
        "externalList":["33"], //外部联系人列表
        "tagList":["3333333"] //外部联系人标签
      } //负责人信息
    }
  ]
}

三、流程实例

1. 流转历史

/openapi/instance/flow/history

请求参数

{
  "instanceId":"数据实例 Id"  //必填 
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result": [
    {
    	"nodeId":"当前节点 Id",
      "nodeName":"节点类型", //参考下面的节点类型说明
      "stepStatus":"FINISH", //请参考上文 节点状态说明
      "handleTime":1611282633611,
      "costTime":0, //单位毫秒
      "costTimeStr":"3天5小时12分20秒",
      "handleDetail":"李晓发起流程"
    }
  ]
}

2. 审批历史

/openapi/instance/flow/approve/history

请求参数

{
  "instanceId":"数据实例 Id"  //必填 
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result": [
    {
      "userId": "34", //处理人 速融云的用户 Id
      "userName": "李晓", //处理人名称
      "headImage": "头像",
      "comment": "不同意", //审批意见
      "signatureUrl": "签名图片",
      "timestamp": 1611318211625 //处理时间
    }
  ]
}

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

/openapi/instance/flow/detail

请求参数

{
   "instanceId":"数据实例 Id"  //必填 
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "userName": "李晓", //发起人名称
    "headImg": "123", //发起人头像
    "nodeId": "RY1ERJELRV71ERJIERTI", //当前节点 Id
    "nodeName": "审批节点", //当前节点名称
    "formApplyStatus": "RUNNING", //表单申请状态 参考上文表单状态说明
    "progress": 33, //进度 0-100
    "totalTime": 35952319, //总耗时 单位毫秒
    "finishTime": 0, //完成时间
    "rejectUserName": "", //拒绝人
    "rejectHeadImg": "", //拒绝人头像
    "rejectTime": 0 //拒绝时间
  }
}

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

/openapi/instance/flow/batch/detail

请求参数

{
  "instanceIdList":[""] //必填 不能为空数组
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":[
    {
      "userName": "李晓", //发起人名称
      "headImg": "123", //发起人头像
      "stepId": "RY1ERJELRV71ERJIERTI", //当前节点 Id
      "stepName": "审批节点", //当前节点名称
      "formApplyStatus": "RUNNING", //表单申请状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      "progress": 33, //进度 0-100
      "totalTime": 35952319, //总耗时 单位毫秒
      "finishTime": 0, //完成时间
      "rejectUserName": "", //拒绝人
      "rejectHeadImg": "", //拒绝人头像
      "rejectTime": 0 //拒绝时间
    }
  ]
}

5. 实例待处理的 buttonList

/openapi/instance/flow/button/list

请求参数

{
  "userId":"33", //速融云的用户 Id 必填
  "instanceId":"数据实例 Id"  //必填 
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":[
    {
      "originName": "agree",  //按钮操作传递 参考上文按钮操作说明
      "customName": "同意",  //按钮显示名称
      "customColor": "#1CA04E", //按钮颜色
      "textColor": "#FFFFFF" //按钮文字颜色
    }
  ]
}

6. 表单的处理

/openapi/instance/flow/handle

请求参数

{
  "userId":"33", //速融云的用户 Id 必填
  "instanceId":"数据实例 Id",  //必填 
  "nodeId":"处理节点的 Id", //必填
  "handleAction":"agree", //对应按钮的originName 必填 参考上文按钮操作说明
  "comment":"审批意见", //选填
  "forwardUser":{
    "memberIdList":["34","35"], //速融云的用户Id
    "roleIdList":["12312312"], //角色 Id信息
    "deptIdList":[33], //部门 Id
    "externalList":["33"], //外部联系人列表 速融云的用户 Id
    "tagList":["3333333"] //外部联系人标签
  } //转交人 转交的时候是必填 其他情况不填
}

可能出现异常情况
表单实例数据不存在
不是流程待处理人
不是当前待处理流程
**
响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":null
}

6.流程催办

/openapi/instance/flow/remind

请求参数

{
  "userId":"33", //速融云的用户 Id 非必填 如果没有此参数 将以团队创建者的身份催办
  "instanceId":"数据实例 Id",  //必填 
  "nodeId":"处理节点的 Id" //必填
}

可能出现异常情况
表单实例数据不存在
不是当前待处理流程
**
响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":null
}

四、待办详情

1.所有待办

/openapi/instance/flow/filter/todo

请求参数

{
  "userId":"33", //速融云的用户 Id 选填 传递此参数表示筛选当前用户的待办
  "appId":"",   //应用的 Id 选填  传递此参数表示筛选此应用的所有待办
  "formId":"",  //表单的 Id 选填 传递此参数表示筛选此表单的所有待办
  //时间过滤
  "filterTime":{
    "method":"EQ",  //EQ 等于 NE 不等于 GTE >=  LTE <= RANGE 范围
    "fixedValue":"FIXED_VALUE", //FIXED_VALUE 固定值 TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 
    "value":[
      1155455444,154545444554
    ]
  },
  "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 选填 不填表示第1页
  "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100 选填 不填表示每页 10 条数据
  "needProgress":0 //是否需要返回进度 0 不返回 1 返回
}

过滤时间说明 等于具体某一天 EQ,FIXED_VALUE,[1592555656610]
本周 EQ,THIS_WEEK,[] -----TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 同理
范围的时候 RANGE,FIXED_VALUE,[1592555656610,1592555656610] 必须传递 2 个时间戳
不筛选的时候 filterTime 传递 null

**
响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 
    "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100
    "totalCount":1, //总数量
    "totalPage":3, //总页码
    "dataList":[
      {
        "instanceId": "600a38c9e4b03726368402de", //实例 Id
        "deadLine": 1611282813611, //超期时间
        "arriveTime": 1611282633894, //进入节点时间
        "nodeId": "RY1ERJELRV71ERJIERTI", //节点 Id
        "nodeType": "approval", //节点类型
        "nodeName": "审批节点", //节点名称
        "userName": "李晓", //发起人
        "headImg": "", //发起人头像
        "progress":0-100, //流程进度
        "titleContent": "流程表单-超时设置", //表单标题
        "expireFlag":"NONE", // NONE 无 REMIND 催办  TIMEOUT 即将超时 OVERTIME 超期
        "formApplyStatus":"INIT" //表单本身状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      }
    ]
  }
}

2.抄送我的

/openapi/instance/flow/filter/cc

请求参数

{
  "userId":"33", //速融云的用户 Id 选填 传递此参数表示筛选当前用户的待办
  "appId":"",   //应用的 Id 选填  传递此参数表示筛选此应用的所有待办
  "formId":"",  //表单的 Id 选填 传递此参数表示筛选此表单的所有待办
  "formStatus":"", //状态筛选 选填 传递此参数表示筛选状态在此状态的数据
  //时间过滤
  "filterTime":{
    "method":"EQ",  //EQ 等于 NE 不等于 GTE >=  LTE <= RANGE 范围
    "fixedValue":"FIXED_VALUE", //FIXED_VALUE 固定值 TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 
    "value":[
      1155455444,154545444554
    ]
  },
  "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 选填 不填表示第1页
  "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100 选填 不填表示每页 10 条数据
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 
    "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100
    "totalCount":1, //总数量
    "totalPage":3, //总页码
    "dataList":[
      {
        "instanceId": "600a38c9e4b03726368402de", //实例 Id
        "deadLine": 1611282813611, //超期时间
        "arriveTime": 1611282633894, //进入节点时间
        "nodeId": "RY1ERJELRV71ERJIERTI", //节点 Id
        "nodeType": "approval", //节点类型
        "nodeName": "审批节点", //节点名称
        "userName": "李晓", //发起人
        "headImg": "", //发起人头像
        "titleContent": "流程表单-超时设置", //表单标题
        "expireFlag":"NONE", // NONE 无 REMIND 催办  TIMEOUT 即将超时 OVERTIME 超期
        "formApplyStatus":"INIT" //表单本身状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      }
    ]
  }
}

3.我发起的

/openapi/instance/flow/filter/create

请求参数

{
  "userId":"33", //速融云的用户 Id 选填 传递此参数表示筛选当前用户的待办
  "appId":"",   //应用的 Id 选填  传递此参数表示筛选此应用的所有待办
  "formId":"",  //表单的 Id 选填 传递此参数表示筛选此表单的所有待办
  "formStatus":"", //状态筛选 选填 传递此参数表示筛选状态在此状态的数据
  //时间过滤
  "filterTime":{
    "method":"EQ",  //EQ 等于 NE 不等于 GTE >=  LTE <= RANGE 范围
    "fixedValue":"FIXED_VALUE", //FIXED_VALUE 固定值 TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 
    "value":[
      1155455444,154545444554
    ]
  },
  "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 选填 不填表示第1页
  "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100 选填 不填表示每页 10 条数据
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 
    "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100
    "totalCount":1, //总数量
    "totalPage":3, //总页码
    "dataList":[
      {
        "instanceId": "600a38c9e4b03726368402de", //实例 Id
        "deadLine": 1611282813611, //超期时间
        "arriveTime": 1611282633894, //进入节点时间
        "nodeId": "RY1ERJELRV71ERJIERTI", //节点 Id
        "nodeType": "approval", //节点类型
        "nodeName": "审批节点", //节点名称
        "userName": "李晓", //发起人
        "headImg": "", //发起人头像
        "titleContent": "流程表单-超时设置", //表单标题
        "expireFlag":"NONE", // NONE 无 REMIND 催办  TIMEOUT 即将超时 OVERTIME 超期
        "formApplyStatus":"INIT" //表单本身状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      }
    ]
  }
}

4.我处理过的

/openapi/instance/flow/filter/handle

请求参数

{
  "userId":"33", //速融云的用户 Id 选填 传递此参数表示筛选当前用户的待办
  "appId":"",   //应用的 Id 选填  传递此参数表示筛选此应用的所有待办
  "formId":"",  //表单的 Id 选填 传递此参数表示筛选此表单的所有待办
  "formStatus":"", //状态筛选 选填 传递此参数表示筛选状态在此状态的数据
  //时间过滤
  "filterTime":{
    "method":"EQ",  //EQ 等于 NE 不等于 GTE >=  LTE <= RANGE 范围
    "fixedValue":"FIXED_VALUE", //FIXED_VALUE 固定值 TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 
    "value":[
      1155455444,154545444554
    ]
  },
  "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 选填 不填表示第1页
  "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100 选填 不填表示每页 10 条数据
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 
    "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100
    "totalCount":1, //总数量
    "totalPage":3, //总页码
    "dataList":[
      {
        "instanceId": "600a38c9e4b03726368402de", //实例 Id
        "deadLine": 1611282813611, //超期时间
        "arriveTime": 1611282633894, //进入节点时间
        "nodeId": "RY1ERJELRV71ERJIERTI", //节点 Id
        "nodeType": "approval", //节点类型
        "nodeName": "审批节点", //节点名称
        "userName": "李晓", //发起人
        "headImg": "", //发起人头像
        "titleContent": "流程表单-超时设置", //表单标题
        "expireFlag":"NONE", // NONE 无 REMIND 催办  TIMEOUT 即将超时 OVERTIME 超期
        "formApplyStatus":"INIT" //表单本身状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      }
    ]
  }
}

5.催办我的

/openapi/instance/flow/filter/remind

请求参数

{
  "userId":"33", //速融云的用户 Id 选填 传递此参数表示筛选当前用户的待办
  "appId":"",   //应用的 Id 选填  传递此参数表示筛选此应用的所有待办
  "formId":"",  //表单的 Id 选填 传递此参数表示筛选此表单的所有待办
  //时间过滤
  "filterTime":{
    "method":"EQ",  //EQ 等于 NE 不等于 GTE >=  LTE <= RANGE 范围
    "fixedValue":"FIXED_VALUE", //FIXED_VALUE 固定值 TODAY 今天 YESTERDAY 昨天 THIS_WEEK 本周 LAST_WEEK 上周 THIS_MONTH 本月 LAST_MONTH 上月 
    "value":[
      1155455444,154545444554
    ]
  },
  "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 选填 不填表示第1页
  "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100 选填 不填表示每页 10 条数据
}

响应参数

{
  "code": 0, 
  "msg": "success", 
  "result":{
    "currentPage":1, //必须大于0默认1
    "pageSize":10,   //必须大于0默认10不能大于100
    "currentPage":1, // 第几页数据从 1 开始 必须大于0默认1 
    "pageSize":10,   //每页多少条数据 默认 10 条 必须大于0默认10不能大于100
    "dataList":[
      {
        "instanceId": "600a38c9e4b03726368402de", //实例 Id
        "deadLine": 1611282813611, //超期时间
        "arriveTime": 1611282633894, //进入节点时间
        "nodeId": "RY1ERJELRV71ERJIERTI", //节点 Id
        "nodeType": "approval", //节点类型
        "nodeName": "审批节点", //节点名称
        "userName": "李晓", //发起人
        "headImg": "", //发起人头像
        "titleContent": "流程表单-超时设置", //表单标题
        "expireFlag":"NONE", // NONE 无 REMIND 催办  TIMEOUT 即将超时 OVERTIME 超期
        "formApplyStatus":"INIT" //表单本身状态 INIT 发起 RUNNING 运行中 REJECT 拒绝 AGREE 同意
      }
    ]
  }
}

以上内容是否对你有帮助？