> ## 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 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

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

## 开始之前

* **角色。** 设置规则、暂停、重新激活和删除都需要对工作区中的二维码拥有写入权限。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。
* **订阅。** 所有 API 请求（包括这些操作）都要求工作区所有者拥有有效订阅。

## access 对象

在[创建](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#创建二维码)或[更新](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#更新二维码)二维码时发送 `access` 对象：

```text theme={null}
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` 对象绝不会重置您未提及的规则。

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

## 设置开始和结束时间

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

```bash theme={null}
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` 可清除计划。这会让二维码立即生效，并移除结束日期：

```json theme={null}
{
  "access": { "activeAt": null, "pauseAt": null }
}
```

## 扫描次数上限

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

```json theme={null}
{
  "access": { "scanLimit": 500 }
}
```

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

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

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

## 密码保护

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

**1. 设置或更改密码**

这也会开启密码保护。

```json theme={null}
{ "access": { "password": "hunter2" } }
```

**2. 关闭保护**

已保存的密码会被保留。

```json theme={null}
{ "access": { "passwordProtected": false } }
```

**3. 重新开启保护**

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

```json theme={null}
{ "access": { "passwordProtected": true } }
```

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

## 暂停、重新激活和删除

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

| 方法 | 路径 | 说明 |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [立即暂停二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#暂停二维码)。在您重新激活之前，扫描会显示暂停页面。 |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [重新激活已暂停的二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#重新激活二维码)。已有的计划和扫描次数上限仍然适用。 |
| `DELETE` | `/api/v1/qrs/{qrId}` | [永久删除二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#删除二维码)及其短链接。 |

暂停和激活都不需要请求体，并返回更新后的[二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#二维码对象)：

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

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

您也可以使用 `PUT /api/v1/qrs/{qrId}` 和 `{ "archived": true }`，或在 `PATCH` 中使用 `archived` 来设置暂停状态。请参阅[设置暂停状态](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#设置暂停状态)。

删除操作会同时移除二维码及其短链接：

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

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

## 更改何时生效

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

## 常见问题

> [accordion] 在 link 下设置规则时返回 422
>
> 请将规则放在 `access` 下，而不是 `link` 下。

> [accordion] 开启密码保护时返回 422
>
> 该二维码还没有密码。请发送 `password`，而不是 `passwordProtected: true`。

> [accordion] 重新激活后二维码仍显示暂停页面
>
> 仍有计划或扫描次数上限在生效。请检查[二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#获取二维码)中的 `access.activeAt`、`access.pauseAt` 和 `access.scanLimit`，并将 `scans` 与上限进行比较。

> [accordion] 需要让链接过期
>
> 此 API 不提供 `link.expiresAt`。请改用 `access.pauseAt`。

## 后续步骤

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

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


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