API-Schlüssel und die Integration API

Mit der Integration API von Ticsie kann Ihr eigenes System Veranstaltungen und Teilnehmer abrufen und Tickets einchecken – von Server zu Server. Hier erfahren Sie, wie Sie ein Schlüsselpaar erstellen, welche Berechtigungen es gibt und was die API kann. Die vollständige Referenz finden Sie in der API-Dokumentation.

Wofür lässt sich die API nutzen?

Teilnehmerlisten in Ihr eigenes System übernehmen, etwa in ein Mitgliederverzeichnis oder ein Akkreditierungssystem.
Ein eigenes Dashboard für Ihre Veranstaltungen bauen.
Einen eigenen Scanner oder ein Drehkreuz anbinden, das Tickets über die API eincheckt.

Die API ist für Aufrufe von Server zu Server gedacht. Die Schlüssel dürfen niemals in einer App oder auf einer Webseite stehen, die Besucher einsehen können.

Ein Schlüsselpaar erstellen

API-Schlüssel öffnen. Gehen Sie zu Einstellungen → API-Schlüssel. Sie benötigen die Rolle Inhaber oder Admin.
Schlüssel benennen. Füllen Sie unter Neues Schlüsselpaar erstellen das Feld Schlüsselname aus, zum Beispiel „Mitgliederverzeichnis“ – so wissen Sie später, wofür er verwendet wird.
Berechtigungen wählen. Kreuzen Sie read und/oder write an (siehe Tabelle unten).
Generieren. Klicken Sie auf Schlüsselpaar generieren. Sie erhalten einen öffentlichen Schlüssel (beginnt mit ticsie_pk_) und einen geheimen Schlüssel (beginnt mit ticsie_sk_).
Geheimen Schlüssel sofort sichern. Unter der Überschrift Speichern Sie jetzt Ihren geheimen Schlüssel wird der geheime Schlüssel ein einziges Mal angezeigt. Klicken Sie auf Kopieren und bewahren Sie ihn an einem sicheren Ort auf, etwa in einem Passwort-Manager oder als Umgebungsvariable auf Ihrem Server.

Wichtig

Der geheime Schlüssel wird nur einmal angezeigt und kann nicht erneut abgerufen werden – Ticsie speichert ihn nicht im Klartext. Haben Sie ihn verloren, widerrufen Sie das Schlüsselpaar und erstellen Sie ein neues.

Berechtigungen

Berechtigung	Im Panel	Ermöglicht
`read`	Veranstaltungen, Bestellungen und Teilnehmer lesen	Veranstaltungen und Teilnehmer abrufen (GET-Anfragen).
`write`	Daten über API erstellen und ändern	Tickets scannen und Teilnehmer einchecken (POST-Anfragen).

Geben Sie jedem Schlüssel so wenige Berechtigungen wie möglich. Ein Schlüssel, der nur Teilnehmerlisten abruft, braucht nur read.

Anfragen, Endpunkte und Limits

Jede Anfrage geht an https://ticsie.se/api/v1/integration und enthält zwei Header:

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

Endpunkt	Berechtigung	Funktion
`GET /events`	read	Listet Ihre Veranstaltungen auf. Filtern mit `period` = `future`, `past` oder `all`.
`GET /events/{id}/attendees`	read	Listet die Teilnehmer (bezahlte Tickets) einer Veranstaltung auf, 50 pro Seite.
`POST /events/{id}/scan`	write	Checkt ein Ticket anhand seiner UUID ein (der Wert im QR-Code des Tickets).

Rate-Limit: 60 Anfragen pro Minute. Wird es überschritten, antwortet die API mit HTTP 429 – warten Sie kurz und versuchen Sie es erneut.
Paginierung: Listen werden in Seiten aufgeteilt. Die nächste Seite rufen Sie mit ?page=2 ab.
Fehler werden als JSON mit einem error_code zurückgegeben, zum Beispiel API_KEY_INVALID oder INSUFFICIENT_PERMISSION.

Beispielanfragen in mehreren Programmiersprachen, Antwortformate und alle Fehlercodes finden Sie in der API-Dokumentation.

Einen Schlüssel widerrufen

Die Liste unter API-Schlüssel zeigt alle Schlüsselpaare mit Name, öffentlichem Schlüssel, Berechtigungen und Erstellungsdatum. Klicken Sie auf Widerrufen und bestätigen Sie mit Ja, widerrufen. Der Schlüssel funktioniert ab sofort nicht mehr. Widerrufen Sie immer Schlüssel, die nicht mehr verwendet werden oder in falsche Hände geraten sein könnten.

Häufige Fragen

Ich habe den geheimen Schlüssel verloren – kann ich ihn noch einmal sehen?

Nein. Der geheime Schlüssel wird nur beim Erstellen des Schlüsselpaars angezeigt. Widerrufen Sie das alte Schlüsselpaar und erstellen Sie ein neues.

Warum erhalte ich den Fehler INSUFFICIENT_PERMISSION?

Dem Schlüssel fehlt die Berechtigung, die der Endpunkt verlangt. Der Check-in über POST /events/{id}/scan erfordert write. Erstellen Sie ein neues Schlüsselpaar mit der richtigen Berechtigung.

Kann ich den API-Schlüssel in einer mobilen App oder auf meiner Website verwenden?

Nein, die Schlüssel dürfen nur auf einem Server verwendet werden. Für den Check-in per Handy gibt es die Ticsie-App.

Kann ich über die API Veranstaltungen oder Bestellungen anlegen?

Derzeit nicht. Die Integration API umfasst die drei oben beschriebenen Endpunkte. Fehlt Ihnen etwas? Hinterlassen Sie einen Vorschlag auf der Seite Suggestions & roadmap.