# 导出可打印的标签

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

只需要二维码图片、不需要标签样式时，不用走这个流程：生成二维码接口和[批量生成二维码结果](https://cli.im/open-api/openapi/v2/scenarios/batch-create-qrcodes.md)里已经带了码图地址。

## 前置条件

- [个人 API Key](https://cli.im/open-api/openapi/v2/auth.md#create-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 | 见[调用额度](https://cli.im/open-api/openapi/v2/error-codes.md#rate-limit) |
