# 按模板批量生成二维码

适用于你已经有一个批量模板，要从业务系统把一批设备、人员或物料生成子码。

## 前置条件

- [个人 API Key](https://cli.im/open-api/openapi/v2/auth.md#create-key) 的权限为「读写」或「完全」。组织 Key 不能调这些接口。
- 当前成员对目标模板所在分区有生成二维码权限。
- 所有接口都是 `POST https://open.cli.im/api/v2/rpc/{路径}`，请求体直接传 JSON，成功数据在响应的 `data` 里。字段的完整定义见 [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)。

## 调用顺序

| 步骤 | 接口 | 作用 |
|---|---|---|
| 1 | `templates/listEditable` | 找到要用的模板 |
| 2 | `templates/getSchema` | 取模板版本和每个字段的 `field_id` |
| 3 | `assets/requestUpload`、`assets/getUpload` | 有图片或附件时先上传，没有就跳过 |
| 4 | `qrcodes/prevalidate` | 校验整批数据，不生成二维码 |
| 5 | `qrcodes/createBatch` | 提交生成二维码任务 |
| 6 | `qrcodeTasks/get` | 轮询任务进度 |
| 7 | `qrcodeTasks/getResults` | 逐项取回码 ID 和链接 |

### 第 1 步：找到模板

```bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/templates/listEditable' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"page": 1, "page_size": 20}'
```

返回模板摘要。`has_more` 为 true 时继续翻页，遇到空页也要看 `has_more`。记下目标模板的 `template_id`。

### 第 2 步：取字段和版本

```json
{"template_id": "<template_id>"}
```

发送到 `templates/getSchema`。从返回里取三样东西：

- `template_version`：后面两步都要原样带上。模板被改过后版本会变，需要重新读取。
- 字段列表：`variable` 为 true 的字段是每个子码各自填写的，用它的 `field_id` 作为取值的键。
- `capabilities.create_children`：为 true 才能在这个模板下生成子二维码。

### 第 3 步：上传图片和附件（可选） {#upload}

字段是图片或文件类型时，不能直接传外部链接，要先上传拿到 `file_key`。

1. 调 `assets/requestUpload` 申请上传。`size` 是文件的实际字节数，最大 20 MiB；`mime_type` 要和上传时的 `Content-Type` 一致。

   ```json
   {
     "file_name": "boiler-01.jpg",
     "mime_type": "image/jpeg",
     "size": 482133,
     "idempotency_key": "upload-boiler-01-20261118"
   }
   ```

2. 返回里有 `file_key`、状态和 `upload`。按 `upload.method`（PUT）把文件原始字节发到 `upload.url`，并原样带上 `upload.headers` 里的全部请求头。这个请求直接发给存储服务，不要带 `Authorization`，也不要用 multipart 或 base64。
3. 调 `assets/getUpload` 传 `{"file_key": "<file_key>"}` 查状态。只有 `temporary_available` 才能引用；`uploading` 时稍后再查，`failed`、`expired` 需要重新申请。
4. 生成二维码时在对应字段里写 `[{"file_key": "<file_key>"}]`。

临时文件有有效期，上传后尽快完成生成二维码。

### 第 4 步：预校验

```json
{
  "template_id": "<template_id>",
  "template_version": "<template_version>",
  "save_plan": true,
  "items": [
    {
      "item_key": "EQ-001",
      "name": "1 号锅炉",
      "values": {
        "<field_id_位置>": "动力车间东侧",
        "<field_id_照片>": [{"file_key": "<file_key>"}]
      }
    },
    {
      "item_key": "EQ-002",
      "name": "2 号锅炉",
      "values": {"<field_id_位置>": "动力车间西侧"}
    }
  ]
}
```

发送到 `qrcodes/prevalidate`。

- `item_key` 是你自己系统里的稳定标识（设备编号、工号等），后面用它对照每一项的结果。
- 一批最多 100 条，请求体最多 1 MiB，更多数据拆成多批。
- 不传 `category_id` 时，子码放进与模板同名的目录。
- 预校验不生成二维码。返回 `valid`、`requested_count`、`errors`、`warnings` 和样例。`valid` 为 true 且传了 `save_plan: true` 时，还会返回 `plan_id`，30 分钟内有效。
- 有 `errors` 就按提示修正后重新校验。

### 第 5 步：提交任务

```json
{"plan_id": "<plan_id>", "idempotency_key": "eq-import-20261118-batch-01"}
```

发送到 `qrcodes/createBatch`。用了 `plan_id` 就不用再传 `items`。

返回 `task_id`、`batch_id`、`status`、`total`、`processed_count` 和 `poll_after_seconds`。任务进入队列不代表码已经建好。

**幂等键**
`idempotency_key` 由你生成，一批数据固定一个。请求超时或结果不明时，用**同一个键和同样的参数**重试，服务会返回原来的任务，不会重复生成二维码。换一个键重试会建出两批码。


### 第 6 步：轮询进度

```json
{"task_id": "<task_id>"}
```

发送到 `qrcodeTasks/get`，按返回的 `poll_after_seconds` 间隔查询，直到 `status` 不再是进行中。整体 `succeeded` 只说明任务跑完了，每一项是否成功要看下一步。

### 第 7 步：逐项取结果

```json
{"task_id": "<task_id>", "page": 1, "page_size": 100}
```

发送到 `qrcodeTasks/getResults`，翻页到 `has_more` 为 false。每一项带 `item_key`、状态、`qrcode_id`、`coding` 和 `web_url`。用 `item_key` 对照你提交的清单：

- `succeeded`：码已建好，字段和图片都已保存。
- `content_pending`：码已建好，内容还在处理，稍后再查。
- 失败项带错误原因，修正后只重新提交失败的条目，用新的幂等键。

## 相关接口

- 只建一个码：`qrcodes/create`（普通码）、`qrcodes/createUrlJump`（跳转码）、`qrcodes/createMultiUrl`（聚合码）、`staticQrcodes/create`（静态码）。
- 没有现成模板：`templates/create` 新建，或用官方模板，见[管理接口](https://cli.im/open-api/openapi/v2/management.md)。
- 建完要打印：见[导出标签](https://cli.im/open-api/openapi/v2/scenarios/export-labels.md)。
- 遇到 429：见[调用额度](https://cli.im/open-api/openapi/v2/error-codes.md#rate-limit)。
