API-Überblick
TixFin mit Ihrer Website oder App verbinden
Verbinden Sie Ihre eigenen Systeme über die Partner-API mit TixFin – eine schreibgeschützte REST-API mit API-Schlüssel-Authentifizierung, über die Sie Events, Ticketkatalog, Tickets und Bestellungen eines Projekts abrufen.
TixFin ist in der Beta, und die Beta ist der Produktivbetrieb. Die Partner-API
antwortet unter https://beta-rest-api.tixfin.com; Projekte im Testmodus liefern
Testdaten.
Was können Sie damit tun?
Typische Anwendungsfälle
| Anwendungsfall | Beschreibung |
|---|---|
| Automatisierung | Events, Tickets und Bestellungen mit Ihren Systemen abgleichen |
| Analyse | Daten für eigene Berichte und Dashboards abrufen |
| Abstimmung | Bestellungen und Tickets mit Ihren eigenen Unterlagen abgleichen |
| Eigene Integrationen | TixFin-Daten in ein CRM, ein Data Warehouse oder ein BI-Werkzeug übernehmen |
Die Partner-API ist derzeit schreibgeschützt. Events anlegen, Tickets verkaufen und den Einlass verwalten Sie im TixFin-Dashboard, nicht über diese API.
Erste Schritte
1. API-Schlüssel erstellen
prefix.secret
- Integrationen
- Endpunktgruppen
- API-Schlüssel erstellen
- Schlüssel rotieren oder widerrufen
Schlüssel gelten jeweils für ein Projekt. Dieselbe Seite listet die vorhandenen Schlüssel, damit Sie sie rotieren oder widerrufen können, und führt diese Aktionen im Prüfprotokoll. Ein Projekt kann höchstens 50 aktive Schlüssel haben. Wenn Sie einen Schlüssel erstellen, rotieren oder widerrufen oder eine Endpunktgruppe umschalten, fragt TixFin Ihren zweiten Faktor ab, sofern Sie ihn nicht in den letzten zehn Minuten bestätigt haben.
2. Die erste Anfrage senden
curl https://beta-rest-api.tixfin.com/api/partner/projects/YOUR_PROJECT_ID/events \
-H "X-API-Key: YOUR_API_KEY"API-Grundlagen
Basis-URL
https://beta-rest-api.tixfin.comAlle Endpunkte der Partner-API gehören zu einem Projekt:
/api/partner/projects/{projectId}/...Authentifizierung
Senden Sie Ihren API-Schlüssel in einem der beiden Header:
X-API-Key: YOUR_API_KEYoder
Authorization: Bearer YOUR_API_KEYDetails finden Sie in der Anleitung zur Authentifizierung.
Antwortformat
Listen-Endpunkte liefern eine seitenweise Hülle:
{
"items": [ /* ... */ ],
"page": 0,
"size": 20,
"totalItems": 42,
"totalPages": 3
}page beginnt bei 0, size liegt zwischen 1 und 100 (Standard 20). Werte
außerhalb dieses Bereichs werden auf die Grenze gesetzt, nicht abgelehnt.
Endpunkte für eine einzelne Ressource (etwa GET /events/{eventId}) liefern
das Objekt direkt.
Den maschinenlesbaren Vertrag erhalten Sie ohne Schlüssel unter
GET /api/partner/openapi.json.
Ratenbegrenzung
Es gilt eine Grenze pro API-Schlüssel und eine pro Client-IP-Adresse:
| Bereich | Dauerrate | Spitze |
|---|---|---|
| Pro API-Schlüssel | 10 Anfragen/Sekunde (600/Minute) | 60 |
| Pro IP-Adresse | 5 Anfragen/Sekunde (300/Minute) | 30 |
Wer eine davon überschreitet, erhält 429 mit einem Retry-After-Header.
Endpunkte
Jeder Schlüssel gilt für eine oder mehrere Endpunktgruppen, und das
Projekt muss die Gruppe ebenfalls aktiviert haben. Fehlt die Gruppe auf einer
der beiden Seiten, antwortet der Endpunkt mit 403.
Endpunktgruppe: events.read
Events auflisten
GET /api/partner/projects/{projectId}/events?page=0&size=20Event-Details abrufen
GET /api/partner/projects/{projectId}/events/{eventId}Endpunktgruppe: ticket_catalog.read
Einträge des Ticketkatalogs auflisten
GET /api/partner/projects/{projectId}/ticket-catalog?eventId={eventId}&page=0&size=20eventId ist optional.
Endpunktgruppe: tickets.read
Tickets auflisten
GET /api/partner/projects/{projectId}/tickets?eventId={eventId}&paymentReference=&status=&page=0&size=20eventId, paymentReference und status sind optionale Filter. status ist
PAID, SCANNED, SCANNED_OUT oder CANCELLED (Groß- und Kleinschreibung
egal); jeder andere Wert findet nichts.
Endpunktgruppe: orders.read
Bestellungen auflisten
GET /api/partner/projects/{projectId}/orders?eventId={eventId}&page=0&size=20Eine „Bestellung“ fasst alle Tickets mit derselben paymentReference
zusammen. eventId ist optional.
Das Dashboard listet außerdem webhooks.read und webhooks.manage. Noch
nutzt kein Partner-Endpunkt diese Gruppen: Webhooks richten Sie im Dashboard
unter Konto → Webhooks ein – siehe Webhooks.
Offizielle SDKs
Statt die REST-API direkt aufzurufen, können Sie eine der offiziellen Client-Bibliotheken nutzen – beide übernehmen Authentifizierung, Seitenparameter und Fehlerbehandlung:
npm install @tixfin/partner-api-clientimport { TixfinPartnerClient } from "@tixfin/partner-api-client";
const client = new TixfinPartnerClient({
projectId: "YOUR_PROJECT_ID",
apiKey: process.env.TIXFIN_PARTNER_API_KEY!,
baseUrl: "https://beta-rest-api.tixfin.com",
});
const events = await client.listEvents();pip install tixfin-partner-apiimport os
from tixfin_partner_api import TixfinPartnerClient
client = TixfinPartnerClient(
project_id="YOUR_PROJECT_ID",
api_key=os.environ["TIXFIN_PARTNER_API_KEY"],
base_url="https://beta-rest-api.tixfin.com",
)
events = client.list_events()Vollständige Referenz und was Version 0.1.0 noch nicht abdeckt: SDK-Anleitung.
Empfehlungen
✅ Sicherheit
- Schlüssel in Umgebungsvariablen speichern, nie im clientseitigen Code
- Jedem Schlüssel nur die Endpunktgruppen geben, die er braucht
- Schlüssel regelmäßig rotieren und ungenutzte widerrufen
✅ Leistung
- Antworten nach Möglichkeit zwischenspeichern
- Mit
page/sizenicht mehr abrufen als nötig (sizehöchstens 100) tickets/ordersnacheventIdfiltern, wenn Sie nur ein Event brauchen
✅ Fehlerbehandlung
- HTTP-Statuscodes prüfen
- Das Feld
detailin Fehlerantworten auslesen - Bei
429die Sekunden ausRetry-Afterabwarten, bevor Sie es erneut versuchen
Fehlercodes
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 401 | API-Schlüssel fehlt, ist fehlerhaft, widerrufen oder unbekannt |
| 403 | Schlüssel gehört zu einem anderen Projekt, hat diese Endpunktgruppe nicht, oder die Gruppe ist für das Projekt deaktiviert |
| 404 | Ressource nicht gefunden |
| 429 | Ratenbegrenzung überschritten (siehe Retry-After) |
| 500 | Serverfehler (Support kontaktieren) |
| 501 | Diese Installation liefert die Daten des Endpunkts noch nicht |
| 502 | Der Dienst, dem die Daten gehören, war nicht erreichbar; später erneut versuchen |
Fehlerantworten sehen so aus:
{
"title": "Unauthorized",
"status": 401,
"detail": "Invalid API key.",
"timestamp": "2026-10-25T09:30:00.000000000Z"
}Mit Accept-Language: de erhalten Sie deutsche title-Werte.
Support
Dokumentation:
Brauchen Sie Hilfe?
- E-Mail: api@tixfin.com
- Bitte angeben: Präfix des API-Schlüssels (nie den ganzen Schlüssel), Details zur Anfrage, Fehlermeldungen
