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.

Etichette digitali: 3 nel piano FreeModelli di etichetta propri: 2 nel piano Free
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"] }
    }
  }'

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.

Pagina neutra per costruzione

Nessun cookie, nessuno script, nessun link e nessuna pubblicità: la pagina mostra solo le informazioni del prodotto e non registra le letture.

Modello pronto per il vino

Produttore, annata, titolo alcolometrico, volume, lotto, ingredienti, allergeni e dichiarazione nutrizionale per 100 ml.

Modelli tuoi per qualsiasi prodotto

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.

Le modifiche non rompono le schede esistenti

Ogni modifica a un modello crea una nuova versione: le schede già pubblicate restano come sono finché non le porti alla nuova versione.

Cinque lingue

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.

Modifiche sicure

Con il numero di revisione, se due persone modificano la stessa scheda la seconda riceve un conflitto invece di sovrascrivere il lavoro della prima.

Sei una cantina?

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.

VoceFreeStandardPremiumBusiness
Richieste API al mese 20020.000Nessun limite1.000.000
Etichette digitali 3505002.000
Modelli di etichetta propri 21050200

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/labels

Header richiesto

x-api-key: LA_TUA_API_KEY
  • GET/api/v1/labels/templates

    Modelli disponibili (predefiniti e tuoi) con campi, tipi, limiti ed etichette per lingua, più la quota dei tuoi modelli.

  • POST/api/v1/labels/templates

    Crea un tuo modello: title, languages, sections. I modelli propri sono sempre neutri.

  • GET/api/v1/labels/templates/:id

    Dettaglio di un modello (version per le versioni precedenti dei tuoi).

  • PUT/api/v1/labels/templates/:id

    Salva una nuova versione del tuo modello. Le schede esistenti non cambiano.

  • DELETE/api/v1/labels/templates/:id

    Archivia il tuo modello: le schede già create continuano a vedersi.

Schede prodotto 16 · /api/v1/labels

Indirizzo

https://www.qrcodegenerate.it/api/v1/labels

Header richiesto

x-api-key: LA_TUA_API_KEY
  • POST/api/v1/labels/products

    Crea una scheda: templateId, name, languages, data.

  • GET/api/v1/labels/products

    Elenco delle schede (limit, offset) con la quota in uso.

  • GET/api/v1/labels/products/:id

    Dettaglio di una scheda, con il link pubblico.

  • PATCH/api/v1/labels/products/:id

    Modifica name, languages, data (null cancella un campo), revision e templateVersion.

  • DELETE/api/v1/labels/products/:id

    Elimina la scheda: la pagina pubblica risponde «non più disponibile».

  • GET/api/v1/labels/products/:id/image

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

  • GET/api/v1/labels/products/:id/history

    Storico 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/:revision

    Una revisione dello storico.

  • POST/api/v1/labels/products/:id/lots

    Crea 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/lots

    Elenco dei lotti della scheda (limit, offset).

  • GET/api/v1/labels/products/:id/lots/:lotId

    Dettaglio di un lotto.

  • PATCH/api/v1/labels/products/:id/lots/:lotId

    Modifica name e data del lotto (null toglie un valore: torna quello della scheda), con revision.

  • DELETE/api/v1/labels/products/:id/lots/:lotId

    Elimina il lotto: la sua pagina risponde «non più disponibile».

  • GET/api/v1/labels/products/:id/lots/:lotId/image

    Immagine del QR della pagina del lotto (format, size, dark, light).

  • GET/api/v1/labels/products/:id/print

    File 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/print

    File 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

CampoTipoObbligatorioDescrizione
templateIdtestoSìIl modello da usare: uno dei modelli fissi (si vedono con GET /templates) oppure un tuo modello.
nametestoSìNome del prodotto, fino a 120 caratteri.
languageselenco di testiNoLingue 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.
dataoggettoNoI 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

CampoTipoObbligatorioDescrizione
nametestoNoNuovo nome, fino a 120 caratteri.
languageselenco di testiNoNuove lingue della scheda.
dataoggettoNoValori da cambiare: si uniscono a quelli già presenti. Un valore null cancella il dato di quel campo.
revisionnumero interoNoIl numero di revisione che hai letto. Se la scheda nel frattempo è cambiata, la richiesta risponde 409 MODIFICA_CONCORRENTE: ricarica la scheda e riprova.
templateVersionnumero interoNoPassa la scheda a un'altra versione del suo modello.

Crea un lotto (corpo JSON)
POST /api/v1/labels/products/:id/lots

CampoTipoObbligatorioDescrizione
nametestoSìNome del lotto mostrato sulla sua pagina (per esempio il codice stampato sulla confezione), fino a 40 caratteri.
dataoggettoNoValori 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

CampoTipoObbligatorioDescrizione
nametestoNoNuovo nome, fino a 40 caratteri.
dataoggettoNoValori da cambiare: si uniscono a quelli del lotto. null toglie il valore del lotto e la pagina torna a mostrare quello della scheda.
revisionnumero interoNoLa 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

CampoTipoObbligatorioDescrizione
formattestoNopdf (predefinito: foglio A4) oppure svg (un solo QR). Entrambi sono vettoriali: restano nitidi a qualsiasi misura.
sizenumero interoNoLato del QR in millimetri, da 15 a 100; predefinito 30. Intorno resta il margine bianco di 4 moduli.
texttestoNo0 per togliere nome e link sotto il codice; altrimenti ci sono.
lotstestoNoSolo 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

CampoTipoObbligatorioDescrizione
titleoggettoSìTitolo del modello nelle lingue scelte: { "it": "…", "en": "…" }.
languageselenco di testiSìDa una a cinque lingue tra it, en, de, fr ed es: l'italiano c'è sempre.
sectionselenco di oggettiSì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.
neutralbooleanoNoI modelli propri sono sempre neutri: se lo indichi può essere solo true.
versionnumero interoNoSolo 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
StatusCodiceQuando accade
403LIMITE_SCHEDEHai raggiunto il numero di schede del tuo piano.
403LIMITE_MODELLIHai raggiunto il numero di modelli propri del tuo piano.
422MODELLO_NON_VALIDOLa definizione del modello non è valida.
422CONTENUTO_NON_NEUTROUn testo contiene un indirizzo web (http, https o www): le pagine neutre non ammettono link.
409MODIFICA_CONCORRENTELa 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.

Prova Etichette digitali con la tua chiave.

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