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

# Zugriffsregeln

> Planen Sie Start und Ende, begrenzen Sie die Anzahl der Scans, verlangen Sie ein Passwort und pausieren, reaktivieren oder löschen Sie einen QR-Code.

> [!NOTE]
>
> Die GetQR API befindet sich in der Beta-Phase und steht ausgewählten Workspaces zur Verfügung. Details können sich bis zur allgemeinen Veröffentlichung noch ändern.

Steuern Sie, wann ein QR-Code aufgelöst wird, wie oft er gescannt werden kann, ob er ein Passwort verlangt und ob er pausiert oder gelöscht ist.

## Bevor Sie beginnen

* **Rolle.** Regeln festlegen, pausieren, reaktivieren und löschen erfordert Schreibzugriff auf QR-Codes im Workspace. Siehe [Authentifizierung](https://docs.getqr.com/de/api/authentication.md).
* **Abonnement.** Jede API-Anfrage, auch diese, erfordert ein aktives Abonnement des Workspace-Admins.

## Das Zugriffsobjekt

Senden Sie ein `access`-Objekt, wenn Sie einen QR-Code [erstellen](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-erstellen) oder [aktualisieren](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-aktualisieren):

```text theme={null}
POST  /api/v1/qrs
PATCH /api/v1/qrs/{qrId}
```

| Feld | Typ | Beschreibung |
| - | - | - |
| `activeAt` | string (ISO 8601) \| null | Geplanter Start. Vor diesem Zeitpunkt zeigen Scans die Pausierungsseite statt des Ziels. `null` bedeutet sofort aktiv. |
| `pauseAt` | string (ISO 8601) \| null | Geplantes Ende. Ab diesem Zeitpunkt zeigen Scans die Pausierungsseite. `null` bedeutet kein Enddatum. |
| `scanLimit` | integer \| null | Maximale Anzahl an Scans über die gesamte Lebensdauer des QR-Codes. Ist sie überschritten, zeigen Scans die Pausierungsseite. `null` bedeutet unbegrenzt. |
| `password` | string \| null | Passwort, das Besucher vor der Weiterleitung eingeben müssen. Wenn Sie es senden, wird der Schutz zugleich eingeschaltet. |
| `passwordProtected` | boolean | Ob der QR-Code ein Passwort verlangt. `false` schaltet den Schutz aus, behält aber das gespeicherte Passwort. `true` schaltet ihn wieder ein. |

Felder, die Sie weglassen, bleiben unverändert. Senden Sie `null`, um eine Regel zu entfernen. Ein unvollständiges `access`-Objekt setzt nie Regeln zurück, die Sie nicht nennen.

> [!WARNING]
>
> Zugriffsregeln gehören unter `access`. Wer `activeAt`, `pauseAt`, `scanLimit`, `password` oder `passwordProtected` unter `link` sendet, erhält `422`.

## Start und Ende planen

`activeAt` und `pauseAt` sind unabhängig voneinander: Setzen Sie eines davon oder beide. Beide erwarten Datums- und Zeitangaben nach ISO 8601, mit `Z` oder einem UTC-Offset.

```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"
    }
  }'
```

Senden Sie `null`, um den Zeitplan zu entfernen. Dadurch ist der QR-Code sofort aktiv, und das Enddatum entfällt:

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

## Scan-Limit

Begrenzen Sie die Gesamtzahl der Scans. Danach wird der QR-Code nicht mehr aufgelöst:

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

Der Zähler für alle Scans läuft immer, ob ein Limit gesetzt ist oder nicht. Deshalb sind Änderungen am Limit vorhersehbar:

* **Limit erhöhen** gibt genau (neues Limit minus bisherige Scans) weitere Scans frei.
* **Limit senken** unter die aktuelle Gesamtzahl sperrt den QR-Code sofort.
* **Limit nachträglich setzen** zählt auch die Scans mit, die ohne Limit erfolgt sind.

`scanLimit` muss eine positive ganze Zahl bis 2147483647 sein. Senden Sie `null` für unbegrenzt.

## Passwortschutz

Legen Sie ein Passwort über dasselbe `access`-Objekt fest. Das gespeicherte Passwort bleibt erhalten, wenn Sie den Schutz ausschalten, sodass Sie ihn wieder einschalten können, ohne es erneut zu senden.

**1. Passwort festlegen oder ändern**

Dadurch wird auch der Schutz eingeschaltet.

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

**2. Schutz ausschalten**

Das gespeicherte Passwort bleibt erhalten.

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

**3. Schutz wieder einschalten**

Sie müssen das Passwort nicht erneut senden. Das funktioniert nur, wenn bereits ein Passwort festgelegt wurde. Andernfalls erhält die Anfrage `422`.

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

* **Beim Erstellen.** Senden Sie `password`, um den Schutz einzuschalten. `passwordProtected` allein hat keine Wirkung, solange kein Passwort existiert.
* **Passwort entfernen.** Senden Sie `"password": null`. Damit wird auch der Schutz ausgeschaltet.
* **Lesen.** Antworten liefern nie das Passwort, nur `access.passwordProtected`.

## Pausieren, reaktivieren und löschen

Pausieren und Reaktivieren sind eigene Endpunkte statt `access`-Felder, weil sie sofort wirken statt nach Zeitplan.

| Methode | Pfad | Beschreibung |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Den QR-Code jetzt pausieren](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-pausieren). Scans zeigen die Pausierungsseite, bis Sie ihn reaktivieren. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Einen pausierten QR-Code reaktivieren](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-reaktivieren). Zeitplan und Scan-Limit gelten weiterhin. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Den QR-Code](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-löschen) und seinen Kurzlink dauerhaft löschen. |

Pausieren und Aktivieren erwarten keinen Anfrage-Body und liefern den aktualisierten [QR-Code](https://docs.getqr.com/de/api/endpoints/qr-codes.md#das-qr-code-objekt):

```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,
  "…": "…"
}
```

Sie können den Pausierungsstatus auch mit `PUT /api/v1/qrs/{qrId}` und `{ "archived": true }` festlegen oder mit `archived` in einem `PATCH`. Siehe [Pausierungsstatus festlegen](https://docs.getqr.com/de/api/endpoints/qr-codes.md#pausierungsstatus-festlegen).

Beim Löschen werden der QR-Code und sein Kurzlink gemeinsam entfernt:

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

> [!WARNING]
>
> Löschen lässt sich nicht rückgängig machen. Der Kurzlink wird nicht mehr aufgelöst, sodass gedruckte Codes nicht mehr funktionieren. Pausieren Sie den QR-Code stattdessen, wenn Sie ihn eventuell wieder brauchen.

## Wann Änderungen wirksam werden

* **Nächster Scan.** Regeln werden beim Scannen geprüft, daher gilt eine Änderung ab dem nächsten Scan, nicht rückwirkend.
* **Pausierungsseite.** Ein QR-Code, der durch einen Zeitplan, ein Scan-Limit oder eine Pause gesperrt ist, zeigt die Pausierungsseite. Der Scan wird nicht weitergeleitet.
* **Passwort.** Besucher, die das Passwort bereits eingegeben haben, behalten den Zugriff, bis sich das Passwort ändert oder der Schutz aus- und wieder eingeschaltet wird.
* **Uhrzeit.** Zeitpläne verwenden die Serveruhr in UTC, nicht die Ortszeit des Besuchers.
* **Regeln greifen zusammen.** Ein QR-Code wird nur aufgelöst, wenn er nicht pausiert ist, innerhalb seines Zeitplans liegt und sein Scan-Limit nicht erreicht hat.

## Häufige Probleme

> [accordion] 422 beim Festlegen einer Regel unter link
>
> Senden Sie die Regel unter `access`, nicht unter `link`.

> [accordion] 422 beim Einschalten des Passwortschutzes
>
> Der QR-Code hat noch kein Passwort. Senden Sie `password` statt `passwordProtected: true`.

> [accordion] Der QR-Code zeigt nach dem Reaktivieren weiterhin die Pausierungsseite
>
> Ein Zeitplan oder Scan-Limit greift noch. Prüfen Sie `access.activeAt`, `access.pauseAt` und `access.scanLimit` im [QR-Code](https://docs.getqr.com/de/api/endpoints/qr-codes.md#qr-code-abrufen) und vergleichen Sie `scans` mit dem Limit.

> [accordion] Der Link soll ablaufen
>
> `link.expiresAt` ist in dieser API nicht verfügbar. Verwenden Sie stattdessen `access.pauseAt`.

## Wie geht es weiter?

> [card] [QR-Codes](https://docs.getqr.com/de/api/endpoints/qr-codes.md)

> [card] [QR-Code-Daten nach Typ](https://docs.getqr.com/de/api/guides/qr-types.md)


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