Endpoints

Die External Scan API bietet Endpoints für zwei Integrationswege:

REST API (Eigene Software)

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

TikFlow Hardware

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

Base URL

https://scan.tikflow.de

REST API Endpoints

POST /scan/validate

Prüft ein Ticket auf Gültigkeit, ohne eine Nutzung zu registrieren. Ideal für Vorprüfungen oder Info-Terminals.

Request

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_abc123.xyz789"}'

Request Body

Parameter	Typ	Erforderlich	Beschreibung
`ticketCode`	string	✅ Ja	Der vollständige Ticket-Code (aus QR-Code)

Response – Ticket gültig

{
  "valid": true,
  "status": "validated",
  "message": "Ticket ist gültig",
  "ticketId": "tkt_abc123xyz",
  "ticketType": "multi",
  "usesAllowed": 10,
  "usesConsumed": 3,
  "usesRemaining": 7,
  "holder": {
    "firstName": "Max",
    "lastName": "Mustermann"
  },
  "validFrom": null,
  "validUntil": "2026-12-31T23:59:59.000Z"
}

Response – Ticket erschöpft

{
  "valid": false,
  "status": "exhausted",
  "message": "Ticket hat keine verbleibenden Nutzungen",
  "ticketId": "tkt_abc123xyz",
  "ticketType": "multi",
  "usesAllowed": 10,
  "usesConsumed": 10,
  "usesRemaining": 0
}

POST /scan/consume

Prüft ein Ticket und registriert gleichzeitig eine Nutzung (Entwertung). Verwenden Sie diesen Endpoint für den tatsächlichen Einlass.

Request

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

Request Body

Parameter	Typ	Erforderlich	Beschreibung
`ticketCode`	string	✅ Ja	Der vollständige Ticket-Code (aus QR-Code)

Response – Erfolgreich entwertet

{
  "valid": true,
  "status": "consumed",
  "message": "Ticket erfolgreich entwertet",
  "scannedAt": "2026-01-06T14:30:00.000Z",
  "ticketId": "tkt_abc123xyz",
  "ticketType": "multi",
  "usesAllowed": 10,
  "usesConsumed": 4,
  "usesRemaining": 6,
  "holder": {
    "firstName": "Max",
    "lastName": "Mustermann"
  },
  "validFrom": null,
  "validUntil": "2026-12-31T23:59:59.000Z"
}

💡 Hinweis: Das Feld scannedAt enthält den Zeitstempel der Entwertung und ist nur bei /scan/consume vorhanden.

Hardware Endpoints

Die Hardware-Endpoints sind für physische Zutrittskontrollgeräte konzipiert, die HTTP-Requests in einem eigenen Datenformat senden. TikFlow erkennt das Gerätemodell automatisch und verarbeitet die Anfrage entsprechend.

ℹ️ Die Konfiguration Ihres Geräts ist unter Hardware-Integration beschrieben.

POST /scan/hw/consume

Empfängt einen Scan-Request vom Hardware-Controller, extrahiert den Ticket-Code aus dem Geräte-Format, validiert und entwertet das Ticket. Die Antwort wird im Geräte-eigenen Format zurückgegeben.

Request (Beispiel: Cloud B4 Controller)

POST /scan/hw/consume?key=YOUR_API_KEY
Content-Type: application/json

{
  "Card": "VEsxLnRrdF9hYmMxMjMueHl6Nzg5",
  "Serial": "897132",
  "Reader": 0
}

Das Feld Card enthält den QR-Code-Inhalt Base64-kodiert. TikFlow dekodiert und verarbeitet ihn automatisch.

Response – Zutritt gewährt

{
  "ActIndex": "0",
  "AcsRes": "1",
  "Time": "1",
  "Name": "Max M.",
  "Note": "Ticket gültig (3/10)"
}

Response – Zutritt verweigert

{
  "ActIndex": "0",
  "AcsRes": "0",
  "Time": "0",
  "Note": "Ticket erschöpft"
}

Response-Felder (Cloud B4)

Feld	Beschreibung
`AcsRes`	`"1"` = Zutritt gewährt, `"0"` = verweigert
`ActIndex`	Relais-Ausgang (`"0"` = IN, `"1"` = OUT)
`Time`	Türöffnungsdauer in Sekunden
`Name`	Anzeige auf dem Gerätedisplay (max. 16 Bytes)
`Note`	Statusmeldung auf dem Display (max. 32 Bytes)

POST /scan/hw/validate

Identisch zu /scan/hw/consume, jedoch ohne Entwertung. Das Ticket wird nur geprüft, keine Nutzung wird registriert.

POST /scan/hw/heartbeat

Verbindungstest für Hardware-Geräte. Der Controller sendet regelmäßig Heartbeat-Requests, um die Verbindung zu prüfen.

Response

{
  "Key": "value_from_request"
}

Der Heartbeat bestätigt dem Gerät, dass der TikFlow-Server erreichbar ist.

Response-Felder (REST API)

Allgemeine Felder

Feld	Typ	Beschreibung
`valid`	boolean	`true` wenn Ticket gültig/entwertet, sonst `false`
`status`	string	Status-Code (siehe unten)
`message`	string	Lesbare Statusmeldung
`ticketId`	string	Eindeutige Ticket-ID
`ticketType`	string	`"single"` oder `"multi"`

Nutzungs-Felder

Feld	Typ	Beschreibung
`usesAllowed`	number	Maximale Anzahl Nutzungen
`usesConsumed`	number	Bereits verbrauchte Nutzungen
`usesRemaining`	number	Verbleibende Nutzungen

Optionale Felder

Feld	Typ	Beschreibung
`holder`	object	Inhaberdaten (falls personalisiert)
`holder.firstName`	string	Vorname des Inhabers
`holder.lastName`	string	Nachname des Inhabers
`validFrom`	string \| null	Gültig ab (ISO 8601)
`validUntil`	string \| null	Gültig bis (ISO 8601)
`scannedAt`	string	Zeitstempel der Entwertung (nur bei `/consume`)
`reason`	string	Ablehnungsgrund bei `status: "rejected"`

Status-Werte

Status	valid	Beschreibung
`validated`	`true`	Ticket ist gültig (nur bei `/validate`)
`consumed`	`true`	Ticket wurde erfolgreich entwertet
`exhausted`	`false`	Alle Nutzungen aufgebraucht
`rejected`	`false`	Ticket ungültig (siehe `reason`)
`not_found`	`false`	Ticket existiert nicht

Rejection Reasons

Bei status: "rejected" enthält das Feld reason den Ablehnungsgrund:

Reason	Beschreibung
`invalid_mac`	Ungültige Ticket-Signatur (manipuliert oder fehlerhaft)
`event_not_allowed`	API-Key hat keinen Zugriff auf dieses Event
`ticket_cancelled`	Ticket wurde storniert
`not_yet_valid`	Ticket ist noch nicht gültig (`validFrom` in der Zukunft)
`expired`	Ticket ist abgelaufen (`validUntil` überschritten)

Beispiel: Ungültige Signatur

{
  "valid": false,
  "status": "rejected",
  "reason": "invalid_mac",
  "message": "Ungültige Ticket-Signatur"
}

Ticket-Typen

Typ	`ticketType`	`usesAllowed`	Beschreibung
Einzelticket	`single`	1	Einmaliger Einlass
Mehrfachkarte	`multi`	2-100	z.B. 10er-Karte Schwimmbad
Dauerkarte	`multi`	9999	Unbegrenzte Nutzungen im Gültigkeitszeitraum

Typische Workflows

REST API: Einlass am Drehkreuz

1. Besucher scannt QR-Code
2. Ihre Software sendet POST /scan/consume mit x-api-key Header
3. Bei valid=true → Drehkreuz freigeben
4. Bei valid=false → Zugang verweigern, message anzeigen

REST API: Vorprüfung am Info-Terminal

1. Besucher scannt QR-Code zur Kontrolle
2. System sendet POST /scan/validate
3. Anzeige: Ticket-Status, verbleibende Nutzungen
4. Keine Entwertung → Besucher kann später am Einlass scannen

TikFlow Hardware: Automatischer Einlass

1. Besucher hält QR-Code vor den Scanner des Geräts
2. Controller sendet Scan-Daten automatisch an /scan/hw/consume
3. TikFlow validiert und entwertet das Ticket
4. Bei Erfolg: Gerät öffnet Drehkreuz/Tür automatisch
5. Bei Ablehnung: Gerät zeigt Fehlermeldung auf dem Display

Authentifizierung Hardware-Integration