PlatoForms User Guide
集成和 API
本页内容
追踪器显示的所有内容也可供其他系统使用：随着运行的移动，webhooks 会触发，REST API 读取运行并对任务进行操作，MCP 服务器向 AI 助手公开相同内容。
Webhooks
在 API 和 webhooks 下添加 webhook，并将 发送时间 设置为 工作流运行或任务更改。它接收团队的每个工作流，或者当您选择一个表单时，只接收使用该表单的工作流。每个调用都包含事件名称、运行以及（如果有）任务及其提交 ID：
| 事件 | 何时 |
|---|---|
workflow.run.started |
启动表单已提交。 |
workflow.run.restarted |
被拒绝的运行从 重新开始 按钮再次启动。 |
workflow.task.created |
一步被分配给某人。 |
workflow.task.completed |
表单步骤已提交。 |
workflow.task.decided |
批准已决定；有效负载包含结果和评论。 |
workflow.run.completed |
每个路径都已完成。 |
workflow.run.rejected |
退回结束了运行。 |
workflow.run.cancelled |
有人在追踪器中或通过 API 取消了运行。 |
单个表单上的表单级 webhook 在提交时继续触发。
REST API
API v4 对运行和任务具有读写访问权限。所有路由都位于 /api/v4/ 下：
| 方法和路由 | 功能 |
|---|---|
GET workflow/<workflow>/definition/ |
工作流的步骤和连接，只读。 |
GET workflow/<workflow>/runs/ |
工作流的运行，可按状态、受让人和逾期进行过滤，分页。 |
GET workflow/run/<run>/ |
一个运行及其任务和时间线。 |
GET workflow/run/<run>/final-pdf/ |
完成的 PDF 文件本身：当有批准记录页面时为包含该页面的副本，否则为最后一个表单自己的 PDF。 |
POST workflow/run/<run>/cancel/ |
取消运行，可选择提供原因。 |
GET workflow/tasks/ |
跨工作流的任务，可按受让人邮箱和状态过滤，适用于收件箱风格的客户端。 |
POST workflow/task/<task>/decide/ |
决定一个批准任务：结果和评论。 |
POST workflow/task/<task>/nudge/ |
重新发送任务的电子邮件。 |
POST workflow/task/<task>/reassign/ |
将任务交给一个电子邮件地址或团队成员。 |
用于提交工作流步骤和按步骤列出工作流提交的旧路由保持不变。
谁可以读取和操作
REST 路由和 MCP 工具遵循与跟踪器相同的访问规则：
- 只有在工作流的每个表单上都是 表单提交查看者 的账户才能列出或读取工作流的运行、任务、提交 ID、树结构和运行详情。其他任何账户都会收到说明原因的 403 回复：“You need Form Submission Viewer permission on every form in this workflow.” 不存在的工作流或运行仍会被报告为不存在。
- 定义也对可以设计工作流的人开放（每个表单上的 表单编辑者）。
GET workflows/只列出该账户可以设计或查看的工作流。 - 提醒、重新分配和取消需要与跟踪器按钮相同的访问权限；重新分配审批还需要每个表单上的 表单编辑者 权限。
- 决定审批需要该账户是该审批的受让人。
- 只有任务的受让人和在表单任务中可以对运行采取行动的人才能包含开放任务的链接。对提醒的回答不包含链接。
MCP 工具
PlatoForms MCP 服务器 为 AI 助手提供相同的视图：list_workflow_runs（按工作流、状态或逾期）、get_workflow_run、list_my_workflow_tasks、decide_workflow_task 和 nudge_workflow_task。决定任务要求连接的用户是其受让人之一，因此助手可以代表您批准，但不能代表其他人。