Skip to content

Billetto API -dokumentaatio ja webhook-opas

Näin tunnistaudut, mitä rajapintoja kutsut ja miten Billetto-webhookit lähettävät lippudataa järjestelmiisi reaaliajassa. Tekniset oppaat kehittäjille, jotka rakentavat Billetton päälle.
KEHITTÄJÄKESKUS

Mitä voit rakentaa Billetto API:lla

Billetto API on REST API, joka palauttaa JSONia. Se antaa omalle koodillesi pääsyn samaan dataan, jolla lipunmyyntisi pyörii: tapahtumiin, lipputyyppeihin, tilauksiin, osallistujiin, kirjanpitomerkintöihin, varauskysymyksiin ja kohderyhmiin. Webhookit lähettävät muutokset heti, kun ne tapahtuvat, joten sinun ei tarvitse kysyä niitä.

Tiimit käyttävät APIa ostajien synkronointiin CRM:ään, myyntien lataamiseen tietovarastoon, tapahtumien näyttämiseen omalla verkkosivustolla, jäsenten lisäämiseen ennakkomyynnin kohderyhmiin ja tilitysten täsmäyttämiseen taloushallinnossa. Tällä sivulla kerrotaan, miten API on rakennettu ja miten webhookit toimivat. Jokaisen rajapinnan täydellinen skeema löytyy API-referenssistä.

Aloita tästä

TUNNISTAUTUMINEN

Tunnistaudu API-avainparilla tai OAuth 2.0:lla

API-avainparit omalle tilillesi

Käytä avainparia, kun omat järjestelmäsi kutsuvat APIa järjestäjätilisi puolesta. Luo se Billettossa kohdassa Integrations → Developers → API - Key pairs, anna sille käyttötarkoitusta kuvaava nimi (esimerkiksi ”CRM-synkronointi” tai ”Tietovarasto”) ja lähetä se jokaisessa kutsussa otsakkeessa Api-Keypair.

  • Luo jokaiselle järjestelmälle oma avainpari, jotta voit perua yhden vaikuttamatta muihin
  • Säilytä salaisuus palvelimellasi. Älä koskaan vie sitä selaimeen, mobiilisovellukseen tai julkiseen repositorioon
  • Peru ja korvaa avainpari heti, jos epäilet sen vuotaneen

OAuth 2.0 sovelluksille, joita muut järjestäjät käyttävät

Käytä OAuthia, kun rakennat tuotetta, johon muut Billetto-järjestäjät yhdistävät tilinsä, kuten markkinointityökalua, tapahtuma-alustaa tai toimistojen hallintanäkymää. OAuth käyttää authorization code -kulkua: järjestäjä kirjautuu Billettoon, hyväksyy sovelluksesi ja saat tunnisteen hänen tililleen. Et koskaan näe hänen salasanaansa, ja hän voi irrottaa sovelluksesi milloin tahansa.

Molemmat tavat kuvataan vaihe vaiheelta aloitusoppaassa.

Tapahtumat ja lipputyypit

Hae tilisi tapahtumat päivämäärineen, paikkoineen, tiloineen ja lipputyyppeineen.

  • GET /organiser/events listaa tapahtumasi
  • Lipputyypit, hinnat ja saatavuus tapahtumittain
  • Varauskysymykset, jotka esität ostajille kassalla

Tyypillinen käyttö

Näytä tulevat tapahtumasi reaaliaikaisella saatavuudella omalla verkkosivustollasi tai sovelluksessasi ja ohjaa ostajat Billetton kassalle.

Tilaukset ja osallistujat

Näe, kuka osti mitä, milloin ja mihin tapahtumaan.

  • GET /organiser/orders listaa tilaukset kaikista tapahtumistasi
  • GET /organiser/events/{event_id}/attendees listaa tapahtuman osallistujat
  • Tulokset tulevat sivuittain: hae seuraava sivu, kunnes niitä ei enää tule

Tyypillinen käyttö

Pidä ostajatiedot ajan tasalla CRM:ssäsi tai lähetä osallistujalistat kulunvalvonta- tai akkreditointijärjestelmään.

Kirjanpitomerkinnät ja raportit

Saat lipunmyyntisi taustalla olevat taloustiedot.

  • GET /organiser/ledger_entries listaa myynnit, hyvitykset, maksut ja tilitykset
  • BI-raportti tapahtumittain tärkeimmillä myyntiluvuilla

Tyypillinen käyttö

Lataa liikevaihto kirjanpitoon tai tietovarastoon ja täsmäytä se tilityksiisi.

Kohderyhmät ja jäsenet

Kirjoita dataa takaisin Billettoon sen sijaan, että vain luet sitä.

  • Kohderyhmien jäsenten luonti, päivitys ja poisto
  • Kokonaisten listojen tuonti ja tuonnin tilan seuranta
  • Kohderyhmän ja sen jäsenmäärän haku

Tyypillinen käyttö

Synkronoi jäsenet, tilaajat tai kumppanilistat CRM:stäsi Audiencesiin ennakkomyyntejä ja eksklusiivisia tarjouksia varten.

Webhook-tilaukset

Hallitse webhookeja koodilla Billetton käyttöliittymän sijaan.

  • POST /organiser/webhooks rekisteröi rajapinnan URL-osoitteen
  • Olemassa olevan webhookin päivitys tai poisto
  • Uuden allekirjoitussalaisuuden luonti webhookille

Tyypillinen käyttö

Rekisteröi webhookit automaattisesti, kun uusi asiakas tai ympäristö otetaan käyttöön, ja vaihda salaisuudet aikataulun mukaan.

Public Event Search

Hae Billettossa julkisesti listattuja tapahtumia kaikilta järjestäjiltä.

  • Kyselyparametrit tulosten rajaamiseen, kuvattu referenssissä
  • Jokainen tulos linkittää tapahtumasivulle ja kassalle

Tyypillinen käyttö

Media, kaupunkioppaat ja kumppanialustat näyttävät sen avulla, mitä on tulossa, ja liput myydään Billetton kautta.

KÄYTÄNNÖSSÄ

Billetto API ja webhookit vaihe vaiheelta

APIVaihe 1: pääsy

Luo avainpari ja tee ensimmäinen kutsu

Avaa Integrations, siirry Developers-välilehdelle ja luo avainpari järjestelmälle, jota olet yhdistämässä. Kopioi salaisuus, lisää se pyyntösi otsakkeisiin ja kutsu rajapintaa, kuten /organiser/orders. Vastaus on JSONia, jonka voit ottaa suoraan käyttöön omassa tietomallissasi.

  • Yksi avainpari integraatiota kohden, nimettynä sitä käyttävän järjestelmän mukaan
  • JSON-vastaukset tapahtumille, tilauksille, osallistujille ja kirjanpitomerkinnöille
  • Peru avainpari milloin tahansa vaikuttamatta muihin
Avaa API-referenssi

AUDIENCESVaihe 2: kirjoita Billettoon

Lisää yhteystietoja kohderyhmään APIn kautta

Audiences-rajapinnat ovat tärkein tapa kirjoittaa dataa Billettoon. Lähetä yhteystietoja CRM:stäsi kohderyhmään tai tuo kokonainen lista ja tarkista tila, kunnes se on valmis. Sen jälkeen ryhmä on valmis kutsuille, ennakkomyynneille ja eksklusiivisille tarjouksille.

  • Lisää, päivitä ja poista jäseniä yksitellen
  • Massatuonnit, joiden tilan voit tarkistaa
  • Ryhmät näkyvät heti Audiencesissa

WEBHOOKSVaihe 3: Billetto-webhookit

Rekisteröi webhook ja seuraa toimituksia reaaliajassa

Lisää rajapintasi URL-osoite Developers-välilehdellä, ja Billetto luo sille allekirjoitussalaisuuden. Siitä lähtien jokainen tilaus, hyvitys, osallistujamuutos tai tapahtuman julkaisu lähetetään URL-osoitteeseesi HTTP POST -pyyntönä, jossa on JSON-runko.

  • Käyttöönotto käyttöliittymässä tai POST /organiser/webhooks -kutsulla
  • Yksi allekirjoitussalaisuus webhookia kohden, ja voit luoda sen uudelleen
  • Webhooks-kortti näyttää jokaisen webhookin URL-osoitteen ja API-version
Lue webhook-referenssi
BILLETTO-WEBHOOKIT

Mitä Billetto-webhookit ovat ja milloin niitä käytetään

Webhook on palvelimellasi oleva URL-osoite, jota Billetto kutsuu, kun tililläsi muuttuu jotain. Sen sijaan, että kysyisit APIlta muutaman minuutin välein uusista tilauksista, saat kutsun sillä hetkellä, kun tilaus luodaan, hyvitetään tai sitä muutetaan.

Siksi webhookit ovat oikea työkalu, kun ajoituksella on merkitystä: vahvistus CRM:ään sekunneissa, Slack-viesti, kun VIP-lippu myydään, tai kulunvalvontajärjestelmä, jonka on tiedettävä perutusta lipusta ennen kuin ovet aukeavat.

Webhookit vai API?

  • Käytä webhookeja reagoidaksesi muutoksiin heti niiden tapahtuessa: uudet tilaukset, hyvitykset, osallistujamuutokset ja julkaistut tapahtumat
  • Käytä APIa historian lataamiseen, yöllisen täyden synkronoinnin ajamiseen tai sellaisten tietojen hakemiseen, joita webhook ei sisällä
  • Käytä molempia luotettavimpaan ratkaisuun: webhookit nopeuteen ja ajastettu API-synkronointi, joka poimii kaiken, mitä jäi saamatta
NÄIN SE TOIMII

Näin Billetto-webhook toimitetaan

Lipun myynnistä käsittelyyn omassa järjestelmässäsi.
1
REKISTERÖI RAJAPINTA
Lisää julkinen HTTPS-osoite Developers-välilehdellä tai APIn kautta ja tallenna Billetton antama allekirjoitussalaisuus.
2
JOKIN MUUTTUU
Ostaja tilaa, lippu hyvitetään, osallistujatietoja muutetaan tai julkaiset tapahtuman.
3
BILLETTO LÄHETTÄÄ POST-PYYNNÖN
Billetto lähettää URL-osoitteeseesi HTTP POST -pyynnön, jonka JSON-runko kuvaa muutoksen.
4
TARKISTA JA VASTAA
Tarkista kutsu allekirjoitussalaisuudellasi, vastaa 2xx-tilakoodilla ja käsittele data taustalla.
WEBHOOKIEN PARHAAT KÄYTÄNNÖT

Rakenna luotettava webhook-vastaanotin

Tietoturva

  • Tarkista jokainen kutsu webhookin allekirjoitussalaisuudella ennen kuin luotat sisältöön. Webhook-referenssi kertoo miten
  • Hyväksy vain HTTPS ja säilytä salaisuus palvelimen asetuksissa, ei koodissa
  • Luo uusi salaisuus, jos se on voinut paljastua, ja päivitä sitten vastaanottimesi

Luotettavuus

  • Vastaa nopeasti. Palauta 2xx-tilakoodi heti, kun kutsu on tarkistettu, ja tee raskas työ jonossa
  • Käsittele kaksoiskappaleet. Tallenna käsitellyt tunnisteet, jotta samaa tilausta ei koskaan luoda kahdesti
  • Älä luota järjestykseen. Jos sillä on merkitystä, hae tilauksen nykyinen tila APIn kautta
  • Täsmäytä säännöllisesti. Ajastettu API-synkronointi poimii sen, mitä rajapintasi menetti katkon aikana
Täydellinen rajapintadokumentaatio

Billetto API -referenssi

API-referenssi dokumentoi jokaisen rajapinnan parametreineen, esimerkkikutsuineen ja vastausobjekteineen. Käytä sitä yhdessä tämän oppaan kanssa, kun aloitat koodaamisen: etsi oikea resurssi yllä ja tarkista sitten tarkat kentät referenssistä.

Webhook-resurssi

Webhook-referenssi

Webhook-resurssi sisältää rajapinnan asetukset: sen URL-osoitteen, käytetyn API-version ja allekirjoitussalaisuuden. Suosittelemme luomaan ensimmäisen webhookin Billettossa kohdassa Integrations → Developers ja hallitsemaan sitä APIn kautta, kun ympäristösi kasvaa.

Kaikkien järjestäjien julkiset tapahtumat

Public Event Search API

Public Event Search API palauttaa tapahtumat, jotka järjestäjät ovat listanneet julkisesti Billettoon, kaikilta järjestäjiltä. Se sopii mediasivustoille, kaupunkioppaille, matkailuorganisaatioille ja kumppanisovelluksille, jotka haluavat näyttää, mitä on tulossa, ja jokainen tulos linkittää Billetton tapahtumasivulle, jolta liput ostetaan.

UKK: API JA WEBHOOKIT

Kysymyksiä Billetto APIsta ja webhookeista

Teknisiä kysymyksiä kehittäjiltä, jotka työskentelevät Billetto APIn kanssa. Etkö löydä vastausta? Puhu tiimimme kanssa.

Mistä löydän Billetto API -avaimeni?

Kirjaudu Billettoon, avaa Integrations ja siirry Developers-välilehdelle. Kohdassa API - Key pairs voit luoda uuden avainparin, nähdä kenelle kukin kuuluu ja perua avaimet, joita et enää käytä.

Mikä ero on API-avainparilla ja OAuthilla?

Avainpari antaa omille järjestelmillesi pääsyn omaan järjestäjätiliisi. OAuth 2.0 on sovelluksille, joihin muut järjestäjät yhdistävät Billetto-tilinsä, jolloin toimit heidän puolestaan tuntematta heidän tunnuksiaan.

Mitä tapahtumia Billetto-webhookit voivat lähettää?

Webhookit kattavat muutokset tilauksissa, osallistujissa ja tapahtumissa, kuten uudet tilaukset, hyvitykset, osallistujamuutokset ja julkaistut tapahtumat. Webhook-referenssi listaa kaikki tapahtumat ja niiden sisällön.

Miten varmistan, että webhook-kutsu tulee Billettolta?

Jokaisella webhookilla on oma allekirjoitussalaisuutensa. Tarkista sillä jokainen saapuva kutsu ennen käsittelyä ja hylkää kutsut, jotka eivät läpäise tarkistusta. Voit luoda webhookille uuden salaisuuden milloin tahansa.

Voinko luoda webhookeja APIn kautta?

Kyllä. Voit rekisteröidä, päivittää ja poistaa webhookeja webhook-rajapintojen kautta ja luoda uuden allekirjoitussalaisuuden olemassa olevalle webhookille. Useimmat tiimit aloittavat käyttöliittymästä ja siirtyvät APIin, kun hallittavana on useita ympäristöjä.

Mitä teen, kun saan HTTP 429 -vastauksen?

429 tarkoittaa, että lähetät liian monta kutsua. Odota ja yritä uudelleen kasvavin tauoin, ja käytä webhookeja tiheän kyselyn sijaan pitääksesi kutsujen määrän pienenä.

Voinko näyttää Billetto-tapahtumia omalla sivustollani tai alustallani?

Kyllä. Käytä Public Event Search APIa Billettossa julkisesti listattuihin tapahtumiin tai järjestäjän events-rajapintaa omiin tapahtumiisi. Ostajat viimeistelevät ostoksen Billetton kassalla.

En ole kehittäjä. Voinko silti yhdistää Billetton muihin työkaluihin?

Kyllä. Google Analytics 4, Meta Pixel, Zapier ja oma maksupalveluntarjoajasi voidaan yhdistää ilman koodia. Billetto-integraatioista näet, mitä voit ottaa käyttöön muutamassa minuutissa.

Valmis ensimmäiseen kutsuun?

Luo avainpari kohdassa Integrations, avaa referenssi ja kutsu ensimmäistä rajapintaasi. Jos haluat yhdistää Google Analyticsin, Meta Pixelin tai Zapierin ilman koodia, aloita Billetto-integraatioista.