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.

Serie anti-contraffazione: 1 nel piano FreePezzi con codice anti-contraffazione: 100 nel piano Free
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
  }'

Perché usarlo.

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.

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. Sul telefono la tabella scorre di lato.

VoceFreeStandardPremiumBusiness
Richieste API al mese 20020.000Nessun limite1.000.000
Serie anti-contraffazione 110100500
Pezzi con codice anti-contraffazione 10010.000200.0001.000.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.

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 13 · /api/v1/authenticity

Indirizzo

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

Header richiesto

x-api-key: LA_TUA_API_KEY
  • 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 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 serie (corpo JSON)
POST /api/v1/authenticity/series

CampoTipoObbligatorioDescrizione
nametestoSìNome della serie, si vede nella pagina di verifica (per esempio il prodotto e l'annata), fino a 120 caratteri.
descriptiontestoNoDescrizione mostrata nella pagina di verifica, fino a 300 caratteri.
labelProductIdtestoNoId di una tua etichetta digitale (/api/v1/labels): la pagina di verifica porta alla sua scheda. null o assente: nessun collegamento.
suspectThresholdnumero interoNoOltre 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.
pinEnabledbooleanoNotrue (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

CampoTipoObbligatorioDescrizione
nametestoNoNuovo nome, fino a 120 caratteri.
descriptiontestoNoNuova descrizione, fino a 300 caratteri.
labelProductIdtestoNoNuova etichetta collegata, oppure null per toglierla.
suspectThresholdnumero interoNoNuova 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

CampoTipoObbligatorioDescrizione
quantitynumero interoSì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

CampoTipoObbligatorioDescrizione
filtertestoNoall (predefinito), checked (controllati almeno una volta), suspect (sospetti) oppure revoked (revocati).
limitnumero interoNoQuanti pezzi per pagina (vedi la guida comune sulla paginazione).
offsetnumero interoNoDa quale pezzo partire.

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

CampoTipoObbligatorioDescrizione
reasontestoNoMotivo 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

CampoTipoObbligatorioDescrizione
fromnumero interoNoSolo per la serie: primo numero di serie da stampare (predefinito 1).
tonumero interoNoSolo per la serie: ultimo numero da stampare. Al massimo 500 pezzi per file; senza to si stampano fino a 500 pezzi da from.
formattestoNoSolo per il singolo pezzo: pdf (predefinito) oppure svg. Per la serie il file è sempre un PDF A4.
sizenumero interoNoLato del QR in millimetri, da 15 a 100; predefinito 30. Intorno resta il margine bianco di 4 moduli.
texttestoNo0 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 4

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"
  }
}

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

Errori frequenti 5
StatusCodiceQuando accade
403LIMITE_SERIEHai raggiunto il numero di serie del tuo piano.
403LIMITE_PEZZIHai raggiunto il numero di pezzi del tuo piano.
422ETICHETTA_NON_TROVATAlabelProductId non è una delle tue etichette digitali.
422PINENABLED_NON_MODIFICABILEIl PIN si sceglie alla creazione della serie e non si cambia dopo.
422INTERVALLO_NON_VALIDOPer 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 2

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.

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.

Prova Anti-contraffazione con la tua chiave.

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