API REST anti-contraffazione: un QR firmato per ogni pezzo

Emetti un codice unico per ogni bottiglia, confezione o oggetto. Chi lo inquadra vede se è tuo e quante volte è stato controllato; con il PIN nascosto lo registra come suo.

Crei una serie (per esempio un vino di un'annata), emetti i pezzi e stampi su ognuno il suo QR. Chi lo inquadra apre una pagina che dice se il codice è stato emesso da te, quante volte è già stato controllato e da quando. Un QR si può fotocopiare: il servizio non impedisce le copie, te le fa scoprire, perché una copia si vede dai controlli ripetuti.

Scheda tecnica Piani e limiti

API REST per QR anti-contraffazione su ogni pezzo venduto

Perché usarlo Anti-contraffazione: i punti di forza

Un codice firmato per ogni pezzo

Ogni pezzo ha un numero di serie e un codice firmato: un codice inventato o alterato risulta non riconosciuto. I codici di biglietti e buoni non valgono qui.

Le copie si vedono

La pagina di verifica mostra quante volte il codice è stato controllato e la data del primo controllo. Oltre una soglia che scegli tu, il pezzo diventa sospetto.

PIN nascosto

Ogni pezzo può avere un PIN da stampare sotto vernice o dentro la confezione. Chi lo inserisce registra il pezzo come suo; chi controlla lo stesso codice dopo viene avvisato.

Revoca

Un pezzo rubato, reso o distrutto si revoca: la sua pagina dice che il codice è stato ritirato. Il motivo resta privato.

Pagina rispettosa

Nessun cookie, nessuno script, nessun indirizzo IP né posizione salvati: per ogni codice solo il numero dei controlli e le date. Le anteprime dei link nelle chat non contano come controlli.

Stampa pronta

Il file con codici e PIN si scarica all'emissione (i PIN si vedono solo in quel momento) e c'è un foglio PDF A4 con i QR da stampare, oppure il singolo QR in SVG.

Collegata all'etichetta digitale

La pagina di verifica può portare alla scheda dell'etichetta digitale dello stesso prodotto, per esempio ingredienti e valori nutrizionali di un vino.

Come funziona

Crea una serie con nome, soglia di sospetto ed eventuale etichetta digitale collegata.
Emetti i pezzi: ricevi per ognuno numero, codice, link di verifica e PIN. Salva subito il file: i PIN non si possono più rileggere.
Stampa i QR (foglio PDF o file per la tipografia) e i PIN nascosti sui pezzi.
Controlla dall'API o dalla dashboard i pezzi controllati e quelli sospetti; revoca quelli che non devono più risultare validi.

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.

Voce	Free	Standard	Premium
Richieste API al mese	500	20.000	Nessun limite
Serie anti-contraffazione	1	10	100
Pezzi con codice anti-contraffazione	100	10.000	200.000

Tutti i prodotti dell'API REST usano la stessa chiave e lo stesso piano. Prezzi e dettagli nella pagina Piani e prezzi.

Scheda tecnica: Anti-contraffazione

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.

Serie e pezzi

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

Header richiesto

x-api-key: LA_TUA_API_KEY

Metodo	Percorso	Descrizione
`POST`	`/api/v1/authenticity/series`	Crea una serie: name, description, labelProductId, suspectThreshold, pinEnabled.
`GET`	`/api/v1/authenticity/series`	Elenco delle tue serie (limit, offset) con la quota in uso.
`GET`	`/api/v1/authenticity/series/:id`	Dettaglio di una serie.
`PATCH`	`/api/v1/authenticity/series/:id`	Cambia nome, descrizione, etichetta collegata o soglia di sospetto. pinEnabled non si cambia.
`DELETE`	`/api/v1/authenticity/series/:id`	Elimina la serie: chi inquadra i suoi codici legge che non sono più gestiti.
`GET`	`/api/v1/authenticity/series/:id/summary`	Riepilogo: emessi, revocati, controllati, sospetti, registrati con il PIN e controlli in tutto.
`POST`	`/api/v1/authenticity/series/:id/items`	Emissione di pezzi con quantity. Il PIN in chiaro c'è solo in questa risposta.
`GET`	`/api/v1/authenticity/series/:id/items`	Elenco dei pezzi per numero di serie, con filter (all, checked, suspect, revoked), limit e offset.
`GET`	`/api/v1/authenticity/series/:id/print`	Foglio PDF A4 con i QR dei pezzi attivi da from a to (size, text).
`GET`	`/api/v1/authenticity/items/:id`	Dettaglio di un pezzo: stato, controlli, date, registrazione con PIN, sospetto. Senza PIN.
`GET`	`/api/v1/authenticity/items/:id/image`	Immagine del QR del pezzo (format, size, dark, light).
`GET`	`/api/v1/authenticity/items/:id/print`	File per la stampa di un pezzo, vettoriale: format pdf o svg, size, text.
`POST`	`/api/v1/authenticity/items/:id/revoke`	Revoca il pezzo, con reason facoltativo.

Parametri

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 serie (corpo JSON)
POST /api/v1/authenticity/series

Campo	Tipo	Obbligatorio	Descrizione
`name`	testo	Sì	Nome della serie, si vede nella pagina di verifica (per esempio il prodotto e l'annata), fino a 120 caratteri.
`description`	testo	No	Descrizione mostrata nella pagina di verifica, fino a 300 caratteri.
`labelProductId`	testo	No	Id di una tua etichetta digitale (/api/v1/labels): la pagina di verifica porta alla sua scheda. null o assente: nessun collegamento.
`suspectThreshold`	numero intero	No	Oltre questo numero di controlli il pezzo diventa sospetto, da 1 a 100; predefinito 5. È sospetto anche un pezzo controllato dopo la registrazione con il PIN.
`pinEnabled`	booleano	No	true (predefinito): ogni pezzo ha un PIN nascosto da stampare sotto vernice o dentro la confezione. Si sceglie qui e non si cambia dopo.

Modifica una serie (corpo JSON, almeno un campo)
PATCH /api/v1/authenticity/series/:id

Campo	Tipo	Obbligatorio	Descrizione
`name`	testo	No	Nuovo nome, fino a 120 caratteri.
`description`	testo	No	Nuova descrizione, fino a 300 caratteri.
`labelProductId`	testo	No	Nuova etichetta collegata, oppure null per toglierla.
`suspectThreshold`	numero intero	No	Nuova soglia, da 1 a 100: il segnale «sospetto» dei pezzi già controllati si ricalcola subito.

pinEnabled non si può inviare in modifica: la risposta è 422 PINENABLED_NON_MODIFICABILE.

Emetti pezzi (corpo JSON)
POST /api/v1/authenticity/series/:id/items

Campo	Tipo	Obbligatorio	Descrizione
`quantity`	numero intero	Sì	Quanti pezzi emettere, da 1 a 1.000 per richiesta. I numeri di serie continuano da quelli già emessi.

Ogni pezzo della risposta ha il suo pin in chiaro (null se la serie non ha PIN): è l'unica volta che si vede, poi resta salvata solo un'impronta. Dopo 10 PIN sbagliati il pezzo non accetta PIN per 24 ore (pinLockedUntil).

Elenco dei pezzi (parametri nell'indirizzo)
GET /api/v1/authenticity/series/:id/items

Campo	Tipo	Obbligatorio	Descrizione
`filter`	testo	No	all (predefinito), checked (controllati almeno una volta), suspect (sospetti) oppure revoked (revocati).
`limit`	numero intero	No	Quanti pezzi per pagina (vedi la guida comune sulla paginazione).
`offset`	numero intero	No	Da quale pezzo partire.

Revoca un pezzo (corpo JSON facoltativo)
POST /api/v1/authenticity/items/:id/revoke

Campo	Tipo	Obbligatorio	Descrizione
`reason`	testo	No	Motivo della revoca, solo per te (non compare nella pagina di verifica), fino a 120 caratteri.

Ripetere la revoca non dà errore e lascia la prima data e il primo motivo.

Foglio per la stampa (parametri nell'indirizzo)
GET /api/v1/authenticity/series/:id/print e GET /api/v1/authenticity/items/:id/print

Campo	Tipo	Obbligatorio	Descrizione
`from`	numero intero	No	Solo per la serie: primo numero di serie da stampare (predefinito 1).
`to`	numero intero	No	Solo per la serie: ultimo numero da stampare. Al massimo 500 pezzi per file; senza to si stampano fino a 500 pezzi da from.
`format`	testo	No	Solo per il singolo pezzo: pdf (predefinito) oppure svg. Per la serie il file è sempre un PDF A4.
`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 della serie, numero e link sotto il codice; altrimenti ci sono.

I pezzi revocati non si stampano. Se nell'intervallo non c'è nessun pezzo attivo la risposta è 422 NESSUN_PEZZO.

Risposte d'esempio

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 una serie

{
  "status": "success",
  "message": "Serie creata.",
  "data": {
    "id": "5c1e8a2f-7b34-4d90-a6e1-2f9b3c7d8e01",
    "name": "Barolo 2020",
    "description": "Bottiglia da 0,75 l",
    "labelProductId": null,
    "suspectThreshold": 5,
    "pinEnabled": true,
    "issued": 0,
    "createdAt": "2026-10-04T10:00:00.000Z",
    "updatedAt": "2026-10-04T10:00:00.000Z"
  }
}

Risposta all'emissione (con il PIN, una volta sola)

{
  "status": "success",
  "message": "2 pezzi emessi. Salva subito i PIN: non si possono più rileggere.",
  "data": {
    "items": [
      {
        "id": "8d2f4b61-0c3a-4e57-9b18-6a7e5d4c3b20",
        "seriesId": "5c1e8a2f-7b34-4d90-a6e1-2f9b3c7d8e01",
        "serial": 1,
        "code": "k7m3p9x2qa4h8n6t5w2z",
        "checkUrl": "https://www.qrcodegenerate.it/a/k7m3p9x2qa4h8n6t5w2z",
        "status": "active",
        "pinEnabled": true,
        "pinConfirmedAt": null,
        "pinLockedUntil": null,
        "checks": 0,
        "firstCheckAt": null,
        "lastCheckAt": null,
        "suspect": false,
        "revokedAt": null,
        "revokeReason": "",
        "createdAt": "2026-10-04T10:00:00.000Z",
        "pin": "h4r8m2xk"
      }
    ],
    "count": 2
  }
}

L'esempio mostra un solo pezzo dell'elenco.

Dettaglio di un pezzo dopo un controllo

{
  "status": "success",
  "data": {
    "id": "8d2f4b61-0c3a-4e57-9b18-6a7e5d4c3b20",
    "seriesId": "5c1e8a2f-7b34-4d90-a6e1-2f9b3c7d8e01",
    "serial": 1,
    "code": "k7m3p9x2qa4h8n6t5w2z",
    "checkUrl": "https://www.qrcodegenerate.it/a/k7m3p9x2qa4h8n6t5w2z",
    "status": "active",
    "pinEnabled": true,
    "pinConfirmedAt": null,
    "pinLockedUntil": null,
    "checks": 1,
    "firstCheckAt": "2026-10-04T10:00:00.000Z",
    "lastCheckAt": "2026-10-04T10:00:00.000Z",
    "suspect": false,
    "revokedAt": null,
    "revokeReason": "",
    "createdAt": "2026-10-04T10:00:00.000Z"
  }
}

Riepilogo di una serie

{
  "status": "success",
  "data": {
    "seriesId": "5c1e8a2f-7b34-4d90-a6e1-2f9b3c7d8e01",
    "issued": 2,
    "revoked": 0,
    "checked": 1,
    "suspect": 0,
    "pinConfirmed": 0,
    "checks": 1
  }
}

Paginazione, limiti di frequenza, formato delle date ed errori sono spiegati nella guida comune.

Errori frequenti

Status	Codice	Quando accade
`403`	`LIMITE_SERIE`	Hai raggiunto il numero di serie del tuo piano.
`403`	`LIMITE_PEZZI`	Hai raggiunto il numero di pezzi del tuo piano.
`422`	`ETICHETTA_NON_TROVATA`	labelProductId non è una delle tue etichette digitali.
`422`	`PINENABLED_NON_MODIFICABILE`	Il PIN si sceglie alla creazione della serie e non si cambia dopo.
`422`	`INTERVALLO_NON_VALIDO`	Per la stampa from e to devono essere numeri di serie, con from non più grande di to.

Un QR si può fotocopiare: la pagina di verifica dice se il codice è stato emesso da te e quante volte è stato controllato, non impedisce le copie.

Dopo troppi PIN sbagliati il pezzo non accetta PIN per un giorno: un blocco definitivo permetterebbe a chi copia i codici di bloccare i clienti veri.

Ogni risposta di errore ha la forma { status, code, message }.

Esempi

Crea una serie con PIN nascosto

curl -X POST "https://www.qrcodegenerate.it/api/v1/authenticity/series" \
  -H "Content-Type: application/json" \
  -H "x-api-key: LA_TUA_API_KEY" \
  -d '{
    "name": "Barolo 2020",
    "description": "Bottiglia da 0,75 l",
    "suspectThreshold": 5,
    "pinEnabled": true
  }'

Emetti i pezzi (e salva subito i PIN)

curl -X POST "https://www.qrcodegenerate.it/api/v1/authenticity/series/ID_SERIE/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: LA_TUA_API_KEY" \
  -d '{ "quantity": 3 }'

Gli esempi per i linguaggi più comuni sul generatore di QR statici sono nella documentazione generale.

Domande frequenti: Anti-contraffazione

Il QR non si può copiare?

Si può fotocopiare, come ogni QR. Per questo la pagina mostra quanti controlli ha avuto il codice: tante letture dello stesso codice, o letture dopo la registrazione con il PIN, indicano una probabile copia.

Aprire la pagina conta come un controllo anche per me?

Sì. Per provare il servizio usa un pezzo di prova; dalla dashboard trovi il link da copiare, ma non un pulsante per aprirlo.

Cosa vede chi controlla un pezzo revocato?

Che il codice è stato ritirato dal produttore e non conferma più l'originalità del pezzo. Il motivo della revoca non compare.

Salvate dove si trova chi controlla?

No. Non salviamo indirizzi IP né posizioni: per ogni codice solo il numero dei controlli e le date del primo e dell'ultimo.

Altri prodotti dell'API REST

QR dinamici

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.

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.

Prova Anti-contraffazione con la tua chiave API

Dalla dashboard sviluppatori generi la chiave e gestisci anche senza scrivere codice. Vedi i piani per limiti e prezzi.

Apri la dashboard