Skip to content

按模板批量生成二维码 ​

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

前置条件 ​

  • 个人 API Key 的权限为「读写」或「完全」。组织 Key 不能调这些接口。
  • 当前成员对目标模板所在分区有生成二维码权限。
  • 所有接口都是 POST https://open.cli.im/api/v2/rpc/{路径},请求体直接传 JSON,成功数据在响应的 data 里。字段的完整定义见 openapi.json。

调用顺序 ​

步骤接口作用
1templates/listEditable找到要用的模板
2templates/getSchema取模板版本和每个字段的 field_id
3assets/requestUpload、assets/getUpload有图片或附件时先上传,没有就跳过
4qrcodes/prevalidate校验整批数据,不生成二维码
5qrcodes/createBatch提交生成二维码任务
6qrcodeTasks/get轮询任务进度
7qrcodeTasks/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 步:上传图片和附件(可选) ​

字段是图片或文件类型时,不能直接传外部链接,要先上传拿到 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 新建,或用官方模板,见管理接口。
  • 建完要打印:见导出标签。
  • 遇到 429:见调用额度。