Documentazione API Billetto e guida ai webhook
Cosa puoi costruire con l'API Billetto
L'API Billetto è un'API REST che restituisce JSON. Dà al tuo codice accesso agli stessi dati su cui si basa la tua biglietteria: eventi, tipi di biglietto, ordini, partecipanti, voci contabili, domande di prenotazione e audience. I webhook ti inviano le modifiche non appena avvengono, senza che tu debba chiederle.
I team la usano per sincronizzare gli acquirenti in un CRM, caricare le vendite in un data warehouse, mostrare gli eventi sul proprio sito, aggiungere membri ad audience di prevendita e riconciliare i pagamenti nel sistema finanziario. Questa pagina spiega come è strutturata l'API e come funzionano i webhook. Lo schema completo di ogni endpoint si trova nel riferimento API.
Inizia da qui
- Guida introduttiva: crea le credenziali e fai la prima chiamata
- Riferimento API: tutti gli endpoint, i parametri e gli oggetti di risposta
- Riferimento webhook: la risorsa webhook e i suoi campi
- Public Event Search: recupera gli eventi pubblici disponibili su Billetto
Autenticati con una coppia di chiavi API o OAuth 2.0
Coppie di chiavi API per il tuo account
Usa una coppia di chiavi quando i tuoi sistemi chiamano l'API per conto del tuo account organizzatore. Creala in Billetto in Integrations → Developers → API - Key pairs, dalle un nome che ne descriva l'uso (ad esempio "Sync CRM" o "Data warehouse") e inviala a ogni chiamata nell'intestazione Api-Keypair.
- Crea una coppia di chiavi per ogni sistema, così puoi revocarne una senza toccare le altre
- Conserva il secret sul tuo server. Non inserirlo mai in un browser, in un'app mobile o in un repository pubblico
- Revoca e sostituisci subito una coppia di chiavi se sospetti che sia stata esposta
OAuth 2.0 per app usate da altri organizzatori
Usa OAuth quando sviluppi un prodotto a cui altri organizzatori Billetto collegano il proprio account, come uno strumento di marketing, una piattaforma di eventi o una dashboard per agenzie. OAuth usa il flusso authorization code: l'organizzatore accede a Billetto, approva la tua app e tu ricevi un token per il suo account. Non vedi mai la sua password e può scollegare la tua app in qualsiasi momento.
Entrambi i metodi sono descritti passo dopo passo nella guida introduttiva.
- Eventi
- Ordini e partecipanti
- Finanza e report
- Audiences
- Webhook
- Eventi pubblici
Eventi e tipi di biglietto
Recupera gli eventi del tuo account con data, luogo, stato e tipi di biglietto.
GET /organiser/eventselenca i tuoi eventi- Tipi di biglietto, prezzi e disponibilità per evento
- Domande di prenotazione poste agli acquirenti al checkout
Uso tipico
Mostra i tuoi prossimi eventi con disponibilità in tempo reale sul tuo sito o nella tua app e indirizza gli acquirenti al checkout Billetto.
Ordini e partecipanti
Scopri chi ha comprato cosa, quando e per quale evento.
GET /organiser/orderselenca gli ordini di tutti i tuoi eventiGET /organiser/events/{event_id}/attendeeselenca i partecipanti di un evento- I risultati arrivano a pagine: richiedi la pagina successiva finché non ce ne sono più
Uso tipico
Mantieni aggiornati i dati degli acquirenti nel tuo CRM o invia le liste dei partecipanti a un sistema di controllo accessi o di accredito.
Voci contabili e report
Ottieni il dettaglio finanziario delle tue vendite di biglietti.
GET /organiser/ledger_entrieselenca vendite, rimborsi, commissioni e pagamenti- Un report BI per evento con i principali dati di vendita
Uso tipico
Carica i ricavi nella tua contabilità o nel data warehouse e riconciliali con i tuoi pagamenti.
Audience e membri
Scrivi dati in Billetto invece di limitarti a leggerli.
- Creare, aggiornare e rimuovere membri delle audience
- Importare liste complete e seguire lo stato dell'importazione
- Recuperare un'audience e il numero dei suoi membri
Uso tipico
Sincronizza membri, iscritti o liste di partner dal tuo CRM con Audiences per prevendite e offerte esclusive.
Sottoscrizioni webhook
Gestisci i webhook via codice invece che dall'interfaccia di Billetto.
POST /organiser/webhooksregistra un URL di endpoint- Aggiornare o rimuovere un webhook esistente
- Generare un nuovo secret di firma per un webhook
Uso tipico
Registra automaticamente i webhook quando configuri un nuovo cliente o ambiente, e ruota i secret secondo una pianificazione.
Public Event Search
Cerca gli eventi pubblicati su Billetto da tutti gli organizzatori.
- Parametri di query per filtrare i risultati, descritti nel riferimento
- Ogni risultato rimanda alla pagina dell'evento e al checkout
Uso tipico
Media, guide cittadine e piattaforme partner mostrano così cosa succede, con biglietti venduti tramite Billetto.
IN PRATICA
L'API e i webhook di Billetto, passo dopo passo
APIPasso 1: accesso
Crea una coppia di chiavi e fai la prima chiamata
Apri Integrations, vai alla scheda Developers e crea una coppia di chiavi per il sistema che stai collegando. Copia il secret, aggiungilo alle intestazioni della richiesta e chiama un endpoint come /organiser/orders. La risposta è JSON che puoi portare direttamente nel tuo modello di dati.
- Una coppia di chiavi per integrazione, con il nome del sistema che la usa
- Risposte JSON per eventi, ordini, partecipanti e voci contabili
- Revoca una coppia di chiavi in qualsiasi momento senza toccare le altre
Integrations
Example dataAPI - Key pairs
+ Create key pairAUDIENCESPasso 2: scrivere in Billetto
Aggiungi contatti a un'audience tramite l'API
Gli endpoint di Audiences sono il modo principale per scrivere dati in Billetto. Invia contatti dal tuo CRM a un'audience, oppure importa una lista completa e controlla lo stato finché non è pronta. A quel punto il gruppo è pronto per inviti, prevendite e offerte esclusive.
- Aggiungi, aggiorna e rimuovi membri uno alla volta
- Importazioni massive con uno stato che puoi consultare
- I gruppi compaiono subito in Audiences
Audiences
Example dataVIP members 2026Synced via API
WEBHOOKSPasso 3: webhook di Billetto
Registra un webhook e segui gli invii in tempo reale
Aggiungi l'URL del tuo endpoint nella scheda Developers e Billetto genera un secret di firma per esso. Da quel momento ogni ordine, rimborso, modifica di un partecipante o pubblicazione di un evento viene inviato al tuo URL come HTTP POST con un corpo JSON.
- Configurazione dall'interfaccia o tramite POST /organiser/webhooks
- Un secret di firma per webhook, che puoi rigenerare
- La scheda Webhooks mostra URL e versione API di ogni webhook
Integrations
Example dataWebhooks
Receive data based on specific webhook events
Recent deliveriesLive
Cosa sono i webhook di Billetto e quando usarli
Un webhook è un URL sul tuo server che Billetto chiama quando qualcosa cambia nel tuo account. Invece di chiedere all'API ogni pochi minuti se ci sono nuovi ordini, ricevi una chiamata nel momento in cui un ordine viene creato, rimborsato o modificato.
Per questo i webhook sono lo strumento giusto quando i tempi contano: una conferma nel CRM in pochi secondi, un messaggio Slack quando viene venduto un biglietto VIP, o un sistema di controllo accessi che deve sapere di un biglietto annullato prima dell'apertura delle porte.
Webhook o API?
- Usa i webhook per reagire alle modifiche appena avvengono: nuovi ordini, rimborsi, modifiche dei partecipanti ed eventi pubblicati
- Usa l'API per caricare lo storico, eseguire una sincronizzazione completa ogni notte o recuperare dettagli che un webhook non contiene
- Usa entrambi per la soluzione più affidabile: webhook per la velocità e una sincronizzazione API pianificata che recupera tutto ciò che è sfuggito
Come viene consegnato un webhook di Billetto
Dalla vendita di un biglietto all'elaborazione nel tuo sistema.Costruisci un ricevitore di webhook affidabile
Sicurezza
- Verifica ogni chiamata con il secret di firma del webhook prima di fidarti del contenuto. Il riferimento webhook spiega come
- Accetta solo HTTPS e conserva il secret nella configurazione del server, non nel codice
- Genera un nuovo secret se potrebbe essere stato esposto, poi aggiorna il tuo ricevitore
Affidabilità
- Rispondi in fretta. Restituisci uno stato 2xx appena la chiamata è verificata e svolgi il lavoro pesante in una coda
- Gestisci i duplicati. Salva gli ID elaborati così lo stesso ordine non viene mai creato due volte
- Non contare sull'ordine di arrivo. Se è importante, recupera lo stato attuale dell'ordine tramite l'API
- Riconcilia regolarmente. Una sincronizzazione API pianificata recupera ciò che il tuo endpoint ha perso durante un'interruzione
Riferimento API Billetto
Il riferimento API documenta ogni endpoint con parametri, chiamate di esempio e oggetti di risposta. Usalo insieme a questa guida quando inizi a programmare: trova sopra la risorsa giusta e poi consulta i campi esatti nel riferimento.
Riferimento webhook
La risorsa webhook contiene la configurazione di un endpoint: il suo URL, la versione API usata e il secret di firma. Ti consigliamo di creare il primo webhook in Billetto in Integrations → Developers e di gestirlo tramite l'API man mano che la tua configurazione cresce.
Public Event Search API
La Public Event Search API restituisce gli eventi che gli organizzatori hanno pubblicato su Billetto, di tutti gli organizzatori. È adatta a siti di informazione, guide cittadine, enti turistici e app partner che vogliono mostrare cosa succede, e ogni risultato rimanda alla pagina dell'evento su Billetto dove si acquistano i biglietti.
Domande sull'API e sui webhook di Billetto
Domande tecniche di sviluppatori che lavorano con l'API Billetto. Non trovi la risposta? Parla con il nostro team.
Accedi a Billetto, apri Integrations e vai alla scheda Developers. In API - Key pairs puoi creare una nuova coppia di chiavi, vedere a chi appartiene ciascuna e revocare quelle che non usi più.
Una coppia di chiavi dà ai tuoi sistemi accesso al tuo account organizzatore. OAuth 2.0 è per le app a cui altri organizzatori collegano il proprio account Billetto, così puoi agire per loro conto senza conoscerne le credenziali.
I webhook coprono le modifiche a ordini, partecipanti ed eventi, come nuovi ordini, rimborsi, modifiche dei partecipanti ed eventi pubblicati. Il riferimento webhook elenca tutti gli eventi e il loro contenuto.
Ogni webhook ha il proprio secret di firma. Usalo per verificare ogni chiamata in arrivo prima di elaborarla e rifiuta le chiamate che non superano la verifica. Puoi generare un nuovo secret per un webhook in qualsiasi momento.
Sì. Puoi registrare, aggiornare e rimuovere webhook tramite gli endpoint webhook e generare un nuovo secret di firma per un webhook esistente. La maggior parte dei team inizia dall'interfaccia e passa all'API quando gestisce più ambienti.
Un 429 significa che stai inviando troppe chiamate. Attendi e riprova con pause sempre più lunghe, e usa i webhook invece di interrogazioni frequenti per tenere basso il numero di chiamate.
Sì. Usa la Public Event Search API per gli eventi pubblicati su Billetto, oppure l'endpoint eventi dell'organizzatore per i tuoi eventi. Gli acquirenti completano l'acquisto nel checkout Billetto.
Sì. Google Analytics 4, il Meta Pixel, Zapier e il tuo fornitore di pagamenti si collegano senza codice. Nelle integrazioni Billetto vedi cosa puoi configurare in pochi minuti.
Denmark