API REST per biglietti con convalida ai varchi

Emetti biglietti con QR firmato per eventi e ingressi. Il personale li convalida dal telefono con una chiave dedicata, con esito chiaro a colori.

Crei un evento, emetti i biglietti (anche a blocchi) e ottieni per ognuno un codice firmato, una pagina da mostrare al cliente e un'immagine QR. Ai varchi il personale usa una pagina di convalida con una chiave che può solo convalidare.

Scheda tecnica Piani e limiti

API REST per biglietti con QR e convalida ai varchi

Perché usarlo Biglietti con convalida: i punti di forza

Biglietti firmati

Ogni codice contiene una firma: un codice inventato o alterato viene riconosciuto come non valido.

Pagina del biglietto per il cliente

Evento, luogo, data, posto e QR in una pagina che si apre dal telefono, con lo stato aggiornato (valido, già utilizzato, annullato). Senza cookie.

Convalida dal telefono

Pagina di convalida per il personale con fotocamera (dove il browser la supporta) o inserimento manuale del codice, anche con lettori USB e Bluetooth. L'esito è a colori e a parole.

Chiavi dedicate alla sola convalida

Ai varchi dai una chiave che può solo convalidare: si revoca in qualsiasi momento, scade da sola e può valere per un solo evento. La chiave API completa non vale per la convalida e viceversa.

Nessun doppio ingresso, anche con rete scarsa

Con scanId, se il telefono ripete la richiesta dopo un timeout non viene consumato un secondo ingresso. In caso di dubbio il sistema non risponde mai «valido» senza aver registrato l'ingresso.

Finestre, ingressi multipli e blocchi

Finestra di validità separata dall'orario dell'evento, da 1 a 20 ingressi per biglietto, fino a 500 biglietti per chiamata, annullamento con motivo.

Come funziona

Crea l'evento con nome, luogo, date e finestra di validità.
Emetti i biglietti: uno o un blocco. Ognuno ha codice, pagina pubblica e immagine QR.
Crea una chiave di convalida per i varchi (si vede una volta sola) e consegnala al personale.
Ai varchi il personale scansiona: esito valido, già usato, annullato, fuori orario, altro evento o non trovato.

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
Eventi con biglietti	1	10	100
Biglietti emessi	50	2.000	50.000
Chiavi di convalida ai varchi	3	10	50

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

Scheda tecnica: Biglietti con convalida

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.

Gestione di eventi, biglietti e chiavi

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

Header richiesto

x-api-key: LA_TUA_API_KEY

Metodo	Percorso	Descrizione
`POST`	`/api/v1/tickets/events`	Crea un evento: name, venue, startsAt, endsAt, validFrom, validUntil, maxEntries.
`GET`	`/api/v1/tickets/events`	Elenco degli eventi con la quota in uso.
`GET`	`/api/v1/tickets/events/:id`	Dettaglio di un evento.
`PATCH`	`/api/v1/tickets/events/:id`	Modifica nome, luogo e date (non maxEntries).
`DELETE`	`/api/v1/tickets/events/:id`	Elimina l'evento.
`GET`	`/api/v1/tickets/events/:id/summary`	Riepilogo: biglietti emessi, annullati, entrati e scansioni respinte per esito.
`POST`	`/api/v1/tickets/events/:id/tickets`	Emette uno o più biglietti (fino a 500 per chiamata): category, seat, holderName.
`GET`	`/api/v1/tickets/events/:id/tickets`	Elenco dei biglietti dell'evento.
`GET`	`/api/v1/tickets/tickets/:id`	Dettaglio di un biglietto, con il link alla sua pagina.
`GET`	`/api/v1/tickets/tickets/:id/image`	Immagine del biglietto con il QR (png, jpeg, webp, svg).
`POST`	`/api/v1/tickets/tickets/:id/cancel`	Annulla un biglietto (reason).
`POST`	`/api/v1/tickets/validator-keys`	Crea una chiave di sola convalida (label, eventId, expiresAt). La chiave si vede una sola volta.
`GET`	`/api/v1/tickets/validator-keys`	Elenco delle chiavi (senza il valore).
`DELETE`	`/api/v1/tickets/validator-keys/:id`	Revoca una chiave.

Convalida ai varchi

https://www.qrcodegenerate.it/api/v1/ticket-validation

Header richiesto

x-validator-key: LA_CHIAVE_DI_CONVALIDA

Metodo	Percorso	Descrizione
`POST`	`/api/v1/ticket-validation/scan`	Convalida un biglietto: code, gate (facoltativo), scanId (facoltativo). Risponde 200 per ogni esito.
`GET`	`/api/v1/ticket-validation/me`	Mostra a quale evento e fino a quando vale la chiave in uso.

Errori frequenti

Status	Codice	Quando accade
`403`	`LIMITE_EVENTI`	Hai raggiunto il numero di eventi del tuo piano.
`403`	`LIMITE_BIGLIETTI`	Hai raggiunto il numero di biglietti del tuo piano (contano anche gli annullati).
`403`	`LIMITE_CHIAVI`	Hai raggiunto il numero di chiavi di convalida del tuo piano.
`503`	`ERRORE_TEMPORANEO`	La convalida non è riuscita a verificare il biglietto: riprova con lo stesso scanId. Non viene mai restituito «valido» senza aver registrato l'ingresso.

Esiti della convalida (campo result): valid, already_used, cancelled, outside_window, wrong_event, not_found.

La convalida ha limiti propri, più ampi di quelli della gestione, pensati per un varco con molti passaggi.

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

Esempi

Crea un evento

curl -X POST "https://www.qrcodegenerate.it/api/v1/tickets/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: LA_TUA_API_KEY" \
  -d '{
    "name": "Concerto di autunno",
    "venue": "Teatro Comunale",
    "startsAt": "2026-11-20T21:00:00+01:00",
    "endsAt": "2026-11-21T00:00:00+01:00",
    "validFrom": "2026-11-20T19:00:00+01:00",
    "validUntil": "2026-11-21T01:00:00+01:00"
  }'

Emetti un blocco di biglietti

curl -X POST "https://www.qrcodegenerate.it/api/v1/tickets/events/ID_EVENTO/tickets" \
  -H "Content-Type: application/json" \
  -H "x-api-key: LA_TUA_API_KEY" \
  -d '{ "tickets": [
    { "category": "Platea", "seat": "A12", "holderName": "Maria Rossi" },
    { "category": "Platea", "seat": "A13", "holderName": "Luca Bianchi" }
  ] }'

Convalida ai varchi

curl -X POST "https://www.qrcodegenerate.it/api/v1/ticket-validation/scan" \
  -H "Content-Type: application/json" \
  -H "x-validator-key: LA_CHIAVE_DI_CONVALIDA" \
  -d '{ "code": "CODICE_DEL_BIGLIETTO", "gate": "Ingresso A", "scanId": "ID-UNICO-DELLA-SCANSIONE" }'

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

Domande frequenti: Biglietti con convalida

Come convalido i biglietti ai varchi?

Crei una chiave di sola convalida e la dai al personale: apre la pagina di convalida dal telefono e scansiona con la fotocamera o scrive il codice. Puoi anche collegare il tuo sistema all'endpoint di scansione.

Cosa succede se un biglietto viene presentato due volte?

La seconda volta l'esito è «già usato» (con più ingressi, finché ne restano). Se il telefono ripete la stessa scansione per un problema di rete, con scanId non si consuma un secondo ingresso.

La chiave dei varchi può fare altro?

No. Può solo convalidare, anche per un solo evento, si può revocare e scade da sola. La tua chiave API completa non va mai consegnata al personale.

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.

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 Biglietti con convalida 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