访问规则

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

控制二维码何时生效、可以被扫描多少次、是否需要输入密码，以及是否暂停或删除。

开始之前

角色。 设置规则、暂停、重新激活和删除都需要对工作区中的二维码拥有写入权限。请参阅身份验证。
订阅。 所有 API 请求（包括这些操作）都要求工作区所有者拥有有效订阅。

access 对象

在创建或更新二维码时发送 access 对象：

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

字段	类型	说明
`activeAt`	string (ISO 8601) \| null	计划开始时间。在此时间之前，扫描会显示暂停页面，而不是目标页面。`null` 表示立即生效。
`pauseAt`	string (ISO 8601) \| null	计划结束时间。从此时间起，扫描会显示暂停页面。`null` 表示没有结束日期。
`scanLimit`	integer \| null	二维码整个生命周期内的最大扫描次数。超出后，扫描会显示暂停页面。`null` 表示不限次数。
`password`	string \| null	访问者在跳转前必须输入的密码。发送它也会开启密码保护。
`passwordProtected`	boolean	二维码是否要求输入密码。`false` 会关闭保护，但保留已保存的密码。`true` 会重新开启保护。

省略的字段保持不变。发送 null 可清除某条规则。部分 access 对象绝不会重置您未提及的规则。

访问规则必须放在 access 下。在 link 下发送 activeAt、pauseAt、scanLimit、password 或 passwordProtected 会返回 422。

设置开始和结束时间

activeAt 和 pauseAt 相互独立：可以只设置其中一个，也可以都设置。两者都接受 ISO 8601 日期时间，需带 Z 或 UTC 偏移量。

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_abc123" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {
      "activeAt": "2026-08-01T09:00:00Z",
      "pauseAt": "2026-08-31T23:59:59Z"
    }
  }'

发送 null 可清除计划。这会让二维码立即生效，并移除结束日期：

{
  "access": { "activeAt": null, "pauseAt": null }
}

扫描次数上限

限制扫描总次数。达到上限后，二维码将不再跳转：

{
  "access": { "scanLimit": 500 }
}

无论是否设置了上限，生命周期扫描计数器都会一直运行。因此，更改上限的效果是可预测的：

提高上限：恰好再释放（新上限减去总扫描次数）次扫描。
降低上限：若低于当前总数，二维码会立即被阻止。
之后再设置上限：未设置上限期间产生的扫描也会计入。

scanLimit 必须是正整数，最大为 2147483647。发送 null 表示不限次数。

密码保护

通过同一个 access 对象设置密码。关闭保护时会保留已保存的密码，因此重新开启时无需再次发送。

设置或更改密码

这也会开启密码保护。

{ "access": { "password": "hunter2" } }

关闭保护

已保存的密码会被保留。

{ "access": { "passwordProtected": false } }

重新开启保护

无需重新发送密码。仅当之前已设置过密码时才有效，否则请求会返回 422。

{ "access": { "passwordProtected": true } }

创建时。 发送 password 即可开启保护。在密码存在之前，单独发送 passwordProtected 不会产生任何效果。
移除密码。 发送 "password": null。保护也会随之关闭。
读取。 响应绝不会返回密码，只返回 access.passwordProtected。

暂停、重新激活和删除

暂停和重新激活是独立的端点，而不是 access 字段，因为它们会立即生效，而不是按计划生效。

方法	路径	说明
`POST`	`/api/v1/qrs/{qrId}/pause`	立即暂停二维码。在您重新激活之前，扫描会显示暂停页面。
`POST`	`/api/v1/qrs/{qrId}/activate`	重新激活已暂停的二维码。已有的计划和扫描次数上限仍然适用。
`DELETE`	`/api/v1/qrs/{qrId}`	永久删除二维码及其短链接。

暂停和激活都不需要请求体，并返回更新后的二维码：

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

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

您也可以使用 PUT /api/v1/qrs/{qrId} 和 { "archived": true }，或在 PATCH 中使用 archived 来设置暂停状态。请参阅设置暂停状态。删除操作会同时移除二维码及其短链接：

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

删除无法撤销。短链接会停止跳转，因此已印刷的二维码将失效。如果以后可能还需要它，请改为暂停二维码。

更改何时生效

下一次扫描。 规则在扫描时检查，因此更改从下一次扫描开始生效，不会追溯。
暂停页面。 被计划、扫描次数上限或暂停阻止的二维码会显示暂停页面，扫描不会跳转。
密码。 已输入过密码的访问者会一直保有访问权限，直到密码更改，或保护被关闭后再重新开启。
时钟。 计划使用 UTC 时区的服务器时钟，而不是访问者的本地时间。
规则叠加。 只有在未暂停、处于计划时间内且未达到扫描次数上限时，二维码才会跳转。

常见问题

在 link 下设置规则时返回 422

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

开启密码保护时返回 422

该二维码还没有密码。请发送 password，而不是 passwordProtected: true。

重新激活后二维码仍显示暂停页面

仍有计划或扫描次数上限在生效。请检查二维码中的 access.activeAt、access.pauseAt 和 access.scanLimit，并将 scans 与上限进行比较。

需要让链接过期

此 API 不提供 link.expiresAt。请改用 access.pauseAt。

API

开始之前

access 对象

设置开始和结束时间

扫描次数上限

密码保护

暂停、重新激活和删除

更改何时生效

常见问题

后续步骤

二维码

各类型的二维码数据

​开始之前

​access 对象

​设置开始和结束时间

​扫描次数上限

​密码保护

​暂停、重新激活和删除

​更改何时生效

​常见问题

​后续步骤

二维码

各类型的二维码数据

开始之前

access 对象

设置开始和结束时间

扫描次数上限

密码保护

暂停、重新激活和删除

更改何时生效

常见问题

后续步骤