三方审批实例同步

Error: 为了更好地提升接口文档的的易理解性，我们对文档进行了升级，请尽快迁移至新版本>>

审批中心不负责审批的流转，审批的流转在三方系统，三方系统在审批流转后生成的审批实例、审批任务、审批抄送数据同步到审批中心。

用户可以在审批中心中浏览三方系统同步过来的实例、任务、抄送信息，并且可以跳转回三方系统进行更详细的查看和操作，其中实例信息在【已发起】列表，任务信息在【待审批】和【已审批】列表，抄送信息在【抄送我】列表
对于审批任务，三方系统也可以配置审批任务的回调接口，这样审批人可以在审批中心中直接进行审批操作，审批中心会回调三方系统，三方系统收到回调后更新任务信息，并将新的任务信息同步回审批中心，形成闭环。

请求

项目	值
HTTP URL	https://www.feishu.cn/approval/openapi/v2/external/instance/create
HTTP Method	POST
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用	`approval:approval:readonly` 访问审批应用

请求头

名称	类型	必填	描述
Authorization	string	是	`tenant_access_token` 值格式："Bearer `access_token`" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

请求体

名称	类型	描述
`content` `必选`	`string`	JSON字符串

三方审批JSON

名称	类型	描述	示例
`approval_code` `必选`	`string`	审批定义 code，创建审批定义返回的值，表示该实例属于哪个流程；该字段会影响到列表中该实例的标题，标题取自对应定义的 name 字段	81D31358-93AF-92D6-7425-01A5D67C4E71
`instance_id` `必选`	`string`	审批实例唯一标识，用户自定义，需确保证租户、应用下唯一	24492654
`status` `必选`	`string`	审批实例状态可选值： - `PENDING`: 审批中 - `APPROVED`: 审批流程结束，结果为同意 - `REJECTED`: 审批流程结束，结果为拒绝 - `CANCELED`: 审批发起人撤回 - `DELETED`: 审批被删除 - `HIDDEN`: 状态隐藏(不显示状态)	PENDING
`extra`	`string`	审批实例扩展 JSON	`{"xxx":"xxx"}`
`links` `必选`	`map`	审批实例链接集合，用于【已发起】列表的跳转，跳转回三方系统； pc_link 和 mobile_link 必须填一个，填写的是哪一端的链接，即会跳转到该链接，不受平台影响
∟ pc_link ``必选	`string`	pc 端的跳转链接，当用户使用飞书 pc 端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9c9c38e07a9101&path=pc/pages/detail?id=1234
∟ mobile_link``必选	`string`	移动端跳转链接，当用户使用飞书移动端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
`title`	`string`	审批展示名称，如果填写了该字段，则审批列表中的审批名称使用该字段，如果不填该字段，则审批名称使用审批定义的名称	@i18n@1
`form`	`list`	用户提交审批时填写的表单数据，用于所有审批列表中展示。可传多个值，但审批中心pc展示前2个,移动端展示前3个,长度不超过2048字符	[ `{ "name": "@i18n@2", "value": "@i18n@3" }` ]
∟ `name`	`string`	表单字段名称	@i18n@2
∟ `value`	`string`	表单值	@i18n@3
`user_id```	`string`	审批发起人 user_id，发起人可在【已发起】列表中看到所有已发起的审批;在【待审批】，【已审批】【抄送我】列表中，该字段展示审批是谁发起的。审批发起人 open id，和 user id 二选一。	a987sf9s
`user_name`	`string`	审批发起人用户名，如果发起人不是真实的用户（例如是某个部门），没有 user_id，则可以使用该字段传名称	@i18n@9
`open_id`	`string`	审批发起人 open id，和 user id 二选一	ou_be73cbc0ee35eb6ca54e9e7cc14998c1
`department_id`	`string`	发起人部门，用于列表中展示发起人所属部门。不传则不展示。如果用户没加入任何部门，传 ""，将展示租户名称传 department_name 展示部门名称	od-8ec33278bc2
`department_name`	`string`	审批发起人部门，如果发起人不是真实的用户（例如是某个部门），没有 department_id，则可以使用该字段传名称	@i18n@10
`start_time` `必选`	`long`	审批发起时间，Unix毫秒时间戳	1556468012678
`end_time` `必选`	`long`	审批实例结束时间：未结束的审批为 0，Unix毫秒时间戳	1556468012678
`update_time` `必选`	`long`	审批实例最近更新时间；用于推送数据版本控制如果 update_mode 值为 UPDATE，则只有传过来的 update_time 有变化时（变大），才会更新审批中心中的审批实例信息。使用该字段主要用来避免并发时老的数据更新了新的数据	1556468012678
`display_method`	`string`	列表页打开审批实例的方式。可选值： - `BROWSER`: 跳转系统默认浏览器打开 - `SIDEBAR`: 飞书中侧边抽屉打开 - `NORMAL`: 飞书内嵌页面打开	BROWSER
`update_mode`	`string`	更新方式可选值： - `REPLACE`: 全量替换，默认值 - `UPDATE`: 增量更新当 update_mode=REPLACE时，每次都以当前推送的数据为最终数据，会删掉审批中心中多余的任务、抄送数据（不在这次推送的数据中）; 当 update_mode=UPDATE时，则不会删除审批中心的数据，而只是进行新增和更新实例、任务数据	UPDATE
`task_list` `必选`	`list`	任务列表	备注: 任务数限制最大不超过200
∟ `task_id` `必选`	`string`	审批实例内的唯一标识，用于更新审批任务时定位数据	112534
∟ `user_id` `必选`	`string`	审批人 user_id，该任务会出现在审批人的【待审批】或【已审批】列表中	a987sf9s
∟ `open_id`	`string`	审批人 open id，和 user id 二选一	ou_be73cbc0ee35eb6ca54e9e7cc14998c1
∟ `title`	`string`	审批任务名称	i18n1
∟ links``必选	`map`	【待审批】或【已审批】中使用的跳转链接，用于跳转回三方系统 pc_link 和 mobile_link 必须填一个，填写的是哪一端的链接，即会跳转到该链接，不受平台影响
∟ pc_link``必选	`string`	pc 端的跳转链接，当用户使用飞书 pc 端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9cfc38e07a9101&path=pc/pages/detail?id=1234
∟ mobile_link``必选	`string`	移动端跳转链接，当用户使用飞书移动端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
∟ `status` `必选`	`string`	任务状态可选值： - `PENDING`: 待审批 - `APPROVED`: 任务同意 - `REJECTED`: 任务拒绝 - `TRANSFERRED`: 任务转交 - `DONE`: 任务通过但审批人未操作；审批人看不到这个任务, 若想要看到, 可以通过抄送该人.
∟ `extra`	`string`	扩展 json，任务结束原因需传complete_reason字段。枚举值与对应说明： - approved：同意 - rejected：拒绝 - node_auto_reject：（因逻辑判断产生的）自动拒绝 - specific_rollback：退回（包括退回到发起人、退回到中间任一审批人） - add：并加签（添加新审批人，和我一起审批） - add_pre：前加签（添加新审批人，在我之前审批） - add_post：后加签（添加新审批人，在我之后审批） - delete_assignee：减签 - forward_resign：转交（转给其他人审批） - recall：撤销（撤回单据，单据失效） - delete ：删除审批单 - admin_forward：管理员在后台操作转交 - system_forward：系统自动转交 - auto_skip：自动通过 - manual_skip：手动跳过 - submit_again：重新提交任务 - restart：重新启动流程 - others：其他（作为兜底）	`{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}`
∟ `create_time` `必选`	`long`	任务创建时间，Unix 毫秒时间戳	1556468012678
∟ `end_time` `必选`	`long`	任务完成时间：未结束的审批为 0，Unix 毫秒时间戳	1556468012678
∟ `update_time` `必选`	`long`	task最近更新时间，用于推送数据版本控制；更新策略同 instance 中的 update_time	1556468012678
∟ `action_context`	`string`	操作上下文，当用户操作时，回调请求中带上该参数，用于传递该任务的上下文数据	123456
∟ `action_configs`	`list`	任务级别操作配置,快捷审批目前支持移动端操作
∟ `action_type` `必选`	`string`	操作类型，每个任务都可以配置2个操作，会展示审批列表中，当用户操作时，回调请求会带上该字段，表示用户进行了同意操作还是拒绝操作 APPROVE - 同意 REJECT - 拒绝 {KEY} - 任意字符串，如果使用任意字符串，则需要提供 action_name	APPROVE
∟ `action_name`	`string`	操作名称，i18n key 用于前台展示，如果 action_type 不是 APPROVAL和REJECT，则必须提供该字段，用于展示特定的操作名称	@i18n@5
∟ `is_need_reason`	`bool`	是否需要意见, 如果为true,则用户操作时，会跳转到意见填写页面	false
∟ `is_reason_required`	`bool`	审批意见是否必填	false
∟ `is_need_attachment`	`bool`	意见是否支持上传附件	false
∟ `display_method`	`string`	列表页打开审批任务的方式。可选值： - `BROWSER`: 跳转系统默认浏览器打开 - `SIDEBAR`: 飞书中侧边抽屉打开 - `NORMAL`: 飞书内嵌页面打开	BROWSER
∟ `exclude_statistics`	`bool`	三方任务支持不纳入效率统计。false：纳入效率统计。true：不纳入效率统计	false
∟ `node_id`	`string`	节点id：必须同时满足 - 一个流程内，每个节点id唯一。如一个流程下「直属上级」、「隔级上级」等每个节点的Node_id均不一样 - 同一个流程定义内，不同审批实例中的相同节点，Node_id要保持不变。例如张三和李四分别发起了请假申请，这2个审批实例中的「直属上级」节点的node_id应该保持一致	node
∟ `node_name`	`string`	节点名称，如「财务审批」「法务审批」，支持中英日三种语言。示例：i18n@name。需要在i18n_resources中传该名称对应的国际化文案	i18n@name
`cc_list`	`list`	抄送列表	备注: 抄送数限制最大不超过200
∟ `cc_id` `必选`	`string`	审批实例内唯一标识	12345
∟ `user_id` `必选`	`string`	抄送人 employee id	12345
∟ `open_id`	`string`	抄送人 open id，和user id 二选一	ou_be73cbc0ee35eb6ca54e9e7cc14998c1
∟ `links` `必选`	`map`	跳转链接，用于【抄送我的】列表中的跳转 pc_link 和 mobile_link 必须填一个，填写的是哪一端的链接，即会跳转到该链接，不受平台影响
∟ `pc_link`	`string`	pc 端的跳转链接，当用户使用飞书 pc 端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c9cfc38e07a9101&path=pc/pages/detail?id=1234
∟ `mobile_link`	`string`	移动端跳转链接，当用户使用飞书移动端时，使用该字段进行跳转	https://applink.feishu.cn/client/mini_program/open?appId=cli_9c9cfc38e07a9101&path=pages/detail?id=1234
∟ `read_status` `必选`	`string`	阅读状态，空值表示不支持已读未读：可选值： - `READ`: 已读 - `UNREAD`: 未读	READ
∟ `extra`	`string`	扩展 json	`{"xxx":"xxx"}`
∟ `title`	`string`	抄送任务名称	xxx
∟ create_time``必选	`long`	抄送发起时间，Unix 毫秒时间戳	1556468012678
∟ update_time``必选	`long`	抄送最近更新时间，用于推送数据版本控制更新策略同 instance 的update_time	1556468012678
∟ `display_method`	`string`	列表页打开审批任务的方式。可选值： - `BROWSER`: 跳转系统默认浏览器打开 - `SIDEBAR`: 飞书中侧边抽屉打开 - `NORMAL`: 飞书内嵌页面打开	BROWSER
i18n_resources``必选	`list`	国际化文案
∟ locale``必选	`string`	语言 - `zh-CN`: 中文 - `en-US`: 英文 - `ja-JP`: 日文	zh-CN
∟ is_default``必选	`bool`	是否默认语言	true
∟ texts``必选	`map`	文案 key, value, i18n key 以 @i18n@ 开头；该字段主要用于做国际化，语序用户同时传多个语言的文案，审批中心会根据用户当前的语音环境使用对应的文案，如果没有传用户当前的语音环境文案，则会使用默认的语言文案。	`{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }`

注意事项：

需确保审批实例内各类唯一 ID 在审批实例内的唯一性，即使不属于同一实体。

json

{
    "content": "{\"approval_code\":\"60D0F7A2-052D-49E9-B570-C29C836CDF8E\",\"instance_id\":\"216263\",\"status\":\"PENDING\",\"extra\":\"\",\"links\":{\"pc_link\":\"http://182.50.118.46:38080/spa/workflow/static4form/index.html?#/main/workflow/req?requestid=\",\"mobile_link\":\"http://182.50.118.46:38080/spa/workflow/static4form/index.html?#/main/workflow/req?requestid=\"},\"title\":\"@i18n@1\",\"form\":[{\"name\":\"@i18n@2\",\"value\":\"@i18n@3\"}],\"user_id\":\"52d6585f\",\"user_name\":\"342a\",\"open_id\":\"123\",\"department_id\":\"od-8ec33ffec336c3a39a278bc25e931676\",\"department_name\":\"XXXX\",\"start_time\":1622444502000,\"update_time\":1622444502000,\"end_time\":0,\"update_mode\":\"REPLACED\",\"task_list\":[{\"task_id\":\"112253\",\"user_id\":\"52d6585f\",\"links\":{\"pc_link\":\"http://\",\"mobile_link\":\"http://\"},\"status\":\"PENDING\",\"extra\":\"\",\"title\":\"同意\",\"create_time\":1566468012678,\"end_time\":0,\"update_time\":1566468012678,\"action_context\":\"123456\",\"action_configs\":[{\"action_type\":\"APPROVE\",\"action_name\":\"@i18n@9\",\"is_need_reason\":true,\"is_reason_required\":true,\"is_need_attachment\":true}]}],\"cc_list\":[{\"cc_id\":\"1231243\",\"user_id\":\"a987sf9s\",\"open_id\":\"\",\"links\":{\"pc_link\":\"http://\",\"mobile_link\":\"http://\"},\"read_status\":\"READ\",\"extra\":\"\",\"title\":\"XXX\",\"create_time\":1556468012678,\"update_time\":1566468012678}],\"i18n_resources\":[{\"locale\":\"zh-CN\",\"is_default\":true,\"texts\":{\"@i18n@1\":\"离开\",\"@i18n@2\":\"天\",\"@i18n@3\":\"2020-08-01\"}},{\"locale\":\"en-US\",\"is_default\":false,\"texts\":{\"@i18n@1\":\"Leave\",\"@i18n@2\":\"Day\",\"@i18n@3\":\"2020-08-01\"}},{\"locale\":\"ja-JP\",\"is_default\":false,\"texts\":{\"@i18n@1\":\"Leave\",\"@i18n@2\":\"Day\",\"@i18n@3\":\"2020-08-01\"}}]}"
}

响应

响应体

参数	类型	必须	说明
code	int	是	返回码，非0表示失败
msg	String	是	返回码的描述
data	map	是	返回业务信息

响应体示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
    }
}

事件

工作空间枚举

工作空间数据表

工作空间视图

角色

apiRef

内容

文件

文件夹

数据校验

表格操作

货币信息

地点 · 数据

事件

事件

审批 · 搜索

飞书原生审批

应用商店集成

第三方审批集成

三方审批实例同步 ​

请求 ​

请求头 ​

请求体 ​

响应 ​

响应体 ​

响应体示例 ​

三方审批实例同步

请求

请求头

请求体

响应

响应体

响应体示例