> ## 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.

# 二维码

> 创建、列出、更新、暂停、复制、删除和下载二维码。

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

在 GetQR 中，二维码由图片和它所经由的短链接组成。创建二维码时会同时创建其短链接，因此您以后无需重新印刷即可更改目标地址。

| 方法 | 路径 | 说明 |
| - | - | - |
| `GET` | `/api/v1/qrs` | [列出二维码](#列出二维码) |
| `POST` | `/api/v1/qrs` | [创建二维码](#创建二维码) |
| `GET` | `/api/v1/qrs/{qrId}` | [获取二维码](#获取二维码) |
| `PATCH` | `/api/v1/qrs/{qrId}` | [更新二维码](#更新二维码) |
| `PUT` | `/api/v1/qrs/{qrId}` | [设置暂停状态](#设置暂停状态) |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [暂停二维码](#暂停二维码) |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [重新激活二维码](#重新激活二维码) |
| `POST` | `/api/v1/qrs/{qrId}/duplicate` | [复制二维码](#复制二维码) |
| `DELETE` | `/api/v1/qrs/{qrId}` | [删除二维码](#删除二维码) |
| `GET` | `/api/v1/qrs/{qrId}/download` | [下载二维码图片](#下载二维码图片) |

> [card] [各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)
>
> 16 种类型各自的 `data` 格式。

> [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)
>
> 点样式、颜色、边框和 Logo。

> [card] [访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)
>
> 生效计划、扫描次数上限和密码。

关于二维码的扫描统计数据，请参阅[数据分析](https://docs.getqr.com/zh/api/endpoints/analytics.md)。

## 二维码对象

除[删除](#删除二维码)和[下载](#下载二维码图片)外，所有二维码端点都会返回此对象。列表端点返回由此类对象组成的数组。

**id** `string`

二维码的唯一 ID，例如 `qr_1EPcVfeHZAY2iNoVLsgW2Aqf`。

**qrType** `string`

二维码类型，例如 `website`。全部 16 个取值请参阅[各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)。

**title** `string | null`

二维码的名称，显示在控制台中。

**description** `string | null`

关于二维码的自由文本备注。

**data** `string`

已保存的载荷。对于 `wifi`、`vcard`、`social`、`multilink`、`event` 和 `sms`，它就是您发送的载荷。对于其他类型，它是短链接，因此请从 `url` 读取目标地址。

**archived** `boolean`

二维码已暂停时为 `true`。

**isStatic** `boolean`

对于在控制台中创建、没有短链接的静态二维码为 `true`。API 始终创建动态二维码。

**shortLink** `string | null`

完整的短链接，例如 `https://getqr.sh/x7Kd2p1`。

**domain** `string | null`

短链接的域名。

**key** `string | null`

短链接的路径（slug）。

**keyIsCustom** `boolean`

路径为自行指定而非自动生成时为 `true`。

**url** `string | null`

短链接跳转到的目标地址。

**ios** `string | null`

iOS 访问者的目标地址，适用于 `app` 二维码。

**android** `string | null`

Android 访问者的目标地址，适用于 `app` 二维码。

**scans** `integer`

扫描总次数。

**access** `object`

访问规则。密码本身绝不会返回。请参阅[访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)。

**properties**

**passwordProtected** `boolean`

访问者是否必须输入密码。

**activeAt** `string | null`

计划开始时间，ISO 8601 格式。

**pauseAt** `string | null`

计划结束时间，ISO 8601 格式。

**scanLimit** `integer | null`

最大扫描次数。

**designKind** `string`

只读。`custom` 表示 API 可以完整编辑的设计。`branded` 和 `ai` 表示在控制台中创建的 Branded design 或 AI design。API 无法编辑其图案，但在您更改其他字段时会保留它。

**design** `object`

已保存的设计：`styles`、`frameOptions` 和 `logoOptions`，每项都是对象或 `null`。它们的结构与请求字段相同，因此可以直接回传。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**file** `object | null`

`pdf`、`image` 或 `video` 二维码的文件：`id`、`name` 和以字节为单位的 `size`。

**appName** `string | null`

只读。在控制台中创建的 `app` 二维码的显示名称。

**pdfBundle** `object | null`

只读。在控制台中创建、包含多个文件的 `pdf` 二维码：`title`、`layout` 和 `files`。

**imageGallery** `object | null`

只读。在控制台中创建、包含多张图片的 `image` 二维码：`title`、`layout` 和 `files`。

**createdAt** `string`

创建日期，ISO 8601 格式。

**updatedAt** `string`

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

敏感信息和内部 ID（`password`、`userId`、`workspaceId`、`projectId`）绝不会返回。

```json theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}
```

## 列出二维码

`GET /api/v1/qrs`

分页返回工作区中的二维码。

**page** `integer` (default: 1)

要返回的页码，最小为 1。

**pageSize** `integer` (default: 100)

每页的二维码数量，1 到 100。更大的值会被拒绝。

**search** `string`

匹配二维码的标题。长度超过 2 个字符的查询还会匹配已保存的 `data`。对于链接类类型，已保存的 `data` 是短链接，因此无法搜索目标 URL。

**sortBy** `string` (default: createdAt)

排序字段：`createdAt`、`updatedAt`、`clicks`（扫描总数）、`lastClicked`（最近一次扫描）或 `type`。`type` 始终按降序排列，并忽略 `sortOrder`。

**sortOrder** `string` (default: desc)

排序方向：`asc` 或 `desc`。

**showArchived** `boolean` (default: false)

包含已暂停的二维码。

**onlyArchived** `boolean` (default: false)

只返回已暂停的二维码。优先于 `showArchived`。

布尔参数取字符串 `true` 或 `false`。只要 `pagination.hasMore` 为 `true`，就继续请求下一页。请参阅[分页](https://docs.getqr.com/zh/api/introduction.md#分页)。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## 创建二维码

`POST /api/v1/qrs`

同时创建二维码及其短链接。返回 `201 Created` 和新建的[二维码](#二维码对象)。

**Idempotency-Key** `string`

由您自定的重试令牌。24 小时内使用相同的键重复请求，会返回原始响应，而不会再创建一个二维码。请参阅[重试与重复请求](#重试与重复请求)。

**qrType** `string` *required*

二维码编码的内容类型，同时决定 `data` 必须采用的格式。取值为 `website`、`pdf`、`image`、`video`、`whatsapp`、`social`、`wifi`、`app`、`feedback`、`vcard`、`sms`、`payment`、`location`、`multilink`、`email`、`event` 之一。

**data** `string` *required*

该类型的载荷，会根据 `qrType` 进行校验。空字符串会跳过校验。各类型的格式见[各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)。

**link** `object`

二维码所经由的短链接。可选：省略时，`link.url` 取 `data` 的值。

**properties**

**url** `string`

短链接跳转到的目标地址。省略或为空时默认为 `data`。两者都发送且不一致时，以 `link.url` 为准。`vcard`、`social`、`multilink` 和 `event` 二维码始终指向其托管页面；带有 `fileId` 的 `pdf`、`image` 和 `video` 二维码始终指向文件。接受的协议：`http:`、`https:`、`wifi:`、`mailto:`、`sms:`、`begin:`。

**domain** `string`

短链接的域名。必须是您工作区中已生效的域名：使用其他域名会返回 `403`，使用尚未生效的域名会返回 `422`。默认为工作区的默认域名。

**key** `string`

短链接路径，3 到 15 个字符，以小写形式保存。不允许使用的路径会返回 `422`，已被占用的路径会返回 `409`。省略时会随机生成一个 7 个字符的路径。

**ios** `string | null`

iOS 访问者的目标 URL，适用于 `app` 二维码。

**android** `string | null`

Android 访问者的目标 URL，适用于 `app` 二维码。

**title** `string | null`

链接预览标题（`og:title`），保存在短链接上。与二维码自身的 `title` 不同。目前尚未在任何地方显示。

**description** `string | null`

链接预览描述（`og:description`），保存在短链接上。目前尚未在任何地方显示。

**expiresAt, expiredUrl** `—`

此 API 不支持：发送其中任何一个都会返回 `422`。如需在指定时间停用二维码，请使用 `access.pauseAt`。

**title** `string`

二维码的名称，显示在控制台中。会去除首尾空格，长度为 1 到 40 个字符。省略时二维码没有标题。

**description** `string`

关于二维码的自由文本备注，最多 280 个字符。

**fileId** `string`

`pdf`、`image` 或 `video` 二维码的文件，需使用匹配的用途上传。对于 `vcard`、`social` 和 `multilink`，这是可选的头像，需使用 `logo` 用途上传。`event` 也接受该字段，但其页面从 `data.fileId` 读取封面。其他类型会返回 `422`。请先通过[文件](https://docs.getqr.com/zh/api/endpoints/files.md)上传文件。请参阅[二维码中的文件](https://docs.getqr.com/zh/api/guides/qr-types.md#二维码中的文件)。

**templateId** `string`

要将其设计应用到新二维码上的[模板](https://docs.getqr.com/zh/api/endpoints/templates.md)。您发送的设计字段会合并到模板设计之上。Branded design 或 AI design 模板会返回 `422`（`art_template_unsupported`）。未知的模板或其他工作区的模板会返回 `404`。

**styles** `object`

点和定位角的形状与颜色。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**frameOptions** `object`

绘制在二维码周围的边框及其行动号召文字。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**logoOptions** `object`

中心 Logo：推荐 Logo，或使用 `logo` 用途上传的您自己的文件。未知的文件、未完成的上传或其他用途的文件都会被拒绝。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**access** `object`

生效计划、扫描次数上限和密码保护。请参阅[访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)。

**properties**

**activeAt** `string | null`

计划开始时间，ISO 8601 格式。

**pauseAt** `string | null`

计划结束时间，ISO 8601 格式。

**scanLimit** `integer | null`

最大扫描次数，为正整数。

**password** `string | null`

访问者必须输入的密码。发送它会开启密码保护。

**passwordProtected** `boolean`

关闭或重新开启保护，并保留已保存的密码。

**archived** `boolean`

二维码是否已暂停。为 `true` 时，创建的二维码处于暂停状态：扫描会显示暂停页面，而不是目标页面。

未知字段会被直接丢弃而不报错。请参阅[API 不支持的功能](https://docs.getqr.com/zh/api/guides/qr-types.md#api-不支持的功能)。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'
```

```json 201 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}
```

### 重试与重复请求

* **带键。** 带上 `Idempotency-Key` 请求头时，24 小时内会重放同一响应。
* **不带键。** 30 秒内发送的相同请求体会被视为重复请求。
* **重放。** 重放会返回已保存的响应，并带有 `x-idempotent-replay: true`。新创建的二维码则返回 `false`。
* **处理中。** 第一个请求仍在处理时发出的第二个请求会收到 `409 conflict`。
* **失败。** 创建失败时会立即释放该键，因此您可以使用同一个键重试。
* **尽力而为。** 如果这一保护机制不可用，创建请求会在无保护的情况下执行。

另请参阅[幂等性](https://docs.getqr.com/zh/api/introduction.md#幂等性)。

## 获取二维码

`GET /api/v1/qrs/{qrId}`

返回一个[二维码](#二维码对象)，包括其短链接、访问规则、设计，以及（对于基于文件的类型）其文件。

**qrId** `string` *required*

二维码的 ID，可从列表或创建接口的响应中获取。

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

响应为完整的[二维码对象](#二维码对象)。

## 更新二维码

`PATCH /api/v1/qrs/{qrId}`

更改二维码的内容、目标地址、设计或访问规则。只发送您要更改的字段。返回更新后的[二维码](#二维码对象)。

**qrId** `string` *required*

二维码的 ID。

请求体接受与[创建二维码](#创建二维码)相同的字段，全部为可选，但有以下区别：

* **`templateId`。** 不接受。
* **`link`。** 部分更新。省略 `link.url` 时会保留当前目标地址。`link.domain` 和 `link.key` 会返回 `422`：已印刷的二维码编码的就是短链接，因此如需使用其他短链接，请创建新的二维码。
* **`data`。** 仅当 `data` 或 `qrType` 发生变化时，才会根据最终的类型进行校验。切换 `qrType` 但不提供匹配的 `data` 会被拒绝。请参阅[切换类型](https://docs.getqr.com/zh/api/guides/qr-types.md#切换类型)。
* **设计。** `styles`、`frameOptions` 和 `logoOptions` 会合并到已保存的设计中，因此部分对象只会更改其中指定的内容。选择其他 Logo 会替换原 Logo，但保留其大小。
* **`access`。** 每个键在发送时生效。`null` 会清除对应规则。访问规则必须放在 `access` 下：放在 `link` 下会返回 `422`。
* **`archived`。** 同时暂停或重新激活二维码及其短链接，效果与[暂停](#暂停二维码)和[重新激活](#重新激活二维码)相同。

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}
```

各类型在印刷后可以更改的内容，请参阅[各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)。

## 设置暂停状态

`PUT /api/v1/qrs/{qrId}`

直接设置暂停状态。[暂停](#暂停二维码)和[重新激活](#重新激活二维码)的作用相同，而且语义更清晰。

**qrId** `string` *required*

二维码的 ID。

**archived** `boolean` *required*

`true` 表示暂停二维码，`false` 表示重新激活。

```bash cURL theme={null}
curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## 暂停二维码

`POST /api/v1/qrs/{qrId}/pause`

停止二维码跳转到目标地址：扫描会改为显示暂停页面。已印刷的二维码及其短链接仍然有效。无需请求体。

**qrId** `string` *required*

二维码的 ID。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## 重新激活二维码

`POST /api/v1/qrs/{qrId}/activate`

让已暂停的二维码重新跳转到目标地址。已有的计划和扫描次数上限仍然适用。无需请求体。

**qrId** `string` *required*

二维码的 ID。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}
```

## 复制二维码

`POST /api/v1/qrs/{qrId}/duplicate`

创建一个内容和设计都相同的副本。无需请求体。返回 `201 Created` 和新建的[二维码](#二维码对象)。

**qrId** `string` *required*

要复制的二维码的 ID。

* **短链接。** 副本拥有自己的短链接，使用工作区默认域名（而不是源二维码的域名）上的随机路径。其扫描次数单独统计。
* **标题。** 标题会加上 ` (Copy)` 后缀。结果不超过 40 个字符：过长的标题会先被截短。没有标题的二维码仍然没有标题。
* **不会复制的内容。** 访问规则（密码、生效计划、扫描次数上限）和暂停状态。副本始终处于启用状态。
* **文件。** PDF 和图片文件（包括文件包和图库中的文件）会被复制，归副本所有。视频文件和设计文件（例如 Logo）则与源二维码共享。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}
```

## 删除二维码

`DELETE /api/v1/qrs/{qrId}`

删除二维码及其短链接。返回被删除的 ID。

> [!WARNING]
>
> 删除是永久性的。已印刷的二维码及其短链接将失效，扫描历史也将无法再访问。如果以后可能还需要它，请改为[暂停](#暂停二维码)二维码。

**qrId** `string` *required*

二维码的 ID。

**id** `string`

被删除的二维码的 ID。

**deleted** `boolean`

始终为 `true`。

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

```json 200 theme={null}
{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }
```

## 下载二维码图片

`GET /api/v1/qrs/{qrId}/download`

按二维码的设计进行渲染，并返回文件。

**qrId** `string` *required*

要渲染的二维码的 ID，可从列表或创建接口的响应中获取。

**format** `string` (default: jpg)

输出格式：`jpg`、`png`、`svg`、`pdf`（A4 页面）或 `eps`。Branded design 或 AI design 只能下载为 `jpg`、`png` 或 `pdf`。

**resolution** `integer` (default: 1024)

图片尺寸（像素）：`1024`、`2048` 或 `4096`。`svg` 和 `pdf` 会忽略该值。Branded design 或 AI design 只能以 `1024` 下载。

| `format` | `Content-Type` | 文件名 |
| - | - | - |
| `jpg` | `image/jpeg` | `<title>-<resolution>px.jpg` |
| `png` | `image/png` | `<title>-<resolution>px.png` |
| `svg` | `image/svg+xml` | `<title>.svg` |
| `pdf` | `application/pdf` | `<title>.pdf` |
| `eps` | `application/postscript` | `<title>-<resolution>px.eps` |

* **响应体。** 响应体就是文件本身。建议的文件名位于 `Content-Disposition` 响应头中，根据标题生成；没有标题的二维码使用 `qr-code`。
* **缓存。** 响应带有 `ETag` 和 `Cache-Control: private, max-age=3600, must-revalidate`。在 `If-None-Match` 中回传 `ETag`，即可在二维码未变化时获得 `304 Not Modified`。
* **错误。** 不支持的格式或分辨率会返回 `400 bad_request`。错误消息会注明原因：`qr_download_invalid_format`、`qr_download_invalid_resolution`、`qr_download_art_format_unsupported` 或 `qr_download_art_resolution_unsupported`。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>
```

## 访问规则

在创建或更新时发送 `access` 对象，即可设置开始和结束时间、限制扫描次数或要求输入密码。省略的规则保持不变，`null` 会清除对应规则。完整的行为说明和示例请参阅[访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)。

## 设计对象

`styles`、`frameOptions` 和 `logoOptions` 用于设置点和定位角的形状、颜色、边框和 Logo。它们在二维码、[模板](https://docs.getqr.com/zh/api/endpoints/templates.md)和[批量创建](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)中的用法相同。未知的形状、边框或 Logo 会被拒绝。所有可接受的值和完整示例请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

## 常见问题

> [accordion] 设置密码、生效计划或扫描次数上限时返回 422
>
> 请将规则放在 `access` 下，而不是 `link` 下。

> [accordion] 更改 link.domain 或 link.key 时返回 422
>
> 短链接创建后无法更改，因为已印刷的二维码编码的就是它。请改为创建新的二维码。

> [accordion] 422 "Expected … for qrType"
>
> `data` 与 `qrType` 的格式不匹配。请在[各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)中查看该类型。

> [accordion] 创建二维码时返回 409 conflict
>
> 相同的创建请求仍在处理中，或 `link.key` 已被占用。请等第一个请求完成后再重试。如果带有 `Idempotency-Key`，重试会返回原来的二维码。

> [accordion] 下载的是 JPEG 而不是 PNG
>
> 参数名为 `format` 和 `resolution`，并且 `format` 默认为 `jpg`。请发送 `format=png`。

> [accordion] 控制台中能看到的二维码返回 404
>
> 每个请求都在 API 密钥所属的工作区中执行。请确认该二维码属于这个工作区。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

## 后续步骤

> [card] [各类型的二维码数据](https://docs.getqr.com/zh/api/guides/qr-types.md)

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

> [card] [访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)

> [card] [数据分析](https://docs.getqr.com/zh/api/endpoints/analytics.md)


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