TixFinDocs
API-Integration

API-Überblick

TixFin mit Ihrer Website oder App verbinden

5 Min. Lesezeit

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

AnwendungsfallBeschreibung
AutomatisierungEvents, Tickets und Bestellungen mit Ihren Systemen abgleichen
AnalyseDaten für eigene Berichte und Dashboards abrufen
AbstimmungBestellungen und Tickets mit Ihren eigenen Unterlagen abgleichen
Eigene IntegrationenTixFin-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

Melden Sie sich im TixFin-Dashboard an
Wählen Sie das Projekt, öffnen Sie dann das Kontomenü → Konto und wählen Sie in der Navigation der Einstellungen unter Abrechnung den Eintrag Integrationen. Dort verwalten Sie die Partner-API des gewählten Projekts. Der Eintrag erscheint nur, wenn Ihre Sitzung mit Zwei-Faktor-Authentifizierung angemeldet ist, und Sie brauchen Zugriff auf die Projekteinstellungen
Aktivieren Sie unter Endpunktgruppen die Gruppen, die dieses Projekt freigeben soll – ein Schlüssel kann nur Gruppen nutzen, die hier aktiv sind
Klicken Sie auf API-Schlüssel erstellen, füllen Sie Name des Schlüssels aus und wählen Sie die Gruppen unter Erlaubte Endpunktgruppen
Kopieren Sie den API-Schlüssel im Klartext und bewahren Sie ihn sicher auf – er wird nur einmal angezeigt, im Format prefix.secret
Partner-API-Einstellungen mit Endpunktgruppen und API-Schlüsseln
  1. Integrationen
  2. Endpunktgruppen
  3. API-Schlüssel erstellen
  4. Schlüssel rotieren oder widerrufen
📸 Partner-API-Einstellungen mit Endpunktgruppen und API-Schlüsseln

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.com

Alle 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_KEY

oder

Authorization: Bearer YOUR_API_KEY

Details 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:

BereichDauerrateSpitze
Pro API-Schlüssel10 Anfragen/Sekunde (600/Minute)60
Pro IP-Adresse5 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=20

Event-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=20

eventId ist optional.

Endpunktgruppe: tickets.read

Tickets auflisten

GET /api/partner/projects/{projectId}/tickets?eventId={eventId}&paymentReference=&status=&page=0&size=20

eventId, 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=20

Eine „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-client
import { 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-api
import 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/size nicht mehr abrufen als nötig (size höchstens 100)
  • tickets/orders nach eventId filtern, wenn Sie nur ein Event brauchen

✅ Fehlerbehandlung

  • HTTP-Statuscodes prüfen
  • Das Feld detail in Fehlerantworten auslesen
  • Bei 429 die Sekunden aus Retry-After abwarten, bevor Sie es erneut versuchen

Fehlercodes

CodeBedeutung
200Erfolg
401API-Schlüssel fehlt, ist fehlerhaft, widerrufen oder unbekannt
403Schlüssel gehört zu einem anderen Projekt, hat diese Endpunktgruppe nicht, oder die Gruppe ist für das Projekt deaktiviert
404Ressource nicht gefunden
429Ratenbegrenzung überschritten (siehe Retry-After)
500Serverfehler (Support kontaktieren)
501Diese Installation liefert die Daten des Endpunkts noch nicht
502Der 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

Nächste Schritte

Auf dieser Seite