Skip to content

导出可打印的标签 ​

适用于码已经建好,要按后台设置的标签样式批量生成可打印的文件。

只需要二维码图片、不需要标签样式时,不用走这个流程:生成二维码接口和批量生成二维码结果里已经带了码图地址。

前置条件 ​

  • 个人 API Key。读取配置和预览「只读」档即可,创建导出任务需要「读写」或「完全」。组织 Key 不能调这些接口。
  • 目标码已经在后台关联了标签样式。
  • 所有接口都是 POST https://open.cli.im/api/v2/rpc/{路径},请求体直接传 JSON,成功数据在响应的 data 里。

调用顺序 ​

步骤接口作用
1labels/getConfig读取当前标签样式、尺寸和支持的导出格式
2labels/preview用少量真实的码生成预览,确认效果
3labelExports/create创建导出任务
4labelExports/get查询任务,取下载地址

第 1 步:读取配置 ​

bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/labels/getConfig' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_id": "<qrcode_id>"}'

qrcode_id 可以是普通码、子码或批量模板的 ID。返回当前关联的样式、标签上的字段、supported_formats 和一次可导出的数量上限。这个接口只读取,不会修改默认样式。

第 2 步:预览 ​

json
{"qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"]}

发送到 labels/preview,一次最多 3 个码。先看预览里的名称、字段和二维码是否符合预期,再导出整批。

第 3 步:创建导出任务 ​

json
{
  "qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>", "<qrcode_id_3>"],
  "format": "a4_pdf",
  "idempotency_key": "label-export-20261118-01"
}

发送到 labelExports/create,返回 task_id。format 从第 1 步的 supported_formats 里选:

format内容
png_zip每个标签一张图片
a4_pdfA4 纸上排多个标签
a4_pdf_singleA4 纸每页一个标签,多个码按页输出

三种格式下载到的都是 ZIP 包。

请求超时或结果不明时,用同一个 idempotency_key 和同样的参数重试,不会重复排队。

第 4 步:取下载地址 ​

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

发送到 labelExports/get。任务完成后返回文件链接,失败时返回原因。下载链接有时效,拿到后尽快下载。

常见返回 ​

返回处理
LABEL_FIELD_PERMISSION_DENIED标签上绑定了当前成员无权查看原文的字段。换一个有权限的成员创建 Key,或在后台调整标签样式
HTTP 403 credential_type_not_allowed正在用组织 Key,换成个人 API Key
HTTP 429见调用额度