API REST · QR dinamici
Stampi una volta, cambi la destinazione quando vuoi
Crea QR che puntano a un link corto stabile. Cambia la destinazione, metti in pausa o riattiva e leggi le statistiche di scansione, senza ristampare.
curl -X POST "https://www.qrcodegenerate.it/api/v1/qrcode/dynamic" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{
"destinationUrl": "https://www.esempio.it/menu",
"label": "Tavolo 12",
"format": "png",
"size": 600
}'
Perché usarlo.
Un QR dinamico contiene un link corto del nostro dominio. Quando qualcuno lo inquadra, lo portiamo alla destinazione che hai impostato. Se la destinazione cambia, il QR stampato resta lo stesso: aggiorni il link con una chiamata API o dalla dashboard.
L'immagine contiene il link corto stabile: cambiare destinazione non cambia il codice, quindi non devi ristampare.
Metti in pausa un QR senza eliminarlo e riattivalo quando serve, per esempio per una promozione a tempo.
Con lo stesso QR chi usa iPhone va all'App Store, chi usa Android a Google Play e gli altri al tuo sito.
Il QR smette di portare alla destinazione dopo una data o dopo un numero di scansioni, e mostra la pagina «Offerta terminata» o un link di riserva.
Scansioni totali, ultima scansione e andamento per giorno, dispositivo, provenienza e paese (quando disponibile).
Le scansioni dei tuoi clienti non contano nella quota di richieste API: contano solo le chiamate che fai tu.
Immagine in PNG, JPEG, WebP o SVG, dimensione da 100 a 2000 pixel, colori a scelta e logo al centro (sull'SVG il logo non si applica).
Dalla dashboard sviluppatori crei, modifichi, metti in pausa, scarichi e controlli le statistiche, con la stessa chiave e gli stessi limiti.
Come funziona.
Crea il QR con una chiamata POST indicando la destinazione: ricevi il link corto e l'immagine.
Stampa o pubblica l'immagine: contiene sempre lo stesso link corto.
Quando serve, cambia la destinazione con PATCH o mettilo in pausa; leggi le statistiche con GET.
Cosa include ogni piano.
I limiti sono quelli dei piani in vigore. Un valore «Nessun limite» significa che non c'è un tetto per quella voce. Sul telefono la tabella scorre di lato.
| Voce | Free | Standard | Premium | Business |
|---|---|---|---|---|
| Richieste API al mese | 200 | 20.000 | Nessun limite | 1.000.000 |
| QR dinamici modificabili | 3 | 100 | 1.000 | 5.000 |
| Destinazione per telefono | — | ✓ | ✓ | ✓ |
| Scadenza per data o scansioni | — | ✓ | ✓ | ✓ |
Tutti i prodotti dell'API REST usano la stessa chiave e lo stesso piano. Prezzi e dettagli nella pagina Piani e prezzi.
Scheda tecnica.
Tutte le richieste partono da https://www.qrcodegenerate.it. Le risposte sono in JSON e gli errori hanno sempre la forma
{ "status", "code", "message" }. La chiave va conservata lato server: non inserirla in codice pubblico o in un frontend non protetto.
QR dinamici 7 · /api/v1/qrcode/dynamic
Indirizzo
https://www.qrcodegenerate.it/api/v1/qrcode/dynamicHeader richiesto
x-api-key: LA_TUA_API_KEY- POST
/api/v1/qrcode/dynamicCrea un QR dinamico: destinationUrl (obbligatorio), label, rules, format, size, color, logoUrl. Risposta 201 con id, shortUrl e immagine.
- GET
/api/v1/qrcode/dynamicElenco dei tuoi QR (limit fino a 100, offset) con la quota in uso.
- GET
/api/v1/qrcode/dynamic/:idDettaglio di un QR: stato, destinazione, scansioni totali, ultima scansione.
- GET
/api/v1/qrcode/dynamic/:id/imageImmagine del QR (format, size, dark, light).
- GET
/api/v1/qrcode/dynamic/:id/statsStatistiche per intervallo (from, to): per giorno, dispositivo, telefono, provenienza, paese e scansioni dopo la scadenza.
- PATCH
/api/v1/qrcode/dynamic/:idCambia destinationUrl, label, status (active oppure paused) o rules.
- DELETE
/api/v1/qrcode/dynamic/:idElimina il QR (eliminazione logica).
Parametri 4 richieste
Per ogni richiesta con un corpo o con parametri nell'indirizzo ecco i campi ammessi. «Obbligatorio» vuol dire che senza quel campo la richiesta viene rifiutata; un campo che non è in tabella viene rifiutato con CAMPO_NON_CONSENTITO.
Crea un QR (corpo JSON)POST /api/v1/qrcode/dynamic
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
destinationUrl | testo | Sì | Indirizzo di destinazione, http o https, fino a 2.048 caratteri. Gli indirizzi verso reti private non sono accettati. |
label | testo | No | Nome che ti aiuta a riconoscere il QR (per esempio «Tavolo 12»), fino a 120 caratteri. |
rules | oggetto | No | Regole facoltative, incluse secondo il piano: { "ios": link per iPhone e iPad, "android": link per Android, "expiresAt": "AAAA-MM-GG" (fine del giorno, ora italiana) o data e ora ISO 8601, "maxScans": numero di scansioni, "afterExpiry": { "url": link dopo la scadenza, "message": testo della pagina «Offerta terminata» } }. Le anteprime dei link nelle chat non contano come scansioni. |
format | testo | No | Formato dell'immagine restituita: png, jpeg, webp o svg. Predefinito png. |
size | numero intero | No | Lato dell'immagine in pixel, da 100 a 2.000. |
color | oggetto | No | Colori nel formato #RRGGBB o #RRGGBBAA: { "dark": "#000000", "light": "#FFFFFF" }. I due colori devono essere diversi. |
logoUrl | testo | No | Indirizzo di un'immagine da mettere al centro del QR. Non si applica al formato svg. |
Modifica un QR (corpo JSON, almeno un campo)PATCH /api/v1/qrcode/dynamic/:id
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
destinationUrl | testo | No | Nuova destinazione: il QR stampato resta lo stesso. |
label | testo | No | Nuovo nome, fino a 120 caratteri. |
status | testo | No | active per attivarlo, paused per metterlo in pausa. |
rules | oggetto | No | Cambia solo le regole che invii; null toglie una regola, "rules": null le toglie tutte. Togliere una regola è sempre possibile, anche se il piano non la include più. |
Immagine di un QR (parametri nell'indirizzo)GET /api/v1/qrcode/dynamic/:id/image
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
format | testo | No | Formato: png, jpeg, webp o svg. Predefinito png. |
size | numero intero | No | Lato in pixel, da 100 a 2.000. |
dark | testo | No | Colore dei moduli, #RRGGBB o #RRGGBBAA. |
light | testo | No | Colore dello sfondo, #RRGGBB o #RRGGBBAA. |
Statistiche di un QR (parametri nell'indirizzo)GET /api/v1/qrcode/dynamic/:id/stats
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
from | data AAAA-MM-GG | No | Primo giorno dell'intervallo. |
to | data AAAA-MM-GG | No | Ultimo giorno incluso. L'intervallo può durare al massimo 400 giorni. I giorni sono quelli dell'Italia (Europe/Rome). |
Risposte d'esempio 3
Gli esempi qui sotto sono risposte reali dell'API, con valori di fantasia. Le risposte di successo hanno "status": "success" e i dati in data.
Risposta alla creazione
{
"status": "success",
"message": "QR dinamico creato.",
"data": {
"id": "0b8f6c1e-2a47-4d1b-9a53-6f0c2e7d8a14",
"code": "bkuhmkzc",
"shortUrl": "https://www.qrcodegenerate.it/q/bkuhmkzc",
"destinationUrl": "https://www.esempio.it/menu",
"label": "Tavolo 12",
"status": "active",
"scanTotal": 0,
"lastScanAt": null,
"rules": {
"ios": null,
"android": null,
"expiresAt": null,
"maxScans": null,
"afterExpiry": {
"url": null,
"message": ""
}
},
"expired": false,
"createdAt": "2026-10-04T10:00:00.000Z",
"updatedAt": "2026-10-04T10:00:00.000Z",
"qr": {
"format": "png",
"mimeType": "image/png",
"base64": "data:image/png;base64,iVBORw0KGgo…"
}
}
}
Il campo base64 contiene l'immagine intera; qui è accorciato.
Risposta all'elenco
{
"status": "success",
"data": {
"items": [
{
"id": "0b8f6c1e-2a47-4d1b-9a53-6f0c2e7d8a14",
"code": "bkuhmkzc",
"shortUrl": "https://www.qrcodegenerate.it/q/bkuhmkzc",
"destinationUrl": "https://www.esempio.it/menu",
"label": "Tavolo 12",
"status": "active",
"scanTotal": 0,
"lastScanAt": null,
"rules": {
"ios": null,
"android": null,
"expiresAt": null,
"maxScans": null,
"afterExpiry": {
"url": null,
"message": ""
}
},
"expired": false,
"createdAt": "2026-10-04T10:00:00.000Z",
"updatedAt": "2026-10-04T10:00:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0,
"quota": {
"used": 1,
"max": 100
}
}
}
In quota, max è il limite del tuo piano (null se non c'è un tetto): il valore qui è solo un esempio.
Risposta alle statistiche
{
"status": "success",
"data": {
"from": "2026-10-01",
"to": "2026-10-04",
"total": 1,
"byDay": [
{
"day": "2026-10-04",
"count": 1
}
],
"byDevice": {
"mobile": 1
},
"byCountry": {
"IT": 1
},
"bySource": {
"instagram": 1
},
"bySystem": {
"ios": 1
},
"afterExpiry": 0
}
}
Paginazione, limiti di frequenza, webhook, formato delle date ed errori sono spiegati nella guida comune.
Errori frequenti 5
| Status | Codice | Quando accade |
|---|---|---|
403 | LIMITE_QR_DINAMICI | Hai raggiunto il numero di QR dinamici del tuo piano. |
422 | CAMPO_NON_CONSENTITO | Hai inviato un campo che non si può impostare (per esempio il codice). |
403 | REGOLE_NON_INCLUSE | Hai impostato una regola (destinazione per telefono o scadenza) che il tuo piano non include. |
422 | REGOLA_NON_VALIDA | Una regola non è valida: link non pubblico, data non nel formato AAAA-MM-GG, numero di scansioni non intero. |
404 | ROTTA_NON_TROVATA | Percorso inesistente o identificativo non valido: la risposta è sempre JSON. |
Ogni risposta di errore ha la forma { status, code, message }.
I QR e le statistiche sono sempre privati: vedi solo quelli del tuo account.
Esempi 2
Crea un QR dinamico
curl -X POST "https://www.qrcodegenerate.it/api/v1/qrcode/dynamic" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{
"destinationUrl": "https://www.esempio.it/menu",
"label": "Tavolo 12",
"format": "png",
"size": 600
}'
Cambia la destinazione senza ristampare
curl -X PATCH "https://www.qrcodegenerate.it/api/v1/qrcode/dynamic/ID_DEL_QR" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{ "destinationUrl": "https://www.esempio.it/menu-autunno" }'
Gli esempi per i linguaggi più comuni sul generatore di QR statici sono nella documentazione generale.
Domande frequenti.
Cosa cambia rispetto a un QR statico?
Il QR statico contiene direttamente il contenuto e non si può modificare. Il QR dinamico contiene un link corto: puoi cambiare la destinazione senza ristampare e vedere le scansioni.
Le scansioni dei clienti consumano la mia quota di richieste?
No. La quota di richieste conta solo le chiamate API che fai tu.
Cosa vede chi scansiona un QR scaduto?
La pagina «Offerta terminata» con il messaggio che scrivi tu, oppure il link di riserva che hai scelto. Spostando la data o alzando il numero di scansioni il QR torna attivo.
Posso mettere il logo?
Sì, con il parametro logoUrl sui formati PNG, JPEG e WebP. Se il logo non può essere usato, il QR esce senza logo e la risposta lo segnala.
Altri servizi dell'API REST.
Emetti biglietti con QR firmato e convalidali ai varchi dal telefono, con chiavi dedicate e senza doppi ingressi.
Etichette digitali →Una pagina pubblica neutra per ogni prodotto, raggiungibile da un QR sull'etichetta. Modello pronto per il vino e modelli tuoi, con versioni.
Anti-contraffazione →Un QR unico e firmato per ogni pezzo venduto: chi lo inquadra vede se il codice è del produttore e quante volte è già stato controllato, e può registrarlo con un PIN nascosto.
Prova QR dinamici con la tua chiave.
Dalla dashboard sviluppatori generi la chiave e gestisci tutto anche senza scrivere codice.