# 码、模板与表单管理接口

使用[个人 API Key 或 OAuth](https://cli.im/open-api/openapi/v2/auth.md)，向 `https://open.cli.im/api/v2/rpc/` 加上下表路径发送 POST 请求。请求体直接传业务 JSON。各接口的请求字段与操作名见 [openapi.json](https://cli.im/open-api/openapi/v2/overview.md#%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-openapi-json)。这些接口不接受[历史组织 Key](https://cli.im/open-api/openapi/v2/auth.md#org-key)。

新建二维码时，[创建个人 Key](https://cli.im/open-api/openapi/v2/auth.md#create-key) 选「读写」即可。要修改成员手工创建的内容或删除时，先核对[组织最高权限](https://cli.im/open-api/openapi/v2/auth.md#org-policy)和凭证档位是否都为「完全」。

## 用官方模板创建一个码

先向 `gallery/get` 传入模板 ID，确认 `data.template.compatibility.can_create_single` 为 true，再将下例请求体发送到 `gallery/create-qrcode`。每次计划新建一个码时分配一个幂等键；超时或结果未知时，用原键和相同参数核对。响应中查看 `data.status`、`data.qrcode_id` 和 `data.web_url`。

```json
{"gallery_template_id":"57751068","name":"Boiler 01","idempotency_key":"boiler-01-install-001"}
```

## 按流程接入

多步流程有单独的场景页，带完整的调用顺序和请求示例：

- [按模板批量生成二维码](https://cli.im/open-api/openapi/v2/scenarios/batch-create-qrcodes.md)，包含[上传图片和附件](https://cli.im/open-api/openapi/v2/scenarios/batch-create-qrcodes.md#upload)
- [修改和删除码、表单](https://cli.im/open-api/openapi/v2/scenarios/edit-and-delete.md)
- [导出可打印的标签](https://cli.im/open-api/openapi/v2/scenarios/export-labels.md)

## 按任务查接口

每个接口的参数、权限和请求示例见[接口清单](https://cli.im/open-api/openapi/v2/api-index.md)里的链接。

| 任务 | 接口路径（省略 `/api/v2/rpc/`） |
|---|---|
| 查找官方模板、按方案批量生成二维码 | `gallery/categories`、`gallery/list`、`gallery/get`、`gallery/prepare-creation`、`gallery/create-from-plan` |
| 新建、预览或修改模板 | `templates/listEditable`、`templates/getSchema`、`templates/create`、`templates/previewEdit`、`templates/edit` |
| 生成二维码和查询批量结果 | `qrcodes/listCreateTargets`、`qrcodes/create`、`qrcodes/createUrlJump`、`qrcodes/createMultiUrl`、`staticQrcodes/create`、`qrcodes/prevalidate`、`qrcodes/createBatch`、`qrcodeTasks/get`、`qrcodeTasks/getResults` |
| 编辑码、创建和编辑表单 | `qrcodes/getEditState`、`qrcodes/edit`、`qrcodes/editUrlJump`、`qrcodes/editMultiUrl`、`qrcodeChildren/edit`、`forms/create`、`forms/getEditState`、`forms/edit` |
| 预览和执行删除 | `qrcodes/previewDelete`、`qrcodes/delete`、`forms/previewDelete`、`forms/delete` |
| 上传素材、预览和导出标签 | `assets/requestUpload`、`assets/getUpload`、`labels/getConfig`、`labels/preview`、`labelExports/create`、`labelExports/get` |
| 查周期计划、执行情况 | `cyclePlans/list`、`cyclePlans/get`、`cycleTasks/listQrcodes`、`cycleTasks/getCompletion` |
| 查询表单记录的后续动态 | `record/getActivities` |
| 查权限、查额度 | `auth/getContext`、`usage/get` |

批量生成二维码时，模板声明 `can_add_fields` 后才能用 `extra_fields` 追加字段。编辑模板正文时，先预览完整组件清单，遗漏的已有组件会被移除。删除时先预览 ID、核对返回对象，再提交同一批 ID、`confirm_token` 和幂等键。删除需「完全」权限；表单需先解除与码的关联。

重试规则见[组织限流与额度](https://cli.im/open-api/openapi/v2/error-codes.md#rate-limit)。
