飞书开放平台 Server API 文档

主题

同步三方审批实例 ​

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

实现效果 ​

调用本接口同步三方审批实例后，企业员工可以在审批中心浏览同步过来的审批实例、任务、抄送信息，并可以跳转回三方系统查看和操作审批，其中，实例信息在审批中心的 已发起 列表、任务信息在 待办 和 已办 列表、抄送信息在 抄送我 列表。

创建三方审批定义时如果设置了三方审批回调 URL，对于审批任务，可以配置三方快捷审批回调，这样审批人可以在审批中心直接进行审批操作，审批中心会将审批结果回调至三方系统，三方系统收到回调后更新任务信息，并将新的任务信息同步回审批中心，形成闭环。

注意事项 ​

需确保审批实例内各类实体（实例、任务、抄送） ID 在审批实例内的唯一性，不属于同一实体之间的 ID 也要确保唯一性。如果实例 ID、任务 ID、抄送 ID 重复，则会导致在审批中心任务看不到对应的审批数据。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/approval/v4/external_instances
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可approval:approval 查看、创建、更新、删除审批应用相关信息 approval:external_instance 查看、创建、更新、删除三方审批实例相关信息

请求头 ​

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

请求体 ​

名称类型必填描述
approval_codestring是审批定义 Code。创建三方审批定义的返回值，用来指定当前实例属于的审批定义。 说明：如果在当前接口设置了 title 参数，则审批实例名称按照 title 展示。如果未设置 title，审批实例的标题取自对应审批定义（approval_code）的 name 参数。
示例值："81D31358-93AF-92D6-7425-01A5D67C4E71"
statusstring是审批实例状态
示例值："PENDING"
可选值有：
- PENDING: 审批中 - APPROVED: 审批流程结束，结果为同意 - REJECTED: 审批流程结束，结果为拒绝 - CANCELED: 审批发起人撤回 - DELETED: 审批被删除 - HIDDEN: 状态隐藏（不显示状态） - TERMINATED: 审批终止
extrastring否审批实例扩展参数，JSON 格式，传值时需要压缩转义为字符串。单据编号通过传 business_key 参数来实现。
注意：以下示例值未转义，使用时请注意转义。你可查看请求体示例中转义后的 extra 示例值。
示例值："{\"xxx\":\"xxx\",\"business_key\":\"xxx\"}"
instance_idstring是审批实例唯一标识，自定义设置。需确保证在当前企业和应用内唯一。
示例值："24492654"
linksexternal_instance_link是审批实例链接信息。设置的链接用于在审批中心 已发起 列表内点击跳转，跳回三方审批系统查看审批详情。
  └ pc_linkstring是PC 端的三方审批实例跳转链接。 说明：
- 当用户使用飞书 PC 端查看实例详情时，通过该链接进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
  └ mobile_linkstring否移动端的三方审批实例跳转链接。 说明：
- 当用户使用飞书移动端查看实例详情时，通过该链接进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
titlestring否审批展示名称。 说明：
- 如果填写了该参数，则审批列表中的审批名称使用该参数。如果不填该参数，则审批名称使用审批定义的名称。 - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - Key 需要以 @i18n@ 开头。
示例值："@i18n@1"
formexternal_instance_form\[\]否用户提交审批时填写的表单数据，用于所有审批列表中展示。可传多个值，最多展示前 3 个，长度不超过 2048 字符。
image.png
示例值：[{ "name": "@i18n@2", "value": "@i18n@3" }]
  └ namestring否表单字段名称。 说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："@i18n@2"
  └ valuestring否表单值。 说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："@i18n@3"
user_idstring否审批发起人 user_id。发起人可在审批中心的 已发起 列表中看到所有已发起的审批。在 待办、已办、抄送我 列表中，该字段用来展示审批的发起人。获取方式参见如何获取用户的 User ID。 注意：审批发起人的 open_id 和 user_id 需至少传入一个。
示例值："a987sf9s"
user_namestring否审批发起人的用户名。如果发起人不是真实的用户（例如是某个部门），没有 user_id，则可以使用该参数传入一个名称。 说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："@i18n@9"
open_idstring否审批发起人 open_id。发起人可在审批中心的 已发起 列表中看到所有已发起的审批。在 待办、已办、抄送我 列表中，该字段用来展示审批的发起人。获取方式参见如何获取用户的 Open ID。 注意：审批发起人的 open_id 和 user_id 需至少传入一个。
示例值："ou_be73cbc0ee35eb6ca54e9e7cc14998c1"
department_idstring否发起人的部门 ID，用于在审批中心列表中展示发起人的所属部门，不传值则不展示。获取方式参见部门 ID。 说明：如果用户没加入任何部门，传 ""，默认展示企业名称。如果传入 department_name 参数，则展示对应的部门名称。
示例值："od-8ec33278bc2"
department_namestring否审批发起人的部门名称。如果发起人不是真实的用户或没有部门，则可以使用该参数传入部门名称。
说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。 - Key 需要以 @i18n@ 开头。
示例值："@i18n@10"
start_timestring是审批发起时间，Unix 毫秒时间戳。
示例值："1556468012678"
end_timestring是审批实例结束时间。未结束的审批为 0，Unix 毫秒时间戳。
示例值："1556468012678"
update_timestring是审批实例最近更新时间，Unix 毫秒时间戳，用于推送数据版本控制。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批实例信息。 说明：使用该参数主要用来避免并发时，旧数据更新了新数据。
示例值："1556468012678"
display_methodstring否列表页打开审批实例的方式。
示例值："BROWSER"
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管打开（即托管在飞书审批中心打开）
update_modestring否更新方式。 - 当 update_mode 取值为 REPLACE 时，每次都以当前推送的数据为最终数据，会删掉审批中心中，不在本次推送数据中的多余的任务、抄送数据。 - 当 update_mode 取值为 UPDATE 时，不会删除审批中心的数据，而只进行新增、更新实例与任务数据。
默认值：REPLACE
示例值："UPDATE"
可选值有：
- REPLACE: 全量替换 - UPDATE: 增量更新
task_listexternal_instance_task_node\[\]否任务列表
数据校验规则：
- 最大长度：300
  └ task_idstring是审批实例内，审批任务的唯一标识，用于更新审批任务时定位数据。
示例值："112534"
  └ user_idstring否审批人 user_id，获取方式参见如何获取用户的 User ID。 说明： - 该任务会出现在审批人的飞书审批中心 待办 或 已办 的列表中。 - user_id 与 open_id 需至少传入一个。
示例值："a987sf9s"
  └ open_idstring否审批人 open_id，获取方式参见如何获取用户的 Open ID。 说明： - 该任务会出现在审批人的飞书审批中心 待办 或 已办 的列表中。 - user_id 与 open_id 需至少传入一个。
示例值："ou_be73cbc0ee35eb6ca54e9e7cc14998c1"
  └ titlestring否审批任务名称。 说明：
- 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："@i18n@4"
  └ linksexternal_instance_link是在审批中心 待办、已办 中使用的三方审批跳转链接，用于跳转回三方审批系统查看任务详情。
    └ pc_linkstring是PC 端的跳转链接。 说明： - 当用户使用飞书 PC 端查看任务详情时，通过该链接进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
    └ mobile_linkstring否移动端的跳转链接。 说明： - 当用户使用飞书移动端查看任务详情时，通过该链接进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
  └ statusstring是任务状态
示例值："PENDING"
可选值有：
- PENDING: 待审批 - APPROVED: 任务同意 - REJECTED: 任务拒绝 - TRANSFERRED: 任务转交 - DONE: 任务通过但审批人未操作。审批人看不到该任务时，如需查看可抄送至该审批人。
  └ extrastring否扩展字段。JSON 格式，传值时需要压缩转义为字符串。 任务结束原因需传 complete_reason 参数，枚举值说明：
- approved：同意 - rejected：拒绝 - node_auto_reject：因逻辑判断产生的自动拒绝 - specific_rollback：退回（包括退回到发起人、退回到中间任一审批人） - add：并加签（添加新审批人，与我一起审批） - add_pre：前加签（添加新审批人，在我之前审批） - add_post：后加签（添加新审批人，在我之后审批） - delete_assignee：减签 - forward: 手动转交 - forward_resign：离职自动转交 - recall：撤销（撤回单据，单据失效） - delete ：删除审批单 - admin_forward：管理员在后台操作转交 - system_forward：系统自动转交 - auto_skip：自动通过 - manual_skip：手动跳过 - submit_again：重新提交任务 - restart：重新启动流程 - others：其他
示例值："{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}"
  └ create_timestring是任务创建时间，Unix 毫秒时间戳。
示例值："1556468012678"
  └ end_timestring是任务完成时间。未结束的审批为 0，Unix 毫秒时间戳。
示例值："1556468012678"
  └ update_timestring否任务最近更新时间，Unix 毫秒时间戳，用于推送数据版本控制。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批任务信息。
示例值："1556468012678"
  └ action_contextstring否操作上下文。当用户操作审批时，回调请求中会包含该参数，用于传递该任务的上下文数据。
示例值："123456"
  └ action_configsaction_config\[\]否任务级别的快捷审批操作配置。 注意：快捷审批目前仅支持在飞书移动端操作。
    └ action_typestring是操作类型。每个任务都可以配置两个操作（同意、拒绝或任意中的两个），操作会展示审批列表中。当用户操作时，回调请求会包含该字段，三方审批可接受到审批人的操作数据。
可选值有：
- APPROVE: 同意 - REJECT: 拒绝 - {KEY}: 任意字符串。如果使用任意字符串，则需要提供 action_name
示例值："APPROVE"
    └ action_namestring否操作名称。如果 action_type 不等于 APPROVAL 或 REJECT，则必须提供该字段，用于展示特定的操作名称。 说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："@i18n@5"
    └ is_need_reasonboolean否是否需要审批意见。取值为 true 时，审批人在审批中心操作任务后，还需要跳转填写审批意见。
示例值：false
    └ is_reason_requiredboolean否审批意见是否必填
示例值：false
    └ is_need_attachmentboolean否审批意见是否支持上传附件
示例值：false
  └ display_methodstring否审批中心列表页打开审批任务的方式。
示例值："BROWSER"
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管模式打开
  └ exclude_statisticsboolean否三方审批任务是否不纳入效率统计。可选值有：
- true：不纳入效率统计 - false：纳入效率统计
示例值：false
默认值：false
  └ node_idstring否审批节点 ID。必须同时满足：
- 一个审批流程内，每个节点 ID 唯一。例如，一个流程下直属上级、隔级上级等节点的 node_id 均不一样。 - 同一个三方审批定义内，不同审批实例中的相同节点，node_id 要保持不变。例如，用户 A 和用户 B 分别发起了请假申请，这两个审批实例中的直属上级节点的 node_id 应该保持一致。
示例值："node"
  └ node_namestring否节点名称。
说明： - 这里传入的是国际化文案 Key（即 i18n_resources.texts 参数中的 Key），还需要在 i18n_resources.texts 参数中以 Key:Value 格式进行赋值。
- Key 需要以 @i18n@ 开头。
示例值："i18n@name"
  └ generate_typestring否任务生成类型，可不填， 但是不要填空字符串
示例值："EXTERNAL_CONSIGN"
可选值有：
- EXTERNAL_CONSIGN: 给代理人生成的任务 - DEFAULT: 系统生成的默认任务
cc_listcc_node\[\]否抄送列表
数据校验规则：
- 最大长度：200
  └ cc_idstring是审批实例内抄送唯一标识。
示例值："123456"
  └ user_idstring否抄送人的 user_id。获取方式参见如何获取用户的 User ID。 注意：抄送人的 open_id 和 user_id 需至少传入一个。
示例值："12345"
  └ open_idstring否抄送人的 open_id。获取方式参见如何获取用户的 Open ID。 注意：抄送人的 open_id 和 user_id 需至少传入一个。
示例值："ou_be73cbc0ee35eb6ca54e9e7cc14998c1"
  └ linksexternal_instance_link是审批抄送跳转链接。设置的链接用于在审批中心 抄送我 列表内点击跳转，跳回三方审批系统查看审批抄送详情。
    └ pc_linkstring是PC 端的三方审批实例跳转链接。 说明：
- 当用户使用飞书 PC 端查看审批抄送时，通过该字段进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234"
    └ mobile_linkstring否移动端的三方审批实例跳转链接。 说明：
- 当用户使用飞书移动端查看审批抄送时，通过该字段进行跳转。 - pc_link 和 mobile_link 至少填一个。
示例值："https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
  └ read_statusstring是抄送人的阅读状态
示例值："READ"
可选值有：
- READ: 已读 - UNREAD: 未读
  └ extrastring否扩展字段。JSON 格式，传值时需要压缩转义为字符串。
示例值："{\"xxx\":\"xxx\"}"
  └ titlestring否抄送任务名称。
示例值："xxx"
  └ create_timestring是抄送发起时间，Unix 毫秒时间戳。
示例值："1556468012678"
  └ update_timestring是抄送最近更新时间，Unix 毫秒时间戳，用于推送数据版本。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批实例信息。
示例值："1556468012678"
  └ display_methodstring否列表页打开审批任务的方式。
示例值："BROWSER"
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管模式打开
i18n_resourcesi18n_resource\[\]是国际化文案
  └ localestring是语言
示例值："zh-CN"
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文 - zh-HK: 繁体中文（中国香港） - zh-TW: 繁体中文（中国台湾） - de-DE: 德语 - es-ES: 西班牙语 - fr-FR: 法语 - id-ID: 印度尼西亚语 - it-IT: 意大利语 - ko-KR: 韩语 - pt-BR: 葡萄牙语 - th-TH: 泰语 - vi-VN: 越南语 - ms-MY: 马来语 - ru-RU: 俄语
  └ textsi18n_resource_text\[\]是文案的 Key:Value。Key 需要以 @i18n@ 开头，并按照各个参数的要求传入 Value。该字段主要用于做国际化，允许用户同时传多个语言的文案，审批中心会根据用户当前的语言环境使用对应的文案，如果没有传用户当前的语言环境文案，则会使用默认的语言文案。
示例值：{ "@i18n@1": "权限申请", "@i18n@2": "OA审批", "@i18n@3": "Permission" }
    └ keystring是文案 Key，需要和各个参数 Key 相匹配。
示例值："@i18n@1"
    └ valuestring是文案 Value，即文案 Key 对应的参数值。
示例值："people"
  └ is_defaultboolean是是否为默认语言。默认语言需要包含所有所需的文案 Key，非默认语言如果 Key 不存在，则会使用默认语言代替。
示例值：true
trusteeship_url_tokenstring否单据托管认证 token，托管回调会附带此 token，帮助业务认证。
示例值："788981c886b1c28ac29d1e68efd60683d6d90dfce80938ee9453e2a5f3e9e306"
trusteeship_user_id_typestring否用户的类型，会影响请求参数用户标识域的选择，包括加签操作回传的目标用户， 目前仅支持 user_id。
示例值："user_id"
trusteeship_urlstrusteeship_urls否单据托管回调接入方的接口 URL 地址。
  └ form_detail_urlstring否获取表单 schema 相关数据的 URL 地址。
示例值："https://#{your_domain}/api/form_detail"
  └ action_definition_urlstring否表示获取审批操作区数据的 URL 地址。
示例值："https://#{your_domain}/api/action_definition"
  └ approval_node_urlstring否获取审批记录相关数据的 URL 地址。
示例值："https://#{your_domain}/api/approval_node"
  └ action_callback_urlstring否进行审批操作时回调的 URL 地址。
示例值："https://#{your_domain}/api/action_callback"
  └ pull_business_data_urlstring否获取托管动态数据 URL 地址。使用该接口时，必须要保证历史托管单据的数据中都同步了该接口地址。如果历史单据中没有该接口，需要重新同步历史托管单据的数据来更新该 URL。该接口用于飞书审批前端和业务进行交互使用，只有使用审批前端的特定组件（由飞书审批前端提供的组件，并且需要和业务进行接口交互的组件）才会需要。
示例值："https://#{your_domain}/api/pull_business_data"
trusteeship_cache_configtrusteeship_instance_cache_config否托管预缓存策略。
  └ form_policystring否托管预缓存策略。
示例值："DISABLE"
可选值有：
- DISABLE: 不启用，默认 - IMMUTABLE: 表单不会随流程进行改变 - BY_NODE: 跟随流程节点变更更新缓存 - BY_USER: 对于每个待办任务存储一份
  └ form_vary_with_localeboolean否表单是否随国际化改变。
示例值：false
  └ form_versionstring否当前使用的表单版本号，保证表单改变后，版本号增加，实际值为 int64 整数。
示例值："1"
resource_regionstring否资源所在地区， 内部统计用字段， 不需要填
示例值："cn"

请求体示例 ​

json
{
    "approval_code": "81D31358-93AF-92D6-7425-01A5D67C4E71",
    "status": "PENDING",
    "extra": "{\"xxx\":\"xxx\",\"business_key\":\"xxx\"}",
    "instance_id": "24492654",
    "links": {
        "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
        "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
    },
    "title": "@i18n@1",
    "form": [
        {
            "name": "@i18n@2",
            "value": "@i18n@3"
        }
    ],
    "user_id": "a987sf9s",
    "user_name": "@i18n@9",
    "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
    "department_id": "od-8ec33278bc2",
    "department_name": "@i18n@10",
    "start_time": "1556468012678",
    "end_time": "1556468012678",
    "update_time": "1556468012678",
    "display_method": "BROWSER",
    "update_mode": "UPDATE",
    "task_list": [
        {
            "task_id": "112534",
            "user_id": "a987sf9s",
            "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
            "title": "@i18n@4",
            "links": {
                "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
            },
            "status": "PENDING",
            "extra": "{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}",
            "create_time": "1556468012678",
            "end_time": "1556468012678",
            "update_time": "1556468012678",
            "action_context": "123456",
            "action_configs": [
                {
                    "action_type": "APPROVE",
                    "action_name": "@i18n@5",
                    "is_need_reason": false,
                    "is_reason_required": false,
                    "is_need_attachment": false
                }
            ],
            "display_method": "BROWSER",
            "exclude_statistics": false,
            "node_id": "node",
            "node_name": "i18n@name",
            "generate_type": "EXTERNAL_CONSIGN"
        }
    ],
    "cc_list": [
        {
            "cc_id": "123456",
            "user_id": "12345",
            "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
            "links": {
                "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
            },
            "read_status": "READ",
            "extra": "{\"xxx\":\"xxx\"}",
            "title": "xxx",
            "create_time": "1556468012678",
            "update_time": "1556468012678",
            "display_method": "BROWSER"
        }
    ],
    "i18n_resources": [
        {
            "locale": "zh-CN",
            "texts": [
                {
                    "key": "@i18n@1",
                    "value": "people"
                }
            ],
            "is_default": true
        }
    ],
    "trusteeship_url_token": "788981c886b1c28ac29d1e68efd60683d6d90dfce80938ee9453e2a5f3e9e306",
    "trusteeship_user_id_type": "user_id",
    "trusteeship_urls": {
        "form_detail_url": "https://#{your_domain}/api/form_detail",
        "action_definition_url": "https://#{your_domain}/api/action_definition",
        "approval_node_url": "https://#{your_domain}/api/approval_node",
        "action_callback_url": "https://#{your_domain}/api/action_callback",
        "pull_business_data_url": "https://#{your_domain}/api/pull_business_data"
    },
    "trusteeship_cache_config": {
        "form_policy": "DISABLE",
        "form_vary_with_locale": false,
        "form_version": "1"
    },
    "resource_region": "cn"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ dataexternal_instance同步的实例数据
    └ approval_codestring审批定义 Code
    └ statusstring审批实例状态
可选值有：
- PENDING: 审批中 - APPROVED: 审批流程结束，结果为同意 - REJECTED: 审批流程结束，结果为拒绝 - CANCELED: 审批发起人撤回 - DELETED: 审批被删除 - HIDDEN: 状态隐藏（不显示状态） - TERMINATED: 审批终止
    └ extrastring审批实例扩展 JSON。单据编号通过传 business_key 字段来实现。
    └ instance_idstring审批实例唯一标识，与请求时传入的 instance_id 一致。
    └ linksexternal_instance_link审批实例链接信息。设置的链接用于在审批中心 已发起 列表内点击跳转，跳回三方审批系统查看审批详情。
      └ pc_linkstringPC 端的三方审批实例跳转链接。当用户使用飞书 PC 端查看实例详情时，通过该链接进行跳转。
      └ mobile_linkstring移动端的三方审批实例跳转链接。当用户使用飞书移动端查看实例详情时，通过该链接进行跳转。
    └ titlestring审批展示名称。
说明： - 如果请求时传入了 title 参数，则审批列表中的审批名称使用该参数值。如果请求时未传入 title 参数，则审批名称使用审批定义的名称。 - 这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
    └ formexternal_instance_form\[\]用户提交审批时填写的表单数据，用于所有审批列表中展示。可传多个值，最多展示前 3 个。
      └ namestring表单字段名称。这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
      └ valuestring表单值。这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
    └ user_idstring审批发起人 user_id。发起人可在审批中心的 已发起 列表中看到所有已发起的审批。在 待办、已办、抄送我 列表中，该字段用来展示审批的发起人。
    └ user_namestring审批发起人的用户名。如果发起人不是真实的用户（例如是某个部门），没有 user_id，则可以使用该参数传入一个名称。
说明：这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
    └ open_idstring审批发起人 open_id。发起人可在审批中心的 已发起 列表中看到所有已发起的审批。在 待办、已办、抄送我 列表中，该字段用来展示审批的发起人。
    └ department_idstring发起人的部门 ID，用于在审批中心列表中展示发起人的所属部门，不传值则不展示。
说明：如果用户没加入任何部门，请求时传 "" 默认展示企业名称。如果请求时传入 department_name 参数，则展示对应的部门名称。
    └ department_namestring审批发起人的部门名称。如果发起人不是真实的用户或没有部门，则可以使用该参数传入部门名称。
说明：这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
    └ start_timestring审批发起时间，Unix 毫秒时间戳。
    └ end_timestring审批实例结束时间。未结束的审批为 0，Unix 毫秒时间戳。
    └ update_timestring审批实例最近更新时间，Unix 毫秒时间戳，用于推送数据版本控制。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批实例信息。 说明：使用该参数主要用来避免并发时，旧数据更新了新数据。
    └ display_methodstring列表页打开审批实例的方式
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管打开
    └ update_modestring更新方式。 - 当 update_mode 取值为 REPLACE 时，每次都以当前推送的数据为最终数据，会删掉审批中心中，不在本次推送数据中的多余的任务、抄送数据。 - 当 update_mode 取值为 UPDATE 时，不会删除审批中心的数据，而只进行新增、更新实例与任务数据。
可选值有：
- REPLACE: 全量替换 - UPDATE: 增量更新
    └ task_listexternal_instance_task_node\[\]任务列表
      └ task_idstring审批实例内，审批任务的唯一标识，用于更新审批任务时定位数据。
      └ user_idstring审批人 user_id，该任务会出现在审批人的飞书审批中心 待办 或 已办 的列表中。
      └ open_idstring审批人 open_id，该任务会出现在审批人的飞书审批中心 待办 或 已办 的列表中。
      └ titlestring审批任务名称。这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
      └ linksexternal_instance_link在审批中心 待办、已办 中使用的三方审批跳转链接，用于跳转回三方审批系统查看任务详情。
        └ pc_linkstringPC 端的跳转链接。当用户使用飞书 PC 端查看任务详情时，通过该链接进行跳转。
        └ mobile_linkstring移动端的跳转链接。当用户使用飞书移动端查看任务详情时，通过该链接进行跳转。
      └ statusstring任务状态
可选值有：
- PENDING: 待审批 - APPROVED: 任务同意 - REJECTED: 任务拒绝 - TRANSFERRED: 任务转交 - DONE: 任务通过但审批人未操作。审批人看不到该任务时，如需查看可抄送至该审批人。
      └ extrastring扩展字段。JSON 格式，传值时需要压缩转义为字符串。 任务结束原因需传 complete_reason 参数，枚举值说明：
- approved：同意 - rejected：拒绝 - node_auto_reject：因逻辑判断产生的自动拒绝 - specific_rollback：退回（包括退回到发起人、退回到中间任一审批人） - add：并加签（添加新审批人，与我一起审批） - add_pre：前加签（添加新审批人，在我之前审批） - add_post：后加签（添加新审批人，在我之后审批） - delete_assignee：减签 - forward: 手动转交 - forward_resign：离职自动转交 - recall：撤销（撤回单据，单据失效） - delete ：删除审批单 - admin_forward：管理员在后台操作转交 - system_forward：系统自动转交 - auto_skip：自动通过 - manual_skip：手动跳过 - submit_again：重新提交任务 - restart：重新启动流程 - others：其他
      └ create_timestring任务创建时间，Unix 毫秒时间戳。
      └ end_timestring任务完成时间。未结束的审批为 0，Unix 毫秒时间戳。
      └ update_timestring任务最近更新时间，Unix 毫秒时间戳，用于推送数据版本控制。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批任务信息。
      └ action_contextstring操作上下文。当用户操作审批时，回调请求中会包含该参数，用于传递该任务的上下文数据。
      └ action_configsaction_config\[\]任务级别的快捷审批操作配置。 注意：快捷审批目前仅支持在飞书移动端操作。
        └ action_typestring操作类型。每个任务都可以配置两个操作（同意、拒绝或任意中的两个），操作会展示审批列表中。当用户操作时，回调请求会包含该字段，三方审批可接受到审批人的操作数据。
可能值有：
- APPROVE: 同意 - REJECT: 拒绝 - {KEY}: 任意字符串。如果使用任意字符串，则需要提供 action_name
        └ action_namestring操作名称。如果 action_type 不等于 APPROVAL 或 REJECT，则必须提供该字段，用于展示特定的操作名称。 说明：这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
        └ is_need_reasonboolean是否需要审批意见。取值为 true 时，审批人在审批中心操作任务后，还需要跳转填写审批意见。
        └ is_reason_requiredboolean审批意见是否必填
        └ is_need_attachmentboolean意见是否支持上传附件
      └ display_methodstring列表页打开审批任务的方式
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管模式打开
      └ exclude_statisticsboolean三方审批任务是否不纳入效率统计。可能值有：
- true：不纳入效率统计 - false：纳入效率统计
      └ node_idstring审批节点 ID。必须同时满足：
- 一个审批流程内，每个节点 ID 唯一。例如，一个流程下直属上级、隔级上级等节点的 node_id 均不一样。 - 同一个三方审批定义内，不同审批实例中的相同节点，node_id 要保持不变。例如，用户 A 和用户 B 分别发起了请假申请，这两个审批实例中的直属上级节点的 node_id 应该保持一致。
      └ node_namestring节点名称，这里返回的是 i18n_resources.texts 参数的 key，对应的取值需要参见返回的 i18n_resources.texts.value。
      └ generate_typestring任务生成类型
可选值有：
- EXTERNAL_CONSIGN: 给代理人生成的任务 - DEFAULT: 默认情况，可不填， 但是不要填空字符串
    └ cc_listcc_node\[\]抄送列表
      └ cc_idstring审批实例内抄送唯一标识
      └ user_idstring抄送人的 user_id
      └ open_idstring抄送人的 open_id
      └ linksexternal_instance_link审批抄送跳转链接。设置的链接用于在审批中心 抄送我 列表内点击跳转，跳回三方审批系统查看审批抄送详情。
        └ pc_linkstringPC 端的三方审批实例跳转链接。当用户使用飞书 PC 端查看审批抄送时，通过该字段进行跳转。
        └ mobile_linkstring移动端的三方审批实例跳转链接。当用户使用飞书移动端查看审批抄送时，通过该字段进行跳转。
      └ read_statusstring抄送人的阅读状态
可选值有：
- READ: 已读 - UNREAD: 未读
      └ extrastring扩展字段 JSON
      └ titlestring抄送任务名称
      └ create_timestring抄送发起时间，Unix 毫秒时间戳。
      └ update_timestring抄送最近更新时间，Unix 毫秒时间戳，用于推送数据版本。如果 update_mode 值为 UPDATE，则仅当传过来的 update_time 有变化时（变大），才会更新审批中心中的审批实例信息。
      └ display_methodstring列表页打开审批任务的方式
可选值有：
- BROWSER: 跳转系统默认浏览器打开 - SIDEBAR: 飞书中侧边抽屉打开 - NORMAL: 飞书内嵌页面打开 - TRUSTEESHIP: 以托管模式打开
    └ i18n_resourcesi18n_resource\[\]国际化文案
      └ localestring语言
可选值有：
- zh-CN: 中文 - en-US: 英文 - ja-JP: 日文 - zh-HK: 繁体中文（中国香港） - zh-TW: 繁体中文（中国台湾） - de-DE: 德语 - es-ES: 西班牙语 - fr-FR: 法语 - id-ID: 印度尼西亚语 - it-IT: 意大利语 - ko-KR: 韩语 - pt-BR: 葡萄牙语 - th-TH: 泰语 - vi-VN: 越南语 - ms-MY: 马来语 - ru-RU: 俄语
      └ textsi18n_resource_text\[\]文案的 Key:Value。Key 需要以 @i18n@ 开头，并按照各个参数的要求传入 Value。该字段主要用于做国际化，允许用户同时传多个语言的文案，审批中心会根据用户当前的语音环境使用对应的文案，如果没有传用户当前的语音环境文案，则会使用默认的语言文案。
        └ keystring文案 Key，和各个参数 Key 相匹配。
        └ valuestring文案 Value，即文案 Key 对应的参数值。
      └ is_defaultboolean是否为默认语言。默认语言需要包含所有所需的文案 Key，非默认语言如果 Key 不存在，则会使用默认语言代替。
    └ trusteeship_url_tokenstring单据托管认证 token，托管回调会附带此 token，帮助业务认证。
    └ trusteeship_user_id_typestring用户的类型，会影响请求参数用户标识域的选择，包括加签操作回传的目标用户， 目前仅支持 user_id。
    └ trusteeship_urlstrusteeship_urls单据托管回调接入方的接口 URL 地址
      └ form_detail_urlstring获取表单 schema 相关数据的 URL 地址
      └ action_definition_urlstring表示获取审批操作区数据的 URL 地址
      └ approval_node_urlstring获取审批记录相关数据的 URL 地址
      └ action_callback_urlstring进行审批操作时回调的 URL 地址
      └ pull_business_data_urlstring获取托管动态数据 URL 地址。使用该接口时，必须要保证历史托管单据的数据中都同步了该接口地址。如果历史单据中没有该接口，需要重新同步历史托管单据的数据来更新该 URL。该接口用于飞书审批前端和业务进行交互使用，只有使用审批前端的特定组件（由飞书审批前端提供的组件，并且需要和业务进行接口交互的组件）才会需要。
    └ trusteeship_cache_configtrusteeship_instance_cache_config托管预缓存策略
      └ form_policystring托管预缓存策略
可选值有：
- DISABLE: 不启用，默认 - IMMUTABLE: 表单不会随流程进行改变 - BY_NODE: 跟随流程节点变更更新缓存 - BY_USER: 对于每个待办任务存储一份
      └ form_vary_with_localeboolean表单是否随国际化改变
      └ form_versionstring当前使用的表单版本号，保证表单改变后，版本号增加，实际值为 int64 整数。
    └ resource_regionstring资源所在地区， 内部统计用字段， 不需要填

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "data": {
            "approval_code": "81D31358-93AF-92D6-7425-01A5D67C4E71",
            "status": "PENDING",
            "extra": "{\"xxx\":\"xxx\",\"business_key\":\"xxx\"}",
            "instance_id": "24492654",
            "links": {
                "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
            },
            "title": "@i18n@1",
            "form": [
                {
                    "name": "@i18n@2",
                    "value": "@i18n@3"
                }
            ],
            "user_id": "a987sf9s",
            "user_name": "@i18n@9",
            "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
            "department_id": "od-8ec33278bc2",
            "department_name": "@i18n@10",
            "start_time": "1556468012678",
            "end_time": "1556468012678",
            "update_time": "1556468012678",
            "display_method": "BROWSER",
            "update_mode": "UPDATE",
            "task_list": [
                {
                    "task_id": "112534",
                    "user_id": "a987sf9s",
                    "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
                    "title": "i18n1",
                    "links": {
                        "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                        "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
                    },
                    "status": "PENDING",
                    "extra": "{\"xxx\":\"xxx\",\"complete_reason\":\"approved\"}",
                    "create_time": "1556468012678",
                    "end_time": "1556468012678",
                    "update_time": "1556468012678",
                    "action_context": "123456",
                    "action_configs": [
                        {
                            "action_type": "APPROVE",
                            "action_name": "@i18n@5",
                            "is_need_reason": false,
                            "is_reason_required": false,
                            "is_need_attachment": false
                        }
                    ],
                    "display_method": "BROWSER",
                    "exclude_statistics": false,
                    "node_id": "node",
                    "node_name": "i18n@name",
                    "generate_type": "EXTERNAL_CONSIGN"
                }
            ],
            "cc_list": [
                {
                    "cc_id": "123456",
                    "user_id": "12345",
                    "open_id": "ou_be73cbc0ee35eb6ca54e9e7cc14998c1",
                    "links": {
                        "pc_link": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/detail?id=1234",
                        "mobile_link": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/detail?id=1234"
                    },
                    "read_status": "READ",
                    "extra": "{\"xxx\":\"xxx\"}",
                    "title": "xxx",
                    "create_time": "1556468012678",
                    "update_time": "1556468012678",
                    "display_method": "BROWSER"
                }
            ],
            "i18n_resources": [
                {
                    "locale": "zh-CN",
                    "texts": [
                        {
                            "key": "@i18n@1",
                            "value": "people"
                        }
                    ],
                    "is_default": true
                }
            ],
            "trusteeship_url_token": "788981c886b1c28ac29d1e68efd60683d6d90dfce80938ee9453e2a5f3e9e306",
            "trusteeship_user_id_type": "user_id",
            "trusteeship_urls": {
                "form_detail_url": "https://#{your_domain}/api/form_detail",
                "action_definition_url": "https://#{your_domain}/api/action_definition",
                "approval_node_url": "https://#{your_domain}/api/approval_node",
                "action_callback_url": "https://#{your_domain}/api/action_callback",
                "pull_business_data_url": "https://#{your_domain}/api/pull_business_data"
            },
            "trusteeship_cache_config": {
                "form_policy": "DISABLE",
                "form_vary_with_locale": false,
                "form_version": "1"
            },
            "resource_region": "cn"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001390001param is invalid参数错误。排查方案： - 根据接口文档的参数说明，检查请求时传入的参数是否正确。 - 如果传入的有表单参数（form），则需要检查该参数内传入的表单控件数据是否正确。如果报错信息内包含控件 ID（如 控件= widget17261088448220001），可以调用查看指定审批定义或者获取单个审批实例详情接口，获取响应参数 form 值，检索有问题的控件 ID，然后检查该控件的配置是否正确。
4001395001There have been some errors. Please try again later服务出现错误。排查方案： 1. 参考接口文档的参数说明，检查请求时传入的参数是否正确。如果传入的有表单参数（form），则需要检查传入的表单控件数据是否正确。 2. 降低请求频率，短时间内不要同步相同的审批实例，请稍后重试。如果重试仍然报错，请联系技术支持。
4001390014tenant_id not found未找到指定租户。

更多错误码信息，参见通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有