# Local API 参考

浏览器 RPA Local API 由 MoreLogin 桌面客户端 V2.73.0 或更高版本提供，地址为 `http://127.0.0.1:<port>/api/rpa/browser/v1`。端口以客户端设置中 Local API 的端口为准，默认是 `40000`。

认证方式与其他 Local API 相同，见[认证](/zh/api-reference/getting-started/authentication)。JSON 正文使用 `Content-Type: application/json`。成功响应为 `{data,meta}`，错误响应为 `{error,meta}`；认证失败使用 Local API 标准的 401 格式。错误处理依据 HTTP 状态、`error.code`、`details` 和 issue 的 `path`，不要解析提示文案。完整规则见[公共约定](/zh/browser-rpa/api/common)。

## 接口目录

### 能力与节点

| 接口 | 方法与路径 |
|  --- | --- |
| [获取 RPA 能力](/zh/browser-rpa/api/get-capabilities) | `GET /capabilities` |
| [查询节点类型](/zh/browser-rpa/api/list-node-types) | `GET /node-types` |
| [获取节点契约](/zh/browser-rpa/api/get-node-type) | `GET /node-types/{nodeType}` |


### 流程校验

| 接口 | 方法与路径 |
|  --- | --- |
| [校验流程](/zh/browser-rpa/api/validate-workflow) | `POST /validations` |


### 模板与节点编辑

| 接口 | 方法与路径 |
|  --- | --- |
| [查询模板列表](/zh/browser-rpa/api/list-templates) | `GET /templates` |
| [创建模板](/zh/browser-rpa/api/create-template) | `POST /templates` |
| [获取模板详情](/zh/browser-rpa/api/get-template) | `GET /templates/{templateId}` |
| [完整更新模板](/zh/browser-rpa/api/replace-template) | `PUT /templates/{templateId}` |
| [删除模板](/zh/browser-rpa/api/delete-template) | `DELETE /templates/{templateId}` |
| [复制模板](/zh/browser-rpa/api/copy-template) | `POST /templates/{templateId}/copies` |
| [查询模板节点](/zh/browser-rpa/api/list-template-nodes) | `GET /templates/{templateId}/nodes` |
| [批量修改模板节点](/zh/browser-rpa/api/edit-template-nodes) | `POST /templates/{templateId}/node-edits` |


### 运行与结果

| 接口 | 方法与路径 |
|  --- | --- |
| [启动模板运行](/zh/browser-rpa/api/start-run) | `POST /runs` |
| [查询执行记录](/zh/browser-rpa/api/list-runs) | `GET /runs` |
| [获取运行详情](/zh/browser-rpa/api/get-run) | `GET /runs/{runId}` |
| [取消运行](/zh/browser-rpa/api/cancel-run) | `POST /runs/{runId}/cancel` |
| [查询节点执行结果](/zh/browser-rpa/api/list-run-nodes) | `GET /runs/{runId}/nodes` |
| [查询运行产物](/zh/browser-rpa/api/list-run-artifacts) | `GET /runs/{runId}/artifacts` |


### 请求恢复

| 接口 | 方法与路径 |
|  --- | --- |
| [查询请求处理结果](/zh/browser-rpa/api/get-request-receipt) | `GET /requests/{key}` |


### 共享参考

- [公共约定](/zh/browser-rpa/api/common)
- [公共数据模型](/zh/browser-rpa/api/data-types)
- [Workflow、变量与结构节点契约](/zh/browser-rpa/api/workflow)
- [错误码](/zh/browser-rpa/api/error-codes)
- [错误详情与恢复矩阵](/zh/browser-rpa/api/recovery)
- [运行观察与请求恢复](/zh/browser-rpa/api/observation)


## 写请求所需的请求头

| 接口 | `Idempotency-Key` | `X-RPA-Catalog-Revision` | `If-Match` |
|  --- | --- | --- | --- |
| [创建模板](/zh/browser-rpa/api/create-template) | 建议传入 | 必填 | — |
| [完整更新模板](/zh/browser-rpa/api/replace-template) | 建议传入 | 必填 | 必填 |
| [删除模板](/zh/browser-rpa/api/delete-template) | 建议传入 | 不需要 | 必填 |
| [复制模板](/zh/browser-rpa/api/copy-template) | 建议传入 | 必填 | 必填，使用源模板的 ETag |
| [批量修改模板节点](/zh/browser-rpa/api/edit-template-nodes) | 建议传入 | 必填 | 必填 |
| [启动模板运行](/zh/browser-rpa/api/start-run) | 建议传入 | 必填 | — |
| [取消运行](/zh/browser-rpa/api/cancel-run) | 建议传入 | 不需要 | — |


`Idempotency-Key` 可选，但不传时，超时后的重试可能重复执行写入。每次新的写入意图生成新的 UUID，并连同方法、路径、正文和 `If-Match` 一起保留，直到确认结果。`If-Match` 填[获取模板详情](/zh/browser-rpa/api/get-template)返回的原样 `ETag`。`X-RPA-Catalog-Revision` 填[获取 RPA 能力](/zh/browser-rpa/api/get-capabilities)返回的 `data.catalogRevision`。[校验流程](/zh/browser-rpa/api/validate-workflow)是只读请求，不需要这些请求头，也不产生请求收据。

## 本机契约

在本机 API 地址后加 `/openapi.json`，即可获取 HTTP 契约。调用 `GET /capabilities` 后，从 `data.docs.schema` 读取工作流 Schema 地址。

## 修改既有模板

先读取最新模板、节点及所用节点契约。局部修改优先使用 `node-edits`：将操作应用于完整候选树后，使用 `purpose:"save"`、`source.kind:"inline"` 和 `source.base:{templateId,version}` 校验候选，再提交操作数组。一次批量编辑要么全部保存为一个新版本，要么不保存。替换节点时提交完整节点与 blocks；删除节点时一并修复引用。完整覆盖用 PUT。子模板依赖填写读回的 `{processId,revisionId}`；依赖版本冲突时重新读取。

## 恢复

| 情况 | 下一步 |
|  --- | --- |
| 写入超时、断线或结果未知 | 先查 `GET /requests/{原始 key}`。`completed` 使用原结果；运行登记完成后仍须查询运行终态。`accepted` 或 `committed` 在有限时间内轮询；`unknown`、普通 404 或收据过期都不能证明未提交，停止自动写入并核对资源。 |
| 明确返回 `RPA_REQUEST_NOT_COMMITTED` 且 `safeToRetrySameKey=true` | 可用原 key、方法、路径、正文和适用的 `If-Match` 恢复同一意图。 |
| 412 版本冲突 | 先查收据；确认未提交后读取最新模板、合并并重新校验，再用新 key 和当前 ETag 提交。 |
| 目录版本变更 | 查收据并确认未提交，然后刷新能力和契约；请求正文及 `If-Match` 不变时，只更新目录头并复用原 key。 |
| 校验 `valid=false` 或确定性的输入错误 | 按 issue 的 path 修复并重新校验。若写请求已登记为 failed，确认无业务提交后再用新 key。遇到 429 或 503 时遵循 `Retry-After` 及收据规则。 |


需要运行已保存的模板时，见[通过 API 运行模板](/zh/browser-rpa/run-api-example)。