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

# Regole di accesso

> Pianifica un inizio e una fine, limita il numero di scansioni, richiedi una password e metti in pausa, riattiva o elimina un QR code.

> [!NOTE]
>
> L'API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

Controlla quando un QR code si risolve, quante volte può essere scansionato, se richiede una password e se è in pausa o eliminato.

## Prima di iniziare

* **Ruolo.** Per impostare regole, mettere in pausa, riattivare ed eliminare serve l'accesso in scrittura ai QR code del workspace. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md).
* **Abbonamento.** Ogni richiesta API, comprese queste, richiede un abbonamento attivo del proprietario del workspace.

## L'oggetto access

Invia un oggetto `access` quando [crei](https://docs.getqr.com/it/api/endpoints/qr-codes.md#crea-un-qr-code) o [aggiorni](https://docs.getqr.com/it/api/endpoints/qr-codes.md#aggiorna-un-qr-code) un QR code:

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

| Campo | Tipo | Descrizione |
| - | - | - |
| `activeAt` | string (ISO 8601) \| null | Inizio programmato. Prima di questo momento, le scansioni mostrano la pagina di pausa invece della destinazione. `null` significa attivo subito. |
| `pauseAt` | string (ISO 8601) \| null | Fine programmata. Da questo momento in poi, le scansioni mostrano la pagina di pausa. `null` significa nessuna data di fine. |
| `scanLimit` | integer \| null | Numero massimo di scansioni nell'intera vita del QR code. Una volta superato, le scansioni mostrano la pagina di pausa. `null` significa illimitato. |
| `password` | string \| null | Password che i visitatori devono inserire prima di essere reindirizzati. Inviarla attiva anche la protezione. |
| `passwordProtected` | boolean | Indica se il QR code richiede una password. `false` disattiva la protezione ma mantiene la password salvata. `true` la riattiva. |

I campi che ometti restano invariati. Invia `null` per cancellare una regola. Un oggetto `access` parziale non reimposta mai le regole che non hai indicato.

> [!WARNING]
>
> Le regole di accesso vanno in `access`. Inviare `activeAt`, `pauseAt`, `scanLimit`, `password` o `passwordProtected` in `link` restituisce `422`.

## Pianifica un inizio e una fine

`activeAt` e `pauseAt` sono indipendenti: imposta uno dei due o entrambi. Entrambi accettano date e ore ISO 8601, con `Z` o con uno scostamento da 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"
    }
  }'
```

Invia `null` per cancellare la pianificazione. Così il QR code diventa attivo subito e la data di fine viene rimossa:

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

## Limite di scansioni

Limita il numero totale di scansioni. Oltre quel numero, il QR code smette di risolversi:

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

Il contatore delle scansioni totali è sempre attivo, che sia impostato un limite o meno. Per questo la modifica del limite è prevedibile:

* **Aumentare il limite** libera esattamente (nuovo limite meno scansioni totali) scansioni aggiuntive.
* **Ridurre il limite** sotto il totale attuale blocca subito il QR code.
* **Impostare un limite in seguito** conta anche le scansioni effettuate mentre non c'era alcun limite.

`scanLimit` deve essere un numero intero positivo, fino a 2147483647. Invia `null` per nessun limite.

## Protezione con password

Imposta una password tramite lo stesso oggetto `access`. Quando disattivi la protezione, la password salvata viene mantenuta, così puoi riattivarla senza inviarla di nuovo.

**1. Imposta o cambia la password**

In questo modo si attiva anche la protezione.

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

**2. Disattiva la protezione**

La password salvata viene mantenuta.

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

**3. Riattiva la protezione**

Non serve inviare di nuovo la password. Funziona solo se una password è già stata impostata. Altrimenti la richiesta riceve `422`.

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

* **In creazione.** Invia `password` per attivare la protezione. `passwordProtected` da solo non ha effetto finché non esiste una password.
* **Rimuovere la password.** Invia `"password": null`. Anche la protezione viene disattivata.
* **Lettura.** Le risposte non restituiscono mai la password, solo `access.passwordProtected`.

## Pausa, riattivazione ed eliminazione

La pausa e la riattivazione sono endpoint separati e non campi di `access`, perché hanno effetto immediato invece che secondo una pianificazione.

| Metodo | Percorso | Descrizione |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Metti subito in pausa il QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md#metti-in-pausa-un-qr-code). Le scansioni mostrano la pagina di pausa finché non lo riattivi. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Riattiva un QR code in pausa](https://docs.getqr.com/it/api/endpoints/qr-codes.md#riattiva-un-qr-code). Eventuali pianificazioni e limiti di scansioni restano validi. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Elimina definitivamente il QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md#elimina-un-qr-code) e il suo link breve. |

Pausa e riattivazione non richiedono un corpo della richiesta e restituiscono il [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md#l-oggetto-qr-code) aggiornato:

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

Puoi impostare lo stato di pausa anche con `PUT /api/v1/qrs/{qrId}` e `{ "archived": true }`, oppure con `archived` in una `PATCH`. Consulta [Imposta lo stato di pausa](https://docs.getqr.com/it/api/endpoints/qr-codes.md#imposta-lo-stato-di-pausa).

L'eliminazione rimuove insieme il QR code e il suo link breve:

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

> [!WARNING]
>
> L'eliminazione non può essere annullata. Il link breve smette di risolversi, quindi i codici stampati smettono di funzionare. Se potrebbe servirti di nuovo, metti invece il QR code in pausa.

## Quando hanno effetto le modifiche

* **Scansione successiva.** Le regole vengono verificate al momento della scansione, quindi una modifica vale dalla scansione successiva, non in modo retroattivo.
* **Pagina di pausa.** Un QR code bloccato da una pianificazione, da un limite di scansioni o da una pausa mostra la pagina di pausa. La scansione non viene reindirizzata.
* **Password.** I visitatori che hanno già inserito la password mantengono l'accesso finché la password non cambia, o finché la protezione non viene disattivata e riattivata.
* **Orologio.** Le pianificazioni usano l'orologio del server in UTC, non l'ora locale del visitatore.
* **Regole combinate.** Un QR code si risolve solo se non è in pausa, rientra nella sua pianificazione e non ha superato il limite di scansioni.

## Problemi comuni

> [accordion] 422 quando imposto una regola in link
>
> Invia la regola in `access`, non in `link`.

> [accordion] 422 quando attivo la protezione con password
>
> Il QR code non ha ancora una password. Invia `password` invece di `passwordProtected: true`.

> [accordion] Il QR code mostra ancora la pagina di pausa dopo la riattivazione
>
> È ancora valida una pianificazione o un limite di scansioni. Controlla `access.activeAt`, `access.pauseAt` e `access.scanLimit` nel [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md#ottieni-un-qr-code) e confronta `scans` con il limite.

> [accordion] Mi serve che il link scada
>
> `link.expiresAt` non è disponibile in questa API. Usa invece `access.pauseAt`.

## Passaggi successivi

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

> [card] [Dati dei QR code per tipo](https://docs.getqr.com/it/api/guides/qr-types.md)


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