> ## 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/ko/api/authentication.md)을 참조하세요.
* **구독.** 이 요청을 포함한 모든 API 요청에는 워크스페이스 소유자의 활성 구독이 필요합니다.

## access 객체

QR 코드를 [생성](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-생성)하거나 [업데이트](https://docs.getqr.com/ko/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`은 서로 독립적이므로 하나만 설정하거나 둘 다 설정할 수 있습니다. 둘 다 `Z` 또는 UTC 오프셋이 붙은 ISO 8601 날짜·시각을 받습니다.

```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/ko/api/endpoints/qr-codes.md#qr-코드-일시-중지). 다시 활성화할 때까지 스캔하면 일시 중지 페이지가 표시됩니다. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [일시 중지된 QR 코드를 재활성화합니다](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-재활성화). 일정과 스캔 제한은 계속 적용됩니다. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [QR 코드와 단축 링크를 영구적으로 삭제합니다](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-삭제). |

일시 중지와 활성화는 요청 본문이 없으며 업데이트된 [QR 코드](https://docs.getqr.com/ko/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/ko/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/ko/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/ko/api/endpoints/qr-codes.md)

> [card] [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)


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