Skip to content

为明确指定的码创建标签导出任务 ​

沿用当前标签样式为明确指定的码创建导出任务:普通码每次 1 个,同一母模板的子码最多 100 个,格式须是 labels/getConfig 返回的 supported_formats 之一。需要幂等键 idempotency_key,超时或结果未知时用原键和原参数重试;取得 task_id 后用 labelExports/get 查询。

请求 ​

text
POST https://open.cli.im/api/v2/rpc/labelExports/create
项目要求
最低权限读写,见权限档位
需要的 scopeqrcodes.write
组织 Key不能调用,返回 403 credential_type_not_allowed,见历史组织 Key

相关调用流程:导出可打印的标签。

请求参数 ​

请求体为 JSON。

字段类型必填说明
qrcode_idsstring[]是要导出的码 ID:普通码每次 1 个,同一批量模板的子码最多 100 个,两类不能混用,不能为空。至少 1 项。最多 100 项
formatstring是导出格式,从 labels/getConfig 返回的 supported_formats 里选:png_zip 图片包;a4_pdf A4 纸多标签排版;a4_pdf_single A4 纸每页一个标签。导出结果都是 ZIP 文件。可选值:png_zip、a4_pdf、a4_pdf_single
idempotency_keystring是幂等键,由调用方生成,1 到 128 位,只能包含字母、数字和 _ . : -。同一个键重复提交会返回第一次的结果,不会重复创建;请求超时或结果不明时用原键和原参数重试,新的请求换一个新键。最长 128 个字符

请求示例 ​

示例里的 ID、幂等键等换成实际值。

bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/labelExports/create' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "qrcode_ids": [
    "7001234"
  ],
  "format": "png_zip",
  "idempotency_key": "label-export-20261118-001"
}'

响应 ​

成功时 HTTP 状态码为 200,顶层 code 为 0,结果在 data 里。失败时的返回见错误码与调用额度和业务错误码。

字段类型一定返回说明
data.task_idstring是导出任务 ID,用于 labelExports/get
data.statusstring是任务状态,刚创建时为 pending。可选值:pending、running、succeeded、failed、expired、unknown
data.accepted_countinteger是已受理的码数量,不代表都已导出成功
data.formatstring是导出格式
data.filesany[]是导出文件;刚创建时为空数组
data.expires_atinteger是文件过期时间(Unix 秒);尚未生成时为 null
data.receipt_expires_atinteger是任务回执的过期时间(Unix 秒)
data.poll_after_secondsinteger是建议的轮询间隔(秒);任务已结束时为 null

响应示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "label_560012",
    "status": "pending",
    "accepted_count": 1,
    "format": "png_zip",
    "files": [],
    "expires_at": null,
    "receipt_expires_at": 1795086400,
    "poll_after_seconds": 3
  }
}

常见错误 ​

QRCODE_NOT_FOUND、LABEL_STYLE_NOT_CONFIGURED、LABEL_TARGETS_MUST_SHARE_TEMPLATE、LABEL_FORMAT_UNSUPPORTED、LABEL_TARGET_NOT_READY、IDEMPOTENCY_CONFLICT、IDEMPOTENCY_IN_PROGRESS、IDEMPOTENCY_OUTCOME_UNKNOWN。含义和处理方式见业务错误码。


本页由 openapi.json 生成。全部接口见接口清单。