API REST · Etichette digitali
Una pagina neutra raggiungibile da un QR
Pubblica ingredienti, allergeni, valori nutrizionali e altre informazioni di prodotto in una pagina pubblica, in più lingue, collegata a un QR sull'etichetta.
curl -X POST "https://www.qrcodegenerate.it/api/v1/labels/products" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{
"templateId": "vino",
"name": "Rosso Esempio 2024",
"languages": ["it", "en"],
"data": {
"produttore": "Cantina Esempio",
"annata": "2024",
"gradazione": 13.5,
"denominazione": { "it": "Vino rosso", "en": "Red wine" },
"ingredienti": { "it": ["Uve"], "en": ["Grapes"] }
}
}'
Perché usarlo.
Per ogni prodotto crei una scheda a partire da un modello. La scheda ha una pagina pubblica con un indirizzo che non cambia quando aggiorni i dati: ci stampi il QR sull'etichetta. La pagina è neutra, cioè mostra solo le informazioni di prodotto.
Nessun cookie, nessuno script, nessun link e nessuna pubblicità: la pagina mostra solo le informazioni del prodotto e non registra le letture.
Produttore, annata, titolo alcolometrico, volume, lotto, ingredienti, allergeni e dichiarazione nutrizionale per 100 ml.
Definisci sezioni (dettagli, elenco, tabella) e campi di testo, testo lungo, elenco e numero, con lingue, campi obbligatori e traducibili. Anche dalla dashboard, con anteprima.
Ogni modifica a un modello crea una nuova versione: le schede già pubblicate restano come sono finché non le porti alla nuova versione.
Italiano, inglese, tedesco, francese e spagnolo. I campi traducibili hanno un valore per lingua; se una traduzione manca, la pagina mostra la lingua base, indicata come tale.
Con il numero di revisione, se due persone modificano la stessa scheda la seconda riceve un conflitto invece di sovrascrivere il lavoro della prima.
Leggi come funziona l'etichetta elettronica del vino, cosa chiedono le regole europee in breve e cosa resta a te. Vai alla pagina per cantine
Come funziona.
Scegli un modello: quello per il vino oppure uno che hai creato tu.
Crea la scheda con i dati del prodotto e le lingue: ricevi il link pubblico e l'immagine del QR.
Stampa il QR sull'etichetta. Aggiorna i dati quando vuoi: l'indirizzo resta lo stesso.
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 |
| Etichette digitali | 3 | 50 | 500 | 2.000 |
| Modelli di etichetta propri | 2 | 10 | 50 | 200 |
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.
Modelli 5 · /api/v1/labels
Indirizzo
https://www.qrcodegenerate.it/api/v1/labelsHeader richiesto
x-api-key: LA_TUA_API_KEY- GET
/api/v1/labels/templatesModelli disponibili (predefiniti e tuoi) con campi, tipi, limiti ed etichette per lingua, più la quota dei tuoi modelli.
- POST
/api/v1/labels/templatesCrea un tuo modello: title, languages, sections. I modelli propri sono sempre neutri.
- GET
/api/v1/labels/templates/:idDettaglio di un modello (version per le versioni precedenti dei tuoi).
- PUT
/api/v1/labels/templates/:idSalva una nuova versione del tuo modello. Le schede esistenti non cambiano.
- DELETE
/api/v1/labels/templates/:idArchivia il tuo modello: le schede già create continuano a vedersi.
Schede prodotto 16 · /api/v1/labels
Indirizzo
https://www.qrcodegenerate.it/api/v1/labelsHeader richiesto
x-api-key: LA_TUA_API_KEY- POST
/api/v1/labels/productsCrea una scheda: templateId, name, languages, data.
- GET
/api/v1/labels/productsElenco delle schede (limit, offset) con la quota in uso.
- GET
/api/v1/labels/products/:idDettaglio di una scheda, con il link pubblico.
- PATCH
/api/v1/labels/products/:idModifica name, languages, data (null cancella un campo), revision e templateVersion.
- DELETE
/api/v1/labels/products/:idElimina la scheda: la pagina pubblica risponde «non più disponibile».
- GET
/api/v1/labels/products/:id/imageImmagine del QR del link pubblico (format, size, dark, light).
- GET
/api/v1/labels/products/:id/historyStorico delle revisioni, dalla più recente (limit, offset): cosa mostrava la pagina, quando, da dove (api o dashboard) e quali campi erano cambiati.
- GET
/api/v1/labels/products/:id/history/:revisionUna revisione dello storico.
- POST
/api/v1/labels/products/:id/lotsCrea un lotto: una pagina figlia della scheda con il suo QR, dove alcuni valori (per esempio il codice del lotto) sostituiscono quelli della scheda. Risposta 201 con lotUrl.
- GET
/api/v1/labels/products/:id/lotsElenco dei lotti della scheda (limit, offset).
- GET
/api/v1/labels/products/:id/lots/:lotIdDettaglio di un lotto.
- PATCH
/api/v1/labels/products/:id/lots/:lotIdModifica name e data del lotto (null toglie un valore: torna quello della scheda), con revision.
- DELETE
/api/v1/labels/products/:id/lots/:lotIdElimina il lotto: la sua pagina risponde «non più disponibile».
- GET
/api/v1/labels/products/:id/lots/:lotId/imageImmagine del QR della pagina del lotto (format, size, dark, light).
- GET
/api/v1/labels/products/:id/printFile vettoriale per la stampa: PDF A4 (predefinito) o SVG, con il QR alla misura in millimetri, nome e link sotto; con lots=1 il PDF contiene anche un QR per ogni lotto.
- GET
/api/v1/labels/products/:id/lots/:lotId/printFile vettoriale per la stampa del QR di un lotto (PDF o SVG).
Parametri 6 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 una scheda prodotto (corpo JSON)POST /api/v1/labels/products
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
templateId | testo | Sì | Il modello da usare: uno dei modelli fissi (si vedono con GET /templates) oppure un tuo modello. |
name | testo | Sì | Nome del prodotto, fino a 120 caratteri. |
languages | elenco di testi | No | Lingue della scheda, tra quelle previste dal modello. Se manca, la scheda ha solo la prima lingua del modello. La prima della lista è la lingua predefinita. |
data | oggetto | No | I valori dei campi del modello, per chiave. Alcuni campi del modello possono essere obbligatori: in tal caso vanno compilati qui. Un testo lungo senza altro limite arriva fino a 2.000 caratteri; i campi traducibili si passano come { "it": …, "en": … }. |
Modifica una scheda (corpo JSON, almeno un campo)PATCH /api/v1/labels/products/:id
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | testo | No | Nuovo nome, fino a 120 caratteri. |
languages | elenco di testi | No | Nuove lingue della scheda. |
data | oggetto | No | Valori da cambiare: si uniscono a quelli già presenti. Un valore null cancella il dato di quel campo. |
revision | numero intero | No | Il numero di revisione che hai letto. Se la scheda nel frattempo è cambiata, la richiesta risponde 409 MODIFICA_CONCORRENTE: ricarica la scheda e riprova. |
templateVersion | numero intero | No | Passa la scheda a un'altra versione del suo modello. |
Crea un lotto (corpo JSON)POST /api/v1/labels/products/:id/lots
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | testo | Sì | Nome del lotto mostrato sulla sua pagina (per esempio il codice stampato sulla confezione), fino a 40 caratteri. |
data | oggetto | No | Valori che sulla pagina del lotto sostituiscono quelli della scheda, con le stesse chiavi e le stesse regole. I campi non indicati mostrano il valore della scheda; un valore vuoto non sostituisce. |
La pagina del lotto è /e/<codice della scheda>/<codice del lotto> e ha un QR suo. Ogni scheda può avere fino a 500 lotti. Se la scheda viene eliminata, anche le pagine dei suoi lotti rispondono «non più disponibile».
Modifica un lotto (corpo JSON, almeno un campo)PATCH /api/v1/labels/products/:id/lots/:lotId
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | testo | No | Nuovo nome, fino a 40 caratteri. |
data | oggetto | No | Valori da cambiare: si uniscono a quelli del lotto. null toglie il valore del lotto e la pagina torna a mostrare quello della scheda. |
revision | numero intero | No | La revisione del lotto che hai letto. Se nel frattempo è cambiata, la richiesta risponde 409 MODIFICA_CONCORRENTE. |
File per la stampa (parametri nell'indirizzo)GET /api/v1/labels/products/:id/print e GET /products/:id/lots/:lotId/print
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
format | testo | No | pdf (predefinito: foglio A4) oppure svg (un solo QR). Entrambi sono vettoriali: restano nitidi a qualsiasi misura. |
size | numero intero | No | Lato del QR in millimetri, da 15 a 100; predefinito 30. Intorno resta il margine bianco di 4 moduli. |
text | testo | No | 0 per togliere nome e link sotto il codice; altrimenti ci sono. |
lots | testo | No | Solo per la scheda e solo con il PDF: 1 aggiunge un QR per ogni lotto, dal più vecchio. |
Il file arriva come allegato da scaricare (etichetta-<codice>.pdf, lotto-<codice>-<lotto>.svg…). Il QR è disegnato modulo per modulo con correzione d'errore di livello M.
Crea o sostituisci un tuo modello (corpo JSON)POST /api/v1/labels/templates e PUT /api/v1/labels/templates/:id
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title | oggetto | Sì | Titolo del modello nelle lingue scelte: { "it": "…", "en": "…" }. |
languages | elenco di testi | Sì | Da una a cinque lingue tra it, en, de, fr ed es: l'italiano c'è sempre. |
sections | elenco di oggetti | Sì | Da 1 a 8 sezioni. Ogni sezione ha id (facoltativo), layout (dettagli, elenco oppure tabella), title e fields. In tutto il modello al massimo 40 campi. |
neutral | booleano | No | I modelli propri sono sempre neutri: se lo indichi può essere solo true. |
version | numero intero | No | Solo con PUT: la versione del modello che hai letto. Se nel frattempo è cambiata, la richiesta risponde 409 MODIFICA_CONCORRENTE. |
Ogni campo di una sezione ha key, type (testo, testo_lungo, elenco o numero), label, e a scelta required, translatable e i limiti del tipo (maxLength, maxItems, maxItemLength, min, max, unit). Le etichette dei campi arrivano a 80 caratteri e l'unità di misura a 12. I campi di tipo elenco vanno nelle sezioni con layout elenco, e solo lì. Ogni modifica crea una nuova versione, fino a 100: le schede già create restano sulla versione che usavano finché non le passi tu alla nuova.
Risposte d'esempio 5
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 di un modello
{
"status": "success",
"message": "Modello creato.",
"data": {
"id": "m_pyj22r5fhq",
"version": 1,
"neutral": true,
"languages": [
"it",
"en"
],
"title": {
"it": "Scheda prodotto",
"en": "Product card"
},
"notice": {
"it": "Informazioni fornite dal titolare di questa scheda, che ne è responsabile.",
"en": "Information provided by the owner of this page, who is responsible for it."
},
"sections": [
{
"id": "dati",
"layout": "dettagli",
"title": {
"it": "Dati",
"en": "Details"
},
"fields": [
{
"key": "nome",
"type": "testo",
"label": {
"it": "Nome",
"en": "Name"
},
"required": true,
"translatable": true,
"maxLength": 60
}
]
}
],
"custom": true,
"status": "active",
"latestVersion": 1,
"createdAt": "2026-10-04T10:00:00.000Z",
"updatedAt": "2026-10-04T10:00:00.000Z"
}
}
Risposta alla creazione di una scheda
{
"status": "success",
"message": "Scheda creata.",
"data": {
"id": "a7c2f905-3e81-4d6b-92f0-5b18e4a7c3d1",
"code": "v7fk5qbqrzk4",
"labelUrl": "https://www.qrcodegenerate.it/e/v7fk5qbqrzk4",
"templateId": "vino",
"templateVersion": 1,
"name": "Rosso Esempio",
"languages": [
"it",
"en"
],
"defaultLang": "it",
"data": {
"produttore": "Cantina Esempio",
"gradazione": 13.5,
"ingredienti": {
"it": [
"Uve"
],
"en": [
"Grapes"
]
}
},
"status": "active",
"revision": 1,
"createdAt": "2026-10-04T10:00:00.000Z",
"updatedAt": "2026-10-04T10:00:00.000Z"
}
}
Modifica con una revisione superata
{
"status": 409,
"code": "MODIFICA_CONCORRENTE",
"message": "La scheda è stata modificata nel frattempo: ricaricala e riprova."
}
Risposta alla creazione di un lotto
{
"status": "success",
"message": "Lotto creato.",
"data": {
"id": "3f9c1d42-8b6e-4a07-b2d5-c1e8f7a90b36",
"productId": "a7c2f905-3e81-4d6b-92f0-5b18e4a7c3d1",
"code": "k4m7p2xq",
"lotUrl": "https://www.qrcodegenerate.it/e/v7fk5qbqrzk4/k4m7p2xq",
"name": "L2024-07",
"data": {
"lotto": "L2024-07"
},
"status": "active",
"revision": 1,
"createdAt": "2026-10-04T10:00:00.000Z",
"updatedAt": "2026-10-04T10:00:00.000Z"
}
}
Storico delle revisioni di una scheda
{
"status": "success",
"data": {
"items": [
{
"revision": 2,
"action": "updated",
"via": "dashboard",
"at": "2026-10-04T10:05:00.000Z",
"name": "Rosso Esempio",
"languages": [
"it",
"en"
],
"defaultLang": "it",
"templateId": "vino",
"templateVersion": 1,
"data": {
"produttore": "Cantina Esempio",
"annata": "2024",
"gradazione": 13.5,
"ingredienti": {
"it": [
"Uve"
],
"en": [
"Grapes"
]
}
},
"changes": [
"data.annata"
]
}
],
"total": 2,
"limit": 50,
"offset": 0
}
}
Ogni revisione conserva quello che la pagina pubblica mostrava. changes elenca cosa è cambiato rispetto alla revisione precedente (vuoto alla creazione, null se la precedente non è nello storico). via dice se la modifica è arrivata dall'API o dalla dashboard. L'esempio mostra una sola revisione dell'elenco.
Paginazione, limiti di frequenza, webhook, formato delle date ed errori sono spiegati nella guida comune.
Errori frequenti 5
| Status | Codice | Quando accade |
|---|---|---|
403 | LIMITE_SCHEDE | Hai raggiunto il numero di schede del tuo piano. |
403 | LIMITE_MODELLI | Hai raggiunto il numero di modelli propri del tuo piano. |
422 | MODELLO_NON_VALIDO | La definizione del modello non è valida. |
422 | CONTENUTO_NON_NEUTRO | Un testo contiene un indirizzo web (http, https o www): le pagine neutre non ammettono link. |
409 | MODIFICA_CONCORRENTE | La scheda o il modello sono cambiati mentre li modificavi: rileggi e riprova. |
La pagina digitale integra l'etichetta fisica, non la sostituisce: le indicazioni obbligatorie per legge restano a carico di chi pubblica il prodotto. Verifica con il tuo consulente cosa deve comparire sull'etichetta stampata.
Ogni risposta di errore ha la forma { status, code, message }.
Esempi 2
Crea la scheda di un vino
curl -X POST "https://www.qrcodegenerate.it/api/v1/labels/products" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{
"templateId": "vino",
"name": "Rosso Esempio 2024",
"languages": ["it", "en"],
"data": {
"produttore": "Cantina Esempio",
"annata": "2024",
"gradazione": 13.5,
"denominazione": { "it": "Vino rosso", "en": "Red wine" },
"ingredienti": { "it": ["Uve"], "en": ["Grapes"] }
}
}'
Aggiorna un dato senza cambiare il link
curl -X PATCH "https://www.qrcodegenerate.it/api/v1/labels/products/ID_SCHEDA" \
-H "Content-Type: application/json" \
-H "x-api-key: LA_TUA_API_KEY" \
-d '{ "data": { "lotto": "L2401" }, "revision": 1 }'
Gli esempi per i linguaggi più comuni sul generatore di QR statici sono nella documentazione generale.
Domande frequenti.
La pagina dell'etichetta contiene pubblicità o tracciamento?
No. La pagina è neutra: nessun cookie, nessuno script, nessun link e nessuna statistica delle letture.
Se cambio un modello cosa succede alle schede già pubblicate?
Niente: ogni modifica crea una nuova versione e le schede restano sulla versione con cui sono nate, finché non le porti tu alla nuova.
Posso usarlo per prodotti diversi dal vino?
Sì. Crei un tuo modello con le sezioni e i campi che servono (testo, elenco, numero) e lo usi per tutti i prodotti che vuoi.
Altri servizi dell'API REST.
Stampi il QR una volta e cambi la destinazione quando vuoi. Pausa, riattivazione e statistiche di scansione, senza ristampare.
Biglietti con convalida →Emetti biglietti con QR firmato e convalidali ai varchi dal telefono, con chiavi dedicate e senza doppi ingressi.
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 Etichette digitali con la tua chiave.
Dalla dashboard sviluppatori generi la chiave e gestisci tutto anche senza scrivere codice.