Skip to content

Documentazione API Billetto e guida ai webhook

Come autenticarti, quali endpoint chiamare e come i webhook di Billetto inviano i dati di biglietteria ai tuoi sistemi in tempo reale. Guide tecniche per sviluppatori che costruiscono su Billetto.
DEVELOPER HUB

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

AUTENTICAZIONE

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 e tipi di biglietto

Recupera gli eventi del tuo account con data, luogo, stato e tipi di biglietto.

  • GET /organiser/events elenca 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/orders elenca gli ordini di tutti i tuoi eventi
  • GET /organiser/events/{event_id}/attendees elenca 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_entries elenca 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/webhooks registra 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
Apri il riferimento API

AUDIENCESPasso 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

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
Leggi il riferimento webhook
WEBHOOK DI BILLETTO

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 FUNZIONA

Come viene consegnato un webhook di Billetto

Dalla vendita di un biglietto all'elaborazione nel tuo sistema.
1
REGISTRA L'ENDPOINT
Aggiungi un URL HTTPS pubblico nella scheda Developers o tramite l'API e conserva il secret di firma che Billetto ti fornisce.
2
QUALCOSA CAMBIA
Un acquirente effettua un ordine, un biglietto viene rimborsato, i dati di un partecipante cambiano o pubblichi un evento.
3
BILLETTO INVIA UN POST
Billetto invia al tuo URL un HTTP POST con un corpo JSON che descrive la modifica.
4
VERIFICA E RISPONDI
Verifica la chiamata con il tuo secret di firma, rispondi con uno stato 2xx ed elabora i dati in background.
BEST PRACTICE WEBHOOK

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
Documentazione completa degli endpoint

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.

La risorsa webhook

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.

Eventi pubblici di tutti gli organizzatori

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.

FAQ SU API E WEBHOOK

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.

Dove trovo la mia chiave API Billetto?

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ù.

Qual è la differenza tra una coppia di chiavi API e OAuth?

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.

Quali eventi possono inviare i webhook di Billetto?

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.

Come verifico che una chiamata webhook provenga da Billetto?

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.

Posso creare webhook tramite l'API?

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.

Cosa faccio con una risposta HTTP 429?

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.

Posso mostrare gli eventi Billetto sul mio sito o sulla mia piattaforma?

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.

Non sono uno sviluppatore. Posso comunque collegare Billetto ad altri strumenti?

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.

Pronto per la prima chiamata?

Crea una coppia di chiavi in Integrations, apri il riferimento e chiama il tuo primo endpoint. Se preferisci collegare Google Analytics, il Meta Pixel o Zapier senza codice, inizia dalle integrazioni Billetto.