接入指南

接口能力

流程的开放接口提供了一系列安全、可靠的 API 接口和事件，来方便企业对流程信息进行查询和操作，通过 API 你可以实现以下功能：

流程相关信息查询：包括流程实例信息、审批任务信息、流程中的单据数据等信息查询
流程动态监控：可通过事件监听流程实例、流程节点、审批任务等状态变更动态
对流程进行操作：包括通过/拒绝审批任务等

接口分组

流程操作

代发起人进行流程相关操作

方法 (API)	权限要求	访问凭证
撤回流程`PUT`/open-apis/corehr/v2/process_withdraw/:process_id	`corehr:process.instance:write`	`tenant_access_token`
撤销流程`PUT`/open-apis/corehr/v2/process_revoke/:process_id	`corehr:process.instance:write`	`tenant_access_token`

代审批人进行相关操作

方法 (API)	权限要求	访问凭证
通过/拒绝审批任务`PUT`/open-apis/corehr/v2/processes/:process_id/approvers/:approver_id	`corehr:process.instance:write`	`tenant_access_token`
加签审批任务`PUT`/open-apis/corehr/v2/processes/:process_id/extra	`corehr:process.instance:write`	`tenant_access_token`
转交审批任务`PUT`/open-apis/corehr/v2/processes/:process_id/transfer	`corehr:process.instance:write`	`tenant_access_token`

流程信息查询

方法 (API)	权限要求	访问凭证
查询流程实例列表`GET`/open-apis/corehr/v2/processes	`corehr:process:read`	`tenant_access_token`
获取单个流程详情`GET`/open-apis/corehr/v2/processes/:process_id	`corehr:process:read`	`tenant_access_token`
获取流程表单数据`GET`/open-apis/corehr/v2/processes/:process_id/form_variable_data	`corehr:process:read`	`tenant_access_token`
获取指定人员审批任务列表`GET`/open-apis/corehr/v2/approvers	`corehr:process:read`	`tenant_access_token`

流程动态监控

事件（event）	权限要求	触发时机
流程实例状态变化	`corehr:process:read`	流程实例状态变化时会触发该事件
流程实例信息变更	`corehr:process:read`	流程中有审批人操作、流程数据更新、流程状态变化时会触发该事件
流程节点状态变更	`corehr:process:read`	流程中节点状态变化时会触发该事件
审批任务状态变更	`corehr:process:read`	单个审批任务状态变化时会触发该事件
抄送单据状态变更	`corehr:process:read`	生成抄送单据后会触发该事件

名词解释

名词	描述
流程定义	指管理员在设置侧配置的流程，类似流程模板，flow_definition_id 是其唯一标识。用户发起的流程是按照对应的流程定义的配置生成
流程实例	指用户在业务功能或者飞书人事的审批中心发起的具体流程，process_id 是其唯一标识
流程状态	流程状态是指整个流程实例的运行状态，随着审批人执行通过、拒绝等操作，流程状态会随之发生变化。流程状态包含以下几种状态： 1. 进行中：表示当前流程实例还在流转中，没有最终结果 1. 已完成：表示当前流程实例已经被通过 1. 已拒绝：表示当前流程实例已经被拒绝 1. 已撤回：表示当前还在“进行中”的流程实例已被发起人或审批单管理员撤回 1. 已撤销：表示当前“已完成”的流程实例已被发起人或审批单管理员撤销
流程节点	每一个审批流程由一或多个流程节点构成，每一个节点表示审批流转过程中的一个步骤，在当前节点完成后进入下一个节点。每当流程实例创建时，会生成该实例对应的各个流程节点，并由流程节点构成审批流程
审批任务	审批任务依赖于流程节点存在，每个流程节点可能包含有一或多个审批任务，每一个任务表明当前流程节点的审批人是谁
任务状态	任务状态是指审批任务的运行状态，随着审批人执行通过、拒绝等操作，任务状态会随之发生变化。任务状态包含以下几种状态： 1. 跳过：在审批任务运行时，由于满足特定条件，某个或某些审批节点会被自动忽略，流程直接进入下一个节点 1. 发起：表示当前审批任务已经被发起人发起 1. 未开始：表示当前审批任务尚未发起 1. 进行中：表示当前审批任务正在在进行中，没有最终结果 1. 已拒绝：表示当前审批任务已经被拒绝 1. 已通过：表示当前审批任务已经被通过，可流转到下一个审批任务 1. 被撤回：表示当前还在“进行中”的审批任务已经被发起人或审批单管理员进行撤回 1. 抄送：表示当前审批任务已经抄送给对应节点的抄送人 1. 表单提交：表示表单节点的操作人已经完成了表单提交操作 1. 失败：表示电子签节点签署失败 1. 已回退：表示当前审批任务已经完成了回退操作 1. 发起撤销：表示当前“已完成”的审批任务被发起人或审批单管理员撤销
业务类型	飞书People 流程支持飞书 People 中多个业务的审批流程（例如信息变更申请、离职等），不同的业务对应不同的业务类型。在不同业务类型下创建的流程将仅在对应的业务可以使用，且如果审批通过，会触发对应业务关联的系统作业（例如“信息变更申请”审批通过后，会自动更新员工的相关信息）。

接入流程

接入准备

1、创建应用

首先需要在飞书开放平台创建一个应用

2、申请调用流程接口和订阅事件所需要的权限

创建应用成功后，在开发配置 -> 权限管理页面申请所需要的权限

3、发布应用版本

api接入示例

接下来我们会尝试利用 Open API 查询指定员工的审批任务，并对该任务进行审批。

获得开放平台应用的 App ID 和 App Secret

在开放平台找到刚才发布通过了的应用，我们可以找到这个应用对应的 App ID 和 App Secret

使用服务端API

以Go语言为例，通过调用服务端API文档，构建出 API Client。

这里我们采用最简单的方式快速构建出一个 API Client 供我们接下来使用。

javascript

var client = lark.NewClient("YOUR_APP_ID", "YOUR_APP_SECRET") // 默认配置为自建应用

查询指定员工的审批任务

通过下面的代码我们可以查询到指定员工的审批任务，其中UserID等入参方式的获取方式可以参考获取指定人员审批任务列表的接口文档。

javascript

func main() {
	// 创建 Client
	client := lark.NewClient("YOUR_APP_ID", "YOUR_APP_SECRET")
	// 创建请求对象
	req := larkcorehr.NewListApproverReqBuilder().
		PageSize(20).
		UserIdType("open_id").
		UserId("123").
		Build()

	// 发起请求
	resp, err := client.Corehr.V2.Approver.List(context.Background(), req)

	// 处理错误
	if err != nil {
		fmt.Println(err)
		return
	}

	// 服务端错误处理
	if !resp.Success() {
		fmt.Printf("logId: %s, error response: \n%s", resp.RequestId(), larkcore.Prettify(resp.CodeError))
		return
	}

	// 业务处理
	fmt.Println(larkcore.Prettify(resp))
}

执行下面的代码后，可以在响应体的Data字段中获得形式如下的数据

json

{
    PageToken: "2",
    HasMore: false,
    ApproverList: [
      {
        ApproverId: "7444909165174081068",
        ProcessId: "7444909155858531884",
        ApproverStatus: 1
      },
      {
        ApproverId: "7444908178954798636",
        ProcessId: "7444908169433728556",
        ApproverStatus: 1
      },
      {
        ApproverId: "7444906172873721388",
        ProcessId: "7444906165458191916",
        ApproverStatus: 1
      }
  ]
}

根据响应体的定义可知：查询的员工有三个正在进行的审批任务。接下来可以根据响应体中的ApproverId和ProcessId对相应的审批任务进行审批。

通过/拒绝审批任务

在获取到流程实例ID和审批任务ID后，通过通过/拒绝审批任务接口实现对审批任务的处理。对于一个简单的审批任务，使用 Open API 通过审批的示例代码如下

javascript

func main() {
	// 创建 Client
	client := lark.NewClient("YOUR_APP_ID", "YOUR_APP_SECRET")
	// 创建请求对象
	req := larkcorehr.NewUpdateProcessApproverReqBuilder().
		ProcessId(`1`).
		ApproverId(`1`).
		ProcessApprover(larkcorehr.NewProcessApproverBuilder().
			Status(2).
			UserId(`ou_91791271921729102012`).
			SystemApproval(true).
			Reason(`原因自定义字符串`)
			Build()).
		Build()

	// 发起请求
	resp, err := client.Corehr.V2.ProcessApprover.Update(context.Background(), req)

	// 处理错误
	if err != nil {
		fmt.Println(err)
		return
	}

	// 服务端错误处理
	if !resp.Success() {
		fmt.Printf("logId: %s, error response: \n%s", resp.RequestId(), larkcore.Prettify(resp.CodeError))
		return
	}

	// 业务处理
	fmt.Println(larkcore.Prettify(resp))
}

事件订阅接入示例

1、配置事件订阅方式

事件订阅方式一共有两种，分别为“推送至开发者服务器”和“长连接”，详细区别可通过链接查看配置事件订阅方式，本示例使用的是长连接的方式来接收事件

2、添加要订阅的事件

添加所需订阅的事件后，当事件发生时，开放平台会向应用推送事件信息，以便应用快速响应事件

3、申请事件权限

添加事件后，还需为应用申请开通相关事件权限才能使订阅生效。应用权限包括接口调用权限和字段访问权限（针对部分敏感字段，需要额外申请字段访问权限）

本示例订阅的“流程实例状态变化”权限要求为“获取流程数据”，已在接入准备中申请过了，此处不再详细演示

4、接收并处理事件

以golang为例（其他示例代码可参考事件订阅示例代码），接收事件代码如下：

javascript

func main() {
	eventHandler := dispatcher.NewEventDispatcher("应用的 verificationToken", "应用的 eventEncryptKey（未设置可以填入空串）").
	OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
			fmt.Printf("[ OnP2MessageReceiveV1 access ], data: %s\n", larkcore.Prettify(event))
			return nil
		}).
	OnCustomizedEvent("此处写订阅事件的eventType", func(ctx context.Context, event *larkevent.EventReq) error {
			fmt.Printf("[ OnCustomizedEvent access ], type: message, data: %s\n", string(event.Body))
			return nil
		})
	// 创建Client
	cli := larkws.NewClient("应用的appId", "应用的appSecret",
		larkws.WithEventHandler(eventHandler),
		larkws.WithLogLevel(larkcore.LogLevelDebug),
	)
	// 启动客户端
	err := cli.Start(context.Background())
	if err != nil {
		panic(err)
	}
}

verificationToken和eventEncryptKey的获取方式

订阅事件eventType的获取方式

事件

事件

员工兼职

员工国际派遣

职位数据事件

事件

事件

事件

事件

事件

事件

事件

成本中心 · version

事件

事件

事件

事件

地点 · address

事件

事件

接入指南 ​

接口能力 ​

接口分组 ​

名词解释 ​

接入流程 ​

接入准备 ​

api接入示例 ​

事件订阅接入示例 ​

接入指南

接口能力

接口分组

名词解释

接入流程

接入准备

api接入示例

事件订阅接入示例