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.

QR dinamici modificabili: 3 nel piano FreeDestinazione per telefono: dal piano StandardScadenza per data o scansioni: dal piano Standard
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
  }'

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.

Il QR stampato non cambia

L'immagine contiene il link corto stabile: cambiare destinazione non cambia il codice, quindi non devi ristampare.

Pausa e riattivazione

Metti in pausa un QR senza eliminarlo e riattivalo quando serve, per esempio per una promozione a tempo.

Destinazione per telefono

Con lo stesso QR chi usa iPhone va all'App Store, chi usa Android a Google Play e gli altri al tuo sito.

Dal piano Standard
Scadenza per data o scansioni

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.

Dal piano Standard
Statistiche di scansione

Scansioni totali, ultima scansione e andamento per giorno, dispositivo, provenienza e paese (quando disponibile).

Le scansioni non consumano richieste

Le scansioni dei tuoi clienti non contano nella quota di richieste API: contano solo le chiamate che fai tu.

Formati e stile

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

Anche senza scrivere codice

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.

VoceFreeStandardPremiumBusiness
Richieste API al mese 20020.000Nessun limite1.000.000
QR dinamici modificabili 31001.0005.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/dynamic

Header richiesto

x-api-key: LA_TUA_API_KEY
  • POST/api/v1/qrcode/dynamic

    Crea un QR dinamico: destinationUrl (obbligatorio), label, rules, format, size, color, logoUrl. Risposta 201 con id, shortUrl e immagine.

  • GET/api/v1/qrcode/dynamic

    Elenco dei tuoi QR (limit fino a 100, offset) con la quota in uso.

  • GET/api/v1/qrcode/dynamic/:id

    Dettaglio di un QR: stato, destinazione, scansioni totali, ultima scansione.

  • GET/api/v1/qrcode/dynamic/:id/image

    Immagine del QR (format, size, dark, light).

  • GET/api/v1/qrcode/dynamic/:id/stats

    Statistiche per intervallo (from, to): per giorno, dispositivo, telefono, provenienza, paese e scansioni dopo la scadenza.

  • PATCH/api/v1/qrcode/dynamic/:id

    Cambia destinationUrl, label, status (active oppure paused) o rules.

  • DELETE/api/v1/qrcode/dynamic/:id

    Elimina 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

CampoTipoObbligatorioDescrizione
destinationUrltestoSìIndirizzo di destinazione, http o https, fino a 2.048 caratteri. Gli indirizzi verso reti private non sono accettati.
labeltestoNoNome che ti aiuta a riconoscere il QR (per esempio «Tavolo 12»), fino a 120 caratteri.
rulesoggettoNoRegole 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.
formattestoNoFormato dell'immagine restituita: png, jpeg, webp o svg. Predefinito png.
sizenumero interoNoLato dell'immagine in pixel, da 100 a 2.000.
coloroggettoNoColori nel formato #RRGGBB o #RRGGBBAA: { "dark": "#000000", "light": "#FFFFFF" }. I due colori devono essere diversi.
logoUrltestoNoIndirizzo 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

CampoTipoObbligatorioDescrizione
destinationUrltestoNoNuova destinazione: il QR stampato resta lo stesso.
labeltestoNoNuovo nome, fino a 120 caratteri.
statustestoNoactive per attivarlo, paused per metterlo in pausa.
rulesoggettoNoCambia 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

CampoTipoObbligatorioDescrizione
formattestoNoFormato: png, jpeg, webp o svg. Predefinito png.
sizenumero interoNoLato in pixel, da 100 a 2.000.
darktestoNoColore dei moduli, #RRGGBB o #RRGGBBAA.
lighttestoNoColore dello sfondo, #RRGGBB o #RRGGBBAA.

Statistiche di un QR (parametri nell'indirizzo)
GET /api/v1/qrcode/dynamic/:id/stats

CampoTipoObbligatorioDescrizione
fromdata AAAA-MM-GGNoPrimo giorno dell'intervallo.
todata AAAA-MM-GGNoUltimo 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
StatusCodiceQuando accade
403LIMITE_QR_DINAMICIHai raggiunto il numero di QR dinamici del tuo piano.
422CAMPO_NON_CONSENTITOHai inviato un campo che non si può impostare (per esempio il codice).
403REGOLE_NON_INCLUSEHai impostato una regola (destinazione per telefono o scadenza) che il tuo piano non include.
422REGOLA_NON_VALIDAUna regola non è valida: link non pubblico, data non nel formato AAAA-MM-GG, numero di scansioni non intero.
404ROTTA_NON_TROVATAPercorso 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.

Prova QR dinamici con la tua chiave.

Dalla dashboard sviluppatori generi la chiave e gestisci tutto anche senza scrivere codice.