Tixly Admin API

Tixly tilbyder et administrations API til integration til eksterne planlægnings og venue management systemer for at oprette events og produktioner i Tixly, og for at få salgsdata på disse events. 

Admin API blev først bygget til specifikationer fra Yesplan, og yderligere endpoints er senere blevet tilføjet. Derfor adskiller autorisationen sig også fra f.eks. CRM API (basic vs. Bearer token), og nogle navne er ikke 100% som hos Tixly, såsom "Production" i stedet for "event group" (på dansk: Produktion). 

Adgang til Admin API opsættes igennem Venue Management modulet i Tixly og inkluderer flere konfigurationsmuligheder.

1. Organisation

   1. Vælger en organisation der vil være ejer af de oprettede events og produktioner. 

2. Filtrer Pr. Organisation

   1. Hvis denne sættes til ja, begrænser det adgangen for at hive information til kun at være events tilhørende denne organisation.

3. Manuel Forbindelse

   1. Hvis sat til ja, kan en back-office bruger tilføje/redigere/fjerne et eksternt ID på events i Tixly's interface.

4. Deaktiverede Værdier 

   1. Giver dig muligheder for at lave nogle eventegenskaber skrivebeskyttet i Tixlys Interface. Dette betyder at det kun kan blive ændret i management softwaren, og sikrer at der ikke opstår uoverensstemmelser mellem de to systemer. Eksempler kan være Eventnavn, start- og sluttidspunkt.

Oversigt over arbejdet med Admin API

Produktioner og events bliver først oprettet i venuemanagement systemet. Når de skal gøres tilgængelige i Tixly, kan venuemanagement systemet pushe dem ved at bruge API'et. 

Hvis der senere sker ændringer eller opdateringer til eventinformationen i venuemanagement systemet, kan disse events igen pushes for at blive opdateret i Tixly. Når et event eller en produktion sendes til Tixly, vil Id på de oprettede elementer i Tixly blive sendt tilbage, så de kan opbevares i venuemanagement systemet.

I Tixly gøres events klar til salg, inklusiv at tildele priser, kvoter, specificering af billetlayouts osv. 

Når events bliver solgt, are der flere muligheder for at hente salgsdata. 

API'et bruger basis HTTP authentication: alle requests skal inkludere en header Authorisation med schemet "Basic". 

Alle data bliver sendt i json format. Dato-tid værdier sendes som JSON strings baseret på ISO 8601 standard.

https://adminapi.{country url}/v2/swagger/ui/index

Yesplan kører stadig på version 2 - https://adminapi.{country url}/v1/swagger/ui/index 

Hent mapping

Første step er at hente de tilgængelige mappings for at få lister over salskonfigurationer, arrangører, sæsoner og eventkategorier der kan bruges til at oprette events. En bruger af planlægningssystemet kan blive vist dette som en liste af muligheder når eventet opsættes.

GET /admin/mappings

Opret en produktion

Push produktionens detaljer fra planlægningssystemet til Tixly Tixly.

POST /admin/productions

{
"production-id": "P-S-1", 
"name": "The first production from this system", 
"sub-title": "SKG2023",
"description": "The best show in Iceland... ",
"available-online": true,
"big-image": "https://cdn.myexamplevenue.com/media//16922-10.jpg",
"small-image": "https://cdn.myexamplevenue.com/media//16922-10-b.jpg"
}

Production-id er planlægningssystemets ID som du senere kan kalde som {externalID}.

For at hente produktionsdetaljer: GET /admin/productions/{externalID} eller for at opdatere produktionsdetaljer: PUT /admin/productions/{externalID}.

Tixly downloader billeder fra de URL's du tilføjer i Tixlys eget system og bruger dem som de er i købsprocessen. 

Opret events

Nu kan du oprette events under denne produktion. 

Brug dit eget event-di og referer til din produktion, som du kan se i de første to properties. 

Sæson, Salskonfiguration og Eventkategori forventer en enkelt værdi fra hver mappingliste.

POST /admin/event

{
"event-id": "2d35c887-fa87-4ff5-9edb-8eac42348f87",
"production-id": "P-S-1",
"name": "Margôt Ros",
"starttime": "2024-09-22T17:00:00",
"endtime": "2024-09-22T18:30:00",
"onlinesalestart": "2024-01-01T09:30:00",
"seasons": "1",
"hallconfigurations": "47",
"eventcategory": "25",
"note-1": "Example note",
"note-2": "More notes"
}

Det er også muligt at sende billeder med /admin/events, disse vil erstatte de billeder i den primære produktion til det givne event.

Dit eget event-ID kan bruges som {externalId} for at få, opdatere eller slette et event. 

Kun events der IKKE har billetter kan blive slettet.

Hent salgsinformation

Du kan hente salgsinformationer pr. event med: GET /admin/events/{externalID}.

Og for alle events på en måned brug: GET /admin/events.

Ovenstående metode returnerer kun events der har et eksternt ID sat på og bruger følgende output format. 

Output eksempel:

{
"tix-event-id": "55177",
"event-id": "EX-0002",
"production-id": null,
"name": "Amélie de musical",
"admin-name": "",
"location": "",
"starttime": "2023-08-19T19:35:00+02:00",
"endtime": "2023-08-19T22:30:00+02:00",
"in-sale": true,
"closed": true,
"salestatus": 0,
"salestatustext": "None",
"ticketscapacity": 2208,
"ticketssold": 34,
"ticketsfree": 0,
"ticketsreserved": 9,
"ticketsallocated": 0,
"ticketsblocked": 7,
"ticketsavailable": 2158,
"ticketstotal": 43,
"ticketstemporarilyreserved": 0,
"ticketsheldforsubscribers": 0,
"ticketsrevenue": 3025,
"ticketsrevenue-excluding-vat": 2775.23,
"productiononline": "1",
"eventonline": "1"
}

De næste to ruter returnerer alle events, inklusiv dem uden et eksternt ID. Det er muligt at begrænse outputtet med en setting i Tixly, så de kun returnerer noget for det der er knyttet til den pågældende organisation. Hvad du skal bruge, afhænger af situationen. 

Hvis du har brug for at få detaljer på events der har fundet sted (f.eks. alle gårsdagens events) eller har brug for en status på alle events i en given uge, brug GET /admin/GetEventsByEventDates.

Hvis du er interesseret i alle events og vil hente ny data på alle der havde salgsaktivitet (f.eks. i går), can du bruge GET /admin/GetEventsBySalesDates.

Outputs på disse ruter er arrays grupperet efter EventID, Billettype, Priszone og Sektion, hvis du ønsker detaljeret salgsinformation. Et eksempel er salg i 3 priszoner, med 5 billettyper, der vil returnerer 15 objekter som dette eksempel: 

{
"ExternalId": "EX-0002",
"EventId": 55177,
"AdminName": "",
"Name": "Amélie de musical",
"StartDate": "08/19/2023 19:35:00",
"Venue": "Example Venue",
"Hall": "Big Hall",
"TicketTypeId": 749,
"TicketType": "Normaal",
"PriceZoneId": 1,
"PriceZone": "1",
"SectionId": 721,
"Section": "Balcony B",
"SoldTickets": 0,
"SoldRevenue": 0,
"ReservedTickets": 1,
"ReservedRevenue": 135,
"Capacity": 2201
},

Ovenstående kapacitet handler om hele eventet, mens solgte og reserverede tal er for kombinationen af EventID, Billettype, Priszone og Sektion. 

Kun disse kombinationer der har salg eller reservationer i sig, kommer med i outputtet. 

Hent salgsdata for en periode

Dette henter alle billetter med sæde- og kundeinformationer der blev solgt i en gien periode. Du kan bruge dette som eksempel på at hente salgstal hver time for at holde det eksterne system up-to-date med seneste salg. 

Ruten hertil er: GET /admin/GetTicketsBySalesDates.

Output er en array med billetter som nedenstående eksempel:

{
"CustomerId": 1620265,
"CustomerName": "Kim Howick",
"FirstName": "Kim",
"LastName": "Howick",
"CustomerEmail": "[email protected]",
"Mobile": "615525685",
"AddressOne": "Blaine 1",
"AddressTwo": "",
"City": "Sneek",
"ZipCode": "8604",
"Country": "Nederland",
"TicketId": 30322525,
"TicketTypeId": 749,
"TicketType": "Normaal",
"PriceZoneId": 1,
"PriceZone": "A",
"Price": 30,
"Created": "04/04/2023 15:58:55",
"TransactionType": 1,
"ExternalId": "E-55-772b",
"EventId": 71845,
"Section": "Zaal",
"RowName": "12",
"SeatName": "6"
},