TikFlow External Scan API

Die TikFlow External Scan API ermöglicht es Ihnen, Ihre eigene Hardware oder Software direkt mit TikFlow zu verbinden. Validieren und entwerten Sie Tickets in Echtzeit – ganz ohne zusätzliche TikFlow-Geräte.

💡 Ideal für: Schwimmbäder, Freizeitparks, Fitnessstudios oder Veranstalter mit bestehenden Zutrittssystemen, die TikFlow-Tickets akzeptieren möchten.

Zwei Integrationswege

TikFlow bietet zwei Möglichkeiten, externe Systeme anzubinden:

Eigene Software / REST API

Für Entwickler, die TikFlow-Tickets in eigene Anwendungen integrieren möchten. Sie senden HTTP-Requests mit einem API-Key im Header und verarbeiten die JSON-Responses in Ihrem Code.

Geeignet für: Individuelle Softwarelösungen, eigene Kassensysteme, Self-Service-Terminals, mobile Apps

TikFlow Hardware

Für physische Zutrittskontrollgeräte wie Drehkreuze, Schranken oder Türcontroller, die HTTP-Requests senden können. TikFlow übernimmt die Kommunikation mit dem Gerät – Sie konfigurieren lediglich die Server-URL.

Geeignet für: Drehkreuze, Schrankenanlagen, Türcontroller, Zugangsschleusen

➡️ Details unter Hardware-Integration

Was kann die API?

Die External Scan API ist speziell für die Einlasskontrolle konzipiert:

Funktion	Beschreibung
Ticket validieren	Prüfen, ob ein Ticket gültig ist (ohne Entwertung)
Ticket entwerten	Prüfen und gleichzeitig eine Nutzung registrieren
Mehrfachkarten	Unterstützung für 10er-Karten, Dauerkarten, Re-Entry
Echtzeit-Antwort	Sofortige Rückmeldung über Ticket-Status

ℹ️ Die API überträgt keine sensiblen Kundendaten wie Zahlungsinformationen oder E-Mail-Adressen – nur scan-relevante Daten.

Base URL

https://scan.tikflow.de

Schnellstart

REST API

1. API-Key erstellen

Öffnen Sie Ihr TikFlow Dashboard und navigieren Sie zu External API. Wählen Sie als Integrationstyp „Eigene Software / API" und erstellen Sie einen neuen API-Key.

⚠️ Der API-Key wird nur einmal angezeigt – speichern Sie ihn sicher ab!

2. Ersten Request senden

curl -X POST https://scan.tikflow.de/scan/validate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticketCode": "TK1.tkt_xxxxx.xxxxx"}'

3. Response verarbeiten

{
  "valid": true,
  "status": "validated",
  "message": "Ticket ist gültig",
  "ticketId": "tkt_abc123xyz",
  "ticketType": "multi",
  "usesAllowed": 10,
  "usesConsumed": 2,
  "usesRemaining": 8
}

TikFlow Hardware

1. API-Key erstellen

Wählen Sie im Dashboard als Integrationstyp „TikFlow Hardware". Nach dem Erstellen erhalten Sie die fertigen URLs für Ihr Gerät.

2. Gerät konfigurieren

Tragen Sie die angezeigte Card URL und Heart URL in die Konfiguration Ihres Zutrittskontrollgeräts ein.

3. Fertig

Ihr Gerät kommuniziert jetzt automatisch mit TikFlow. QR-Codes werden gescannt, validiert und bei Gültigkeit wird der Zutritt freigegeben.

➡️ Schritt-für-Schritt-Anleitung unter Hardware-Integration

Verfügbare Endpoints

REST API (Eigene Software)

Methode	Endpoint	Auth	Beschreibung
`POST`	`/scan/validate`	Header	Ticket prüfen ohne zu entwerten
`POST`	`/scan/consume`	Header	Ticket prüfen und entwerten

TikFlow Hardware

Methode	Endpoint	Auth	Beschreibung
`POST`	`/scan/hw/consume`	Query-Param	Ticket entwerten (Geräte-Format)
`POST`	`/scan/hw/validate`	Query-Param	Ticket validieren (Geräte-Format)
`POST`	`/scan/hw/heartbeat`	Query-Param	Heartbeat / Verbindungstest

➡️ Details unter Endpoints

Rate Limits

Limit	Wert
Anfragen pro Sekunde	50
Burst-Kapazität	100
Anfragen pro Monat	500.000 pro API-Key

Bei Überschreitung erhalten Sie HTTP Status 429 Too Many Requests.

Nächste Schritte

Authentifizierung – API-Keys erstellen und verwalten
Endpoints – Detaillierte Endpoint-Dokumentation
Hardware-Integration – Geräte konfigurieren und anbinden
Fehlerbehandlung – Status-Codes und Troubleshooting

Einstellungen Authentifizierung