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

# アクセスルール

> 開始と終了の予約、スキャン数の上限、パスワードの設定、QR コードの一時停止・再開・削除。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

QR コードがいつリンク先に進むか、何回スキャンできるか、パスワードを求めるか、一時停止中か削除済みかを制御します。

## 始める前に

* **役割。** ルールの設定、一時停止、再開、削除には、ワークスペースの QR コードへの書き込み権限が必要です。[認証](https://docs.getqr.com/ja/api/authentication.md) をご覧ください。
* **サブスクリプション。** これらを含むすべての API リクエストには、ワークスペースのオーナーの有効なサブスクリプションが必要です。

## access オブジェクト

QR コードを [作成](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを作成する) または [更新](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを更新する) するときに、`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 | QR コードの全期間を通じたスキャン回数の上限。上限を超えると、スキャンすると停止ページが表示されます。`null` の場合は無制限です。 |
| `password` | string \| null | 訪問者がリダイレクト前に入力する必要があるパスワード。送ると保護も有効になります。 |
| `passwordProtected` | boolean | QR コードがパスワードを求めるかどうか。`false` にすると保護はオフになりますが、保存済みのパスワードは残ります。`true` にすると再びオンになります。 |

省略したフィールドは変更されません。ルールをクリアするには `null` を送ります。部分的な `access` オブジェクトを送っても、指定していないルールがリセットされることはありません。

> [!WARNING]
>
> アクセスルールは `access` の下に置きます。`activeAt`、`pauseAt`、`scanLimit`、`password`、`passwordProtected` を `link` の下で送ると `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` を送ります。QR コードはすぐに有効になり、終了日時もなくなります。

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

## スキャン上限

スキャンの合計回数に上限を設けます。上限に達すると、QR コードはリンク先に進まなくなります。

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

全期間のスキャンカウンターは、上限の有無にかかわらず常に動いています。そのため、上限を変更したときの動作は予測できます。

* **上限を引き上げる** と、ちょうど（新しい上限 − 総スキャン数）回分のスキャンが追加で可能になります。
* **上限を引き下げて** 現在の合計を下回ると、QR コードはすぐにブロックされます。
* **後から上限を設定する** と、上限がなかった間のスキャンもカウントされます。

`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` | [QR コードを今すぐ一時停止します](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを一時停止する)。再開するまで、スキャンすると停止ページが表示されます。 |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [一時停止中の QR コードを再開します](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを再開する)。スケジュールとスキャン上限は引き続き適用されます。 |
| `DELETE` | `/api/v1/qrs/{qrId}` | [QR コードとその短縮リンクを完全に削除します](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを削除する)。 |

一時停止と再開はリクエストボディを受け取らず、更新された [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードオブジェクト) を返します。

```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/ja/api/endpoints/qr-codes.md#一時停止状態を設定する) をご覧ください。

削除すると、QR コードとその短縮リンクが一緒に削除されます。

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

> [!WARNING]
>
> 削除は元に戻せません。短縮リンクがリンク先に進まなくなるため、印刷済みのコードも使えなくなります。再び必要になる可能性がある場合は、代わりに QR コードを一時停止してください。

## 変更が反映されるタイミング

* **次のスキャンから。** ルールはコードがスキャンされたときに確認されるため、変更は次のスキャンから適用され、さかのぼって適用されることはありません。
* **停止ページ。** スケジュール、スキャン上限、一時停止によってブロックされた QR コードは、停止ページを表示します。スキャンはリダイレクトされません。
* **パスワード。** すでにパスワードを入力した訪問者は、パスワードが変更されるか、保護がオフにされて再びオンにされるまで、アクセスを維持します。
* **時計。** スケジュールは、訪問者の現地時刻ではなく、UTC のサーバー時刻を使います。
* **ルールの組み合わせ。** QR コードがリンク先に進むのは、一時停止中でなく、スケジュールの期間内で、スキャン上限に達していない場合だけです。

## よくある問題

> [accordion] link の下でルールを設定すると 422 になる
>
> ルールは `link` ではなく `access` の下で送ってください。

> [accordion] パスワード保護をオンにすると 422 になる
>
> QR コードにまだパスワードがありません。`passwordProtected: true` の代わりに `password` を送ってください。

> [accordion] 再開した後も QR コードが停止ページを表示する
>
> スケジュールまたはスキャン上限がまだ適用されています。[QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを取得する) の `access.activeAt`、`access.pauseAt`、`access.scanLimit` を確認し、`scans` を上限と比べてください。

> [accordion] リンクに有効期限を設定したい
>
> この API では `link.expiresAt` は利用できません。代わりに `access.pauseAt` を使ってください。

## 次のステップ

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)

> [card] [QR コードの種類別データ](https://docs.getqr.com/ja/api/guides/qr-types.md)


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