Zurück zu Neuigkeiten

TSC über OData und API mit ERP, WMS oder Werkschutz verbinden

Pavel NOVOTNÝ
Blog
TSC über OData und API mit ERP, WMS oder Werkschutz verbinden

Die Anbindung eines Reservierungssystems an ein ERP, WMS oder eine Anwendung des Werkschutzes muss nicht als großes Integrationsprojekt beginnen. Für einen praktischen Ablauf an der Einfahrt genügen vier API-Aufrufe: Bearer-Token abrufen, Reservierung anhand ihrer Nummer finden, Ankunft erfassen und später die Abfahrt erfassen.

Das Personal am Tor muss die interne Reservierungskennung in Time Slot Control nicht kennen. Es arbeitet mit einer Angabe, die der Fahrer bereits auf der Bestätigung oder im QR-Code hat: ReservationNumber. TSC liefert über OData den passenden Datensatz und dessen Kennung Id; dieselbe Kennung Id wird anschließend für die Statusaktionen verwendet.

OData und API: zwei Teile einer Schnittstelle

Time Slot Control verbindet den Standard OData v4 mit klassischen API-Endpunkten. Die Aufgaben sind klar verteilt:

  • der Authentifizierungsendpunkt stellt einen JWT-Bearer-Token aus,
  • OData filtert die Daten und lädt nur die benötigten Felder,
  • gebundene OData-Aktionen führen einen konkreten Prozessschritt aus, zum Beispiel GateArrival oder GateDeparture.

Der Token wird also nicht über eine „OData-Abfrage“ abgerufen. Der Authentifizierungsendpunkt derselben TSC-API stellt ihn aus; danach wird er im Header jeder OData-Anfrage gesendet. Über OData stehen ERP- und WMS-Systemen außerdem Unternehmen, Aufträge und Auftragspositionen zur Verfügung. Mit IntegrationId lassen sich TSC-Kennungen den Schlüsseln des Quellsystems zuordnen.

Fünf Schritte zur Anbindung des Werkschutzes an Time Slot Control: Reservierungsnummer, Bearer-Token, OData-Abfrage, Ankunft und Abfahrt

Praxisbeispiel: Der Werkschutz erfasst Einfahrt und Ausfahrt

Der Fahrer kommt am Tor an und legt die Reservierungsnummer vor. Das Personal scannt sie oder gibt sie in die vorhandene Anwendung ein. Die Anwendung prüft die Reservierung in TSC, kann Kennzeichen, Frachtführer und geplante Zeit abgleichen und erfasst nach Freigabe der Einfahrt, dass sich der Frachtführer auf dem Gelände befindet. Bei der Ausfahrt verwendet sie dieselbe Kennung Id und kennzeichnet, dass der Frachtführer das Gelände verlassen hat.

Die folgenden Beispiele verwenden die Sandbox unter https://api.tscsandbox.com. Ersetzen Sie den Platzhalter {tenant} durch den Namen Ihrer Umgebung. Die Produktions-API besitzt unter https://api.timeslotcontrol.com dieselbe Struktur.

Vorbereitung

Legen Sie in TSC ein eigenes API-Konto für die Integration an. Das Konto benötigt die Rolle für den API-Zugriff und ausschließlich die tatsächlich verwendeten Berechtigungen—insbesondere zum Lesen von Reservierungen sowie zum Ausführen der Ankunfts- und Abfahrtsaktionen. Speichern Sie das Passwort nicht im Quellcode, sondern in einem Secrets-Manager oder in der geschützten Konfiguration Ihrer Integrationsplattform.

1. Bearer-Token abrufen

curl -X POST "https://api.tscsandbox.com/v1/{tenant}/Token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "api-gatehouse@example.com",
    "Password": "<secret-from-vault>"
  }'

Die Antwort enthält den Token:

{
  "token": "eyJhbGciOi..."
}

Verwenden Sie diesen Wert in den weiteren Aufrufen als Authorization: Bearer <token>. Für jedes Fahrzeug ist kein eigener Token erforderlich. Die Integration kann ihn sicher im Speicher halten und nach Ablauf oder nach einer Antwort 401 Unauthorized erneuern.

2. Reservierung anhand der ReservationNumber laden

Ein OData-Filter sucht die Reservierung anhand ihrer Nummer. Mit $select lädt der Werkschutz nur die benötigten Felder:

curl --get "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation" \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "\$filter=ReservationNumber eq 'R-2026-00421'" \
  --data-urlencode "\$select=Id,ReservationNumber,VehicleNumberPlate,Carrier,Start,End,RealGateVehicleArrival,RealGateVehicleDeparture" \
  --data-urlencode "\$top=2"

Eine typische Antwort enthält einen OData-Umschlag und das Array value:

{
  "@odata.context": "https://api.tscsandbox.com/odata/v1/{tenant}/$metadata#Reservation(...)" ,
  "value": [
    {
      "Id": "37efcb13-f1cb-4a61-baea-adfb4337036f",
      "ReservationNumber": "R-2026-00421",
      "VehicleNumberPlate": "1AB2345",
      "Carrier": "Example Carrier",
      "Start": "2026-09-01T12:30:00Z",
      "End": "2026-09-01T13:30:00Z",
      "RealGateVehicleArrival": null,
      "RealGateVehicleDeparture": null
    }
  ]
}

Fahren Sie im Produktivbetrieb nur fort, wenn die Abfrage genau einen Datensatz zurückgibt und dieser den betrieblichen Regeln entspricht. Kein Treffer muss manuell geprüft werden. Liefert die Abfrage mehrere Datensätze, darf die Integration nicht automatisch den ersten Eintrag auswählen. Mit $top=2 lässt sich dieser Fall mit geringem Aufwand erkennen.

3. Frachtführer als auf dem Gelände markieren

Verwenden Sie nach der Prüfung der Reservierung die zurückgegebene Kennung Id in der gebundenen Aktion GateArrival:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateArrival" \
  -H "Authorization: Bearer ${TOKEN}"

Bei Erfolg antwortet der Server mit 204 No Content. TSC speichert die tatsächliche Ankunftszeit, und die Änderung ist sofort an der Reservierung sichtbar. Nachgelagerte Workflows, Benachrichtigungen und Integrationen können anschließend der üblichen Konfiguration der Kundenumgebung folgen.

4. Frachtführer bei der Ausfahrt als abgefahren markieren

Bei der Ausfahrt verwendet die Anwendung dieselbe Kennung Id. Der Wert null weist TSC an, die aktuelle Serverzeit zu verwenden:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateDeparture" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "GateDepartureDateTime": null }'

Verfügt das Integrationsgerät über einen eigenen verlässlichen Ereigniszeitpunkt, kann es statt null einen UTC-Wert im ISO-8601-Format senden, zum Beispiel 2026-09-01T14:32:00Z. Bei Erfolg lautet die Antwort erneut 204 No Content.

Vollständiges Minimalbeispiel in PowerShell

Der gleiche Ablauf lässt sich in einem kurzen Skript abbilden. Ankunft und Abfahrt werden in der Praxis zu unterschiedlichen Zeitpunkten aufgerufen, verwenden aber dieselbe Reservierungskennung Id:

$baseUri = 'https://api.tscsandbox.com'
$tenant = '<tenant>'
$reservationNumber = 'R-2026-00421'

$tokenResponse = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUri/v1/$tenant/Token" `
  -ContentType 'application/json' `
  -Body (@{
    Username = 'api-gatehouse@example.com'
    Password = '<secret-from-vault>'
  } | ConvertTo-Json)

$headers = @{
  Authorization = "Bearer $($tokenResponse.token)"
}

$safeNumber = $reservationNumber.Replace("'", "''")
$filter = [Uri]::EscapeDataString("ReservationNumber eq '$safeNumber'")
$select = 'Id,ReservationNumber,VehicleNumberPlate,Carrier,RealGateVehicleArrival,RealGateVehicleDeparture'
$queryUri = "$baseUri/odata/v1/$tenant/Reservation?`$filter=$filter&`$select=$select&`$top=2"
$result = Invoke-RestMethod -Method Get -Uri $queryUri -Headers $headers
$reservations = @($result.value)

if ($reservations.Count -ne 1) {
  throw "Expected exactly one reservation, returned: $($reservations.Count)."
}

$reservationId = $reservations[0].Id

# When entry is permitted
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateArrival" `
  -Headers $headers

# Later, at the exit
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateDeparture" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body (@{ GateDepartureDateTime = $null } | ConvertTo-Json)

Das Beispiel enthält absichtlich kein echtes Passwort, keinen konkreten Tenant und keine Kundendaten. Eine Produktivanwendung benötigt zusätzlich eine sichere Ablage der Geheimnisse, Timeouts, kontrollierte Wiederholungen, die Protokollierung einer Korrelations-ID sowie die Behandlung von 401, 403, 404, 429 und weiteren Fehlerantworten.

Warum dieses Muster auch für ERP und WMS geeignet ist

Der Werkschutz ist ein anschauliches Beispiel, weil das Ergebnis sofort sichtbar ist. Das gleiche Prinzip funktioniert auch innerhalb eines ERP- oder WMS-Systems:

  • das ERP kann Unternehmen, Aufträge und Auftragspositionen über OData synchronisieren,
  • das WMS kann die aktuelle Reservierung laden und eine Rampe oder Lageroperation vorbereiten,
  • der Werkschutz kann Ankunft und Abfahrt erfassen, ohne in eine andere Anwendung zu wechseln,
  • BI-Werkzeuge können Plan- und Istzeiten auslesen, um Wartezeiten und den Durchsatz auf dem Gelände auszuwerten,
  • ausgehende Webhooks können Folgesysteme ohne regelmäßiges Polling über Änderungen informieren.

Die Integration muss daher nicht das vollständige Datenmodell kopieren. Jedes System lädt nur die Daten, die es für seinen Prozessschritt benötigt; TSC bleibt die maßgebliche Datenquelle für die Reservierung und ihre logistischen Meilensteine.

Vom Prototyp zum sicheren Produktivbetrieb

Testen Sie die erste Variante in der Sandbox. In der interaktiven API-Dokumentation unter api.tscsandbox.com können Sie Endpunkte durchsuchen, einen Bearer-Token eingeben und sofort Aufrufbeispiele abrufen. Das genaue Anmeldeverfahren beschreibt die Authentifizierungsreferenz; die OData-Anleitung erläutert die Filtermöglichkeiten.

Für den Produktivbetrieb empfehlen wir: ein eigenes Konto je Integration, nur die mindestens erforderlichen Berechtigungen, das Passwort in einem sicheren Speicher, die Wiederverwendung eines gültigen Tokens, die Prüfung auf genau ein Ergebnis und eine eindeutige Behandlung aller Fehlerzustände. Gestalten Sie Ankunfts- und Abfahrtsaufrufe sicher wiederholbar—nach Erfolg speichert die Integration die Kennung Id; bei unklarem Ergebnis lädt sie zunächst den aktuellen Reservierungsstatus erneut.

Eine Reservierungsnummer, ein aktueller Status im gesamten Prozess

Der größte Nutzen liegt nicht in den vier HTTP-Anfragen selbst. Entscheidend ist, dass Werkschutz, Lager, Disposition und ERP mit derselben Reservierung und denselben Zeitstempeln arbeiten. Manuelle Übertragung, telefonische Rückfragen und verzögerte Statusaktualisierungen entfallen.

Weitere Möglichkeiten finden Sie auf der Seite Time Slot Control API & Integrationen. Um einen ähnlichen Ablauf für Ihr ERP, WMS, Ihren Scanner oder Werkschutz zu testen, beginnen Sie mit einem konkreten Prozess in der Sandbox. Für die erste funktionierende Verbindung genügen häufig wenige, präzise definierte API-Aufrufe.

Zurück zu Neuigkeiten