Regole di accesso

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.
Abbonamento. Ogni richiesta API, comprese queste, richiede un abbonamento attivo del proprietario del workspace.

L’oggetto access

Invia un oggetto access quando crei o aggiorni un QR code:

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.

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.

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:

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

Limite di scansioni

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

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

Imposta o cambia la password

In questo modo si attiva anche la protezione.

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

Disattiva la protezione

La password salvata viene mantenuta.

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

Riattiva la protezione

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

{ "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. Le scansioni mostrano la pagina di pausa finché non lo riattivi.
`POST`	`/api/v1/qrs/{qrId}/activate`	Riattiva un QR code in pausa. Eventuali pianificazioni e limiti di scansioni restano validi.
`DELETE`	`/api/v1/qrs/{qrId}`	Elimina definitivamente il QR code e il suo link breve.

Pausa e riattivazione non richiedono un corpo della richiesta e restituiscono il QR code aggiornato:

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

{
  "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. L’eliminazione rimuove insieme il QR code e il suo link breve:

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

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

422 quando imposto una regola in link

Invia la regola in access, non in link.

422 quando attivo la protezione con password

Il QR code non ha ancora una password. Invia password invece di passwordProtected: true.

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 e confronta scans con il limite.

Mi serve che il link scada

link.expiresAt non è disponibile in questa API. Usa invece access.pauseAt.

API

Prima di iniziare

L’oggetto access

Pianifica un inizio e una fine

Limite di scansioni

Protezione con password

Pausa, riattivazione ed eliminazione

Quando hanno effetto le modifiche

Problemi comuni

Passaggi successivi

QR code

Dati dei QR code per tipo

​Prima di iniziare

​L’oggetto access

​Pianifica un inizio e una fine

​Limite di scansioni

​Protezione con password

​Pausa, riattivazione ed eliminazione

​Quando hanno effetto le modifiche

​Problemi comuni

​Passaggi successivi

QR code

Dati dei QR code per tipo

Prima di iniziare

L’oggetto access

Pianifica un inizio e una fine

Limite di scansioni

Protezione con password

Pausa, riattivazione ed eliminazione

Quando hanno effetto le modifiche

Problemi comuni

Passaggi successivi