Quando la tua azienda ha bisogno di integrare il ticketing nella propria infrastruttura esistente, la qualità della API è determinante. Se stai ancora valutando le opzioni, la nostra guida su come scegliere una piattaforma di ticketing copre i criteri principali. Una API progettata male significa mesi di sviluppo, bug costanti e limitazioni che scopri troppo tardi. Questa guida ti aiuta a capire cosa valutare prima di impegnarti con una piattaforma.
La buona notizia è che quasi nulla di ciò che serve richiedere è opinabile. La maggior parte è scritta in specifiche pubbliche: OpenAPI per il contratto, le RFC dell'IETF per l'autenticazione, gli errori e il fine vita di un endpoint, e la documentazione del fornitore di pagamenti per la consegna degli eventi. Quello che segue è questo elenco, con il riferimento concreto a fianco.
Cosa indica la qualità della documentazione di una API?
La qualità della documentazione riflette la maturità della API. Cerca questi elementi:
- Specifica OpenAPI/Swagger: permette di generare client automaticamente
- Esempi di codice: nei linguaggi che usi (JS, Python, PHP...)
- Guide sui casi d'uso: non solo riferimento, ma anche tutorial
- Changelog: cronologia delle modifiche e politica di versionamento
- Status page: visibilità sulla disponibilità del servizio
Lo standard ha un nome e una data. La OpenAPI Specification 3.1.0 è stata pubblicata il 15 febbraio 2021 e richiede un campo openapi con la versione della specifica usata nel documento, distinta dalla versione della API stessa. Supporta JSON e YAML, e raccomanda YAML 1.2 affinché la conversione tra i due formati non perda informazioni.
Il confronto pratico è semplice. Un documento OpenAPI valido si carica in un generatore e produce un client tipizzato nel tuo linguaggio in pochi minuti. Un PDF o una pagina con esempi sparsi no. Chiedi il file, non lo screenshot: se il fornitore non riesce a consegnarti l'openapi.yaml lo stesso giorno in cui lo richiedi, l'integrazione parte già con un debito.
Come deve autenticarsi una API di ticketing sicura?
La API gestisce dati sensibili e transazioni economiche. La sicurezza non è negoziabile.
- OAuth 2.0: standard moderno per l'autenticazione
- API key con scope: permessi granulari per ogni key
- Rotazione delle credenziali: possibilità di ruotarle senza downtime
- Rate limiting: protezione contro gli abusi, con limiti documentati
- Log di accesso: audit di chi accede a cosa
Il framework di base è la RFC 6749, che definisce l'OAuth 2.0 Authorization Framework. Ma quello che conviene portare alla riunione tecnica è la RFC 9700, *Best Current Practice for OAuth 2.0 Security*, pubblicata nel 2025. Tre dei suoi requisiti si verificano in un pomeriggio:
- I server di autorizzazione devono supportare PKCE, e i client pubblici devono usarlo. È la protezione contro il furto del codice di autorizzazione.
- La validazione della *redirect URI* deve avvenire tramite confronto esatto delle stringhe, con l'unica eccezione delle porte variabili su
localhostper le applicazioni native. Qualsiasi corrispondenza basata su pattern è una porta aperta. - I token di accesso dovrebbero essere legati all'emittente tramite mTLS o DPoP, affinché un token trafugato non sia utilizzabile da altre mani.
Se il fornitore offre solo una API key statica ed eterna, non è automaticamente da scartare, ma il contratto deve coprire ciò che questa scelta implica: scope reali, rotazione senza interrompere il servizio e un registro degli accessi che tu possa esportare.
Quali endpoint essenziali deve coprire la API?
Verifica che la API copra tutte le operazioni di cui hai bisogno.
- Eventi: creazione, modifica, elenco, gestione degli stati
- Biglietti: tipologie, prezzi, disponibilità, prenotazioni
- Ordini: creazione, consultazione, annullamento, rimborso
- Validazione: verifica dei biglietti, registrazione degli accessi
- Webhook: notifiche di eventi (vendita, accesso, ecc.)
C'è una domanda che conta più dell'elenco precedente: cosa succede se la stessa richiesta arriva due volte. Nel ticketing, un retry di rete su una creazione d'ordine può duplicare una vendita e bloccare una capienza che non esiste. La risposta corretta è una chiave di idempotenza per ogni operazione di scrittura, in modo che il secondo tentativo restituisca il risultato del primo invece di creare un nuovo ordine. Chiedilo per scritto e pretendi di vedere il comportamento in sandbox.
La seconda domanda riguarda la paginazione e i limiti di lettura. Una API che non documenta quanti ordini restituisce per pagina né come si scorre lo storico trasforma qualsiasi esportazione notturna verso la tua dashboard delle metriche in un problema di ingegneria a tuo carico.
A cosa servono i webhook in un'integrazione?
I webhook sono fondamentali per mantenere il tuo sistema sincronizzato senza bisogno di polling costante.
- Eventi disponibili: quali azioni attivano i webhook
- Payload documentato: struttura chiara per ogni tipo di evento
- Retry: cosa succede se il tuo endpoint fallisce
- Verifica della firma: per validare l'autenticità del webhook
- Log: cronologia dei webhook inviati e relativo stato
Come si verifica una firma
La procedura meglio documentata del settore è quella di Stripe, e funge da modello anche se il tuo fornitore è diverso. La sua documentazione sui webhook descrive un header Stripe-Signature con un timestamp con prefisso t= e una o più firme con prefisso di schema; l'unico schema valido in produzione è v1. La firma viene calcolata come un HMAC con SHA-256 sulla stringa formata dal timestamp, un punto e il corpo JSON esatto della richiesta, usando il segreto dell'endpoint come chiave.
Tre dettagli che fanno fallire le integrazioni reali. Primo: bisogna usare il corpo grezzo; se il tuo framework reserializza il JSON, la verifica fallisce sempre. Secondo: il confronto deve avvenire in tempo costante, per non far trasparire informazioni tramite il tempo di risposta. Terzo: le librerie ufficiali applicano una tolleranza predefinita di 5 minuti tra il timestamp e l'ora attuale, e la documentazione stessa avverte di non impostarla a zero, perché questo disattiva il controllo di freschezza e riapre la porta agli attacchi di replay.
Retry, duplicati e ordine
I numeri concreti contano quando dimensioni la tua coda. Stripe documenta retry automatici per un massimo di tre giorni con backoff esponenziale in modalità produzione, e tre retry nel giro di poche ore in sandbox. Il reinvio manuale funziona fino a 15 giorni dal pannello e fino a 30 giorni dalla CLI. Si possono registrare fino a 16 endpoint di webhook.
E due avvertenze che conviene riportare tali e quali nel tuo design: l'ordine di consegna degli eventi non è garantito, e un endpoint può ricevere lo stesso evento più di una volta. La raccomandazione ufficiale è registrare gli identificativi degli eventi già elaborati e non usare il timestamp di creazione per dedurre l'ordine. Inoltre, l'endpoint deve restituire un 2xx prima della logica pesante: qualsiasi risposta 3xx viene considerata un fallimento di consegna, e un *timeout* attiva il ciclo di retry.
Come deve gestire la API gli errori e i limiti di utilizzo?
Con formati standard, non con stringhe inventate. La RFC 9457, *Problem Details for HTTP APIs*, pubblicata nel 2023, definisce un corpo di errore leggibile da macchina con cinque campi: type (URI che identifica il tipo di problema), title, status, detail e instance, servito come application/problem+json. Una API che lo adotta ti evita di dover scrivere un traduttore di errori per ogni fornitore.
Per i limiti di utilizzo, il riferimento è la RFC 6585, *Additional HTTP Status Codes*, di aprile 2012, che ha introdotto il codice 429 Too Many Requests. La specifica stessa afferma che la risposta dovrebbe includere dettagli che spieghino la condizione e può includere un header Retry-After che indica quanto attendere. Questo header è la differenza tra un retry con criterio e un ciclo che peggiora la saturazione.
Durante la valutazione, chiedi quali limiti applica la API per minuto e per chiave, se sono diversi in lettura e scrittura, e cosa succede nei picchi di una prevendita, che è esattamente il momento in cui la tua integrazione viene chiamata di più. Una piattaforma che non pubblica i propri limiti ti sta chiedendo di scoprirli nel peggiore dei giorni possibili.
Perché ho bisogno di un ambiente di test (sandbox)?
Sviluppare direttamente in produzione è una ricetta per il disastro. Serve un sandbox adeguato.
- Ambiente sandbox separato: dati di test che non influenzano la produzione
- Carte di test: per simulare pagamenti senza addebiti reali
- Dati di esempio: eventi e biglietti precaricati per i test
- Parità con la produzione: stesso comportamento, stesse risposte
Aggiungi un test che quasi nessuno fa durante la valutazione: forzare gli errori. Un sandbox utile permette di simulare un pagamento rifiutato, un rimborso parziale, un'autenticazione bancaria che l'acquirente abbandona e un webhook che arriva in ritardo. Se puoi testare solo il percorso ideale, non hai testato nulla.
Anche il tempo conta. Verifica che il sandbox permetta di anticipare la data di un evento per controllare la chiusura delle vendite, la validazione all'ingresso e la generazione dei report successivi senza dover aspettare settimane.
Quali obblighi legali comporta l'integrazione?
Due fronti, e nessuno dei due è opzionale nell'Unione Europea.
Il primo sono i pagamenti. Il Regolamento Delegato (UE) 2018/389 richiede, all'articolo 4, che l'autenticazione si basi su due o più elementi appartenenti alle categorie conoscenza, possesso e inerenza, e all'articolo 5 il collegamento dinamico: il codice generato deve essere specifico per l'importo e il beneficiario accettati dall'ordinante. L'articolo 16 prevede l'esenzione per importi di scarso valore: operazioni fino a 30 EUR, con un accumulo precedente che non superi i 100 EUR o un massimo di cinque operazioni a distanza consecutive. La tua integrazione deve saper riportare l'acquirente al flusso dopo un'autenticazione, e questo si verifica in sandbox, non la notte dell'apertura delle vendite. Se vendi in Spagna, conviene confrontarlo con i metodi di pagamento disponibili.
Il secondo sono i dati. Il Regolamento (UE) 2016/679 obbliga, all'articolo 32, ad applicare misure tecniche e organizzative appropriate, tra cui la crittografia e la capacità di garantire riservatezza e integrità, e all'articolo 33 a notificare le violazioni di sicurezza all'autorità di controllo senza ingiustificato ritardo e, se possibile, entro un termine massimo di 72 ore. La API che ti fornisce email e numeri di telefono dei partecipanti ti rende responsabile di ciò che ne fai: il contratto di responsabile del trattamento va firmato prima della prima chiamata, non dopo. I dettagli operativi sono nella nostra guida al GDPR per gli organizzatori.
Come si versiona e si deprecia una API senza rompere la tua integrazione?
Con regole pubbliche. Il versionamento semantico 2.0.0 riserva l'incremento della versione principale ai cambiamenti incompatibili con le versioni precedenti, quello della versione minore alle funzionalità compatibili e quello della patch alle correzioni. Applicato a una API, significa che una modifica che rompe il tuo client non può arrivare con un deploy silenzioso di un martedì qualsiasi.
Per il fine vita esiste un header standard. La RFC 8594, di maggio 2019, definisce il campo di risposta HTTP Sunset con un unico timestamp che indica quando è probabile che la risorsa smetta di rispondere, e un tipo di relazione di link sunset per puntare alla politica di ritiro o migrazione. Chiedere se la API lo emette è un modo rapido per capire se il fornitore ha pensato al ciclo di vita o solo al lancio.
Lo stesso vale per il widget di vendita integrato: se il suo JavaScript viene servito da un URL senza versione, qualsiasi modifica del fornitore arriva al tuo sito senza preavviso.
Quale supporto tecnico deve offrire il fornitore?
Quando qualcosa si rompe alle 2 di notte prima del tuo evento, hai bisogno di risposte rapide.
- Canale tecnico: accesso agli sviluppatori, non solo a un supporto generico
- SLA documentato: tempi di risposta garantiti
- Community: forum o Slack dove risolvere i dubbi
- Onboarding tecnico: sessione di integrazione guidata
Chiedi che lo SLA specifichi tre cose con numeri precisi: tempo di prima risposta per livello di gravità, finestra orario coperta e cosa succede se non viene rispettato. Un impegno senza conseguenze è solo una dichiarazione di intenti. E chiedi informazioni sulla finestra dei deploy: una piattaforma che rilascia in produzione un venerdì di prevendita ha un problema di processo, non di tecnologia.
Come scelgo la API di ticketing giusta?
Una buona API di ticketing accelera il tuo sviluppo, riduce i bug e ti permette di costruire esperienze personalizzate. È anche la base per integrare un widget di vendita integrato nel tuo sito o collegare la tua dashboard delle metriche. Una API scadente ti rinchiude in limitazioni che scopri troppo tardi. Investi tempo nella valutazione prima di impegnarti: chiedi l'accesso al sandbox, testa gli endpoint critici e parla con il team tecnico. La decisione giusta ti farà risparmiare mesi di frustrazione.
Nove verifiche concrete per questa valutazione:
- Chiedi il file OpenAPI, non la documentazione in HTML. Se non esiste, genera tu stesso il client e aggiungilo al costo del progetto.
- Richiedi PKCE e validazione esatta della redirect URI se è presente OAuth 2.0, come richiesto dalla RFC 9700.
- Testa l'idempotenza: lancia due volte la stessa creazione d'ordine e verifica che ne venga creato solo uno.
- Verifica a mano una firma di webhook prima di fidarti della libreria, e imposta una tolleranza temporale diversa da zero.
- Fai fallire il tuo endpoint apposta e misura quanti retry arrivano, per quanto tempo e con quali header.
- Duplica un webhook e verifica che il tuo sistema non venda due volte lo stesso biglietto.
- Chiedi i limiti di utilizzo per chiave e se la API restituisce
429conRetry-After. - Controlla il formato degli errori:
application/problem+jsoncontype,title,status,detaileinstancefa risparmiare settimane. - Chiedi informazioni sull'header Sunset e sulla politica di versionamento prima di firmare, non quando arriva l'avviso.
Fonti
- OpenAPI Specification v3.1.0, 15 febbraio 2021 (OpenAPI Initiative)
- OpenAPI/Swagger Specification (SmartBear, Swagger)
- OAuth 2.0, pagina ufficiale dello standard
- RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
- RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
- RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
- RFC 6585: Additional HTTP Status Codes, aprile 2012 (IETF)
- RFC 8594: The Sunset HTTP Header Field, maggio 2019 (IETF)
- Semantic Versioning 2.0.0, specifica in spagnolo
- Receive Stripe events in your webhook endpoint, documentazione ufficiale di Stripe
- Regolamento Delegato (UE) 2018/389, norme tecniche di regolamentazione per l'autenticazione forte del cliente (EUR-Lex)
- Regolamento (UE) 2016/679, Regolamento Generale sulla Protezione dei Dati (EUR-Lex)