批量创建二维码

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

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

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

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

工作原理

发起批量创建

使用通过 JSON 创建或通过 CSV 文件创建端点发送数据行。API 会返回 202，以及批量创建任务和它的 id。

轮询进度

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

下载压缩包

当 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 二维码。请参阅二维码类型。

请求头

string

必填

Bearer 后跟您的 API 密钥。请参阅身份验证。

string

通过 JSON 创建时为 application/json，通过 CSV 文件创建时为 multipart/form-data。

批量创建对象

string

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

string

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

string

源文件的名称。

integer

行数。

integer

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

integer

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

integer

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

boolean

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

object | null

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

string | null

status 变为 completed 后，下载压缩包的路径。

string

开始日期，ISO 8601 格式。

string

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

string | null

完成日期，ISO 8601 格式。

string | null

失败日期，ISO 8601 格式。

获取当前批量创建任务

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

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

通过 JSON 创建

POST /api/v1/bulk-qr-creations 根据一组数据行发起批量创建。返回 202 Accepted。批量创建任务在后台运行。

object[]

必填

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

object

必填

应用到每个二维码的设计：styles、frameOptions 和 logoOptions，全部为可选。发送 {} 表示使用默认设计。其他字段会被拒绝。请参阅自定义设计。

string

必填

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

string

必填

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

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"
  }'

{
  "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 创建相同，但数据行以 CSV 文件的形式通过 multipart/form-data 发送。返回 202 Accepted。文件必须是不超过 1,000,000 字节的 .csv 文件。其表头行必须严格为 name,url，之后最多 100 行数据。请参阅 CSV 格式。

file

必填

CSV 文件。

string

必填

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

string

必填

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

string

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

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "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。

string

必填

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

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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。中止已经失败的批量创建任务会原样返回该任务。

已完成的批量创建任务无法中止：请求会返回 400。请改用二维码端点逐个删除其中的二维码。

string

必填

批量创建任务的 ID。

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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 后即可下载。下载会关闭该批量创建任务，因此获取当前批量创建任务将不再返回它。

string

必填

批量创建任务的 ID。

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

常见问题

返回 422 并提示 "contains an invalid HTTP(S) URL"

消息会指出出错的行。每个 URL 都必须是带有真实域名的 http 或 https 地址，例如 example.com/menu。请修正该行后重新发送请求。

422 "CSV headers must be exactly: name,url."

CSV 的第一行必须是 name,url，顺序不变、全部小写，且不能有其他列。

422 "This idempotencyKey was already used with a different request body."

键不能用于另一批不同的数据。请发送新的 idempotencyKey。

409 "The bulk QR archive is not ready for download."

批量创建任务尚未完成。请继续轮询，直到 status 变为 completed。

400 "Cannot cancel a finished bulk QR creation."

批量创建任务已经完成，因此无法回滚。

403 exceeded_limit

您的工作区使用的是 Single QR 套餐，该套餐不包含批量创建。请升级套餐。

返回的是之前的批量创建任务，而不是新任务

您的工作区中还有另一个批量创建任务正在运行，或者您重复使用了某个 idempotencyKey。请等它完成，或使用新的键。

API

批量创建二维码

工作原理

数据行

请求头

批量创建对象

获取当前批量创建任务

通过 JSON 创建

通过 CSV 文件创建

获取批量创建任务

中止批量创建任务

下载压缩包

常见问题

后续步骤

自定义设计

二维码

在应用中批量创建

CSV 格式

​工作原理

​数据行

​请求头

​批量创建对象

​获取当前批量创建任务

​通过 JSON 创建

​通过 CSV 文件创建

​获取批量创建任务

​中止批量创建任务

​下载压缩包

​常见问题

​后续步骤

自定义设计

二维码

在应用中批量创建

CSV 格式

工作原理

数据行

请求头

批量创建对象

获取当前批量创建任务

通过 JSON 创建

通过 CSV 文件创建

获取批量创建任务

中止批量创建任务

下载压缩包

常见问题

后续步骤