QR code - GetQR Docs

L’API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

In GetQR un QR code è l’immagine più il link breve attraverso cui si risolve. Quando crei un QR code viene creato anche il suo link breve, così puoi cambiare la destinazione in seguito senza ristampare il codice.

Metodo	Percorso	Descrizione
`GET`	`/api/v1/qrs`	Elenca i QR code
`POST`	`/api/v1/qrs`	Crea un QR code
`GET`	`/api/v1/qrs/{qrId}`	Ottieni un QR code
`PATCH`	`/api/v1/qrs/{qrId}`	Aggiorna un QR code
`PUT`	`/api/v1/qrs/{qrId}`	Imposta lo stato di pausa
`POST`	`/api/v1/qrs/{qrId}/pause`	Metti in pausa un QR code
`POST`	`/api/v1/qrs/{qrId}/activate`	Riattiva un QR code
`POST`	`/api/v1/qrs/{qrId}/duplicate`	Duplica un QR code
`DELETE`	`/api/v1/qrs/{qrId}`	Elimina un QR code
`GET`	`/api/v1/qrs/{qrId}/download`	Scarica l’immagine di un QR code

Dati dei QR code per tipo

Il formato di data per ciascuno dei 16 tipi.

Personalizzazione

Stili dei punti, colori, cornici e loghi.

Regole di accesso

Pianificazione, limite di scansioni e password.

Per le statistiche delle scansioni di un QR code, consulta Statistiche.

L’oggetto QR code

Tutti gli endpoint dei QR code rispondono con questo oggetto, tranne Elimina e Scarica. L’elenco ne restituisce un array.

string

ID univoco del QR code, ad esempio qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Tipo di QR code, ad esempio website. Consulta Dati dei QR code per tipo per tutti i 16 valori.

string | null

Nome del QR code, mostrato nella dashboard.

string | null

Nota di testo libero sul QR code.

string

Il payload salvato. Per wifi, vcard, social, multilink, event e sms è il payload che hai inviato. Per tutti gli altri tipi è il link breve, quindi leggi la destinazione da url.

boolean

true quando il QR code è in pausa.

boolean

true per un QR code statico creato nella dashboard, che non ha un link breve. L’API crea sempre QR code dinamici.

string | null

Link breve completo, ad esempio https://getqr.sh/x7Kd2p1.

string | null

Dominio del link breve.

string | null

Slug del link breve.

boolean

true quando lo slug è stato scelto e non generato.

string | null

Destinazione a cui reindirizza il link breve.

string | null

Destinazione per i visitatori iOS, per i QR code app.

string | null

Destinazione per i visitatori Android, per i QR code app.

integer

Numero totale di scansioni.

object

Regole di accesso. La password non viene mai restituita. Consulta Regole di accesso.

Mostra properties

boolean

Indica se i visitatori devono inserire una password.

string | null

Inizio programmato, ISO 8601.

string | null

Fine programmata, ISO 8601.

integer | null

Numero massimo di scansioni.

string

Sola lettura. custom è un design che l’API può modificare completamente. branded e ai sono un design Branded o un design AI creato nella dashboard. L’API non può modificarne l’immagine, ma la mantiene quando modifichi altri campi.

object

Il design salvato: styles, frameOptions e logoOptions, ciascuno un oggetto o null. Hanno la stessa struttura dei campi della richiesta, così puoi reinviarli. Consulta Personalizzazione.

object | null

Il file di un QR code pdf, image o video: id, name e size in byte.

string | null

Sola lettura. Nome visualizzato di un QR code app creato nella dashboard.

object | null

Sola lettura. Un QR code pdf con più file, creato nella dashboard: title, layout e files.

object | null

Sola lettura. Un QR code image con più immagini, creato nella dashboard: title, layout e files.

string

Data di creazione, ISO 8601.

string

Data dell’ultimo aggiornamento, ISO 8601.

I dati riservati e gli ID interni (password, userId, workspaceId, projectId) non vengono mai restituiti.

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}

Elenca i QR code

GET /api/v1/qrs Restituisce i QR code del tuo workspace, una pagina alla volta.

integer

predefinito:"1"

Pagina da restituire, 1 o superiore.

integer

predefinito:"100"

QR code per pagina, da 1 a 100. Un valore maggiore viene rifiutato.

string

Cerca nel titolo del QR code. Le query di più di 2 caratteri cercano anche nel data salvato. Per i tipi con link il data salvato è il link breve, quindi gli URL di destinazione non sono ricercabili.

string

predefinito:"createdAt"

Campo di ordinamento: createdAt, updatedAt, clicks (scansioni totali), lastClicked (ultima scansione) o type. type ordina sempre in senso decrescente e ignora sortOrder.

string

predefinito:"desc"

Direzione dell’ordinamento: asc o desc.

boolean

predefinito:"false"

Include i QR code in pausa.

boolean

predefinito:"false"

Restituisce solo i QR code in pausa. Ha la precedenza su showArchived.

I parametri booleani accettano le stringhe true o false. Richiedi la pagina successiva finché pagination.hasMore è true. Consulta Paginazione.

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

Crea un QR code

POST /api/v1/qrs Crea insieme un QR code e il suo link breve. Risponde 201 Created con il nuovo QR code.

string

Il tuo token per i nuovi tentativi. Se ripeti la richiesta con la stessa chiave entro 24 ore, ricevi la risposta originale invece di creare un secondo QR code. Consulta Nuovi tentativi e duplicati.

string

obbligatorio

Cosa codifica il QR code. Stabilisce anche il formato richiesto per data. Uno tra website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

obbligatorio

Il payload del tipo, verificato in base a qrType. Una stringa vuota salta la verifica. Il formato di ogni tipo è in Dati dei QR code per tipo.

object

Il link breve attraverso cui si risolve il QR code. Facoltativo: se lo ometti, link.url segue data.

Mostra properties

string

Destinazione a cui reindirizza il link breve. Se omesso o vuoto, il valore predefinito è data. Se li invii entrambi e sono diversi, prevale link.url. I QR code vcard, social, multilink ed event puntano sempre alla loro pagina ospitata, e i QR code pdf, image e video con un fileId puntano al file. Schemi accettati: http:, https:, wifi:, mailto:, sms:, begin:.

string

Dominio del link breve. Deve essere un dominio attivo del tuo workspace: un altro dominio riceve 403, e un dominio non ancora attivo riceve 422. Predefinito: il dominio predefinito del workspace.

string

Slug del link breve, da 3 a 15 caratteri, salvato in minuscolo. Uno slug non consentito riceve 422, e uno già occupato riceve 409. Se omesso, viene generato uno slug casuale di 7 caratteri.

string | null

URL di destinazione per i visitatori su iOS, per i QR code app.

string | null

URL di destinazione per i visitatori su Android, per i QR code app.

string | null

Titolo dell’anteprima del link (og:title), salvato sul link breve. È diverso dal title del QR code. Al momento non viene mostrato da nessuna parte.

string | null

Descrizione dell’anteprima del link (og:description), salvata sul link breve. Al momento non viene mostrata da nessuna parte.

—

Non disponibili in questa API: inviarne uno restituisce 422. Usa access.pauseAt per fermare il QR code a un orario stabilito.

string

Nome del QR code, mostrato nella dashboard. Senza spazi iniziali e finali, da 1 a 40 caratteri. Se lo ometti, il QR code resta senza titolo.

string

Nota di testo libero sul QR code. Fino a 280 caratteri.

string

Il file di un QR code pdf, image o video, caricato con il target corrispondente. Per vcard, social e multilink, un’immagine del profilo facoltativa caricata con il target logo. Anche event lo accetta, ma la sua pagina legge la copertina da data.fileId. Gli altri tipi ricevono 422. Carica prima il file con File. Consulta File nei QR code.

string

Template il cui design viene applicato al nuovo QR code. I campi di design che invii vengono uniti sopra di esso. Un template con design Branded o design AI riceve 422 (art_template_unsupported). Un template sconosciuto, o di un altro workspace, riceve 404.

object

Forme e colori di punti e angoli. Consulta Personalizzazione.

object

Cornice disegnata attorno al QR code e testo del suo invito all’azione. Consulta Personalizzazione.

object

Logo al centro: un logo suggerito o un tuo file caricato con il target logo. Un file sconosciuto, un caricamento non completato o un file di un altro target viene rifiutato. Consulta Personalizzazione.

object

Pianificazione, limite di scansioni e protezione con password. Consulta Regole di accesso.

Mostra properties

string | null

Inizio programmato, ISO 8601.

string | null

Fine programmata, ISO 8601.

integer | null

Numero massimo di scansioni, un numero intero positivo.

string | null

Password che i visitatori devono inserire. Inviarla attiva la protezione.

boolean

Disattiva o riattiva la protezione, mantenendo la password salvata.

boolean

Indica se il QR code è in pausa. true lo crea già in pausa: le scansioni mostrano la pagina di pausa invece della destinazione.

I campi sconosciuti vengono scartati senza errori. Consulta Non supportato dall’API.

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}

Nuovi tentativi e duplicati

Con una chiave. Con un header Idempotency-Key, la risposta viene riproposta per 24 ore.
Senza chiave. Un corpo identico inviato entro 30 secondi viene considerato un duplicato.
Risposte riproposte. Una risposta riproposta restituisce la risposta salvata con x-idempotent-replay: true. Un nuovo QR code restituisce false.
Richieste in corso. Una seconda richiesta mentre la prima è ancora in corso riceve 409 conflict.
Errori. Una creazione non riuscita libera subito la chiave, così puoi riprovare con la stessa chiave.
Senza garanzia. Se il meccanismo di protezione non è disponibile, le creazioni vengono eseguite senza protezione.

Consulta anche Idempotenza.

Ottieni un QR code

GET /api/v1/qrs/{qrId} Restituisce un QR code con il suo link breve, le regole di accesso, il design e, per i tipi basati su file, il relativo file.

string

obbligatorio

ID del QR code, dalla risposta dell’elenco o della creazione.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

La risposta è l’oggetto QR code completo.

Aggiorna un QR code

PATCH /api/v1/qrs/{qrId} Modifica il contenuto, la destinazione, il design o le regole di accesso di un QR code. Invia solo i campi che vuoi modificare. Risponde con il QR code aggiornato.

string

obbligatorio

ID del QR code.

Il corpo accetta gli stessi campi di Crea un QR code, tutti facoltativi, con queste differenze:

templateId. Non accettato.
link. Parziale. Se ometti link.url, la destinazione attuale viene mantenuta. link.domain e link.key ricevono 422: il link breve è ciò che il codice stampato codifica, quindi crea un nuovo QR code per usarne uno diverso.
data. Verificato in base al tipo risultante solo quando data o qrType cambiano. Cambiare qrType senza un data corrispondente viene rifiutato. Consulta Cambiare tipo.
Design. styles, frameOptions e logoOptions vengono uniti al design salvato, quindi un oggetto parziale modifica solo ciò che indica. Se scegli un altro logo, sostituisce quello attuale ma ne mantiene la dimensione.
access. Ogni chiave viene applicata se presente. null cancella una regola. Le regole di accesso vanno in access: inviarle in link restituisce 422.
archived. Mette in pausa o riattiva insieme il QR code e il suo link breve, come Metti in pausa e Riattiva.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

Cosa puoi modificare dopo la stampa per ogni tipo è indicato in Dati dei QR code per tipo.

Imposta lo stato di pausa

PUT /api/v1/qrs/{qrId} Imposta direttamente lo stato di pausa. Metti in pausa e Riattiva fanno la stessa cosa in modo più leggibile.

string

obbligatorio

ID del QR code.

boolean

obbligatorio

true per mettere in pausa il QR code, false per riattivarlo.

curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Metti in pausa un QR code

POST /api/v1/qrs/{qrId}/pause Impedisce al QR code di risolversi verso la sua destinazione: le scansioni mostrano invece la pagina di pausa. Il codice stampato e il suo link breve restano validi. Nessun corpo della richiesta.

string

obbligatorio

ID del QR code.

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

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Riattiva un QR code

POST /api/v1/qrs/{qrId}/activate Fa sì che un QR code in pausa torni a risolversi verso la sua destinazione. Eventuali pianificazioni e limiti di scansioni restano validi. Nessun corpo della richiesta.

string

obbligatorio

ID del QR code.

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

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

Duplica un QR code

POST /api/v1/qrs/{qrId}/duplicate Crea una copia con lo stesso contenuto e lo stesso design. Nessun corpo della richiesta. Risponde 201 Created con il nuovo QR code.

string

obbligatorio

ID del QR code da copiare.

Link breve. La copia riceve un proprio link breve, con uno slug casuale sul dominio predefinito del workspace, non sul dominio dell’originale. Le sue scansioni vengono conteggiate separatamente.
Titolo. Al titolo viene aggiunto il suffisso (Copy). Il risultato resta entro 40 caratteri: un titolo lungo viene prima accorciato. Un QR code senza titolo resta senza titolo.
Non copiati. Le regole di accesso (password, pianificazione, limite di scansioni) e lo stato di pausa. La copia è sempre attiva.
File. I file PDF e immagine, compresi quelli di raccolte e gallerie, vengono copiati, quindi appartengono alla copia. I file video e i file di design, come i loghi, sono condivisi con l’originale.

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

{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}

Elimina un QR code

DELETE /api/v1/qrs/{qrId} Elimina il QR code e il suo link breve. Risponde con l’ID eliminato.

L’eliminazione è definitiva. Il codice stampato e il suo link breve smettono di funzionare, e la cronologia delle scansioni non è più accessibile. Se potrebbe servirti di nuovo, metti in pausa il QR code.

string

obbligatorio

ID del QR code.

string

ID del QR code eliminato.

boolean

Sempre true.

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

Scarica l’immagine di un QR code

GET /api/v1/qrs/{qrId}/download Genera il QR code con il suo design e restituisce il file.

string

obbligatorio

ID del QR code da generare, dalla risposta dell’elenco o della creazione.

string

predefinito:"jpg"

Formato di output: jpg, png, svg, pdf (una pagina A4) o eps. Un design Branded o un design AI si scarica solo in jpg, png o pdf.

integer

predefinito:"1024"

Dimensione dell’immagine in pixel: 1024, 2048 o 4096. svg e pdf la ignorano. Un design Branded o un design AI si scarica solo a 1024.

`format`	`Content-Type`	Nome del file
`jpg`	`image/jpeg`	`<title>-<resolution>px.jpg`
`png`	`image/png`	`<title>-<resolution>px.png`
`svg`	`image/svg+xml`	`<title>.svg`
`pdf`	`application/pdf`	`<title>.pdf`
`eps`	`application/postscript`	`<title>-<resolution>px.eps`

Corpo. Il corpo della risposta è il file. Il nome del file suggerito si trova nell’header Content-Disposition ed è costruito dal titolo, oppure è qr-code per un QR code senza titolo.
Cache. Le risposte includono un ETag e Cache-Control: private, max-age=3600, must-revalidate. Rinvia l’ETag in If-None-Match per ricevere 304 Not Modified quando il QR code non è cambiato.
Errori. Un formato o una risoluzione non supportati ricevono 400 bad_request. Il messaggio di errore indica il motivo: qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported o qr_download_art_resolution_unsupported.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>

Regole di accesso

Invia un oggetto access in creazione o in aggiornamento per pianificare un inizio e una fine, limitare il numero di scansioni o richiedere una password. Le regole omesse restano invariate e null ne cancella una. Il comportamento completo, con esempi, è descritto in Regole di accesso.

Oggetti di design

styles, frameOptions e logoOptions impostano le forme di punti e angoli, i colori, la cornice e il logo. Funzionano allo stesso modo su QR code, template e creazioni in blocco. Forme, cornici o loghi sconosciuti vengono rifiutati. Tutti i valori accettati e un esempio completo sono in Personalizzazione.

Problemi comuni

422 quando imposto una password, una pianificazione o un limite di scansioni

Invia la regola in access, non in link.

422 quando modifico link.domain o link.key

Il link breve non può cambiare dopo la creazione, perché il codice stampato lo codifica. Crea invece un nuovo QR code.

422 "Expected … for qrType"

data non corrisponde al formato di qrType. Controlla il tipo in Dati dei QR code per tipo.

409 conflict durante la creazione di un QR code

Una creazione identica è ancora in corso, oppure link.key è già occupato. Riprova quando la prima richiesta è terminata. Con una Idempotency-Key, il nuovo tentativo restituisce il QR code originale.

Il download è un JPEG, non un PNG

I parametri sono format e resolution, e il valore predefinito di format è jpg. Invia format=png.

404 per un QR code che vedo nella dashboard

Ogni richiesta viene eseguita nel workspace della tua chiave API. Verifica che il QR code appartenga a quel workspace. Consulta Autenticazione.

Dati dei QR code per tipo

Personalizzazione

Regole di accesso

​L’oggetto QR code

​Elenca i QR code

​Crea un QR code

​Nuovi tentativi e duplicati

​Ottieni un QR code

​Aggiorna un QR code

​Imposta lo stato di pausa

​Metti in pausa un QR code

​Riattiva un QR code

​Duplica un QR code

​Elimina un QR code

​Scarica l’immagine di un QR code

​Regole di accesso

​Oggetti di design

​Problemi comuni

​Passaggi successivi

Dati dei QR code per tipo

Personalizzazione

Regole di accesso

Statistiche

L’oggetto QR code

Elenca i QR code

Crea un QR code

Nuovi tentativi e duplicati

Ottieni un QR code

Aggiorna un QR code

Imposta lo stato di pausa

Metti in pausa un QR code

Riattiva un QR code

Duplica un QR code

Elimina un QR code

Scarica l’immagine di un QR code

Regole di accesso

Oggetti di design

Problemi comuni

Passaggi successivi