修改和删除二维码、表单
适用于业务系统要更新已有码的内容,或清理不再使用的码和表单。
能改什么取决于权限档位
| 档位 | 修改 | 删除 |
|---|---|---|
| 只读 | 不能 | 不能 |
| 读写 | 只能改通过接口(API 或 MCP)创建的内容 | 不能 |
| 完全 | 还能改成员在后台手工创建的内容 | 能 |
实际生效的是组织最高权限和 Key 档位里较低的一个,并且成员本人要对目标有管理权限。组织 Key 不能调这些接口。
所有接口都是 POST https://open.cli.im/api/v2/rpc/{路径},请求体直接传 JSON,成功数据在响应的 data 里。
修改
修改分两步:先读当前状态拿到 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,来自活码列表的 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在保存时带上。 - 静态码:内容不能改,需要重新创建。
删除
删除也分两步:先预览拿到确认令牌,再凭令牌删除。需要「完全」档。
| 对象 | 先预览 | 再删除 | 限制 |
|---|---|---|---|
| 普通码、跳转码、聚合码、子码 | 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_token10 分钟内有效,过期或目标变了就重新预览。- 返回的
status为succeeded表示全部删除;partial_success时分别看已删除和出错的条目。 - 结果不明时用同一个
idempotency_key和同样的参数重试。
删除后可以在后台「设置 → 操作日志」里恢复,接口不提供恢复。
常见返回
| 返回 | 处理 |
|---|---|
HTTP 403 credential_type_not_allowed | 正在用组织 Key,换成个人 API Key |
AI_DELETE_DISABLED | 组织最高权限不到「完全」,请超级管理员调整组织策略 |
ACCESS_LEVEL_READ_ONLY | 组织最高权限是「只读」,所有写入都会被拒绝 |
| HTTP 429 | 见调用额度 |