API-nøkler og Integration API

Med Ticsies Integration API kan ditt eget system hente arrangementer og deltakere og sjekke inn billetter – server til server. Her ser du hvordan du oppretter et nøkkelpar, hvilke tillatelser som finnes, og hva API-et kan gjøre. Den fullstendige referansen finner du i API-dokumentasjonen.

Hva kan API-et brukes til?

Hente deltakerlister inn i et eget system, for eksempel et medlemsregister eller et akkrediteringssystem.
Bygge et eget dashbord over arrangementene dine.
Koble til en egen skanner eller port som sjekker inn billetter via API-et.

API-et er laget for server-til-server-kall. Nøklene må aldri ligge i en app eller på en nettside som besøkende kan se.

Opprett et nøkkelpar

Åpne API-nøkler. Gå til Innstillinger → API-nøkler. Du trenger rollen Eier eller Admin.
Gi nøkkelen et navn. Under Opprett nytt nøkkelpar fyller du inn Navn på nøkkelen, for eksempel «Medlemsregister» – så vet du senere hva den brukes til.
Velg tillatelser. Kryss av for read og/eller write (se tabellen nedenfor).
Generer. Klikk på Generer nøkkelpar. Du får en offentlig nøkkel (begynner med ticsie_pk_) og en hemmelig nøkkel (begynner med ticsie_sk_).
Lagre den hemmelige nøkkelen med en gang. Under overskriften Lagre den hemmelige nøkkelen din nå vises den hemmelige nøkkelen én eneste gang. Klikk på Kopier og lagre den på et trygt sted, for eksempel i en passordbehandler eller som miljøvariabel på serveren din.

Viktig

Den hemmelige nøkkelen vises bare én gang og kan ikke hentes frem igjen – Ticsie lagrer den ikke i klartekst. Har du mistet den, tilbakekaller du nøkkelparet og oppretter et nytt.

Tillatelser

Tillatelse	I panelet	Gir tilgang til
`read`	Lese arrangementer, ordrer og deltakere	Hente arrangementer og deltakere (GET-kall).
`write`	Opprette og endre data via API	Skanne billetter og sjekke inn deltakere (POST-kall).

Gi hver nøkkel så få tillatelser som mulig. En nøkkel som bare henter deltakerlister, trenger bare read.

Kall, endepunkter og begrensninger

Hvert kall sendes til https://ticsie.se/api/v1/integration med to headere:

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

Endepunkt	Tillatelse	Gjør
`GET /events`	read	Lister arrangementene dine. Filtrer med `period` = `future`, `past` eller `all`.
`GET /events/{id}/attendees`	read	Lister deltakere (betalte billetter) for et arrangement, 50 per side.
`POST /events/{id}/scan`	write	Sjekker inn en billett med dens UUID (verdien i billettens QR-kode).

Grense: 60 kall per minutt. Overskrides grensen, svarer API-et med HTTP 429 – vent og prøv igjen.
Paginering: lister deles opp i sider. Hent neste side med ?page=2.
Feil returneres som JSON med en error_code, for eksempel API_KEY_INVALID eller INSUFFICIENT_PERMISSION.

Eksempelkall i flere programmeringsspråk, svarformater og alle feilkoder finner du i API-dokumentasjonen.

Tilbakekall en nøkkel

I listen under API-nøkler ser du alle nøkkelpar med navn, offentlig nøkkel, tillatelser og når de ble opprettet. Klikk på Tilbakekall og bekreft med Ja, tilbakekall. Nøkkelen slutter å fungere umiddelbart. Tilbakekall alltid en nøkkel som ikke lenger brukes, eller som kan ha havnet i feil hender.

Vanlige spørsmål

Jeg har mistet den hemmelige nøkkelen – kan jeg få se den igjen?

Nei. Den hemmelige nøkkelen vises bare når nøkkelparet opprettes. Tilbakekall det gamle nøkkelparet og opprett et nytt.

Hvorfor får jeg feilen INSUFFICIENT_PERMISSION?

Nøkkelen mangler tillatelsen som endepunktet krever. Innsjekking via POST /events/{id}/scan krever write. Opprett et nytt nøkkelpar med riktig tillatelse.

Kan jeg bruke API-nøkkelen i en mobilapp eller på nettstedet mitt?

Nei, nøklene skal bare brukes på en server. For innsjekking med mobilen finnes Ticsie-appen.

Kan jeg opprette arrangementer eller ordrer via API-et?

Ikke i dag. Integration API har de tre endepunktene som er beskrevet ovenfor. Savner du noe? Legg inn et forslag på Ønsker og veikart.