# 修改和删除二维码、表单

适用于业务系统要更新已有码的内容，或清理不再使用的码和表单。

## 能改什么取决于权限档位

| 档位 | 修改 | 删除 |
|---|---|---|
| 只读 | 不能 | 不能 |
| 读写 | 只能改通过接口（API 或 MCP）创建的内容 | 不能 |
| 完全 | 还能改成员在后台手工创建的内容 | 能 |

实际生效的是[组织最高权限](https://cli.im/open-api/openapi/v2/auth.md#org-policy)和 Key 档位里较低的一个，并且成员本人要对目标有管理权限。组织 Key 不能调这些接口。

所有接口都是 `POST https://open.cli.im/api/v2/rpc/{路径}`，请求体直接传 JSON，成功数据在响应的 `data` 里。

## 修改 {#edit}

修改分两步：先读当前状态拿到 `version`，再带着 `version` 提交。

| 对象 | 先读 | 再改 |
|---|---|---|
| 普通码、图文展示码 | `qrcodes/getEditState` | `qrcodes/edit` |
| 跳转码 | `qrcodes/getEditState` | `qrcodes/editUrlJump` |
| 聚合码 | `qrcodes/getEditState` | `qrcodes/editMultiUrl` |
| 批量模板下的子码 | `qrcodes/getEditState` | `qrcodeChildren/edit` |
| 表单 | `forms/getEditState` | `forms/edit` |
| 批量模板本身 | `templates/getSchema` | `templates/previewEdit`，再 `templates/edit` |

### 第 1 步：读当前状态

```bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/getEditState' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_id": "<qrcode_id>"}'
```

`qrcode_id` 是数字 ID，来自[活码列表](https://cli.im/open-api/openapi/v2/api/qrcodes-list.md)的 `id` 或生成二维码时的返回，不是 `coding`。

返回 `kind`、`version`、`editable` 和 `reason`。子码带 `fields`，普通码带 `components`，网址类的码带链接。`editable` 为 false 时不要提交，按 `reason` 处理：

| reason | 含义 |
|---|---|
| `AI_EDIT_NOT_AI_CREATED` | 这是成员手工创建的内容，组织最高权限不到「完全」 |
| `AI_EDIT_SCOPE_REQUIRED` | 这是成员手工创建的内容，当前 Key 不是「完全」档 |

### 第 2 步：提交修改

改一个子码的字段，发送到 `qrcodeChildren/edit`：

```json
{
  "qrcode_id": "<qrcode_id>",
  "version": "<version>",
  "idempotency_key": "eq-001-move-20261118",
  "values": {"<field_id_位置>": "动力车间南侧"}
}
```

- 没传的字段保持原值，不要传 `null`。
- 提交成功后返回新的 `version`，下次修改用新的。如果提示版本不一致，说明内容被别人改过，重新读状态再提交。
- 修改码的内容不会改变码的链接，已经印出去的码继续有效。

各对象的差别：

- **普通码**（`qrcodes/edit`）：`components` 是完整的有序清单。要保留的已有组件写成 `{"type": "keep", "ref": "<components[].ref>"}`，没列出的组件会被删除。只改名称时只传 `name`。
- **子码**（`qrcodeChildren/edit`）：`values` 只传要改的字段。不能改模板的公共字段。
- **表单**（`forms/edit`）：`fields` 是完整快照。可以改名称、必填、顺序，可以追加字段和选项；不能删字段、删选项或改字段类型。
- **批量模板**：先用 `templates/previewEdit` 看会影响多少子码，返回的 `preview_token` 在保存时带上。
- **静态码**：内容不能改，需要重新创建。

## 删除 {#delete}

删除也分两步：先预览拿到确认令牌，再凭令牌删除。需要「完全」档。

| 对象 | 先预览 | 再删除 | 限制 |
|---|---|---|---|
| 普通码、跳转码、聚合码、子码 | `qrcodes/previewDelete` | `qrcodes/delete` | 一次最多 20 个；不支持批量模板本身和静态码 |
| 表单 | `forms/previewDelete` | `forms/delete` | 一次最多 5 个；表单不能关联着任何码 |

### 第 1 步：预览

```json
{"qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"]}
```

发送到 `qrcodes/previewDelete`。预览不修改数据，返回 `items`（每个目标的名称、类型等）和 `confirm_token`。在你的系统里核对 `items` 确实是要删的对象。

### 第 2 步：删除

```json
{
  "qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"],
  "confirm_token": "<confirm_token>",
  "idempotency_key": "cleanup-20261118-01"
}
```

发送到 `qrcodes/delete`。

- `qrcode_ids` 必须和预览时完全相同。
- `confirm_token` 10 分钟内有效，过期或目标变了就重新预览。
- 返回的 `status` 为 `succeeded` 表示全部删除；`partial_success` 时分别看已删除和出错的条目。
- 结果不明时用同一个 `idempotency_key` 和同样的参数重试。

删除后可以在后台「设置 → 操作日志」里恢复，接口不提供恢复。

## 常见返回

| 返回 | 处理 |
|---|---|
| HTTP 403 `credential_type_not_allowed` | 正在用组织 Key，换成[个人 API Key](https://cli.im/open-api/openapi/v2/auth.md#create-key) |
| `AI_DELETE_DISABLED` | 组织最高权限不到「完全」，请超级管理员[调整组织策略](https://cli.im/open-api/openapi/v2/auth.md#org-policy) |
| `ACCESS_LEVEL_READ_ONLY` | 组织最高权限是「只读」，所有写入都会被拒绝 |
| HTTP 429 | 见[调用额度](https://cli.im/open-api/openapi/v2/error-codes.md#rate-limit) |
