Skip to content

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

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

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

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

实际生效的是组织最高权限和 Key 档位里较低的一个,并且成员本人要对目标有管理权限。组织 Key 不能调这些接口。

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

修改 ​

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

对象先读再改
普通码、图文展示码qrcodes/getEditStateqrcodes/edit
跳转码qrcodes/getEditStateqrcodes/editUrlJump
聚合码qrcodes/getEditStateqrcodes/editMultiUrl
批量模板下的子码qrcodes/getEditStateqrcodeChildren/edit
表单forms/getEditStateforms/edit
批量模板本身templates/getSchematemplates/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/previewDeleteqrcodes/delete一次最多 20 个;不支持批量模板本身和静态码
表单forms/previewDeleteforms/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
AI_DELETE_DISABLED组织最高权限不到「完全」,请超级管理员调整组织策略
ACCESS_LEVEL_READ_ONLY组织最高权限是「只读」,所有写入都会被拒绝
HTTP 429见调用额度