Zugriffsregeln

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.
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 oder aktualisieren:

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.

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.

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:

{
  "access": { "activeAt": null, "pauseAt": null }
}

Scan-Limit

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

{
  "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.

Passwort festlegen oder ändern

Dadurch wird auch der Schutz eingeschaltet.

{ "access": { "password": "hunter2" } }

Schutz ausschalten

Das gespeicherte Passwort bleibt erhalten.

{ "access": { "passwordProtected": false } }

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.

{ "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. Scans zeigen die Pausierungsseite, bis Sie ihn reaktivieren.
`POST`	`/api/v1/qrs/{qrId}/activate`	Einen pausierten QR-Code reaktivieren. Zeitplan und Scan-Limit gelten weiterhin.
`DELETE`	`/api/v1/qrs/{qrId}`	Den QR-Code und seinen Kurzlink dauerhaft löschen.

Pausieren und Aktivieren erwarten keinen Anfrage-Body und liefern den aktualisierten QR-Code:

curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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. Beim Löschen werden der QR-Code und sein Kurzlink gemeinsam entfernt:

{ "id": "qr_abc123", "deleted": true }

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

422 beim Festlegen einer Regel unter link

Senden Sie die Regel unter access, nicht unter link.

422 beim Einschalten des Passwortschutzes

Der QR-Code hat noch kein Passwort. Senden Sie password statt passwordProtected: true.

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 und vergleichen Sie scans mit dem Limit.

Der Link soll ablaufen

link.expiresAt ist in dieser API nicht verfügbar. Verwenden Sie stattdessen access.pauseAt.

API

Bevor Sie beginnen

Das Zugriffsobjekt

Start und Ende planen

Scan-Limit

Passwortschutz

Pausieren, reaktivieren und löschen

Wann Änderungen wirksam werden

Häufige Probleme

Wie geht es weiter?

QR-Codes

QR-Code-Daten nach Typ

​Bevor Sie beginnen

​Das Zugriffsobjekt

​Start und Ende planen

​Scan-Limit

​Passwortschutz

​Pausieren, reaktivieren und löschen

​Wann Änderungen wirksam werden

​Häufige Probleme

​Wie geht es weiter?

QR-Codes

QR-Code-Daten nach Typ

Bevor Sie beginnen

Das Zugriffsobjekt

Start und Ende planen

Scan-Limit

Passwortschutz

Pausieren, reaktivieren und löschen

Wann Änderungen wirksam werden

Häufige Probleme

Wie geht es weiter?