Die Public API

Mit der API arbeiten deine eigenen Programme direkt mit deinem Workspace: Events anlegen, Bestellungen abholen, Kunden mit deinem CRM abgleichen. Es ist dieselbe API, mit der auch das Dashboard arbeitet. Hier steht, wie sie grundsätzlich funktioniert. Alle Endpunkte mit Feldern und Beispielen findest du in der API-Doku.

So legst du los

1. Öffne Integrationen und klick bei API-Keys auf API-Doku. Die API-Doku öffnet sich in einem neuen Tab, du findest sie auch direkt unter api-docs.tickysmart.io. Sie ist auf Englisch.

2. Leg einen API-Key an und gib ihm nur den Zugriff, den dein Programm braucht: API-Keys anlegen und verwalten.
3. Schick die erste Anfrage, zum Beispiel die Liste deiner Events.

Die Seite Integrationen sehen Inhaber und Admins.

Adresse und Anmeldung

Alle Anfragen gehen an https://api.tickysmart.io/v1. Jeder Pfad enthält den Kurznamen deines Workspaces, so wie er in der Adresse des Dashboards nach /t/ steht. Den Key schickst du im Header Authorization mit:

curl https://api.tickysmart.io/v1/tenants/kulturhaus-am-fluss/events \
  -H "Authorization: Bearer ts_live_…"

• Ein Key gilt nur für den Workspace, in dem du ihn angelegt hast.
• Keys gehören dem Workspace, nicht einer Person. Verlässt jemand das Team, arbeiten seine Keys weiter.
• Der Key gehört auf deinen Server. Bau ihn nie in eine Website oder App ein, die andere herunterladen.

Was die API kann

Die API deckt die Bereiche ab, für die du einem Key Zugriff gibst:

Bereich	Was dazugehört
Events und Tickets	Events, Termine, Ticketarten, Extras, Bereiche und Orte
Bestellungen	Bestellungen, Stornos, Erstattungen und die Warteliste
Kunden	Namen und E-Mail-Adressen der Käufer, auch in Bestellungen
Rabatte, Gutscheine und Partner	Rabattcodes und Gutscheine, dazu Partnerlinks
Statistik	Umsätze und Verkaufszahlen
Webhooks	Webhook-Endpunkte anlegen und verwalten

Team, Zahlungskonten, Abrechnung, Einstellungen, eigene Domains und die API-Keys selbst gibt es nur im Dashboard. Fragt ein Key danach, antwortet die API mit API_KEY_NOT_ALLOWED.

Statt regelmäßig nachzufragen, ob es etwas Neues gibt, kannst du dich auch benachrichtigen lassen: Webhooks einrichten.

Test und Live

Keys beginnen mit ts_live_. In einer Testumgebung mit simulierten Zahlungen beginnen sie mit ts_test_. Ein Key funktioniert nur in der Umgebung, in der er entstanden ist. In der Liste deiner Keys steht dazu Live oder Test.

Fehler

Jeder Fehler hat einen HTTP-Status und immer denselben Aufbau:

{ "code": "ORDER_NOT_FOUND", "message": "Order not found" }

Bau deine Logik auf code auf. Die Codes bleiben gleich, message ist ein Hinweis für Entwickler und kann sich ändern. Manche Fehler haben zusätzlich details, etwa die noch freien Mengen, wenn Tickets fehlen.

Status	Code	Bedeutung
400	INVALID_INPUT	Eingaben ungültig, message nennt die Felder
401	UNAUTHENTICATED	Kein Key mitgeschickt, oder der Header beginnt nicht mit Bearer ts_
401	INVALID_API_KEY	Key unbekannt oder widerrufen
401	API_KEY_WRONG_MODE	Test-Key in der Live-Umgebung oder umgekehrt
403	API_KEY_SCOPE_MISSING	Dem Key fehlt der Zugriff auf diesen Bereich
403	API_KEY_NOT_ALLOWED	Das geht nur im Dashboard
404	TENANT_NOT_FOUND	Der Kurzname im Pfad passt nicht zum Workspace des Keys
404	…_NOT_FOUND	Das Objekt gibt es nicht, z. B. EVENT_NOT_FOUND
429	RATE_LIMITED	Zu viele Anfragen, siehe unten
500	INTERNAL_ERROR	Fehler bei uns, später mit demselben Idempotency-Key wiederholen

Grenzen und Wiederholungen

• Anfragen pro Key: Jeder Key darf in zehn Sekunden eine feste Zahl an Anfragen schicken, die genaue Zahl steht in der API-Doku. Jede Antwort zeigt in RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, wie viel noch geht. Darüber kommt 429 mit Retry-After: so viele Sekunden warten, dann weitermachen.
• Sicher wiederholen: Schick bei POST, PATCH, PUT und DELETE einen eigenen Header Idempotency-Key mit, zum Beispiel eine UUID. Bricht die Verbindung ab, wiederholst du die Anfrage mit demselben Wert. 24 Stunden lang bekommst du dann die gespeicherte Antwort, und nichts passiert doppelt.
• Lange Listen: Bestellungen, Kunden und Webhook-Zustellungen kommen seitenweise. Die Antwort enthält items und nextCursor; den Wert schickst du als ?cursor=… für die nächste Seite. Auf der letzten Seite ist nextCursor leer (null).

Geld, Zeit und Sprachen

• Beträge sind ganze Zahlen in der kleinsten Einheit der Währung, immer mit ISO-Code: 2800 mit EUR sind 28,00 €, bei Währungen ohne Nachkommastellen wie JPY ist 2800 genau 2800.
• Zeitpunkte stehen im Format ISO 8601 mit Zeitzone. Jedes Event hat seine eigene Zeitzone, damit du Ortszeiten richtig anzeigst.
• Texte wie Titel und Beschreibungen kommen pro Sprache, etwa { "de": "Sommerfest", "en": "Summer Festival" }. Fehlt eine Sprache, gilt die Standardsprache deines Shops.
• Steuersätze sind Prozentwerte (7, 8.1). Ob Preise brutto oder netto gelten, legt jedes Event fest.

Die API hat ihre Version im Pfad (/v1). Neue Felder, Endpunkte und Ereignisse kommen ohne neue Version dazu. Ignoriere also, was dein Programm nicht kennt.

Häufige Fragen

Kann ich die API direkt im Browser auf meiner Website nutzen?

Nein. Wer deine Website öffnet, könnte den Key sonst auslesen. Ruf die API von deinem Server aus auf und gib nur die Daten weiter, die deine Website braucht. Willst du nur deinen Shop auf der Website zeigen, brauchst du keine API.

Was bedeutet „Test“ bei einem Key?

Der Key stammt aus einer Testumgebung, in der Zahlungen nur simuliert sind. Er funktioniert nur dort. In deinem Workspace entstehen Live-Keys.

Gibt es fertige Bibliotheken für meine Programmiersprache?

Eigene Bibliotheken bieten wir nicht an. Die API-Doku beschreibt alles als OpenAPI-Datei, die du dort herunterladen kannst. Damit erzeugst du dir mit gängigen Werkzeugen einen Client oder importierst sie zum Ausprobieren in Programme wie Postman.

Woher weiß ich, welchen Zugriff ein Endpunkt braucht?

Das steht in der API-Doku bei jedem Endpunkt unter „Required access“, zum Beispiel „Orders: read“. Fehlt dem Key der Zugriff, antwortet die API mit API_KEY_SCOPE_MISSING.