> ## 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]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

Керуйте тим, коли QR-код спрацьовує, скільки разів його можна відсканувати, чи запитує він пароль і чи призупинений або видалений він.

## Перш ніж почати

* **Роль.** Щоб задавати правила, призупиняти, відновлювати й видаляти, потрібен доступ на запис до QR-кодів у робочому просторі. Див. [Автентифікація](https://docs.getqr.com/ua/api/authentication.md).
* **Підписка.** Кожен запит до API, зокрема ці, потребує активної підписки власника робочого простору.

## Об'єкт access

Надсилайте об'єкт `access`, коли [створюєте](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#створення-qr-коду) або [оновлюєте](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#оновлення-qr-коду) QR-код:

```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/ua/api/endpoints/qr-codes.md#призупинення-qr-коду). Під час сканування показується сторінка паузи, доки ви його не відновите. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Відновити призупинений QR-код](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#відновлення-qr-коду). Розклад і ліміт сканувань, якщо їх задано, і далі діють. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Остаточно видалити QR-код](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#видалення-qr-коду) та його коротке посилання. |

Призупинення й відновлення не приймають тіла запиту й повертають оновлений [QR-код](https://docs.getqr.com/ua/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 }` або через `archived` у `PATCH`. Див. [Встановлення стану паузи](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#встановлення-стану-паузи).

Видалення прибирає QR-код разом із його коротким посиланням:

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

> [!WARNING]
>
> Видалення неможливо скасувати. Коротке посилання перестає працювати, тож надруковані коди перестають працювати теж. Якщо QR-код може знадобитися знову, краще призупиніть його.

## Коли зміни набувають чинності

* **Наступне сканування.** Правила перевіряються під час сканування коду, тож зміна діє з наступного сканування, а не заднім числом.
* **Сторінка паузи.** QR-код, заблокований розкладом, лімітом сканувань або паузою, показує сторінку паузи. Сканування не перенаправляється.
* **Пароль.** Відвідувачі, які вже ввели пароль, зберігають доступ, доки пароль не зміниться або доки захист не вимкнуть і не ввімкнуть знову.
* **Годинник.** Розклади використовують годинник сервера в UTC, а не місцевий час відвідувача.
* **Правила діють разом.** QR-код спрацьовує, лише якщо він не призупинений, перебуває в межах розкладу й не перевищив ліміт сканувань.

## Поширені проблеми

> [accordion] 422 під час задання правила в link
>
> Надсилайте правило в `access`, а не в `link`.

> [accordion] 422 під час увімкнення захисту паролем
>
> QR-код ще не має пароля. Надішліть `password` замість `passwordProtected: true`.

> [accordion] Після відновлення QR-код і далі показує сторінку паузи
>
> Діє розклад або ліміт сканувань. Перевірте `access.activeAt`, `access.pauseAt` і `access.scanLimit` у [QR-коді](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#отримання-qr-коду) і порівняйте `scans` з лімітом.

> [accordion] Мені потрібно, щоб посилання завершило дію
>
> `link.expiresAt` у цьому API недоступний. Натомість використовуйте `access.pauseAt`.

## Що далі

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)

> [card] [Дані QR-коду за типами](https://docs.getqr.com/ua/api/guides/qr-types.md)


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