按模板批量生成二维码
适用于你已经有一个批量模板,要从业务系统把一批设备、人员或物料生成子码。
前置条件
- 个人 API Key 的权限为「读写」或「完全」。组织 Key 不能调这些接口。
- 当前成员对目标模板所在分区有生成二维码权限。
- 所有接口都是
POST https://open.cli.im/api/v2/rpc/{路径},请求体直接传 JSON,成功数据在响应的data里。字段的完整定义见 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 步:找到模板
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 步:取字段和版本
{"template_id": "<template_id>"}发送到 templates/getSchema。从返回里取三样东西:
template_version:后面两步都要原样带上。模板被改过后版本会变,需要重新读取。- 字段列表:
variable为 true 的字段是每个子码各自填写的,用它的field_id作为取值的键。 capabilities.create_children:为 true 才能在这个模板下生成子二维码。
第 3 步:上传图片和附件(可选)
字段是图片或文件类型时,不能直接传外部链接,要先上传拿到 file_key。
调
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" }返回里有
file_key、状态和upload。按upload.method(PUT)把文件原始字节发到upload.url,并原样带上upload.headers里的全部请求头。这个请求直接发给存储服务,不要带Authorization,也不要用 multipart 或 base64。调
assets/getUpload传{"file_key": "<file_key>"}查状态。只有temporary_available才能引用;uploading时稍后再查,failed、expired需要重新申请。生成二维码时在对应字段里写
[{"file_key": "<file_key>"}]。
临时文件有有效期,上传后尽快完成生成二维码。
第 4 步:预校验
{
"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 步:提交任务
{"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 步:轮询进度
{"task_id": "<task_id>"}发送到 qrcodeTasks/get,按返回的 poll_after_seconds 间隔查询,直到 status 不再是进行中。整体 succeeded 只说明任务跑完了,每一项是否成功要看下一步。
第 7 步:逐项取结果
{"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:码已建好,内容还在处理,稍后再查。- 失败项带错误原因,修正后只重新提交失败的条目,用新的幂等键。