导出可打印的标签
适用于码已经建好,要按后台设置的标签样式批量生成可打印的文件。
只需要二维码图片、不需要标签样式时,不用走这个流程:生成二维码接口和批量生成二维码结果里已经带了码图地址。
前置条件
- 个人 API Key。读取配置和预览「只读」档即可,创建导出任务需要「读写」或「完全」。组织 Key 不能调这些接口。
- 目标码已经在后台关联了标签样式。
- 所有接口都是
POST https://open.cli.im/api/v2/rpc/{路径},请求体直接传 JSON,成功数据在响应的data里。
调用顺序
| 步骤 | 接口 | 作用 |
|---|---|---|
| 1 | labels/getConfig | 读取当前标签样式、尺寸和支持的导出格式 |
| 2 | labels/preview | 用少量真实的码生成预览,确认效果 |
| 3 | labelExports/create | 创建导出任务 |
| 4 | labelExports/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_pdf | A4 纸上排多个标签 |
a4_pdf_single | A4 纸每页一个标签,多个码按页输出 |
三种格式下载到的都是 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 | 见调用额度 |