API-nøgler og Integration API

Med Ticsies Integration API kan dit eget system hente arrangementer og deltagere og tjekke billetter ind – server til server. Her kan du se, hvordan du opretter et nøglepar, hvilke rettigheder der findes, og hvad API'et kan. Den fulde reference finder du i API-dokumentationen.

Hvad kan API'et bruges til?

Hente deltagerlister ind i dit eget system, for eksempel et medlemsregister eller et akkrediteringssystem.
Bygge dit eget dashboard over dine arrangementer.
Tilslutte din egen scanner eller adgangsport, der tjekker billetter ind via API'et.

API'et er beregnet til kald fra server til server. Nøglerne må aldrig ligge i en app eller på en webside, som besøgende kan se.

Opret et nøglepar

Åbn API-nøgler. Gå til Indstillinger → API-nøgler. Du skal have rollen Ejer eller Admin.
Navngiv nøglen. Under Opret nyt nøglepar udfylder du Navn på nøglen, for eksempel »Medlemsregister« – så ved du senere, hvad den bruges til.
Vælg rettigheder. Sæt flueben ved read og/eller write (se tabellen nedenfor).
Generer. Klik på Generer nøglepar. Du får en offentlig nøgle (begynder med ticsie_pk_) og en hemmelig nøgle (begynder med ticsie_sk_).
Gem den hemmelige nøgle med det samme. Under overskriften Gem din hemmelige nøgle nu vises den hemmelige nøgle én eneste gang. Klik på Kopier, og gem den et sikkert sted, for eksempel i en adgangskodeadministrator eller som miljøvariabel på din server.

Vigtigt

Den hemmelige nøgle vises kun én gang og kan ikke hentes igen – Ticsie gemmer den ikke i klartekst. Har du mistet den, så tilbagekald nøgleparret, og opret et nyt.

Rettigheder

Rettighed	I panelet	Giver adgang til
`read`	Læse begivenheder, ordrer og deltagere	At hente arrangementer og deltagere (GET-kald).
`write`	Oprette og ændre data via API	At scanne billetter og tjekke deltagere ind (POST-kald).

Giv hver nøgle så få rettigheder som muligt. En nøgle, der kun henter deltagerlister, behøver kun read.

Kald, endpoints og begrænsninger

Hvert kald sendes til https://ticsie.se/api/v1/integration med to headers:

X-API-Key: ticsie_pk_...
X-API-Secret: ticsie_sk_...

Endpoint	Rettighed	Gør
`GET /events`	read	Viser dine arrangementer. Filtrer med `period` = `future`, `past` eller `all`.
`GET /events/{id}/attendees`	read	Viser deltagere (betalte billetter) til et arrangement, 50 pr. side.
`POST /events/{id}/scan`	write	Tjekker en billet ind med dens UUID (værdien i billettens QR-kode).

Grænse: 60 kald pr. minut. Overskrides grænsen, svarer API'et med HTTP 429 – vent, og prøv igen.
Paginering: Lister deles op i sider. Hent næste side med ?page=2.
Fejl returneres som JSON med en error_code, for eksempel API_KEY_INVALID eller INSUFFICIENT_PERMISSION.

Eksempelkald i flere programmeringssprog, svarformater og alle fejlkoder finder du i API-dokumentationen.

Tilbagekald en nøgle

På listen under API-nøgler ser du alle nøglepar med navn, offentlig nøgle, rettigheder og oprettelsesdato. Klik på Tilbagekald, og bekræft med Ja, tilbagekald. Nøglen holder op med at virke med det samme. Tilbagekald altid en nøgle, der ikke længere bruges, eller som kan være havnet i de forkerte hænder.

Ofte stillede spørgsmål

Jeg har mistet den hemmelige nøgle – kan jeg se den igen?

Nej. Den hemmelige nøgle vises kun, når nøgleparret oprettes. Tilbagekald det gamle nøglepar, og opret et nyt.

Hvorfor får jeg fejlen INSUFFICIENT_PERMISSION?

Nøglen mangler den rettighed, som endpointet kræver. Indtjekning via POST /events/{id}/scan kræver write. Opret et nyt nøglepar med den rette rettighed.

Kan jeg bruge API-nøglen i en mobilapp eller på mit website?

Nej, nøglerne må kun bruges på en server. Til indtjekning med mobilen findes Ticsie-appen.

Kan jeg oprette arrangementer eller ordrer via API'et?

Ikke i dag. Integration API'et har de tre endpoints, der er beskrevet ovenfor. Mangler du noget? Kom med et forslag under Ønsker og roadmap.