Egy foglalási rendszer ERP-, WMS- vagy portaszolgálati alkalmazással való összekapcsolása nem feltétlenül igényel nagy integrációs projektet. Egy gyakorlati beléptetési folyamathoz mindössze négy API-hívás szükséges: Bearer token igénylése, a foglalás kikeresése a száma alapján, az érkezés rögzítése, majd később a távozás rögzítése.

A portaszolgálat munkatársának nem kell ismernie a foglalás belső Time Slot Control-azonosítóját. Azt az adatot használja, amely már a sofőr birtokában van a visszaigazoláson vagy a QR-kódban: ReservationNumber. A TSC OData-n keresztül visszaadja a megfelelő rekordot és annak Id azonosítóját; a státuszműveletekhez később ugyanez a Id azonosító használható.

OData és API: ugyanazon felület két része

A Time Slot Control az OData v4 szabványt hagyományos API-végpontokkal ötvözi. A feladatok megosztása egyszerű:

a hitelesítési végpont JWT Bearer tokent ad ki,
az OData lehetővé teszi a szűrést és csak a szükséges adatok lekérését,
a kötött OData-műveletek egy konkrét folyamatlépést hajtanak végre, például a GateArrival vagy a GateDeparture műveletet.

A token tehát nem „OData-lekérdezéssel” szerezhető meg. Ugyanannak a TSC API-nak a hitelesítési végpontja adja ki, majd minden OData-kérés fejlécében továbbítani kell. Az ERP és WMS rendszerek OData-n keresztül a vállalatokat, megrendeléseket és rendelési sorokat is elérhetik; a IntegrationId segítségével a TSC azonosítói összekapcsolhatók a forrásrendszer kulcsaival.

A portaszolgálat és a Time Slot Control összekapcsolásának öt lépése: foglalási szám, Bearer token, OData-lekérdezés, érkezés és távozás

Gyakorlati példa: a portaszolgálat rögzíti a be- és kilépést

A sofőr megérkezik a portaszolgálathoz, és bemutatja a foglalási számot. A munkatárs szkennerrel beolvassa, vagy beírja a meglévő alkalmazásba. Az alkalmazás ellenőrzi a foglalást a TSC-ben, összevetheti a rendszámot, a fuvarozót és a tervezett időpontot, majd a belépés engedélyezése után rögzíti, hogy a fuvarozó a telephelyen tartózkodik. Kilépéskor ugyanazt a Id azonosítót használja, és jelzi, hogy a fuvarozó elhagyta a telephelyet.

Az alábbi példák a https://api.tscsandbox.com címen elérhető sandbox környezetet használják. A {tenant} helyőrzőt cserélje le a saját környezete nevére. A produkciós API ugyanilyen felépítésben érhető el a https://api.timeslotcontrol.com címen.

Előkészületek

Hozzon létre a TSC-ben egy dedikált API-fiókot. A fióknak API-hozzáférési szerepkörre és kizárólag az integráció által ténylegesen használt jogosultságokra van szüksége—különösen a foglalások olvasására, valamint az érkezési és távozási műveletek végrehajtására. A jelszót ne tárolja a forráskódban; használjon titokkezelőt vagy az integrációs platform védett konfigurációját.

1. Bearer token igénylése

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>"
  }'

A válasz tartalmazza a tokent:

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

A további hívásokban ezt az értéket használja Authorization: Bearer <token> formában. Nem kell minden járműhöz külön tokent létrehozni. Az integráció biztonságosan tárolhatja a memóriában, és megújíthatja a lejárata után vagy 401 Unauthorized válasz esetén.

2. Foglalás lekérése ReservationNumber alapján

Egy OData-szűrő a száma alapján keresi meg a foglalást. A $select használatával a portaszolgálati alkalmazás csak a szükséges mezőket tölti le:

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"

Egy tipikus válasz OData-burkolót és egy value tömböt tartalmaz:

{
  "@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
    }
  ]
}

Produkcióban csak akkor folytassa a folyamatot, ha a lekérdezés pontosan egy, az üzemeltetési szabályoknak megfelelő rekordot ad vissza. Találat hiányában manuális ellenőrzés szükséges. Ha több rekord érkezik, az integráció nem választhatja ki automatikusan az elsőt. A $top=2 használatával ez az eset kis erőforrásigénnyel felismerhető.

3. A fuvarozó telephelyen tartózkodásának rögzítése

A foglalás ellenőrzése után a visszakapott Id azonosítót használja a kötött GateArrival műveletben:

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

A sikeres hívás válasza 204 No Content. A TSC elmenti a tényleges érkezési időt, és a változás azonnal megjelenik a foglalásnál. A további munkafolyamatok, értesítések és integrációk ezután az ügyfélkörnyezet szokásos beállításai szerint működhetnek.

4. A fuvarozó távozásának rögzítése

Kilépéskor az alkalmazás ugyanazt a Id azonosítót használja. A null érték arra utasítja a TSC-t, hogy a szerver aktuális idejét használja:

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 }'

Ha az integrációs eszköz saját, megbízható eseményidővel rendelkezik, a null helyett ISO 8601 formátumú UTC-értéket is küldhet, például 2026-09-01T14:32:00Z. A sikeres hívás válasza ismét 204 No Content.

Teljes minimális példa PowerShellben

Ugyanez a folyamat rövid szkriptben is megvalósítható. Az érkezési és távozási hívások a gyakorlatban különböző időpontokban futnak, de ugyanazt a foglalási Id azonosítót használják:

$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)

A példa szándékosan nem tartalmaz valódi jelszót, konkrét tenantet vagy ügyféladatokat. A produkciós alkalmazásnak emellett gondoskodnia kell a titkok biztonságos tárolásáról, az időkorlátokról, a szabályozott újrapróbálásról, a korrelációs azonosító naplózásáról, valamint a 401, 403, 404, 429 és más hibaválaszok kezeléséről.

Miért működik ugyanez a minta ERP és WMS esetén is?

A portaszolgálat szemléletes példa, mert az eredmény azonnal látható. Ugyanez az elv azonban az ERP-ben vagy a WMS-ben is alkalmazható:

az ERP OData-n keresztül szinkronizálhatja a vállalatokat, megrendeléseket és rendelési sorokat,
a WMS lekérheti az aktuális foglalást, és előkészítheti a rakodóhelyet vagy a raktári műveletet,
a portaszolgálat másik alkalmazás megnyitása nélkül rögzítheti az érkezést és a távozást,
a BI-eszközök a tervezett és tényleges időpontokból elemezhetik a várakozást és a telephely áteresztőképességét,
a kimenő webhookok rendszeres lekérdezés nélkül tájékoztathatják a kapcsolódó rendszereket a változásokról.

Az integrációnak így nem kell lemásolnia a teljes adatmodellt. Minden rendszer csak a saját lépéséhez szükséges adatokat tölti le, miközben a TSC marad a foglalás és annak logisztikai mérföldkövei hiteles adatforrása.

A prototípustól a biztonságos üzemeltetésig

Az első változatot a sandboxban ellenőrizze. Az api.tscsandbox.com interaktív API-dokumentációjában böngészheti a végpontokat, megadhatja a Bearer tokent, és azonnal hívási példákat kaphat. A pontos bejelentkezési eljárást a hitelesítési útmutató, a szűrési lehetőségeket pedig az OData-útmutató ismerteti.

Produkcióban tartson be néhány szabályt: integrációnként egy dedikált fiók, csak a minimálisan szükséges jogosultságok, a jelszó biztonságos tárolása, az érvényes token újrafelhasználása, pontosan egy találat megkövetelése és minden hiba egyértelmű kezelése. Az érkezési és távozási hívásokat idempotens módon tervezze meg—siker után mentse el a Id azonosítót; bizonytalan eredmény esetén először kérje le újra a foglalás aktuális állapotát.

Egy foglalási szám, egy aktuális állapot a teljes folyamatban

A legnagyobb előny nem magában a négy HTTP-kérésben rejlik, hanem abban, hogy a portaszolgálat, a raktár, a diszpécserszolgálat és az ERP ugyanazzal a foglalással és ugyanazokkal az időbélyegekkel dolgozik. Elhagyható a kézi adatátírás, a telefonos ellenőrzés és a késleltetett állapotfrissítés.

További lehetőségeket a Time Slot Control API és integrációk oldalon talál. Ha hasonló folyamatot szeretne kipróbálni ERP-, WMS-, szkenner- vagy portaszolgálati alkalmazásában, kezdjen egy konkrét esettel a sandboxban. Az első működő kapcsolat gyakran mindössze néhány pontosan meghatározott API-hívást igényel.