二维码 - GetQR Docs

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`	下载二维码图片

各类型的二维码数据

16 种类型各自的 data 格式。

自定义设计

点样式、颜色、边框和 Logo。

访问规则

生效计划、扫描次数上限和密码。

关于二维码的扫描统计数据，请参阅数据分析。

二维码对象

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

string

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

string

二维码类型，例如 website。全部 16 个取值请参阅各类型的二维码数据。

string | null

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

string | null

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

string

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

boolean

二维码已暂停时为 true。

boolean

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

string | null

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

string | null

短链接的域名。

string | null

短链接的路径（slug）。

boolean

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

string | null

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

string | null

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

string | null

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

integer

扫描总次数。

object

访问规则。密码本身绝不会返回。请参阅访问规则。

显示 properties

boolean

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

string | null

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

string | null

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

integer | null

最大扫描次数。

string

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

object

已保存的设计：styles、frameOptions 和 logoOptions，每项都是对象或 null。它们的结构与请求字段相同，因此可以直接回传。请参阅自定义设计。

object | null

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

string | null

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

object | null

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

object | null

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

string

创建日期，ISO 8601 格式。

string

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

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

{
  "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 分页返回工作区中的二维码。

integer

默认值:"1"

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

integer

默认值:"100"

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

string

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

string

默认值:"createdAt"

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

string

默认值:"desc"

排序方向：asc 或 desc。

boolean

默认值:"false"

包含已暂停的二维码。

boolean

默认值:"false"

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

布尔参数取字符串 true 或 false。只要 pagination.hasMore 为 true，就继续请求下一页。请参阅分页。

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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 和新建的二维码。

string

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

string

必填

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

string

必填

该类型的载荷，会根据 qrType 进行校验。空字符串会跳过校验。各类型的格式见各类型的二维码数据。

object

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

显示 properties

string

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

string

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

string

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

string | null

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

string | null

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

string | null

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

string | null

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

—

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

string

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

string

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

string

pdf、image 或 video 二维码的文件，需使用匹配的用途上传。对于 vcard、social 和 multilink，这是可选的头像，需使用 logo 用途上传。event 也接受该字段，但其页面从 data.fileId 读取封面。其他类型会返回 422。请先通过文件上传文件。请参阅二维码中的文件。

string

要将其设计应用到新二维码上的模板。您发送的设计字段会合并到模板设计之上。Branded design 或 AI design 模板会返回 422（art_template_unsupported）。未知的模板或其他工作区的模板会返回 404。

object

点和定位角的形状与颜色。请参阅自定义设计。

object

绘制在二维码周围的边框及其行动号召文字。请参阅自定义设计。

object

中心 Logo：推荐 Logo，或使用 logo 用途上传的您自己的文件。未知的文件、未完成的上传或其他用途的文件都会被拒绝。请参阅自定义设计。

object

生效计划、扫描次数上限和密码保护。请参阅访问规则。

显示 properties

string | null

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

string | null

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

integer | null

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

string | null

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

boolean

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

boolean

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

未知字段会被直接丢弃而不报错。请参阅API 不支持的功能。

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

{
  "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。
失败。 创建失败时会立即释放该键，因此您可以使用同一个键重试。
尽力而为。 如果这一保护机制不可用，创建请求会在无保护的情况下执行。

另请参阅幂等性。

获取二维码

GET /api/v1/qrs/{qrId} 返回一个二维码，包括其短链接、访问规则、设计，以及（对于基于文件的类型）其文件。

string

必填

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

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

响应为完整的二维码对象。

更新二维码

PATCH /api/v1/qrs/{qrId} 更改二维码的内容、目标地址、设计或访问规则。只发送您要更改的字段。返回更新后的二维码。

string

必填

二维码的 ID。

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

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

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

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

各类型在印刷后可以更改的内容，请参阅各类型的二维码数据。

设置暂停状态

PUT /api/v1/qrs/{qrId} 直接设置暂停状态。暂停和重新激活的作用相同，而且语义更清晰。

string

必填

二维码的 ID。

boolean

必填

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

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

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

暂停二维码

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

string

必填

二维码的 ID。

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

重新激活二维码

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

string

必填

二维码的 ID。

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

复制二维码

POST /api/v1/qrs/{qrId}/duplicate 创建一个内容和设计都相同的副本。无需请求体。返回 201 Created 和新建的二维码。

string

必填

要复制的二维码的 ID。

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

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

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

string

必填

二维码的 ID。

string

被删除的二维码的 ID。

boolean

始终为 true。

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }

下载二维码图片

GET /api/v1/qrs/{qrId}/download 按二维码的设计进行渲染，并返回文件。

string

必填

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

string

默认值:"jpg"

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

integer

默认值:"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。

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/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 会清除对应规则。完整的行为说明和示例请参阅访问规则。

设计对象

styles、frameOptions 和 logoOptions 用于设置点和定位角的形状、颜色、边框和 Logo。它们在二维码、模板和批量创建中的用法相同。未知的形状、边框或 Logo 会被拒绝。所有可接受的值和完整示例请参阅自定义设计。

常见问题

设置密码、生效计划或扫描次数上限时返回 422

请将规则放在 access 下，而不是 link 下。

更改 link.domain 或 link.key 时返回 422

短链接创建后无法更改，因为已印刷的二维码编码的就是它。请改为创建新的二维码。

422 "Expected … for qrType"

data 与 qrType 的格式不匹配。请在各类型的二维码数据中查看该类型。

创建二维码时返回 409 conflict

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

下载的是 JPEG 而不是 PNG

参数名为 format 和 resolution，并且 format 默认为 jpg。请发送 format=png。

控制台中能看到的二维码返回 404

每个请求都在 API 密钥所属的工作区中执行。请确认该二维码属于这个工作区。请参阅身份验证。

各类型的二维码数据

自定义设计

访问规则

​二维码对象

​列出二维码

​创建二维码

​重试与重复请求

​获取二维码

​更新二维码

​设置暂停状态

​暂停二维码

​重新激活二维码

​复制二维码

​删除二维码

​下载二维码图片

​访问规则

​设计对象

​常见问题

​后续步骤

各类型的二维码数据

自定义设计

访问规则

数据分析

二维码对象

列出二维码

创建二维码

重试与重复请求

获取二维码

更新二维码

设置暂停状态

暂停二维码

重新激活二维码

复制二维码

删除二维码

下载二维码图片

访问规则

设计对象

常见问题

后续步骤