> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 批量创建二维码

> 一次创建最多 100 个二维码，并以 ZIP 压缩包的形式下载。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

批量创建可将一组名称和 URL 转换为使用同一设计的 Website 二维码。它在后台运行：先发起任务，再轮询进度，最后下载 ZIP 压缩包。

| 方法 | 路径 | 说明 |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [获取当前批量创建任务](#获取当前批量创建任务) |
| `POST` | `/api/v1/bulk-qr-creations` | [通过 JSON 创建](#通过-json-创建) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [通过 CSV 文件创建](#通过-csv-文件创建) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [获取批量创建任务](#获取批量创建任务) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [中止批量创建任务](#中止批量创建任务) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [下载压缩包](#下载压缩包) |

## 工作原理

**1. 发起批量创建**

使用[通过 JSON 创建](#通过-json-创建)或[通过 CSV 文件创建](#通过-csv-文件创建)端点发送数据行。API 会返回 `202`，以及批量创建任务和它的 `id`。

**2. 轮询进度**

每隔几秒调用一次[获取批量创建任务](#获取批量创建任务)，直到 `status` 变为 `completed` 或 `failed`。

**3. 下载压缩包**

当 `status` 为 `completed` 时，调用[下载压缩包](#下载压缩包)，获取包含二维码图片的 ZIP 文件。

* **上限。** 每次批量创建最多 100 行。
* **一次一个。** 每个工作区同时只能运行一个批量创建任务。已有任务运行时再发起新任务，会返回正在运行的那个任务。
* **幂等性。** 每个请求都需要 `idempotencyKey`。使用相同的键和相同的请求体重复请求，会返回已经发起的批量创建任务。相同的键搭配不同的请求体会返回 `422`。
* **数据行。** 每行都需要 `name` 和 `url`。请参阅[数据行](#数据行)。
* **套餐。** Single QR 套餐不支持批量创建：请求会返回 `403 exceeded_limit`。

## 数据行

* **名称。** 作为二维码的标题。会去除首尾空格并截断为 40 个字符。重复的名称（不区分大小写）会加上编号：`Menu`、`Menu 2`、`Menu 3`。
* **URL。** 作为目标地址。必须是带有真实域名的 `http` 或 `https` 地址（例如 `example.com/menu`），且不能包含空格。没有协议的 URL 会自动加上 `https://`。
* **空行。** 名称和 URL 都为空的行会被跳过。只有其中一项的行会被拒绝。

每个二维码都是基于短链接的 `website` 二维码。请参阅[二维码类型](https://docs.getqr.com/zh/api/guides/qr-types.md)。

## 请求头

**Authorization** `string` *required*

`Bearer` 后跟您的 API 密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

**Content-Type** `string`

[通过 JSON 创建](#通过-json-创建)时为 `application/json`，[通过 CSV 文件创建](#通过-csv-文件创建)时为 `multipart/form-data`。

## 批量创建对象

**id** `string`

批量创建任务的 ID，例如 `cm2k7x9qb0003ax8eb4f6gh2t`。

**status** `string`

`queued`、`processing`、`packaging` 或 `completed`。失败或被中止的批量创建任务会经过 `rollingBack` 变为 `failed`。

**sourceFilename** `string`

源文件的名称。

**totalCount** `integer`

行数。

**createdCount** `integer`

目前已创建的二维码数量。

**renderedCount** `integer`

目前已渲染的二维码图片数量。

**percent** `integer`

总体进度，0 到 100。创建阶段最多到 40，渲染阶段最多到 90，打包阶段为 95，`completed` 为 100。

**stalled** `boolean`

正在运行的批量创建任务 2 分钟内没有进展时为 `true`。请继续轮询：[获取批量创建任务](#获取批量创建任务)会重新启动停滞的任务。

**error** `object | null`

当 `status` 为 `failed` 时：`code` 和 `message`。被中止的批量创建任务的代码为 `cancelled_by_user`。失败的批量创建任务会被回滚，因此其中的二维码都不会保留。

**downloadUrl** `string | null`

`status` 变为 `completed` 后，[下载压缩包](#下载压缩包)的路径。

**createdAt** `string`

开始日期，ISO 8601 格式。

**updatedAt** `string`

最后更新日期，ISO 8601 格式。

**completedAt** `string | null`

完成日期，ISO 8601 格式。

**failedAt** `string | null`

失败日期，ISO 8601 格式。

## 获取当前批量创建任务

`GET /api/v1/bulk-qr-creations`

返回工作区中仍在运行的批量创建任务。没有正在运行的任务时，返回最近一个已结束的任务（`completed` 或 `failed`），直到它被关闭为止：下载其压缩包或在控制台中关闭它都可以将其关闭。否则返回 `null`。重启后可用它恢复跟踪。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}
```

```json 200 (nothing to resume) theme={null}
null
```

## 通过 JSON 创建

`POST /api/v1/bulk-qr-creations`

根据一组数据行发起批量创建。返回 `202 Accepted`。批量创建任务在后台运行。

**rows** `object[]` *required*

要创建的二维码，最多 100 个。每行为 `{ "name": "...", "url": "..." }`，不接受其他字段。请参阅[数据行](#数据行)。

**design** `object` *required*

应用到每个二维码的设计：`styles`、`frameOptions` 和 `logoOptions`，全部为可选。发送 `{}` 表示使用默认设计。其他字段会被拒绝。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**sourceFilename** `string` *required*

显示在控制台中并用于压缩包命名的名称，1 到 255 个字符。

**idempotencyKey** `string` *required*

您为本次批量创建自定的键，8 到 100 个字符。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## 通过 CSV 文件创建

`POST /api/v1/bulk-qr-creations/csv`

与[通过 JSON 创建](#通过-json-创建)相同，但数据行以 CSV 文件的形式通过 `multipart/form-data` 发送。返回 `202 Accepted`。

文件必须是不超过 1,000,000 字节的 `.csv` 文件。其表头行必须严格为 `name,url`，之后最多 100 行数据。请参阅 [CSV 格式](https://docs.getqr.com/zh/bulk/csv-format.md)。

**file** `file` *required*

CSV 文件。

**design** `string` *required*

序列化为 JSON 的设计对象，例如 `{"styles":{"dotsOptions":{"type":"rounded"}}}`。发送 `{}` 表示使用默认设计。

**idempotencyKey** `string` *required*

您为本次批量创建自定的键，8 到 100 个字符。

**sourceFilename** `string`

显示在控制台中并用于压缩包命名的名称，最多 255 个字符。默认为上传文件的名称。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "file=@campaign-links.csv" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"
```

```csv campaign-links.csv theme={null}
name,url
Menu,https://example.com/menu
Wine list,example.com/wine
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## 获取批量创建任务

`GET /api/v1/bulk-qr-creations/{id}`

返回批量创建任务的状态和进度。当 `status` 为 `queued`、`processing` 或 `packaging` 时请持续轮询。压缩包就绪后会出现 `downloadUrl`。

**id** `string` *required*

批量创建任务的 ID。可从创建接口或获取当前任务接口的响应中获取。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}
```

## 中止批量创建任务

`DELETE /api/v1/bulk-qr-creations/{id}`

停止正在运行的批量创建任务，并删除它已经创建的二维码。回滚在请求期间完成，因此响应通常为 `status` `failed` 和 `error.code` `cancelled_by_user`。中止已经失败的批量创建任务会原样返回该任务。

> [!WARNING]
>
> 已完成的批量创建任务无法中止：请求会返回 `400`。请改用[二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)端点逐个删除其中的二维码。

**id** `string` *required*

批量创建任务的 ID。

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}
```

## 下载压缩包

`GET /api/v1/bulk-qr-creations/{id}/download`

返回一个 ZIP 压缩包，其中每个二维码对应一张 1024 px 的 JPEG，并以对应的数据行命名：`001-Menu.jpg`、`002-Wine list.jpg` 等。压缩包以 `sourceFilename` 命名。`status` 变为 `completed` 后即可下载。下载会关闭该批量创建任务，因此[获取当前批量创建任务](#获取当前批量创建任务)将不再返回它。

**id** `string` *required*

批量创建任务的 ID。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>
```

## 常见问题

> [accordion] 返回 422 并提示 "contains an invalid HTTP(S) URL"
>
> 消息会指出出错的行。每个 URL 都必须是带有真实域名的 `http` 或 `https` 地址，例如 `example.com/menu`。请修正该行后重新发送请求。

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> CSV 的第一行必须是 `name,url`，顺序不变、全部小写，且不能有其他列。

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> 键不能用于另一批不同的数据。请发送新的 `idempotencyKey`。

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> 批量创建任务尚未完成。请继续轮询，直到 `status` 变为 `completed`。

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> 批量创建任务已经完成，因此无法回滚。

> [accordion] 403 exceeded\_limit
>
> 您的工作区使用的是 Single QR 套餐，该套餐不包含批量创建。请升级套餐。

> [accordion] 返回的是之前的批量创建任务，而不是新任务
>
> 您的工作区中还有另一个批量创建任务正在运行，或者您重复使用了某个 `idempotencyKey`。请等它完成，或使用新的键。

## 后续步骤

> [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)

> [card] [在应用中批量创建](https://docs.getqr.com/zh/bulk/overview.md)

> [card] [CSV 格式](https://docs.getqr.com/zh/bulk/csv-format.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.