Späť na novinky

Ako prepojiť TSC s ERP, WMS alebo vrátnicou cez OData a API

Pavel NOVOTNÝ
Blog
Ako prepojiť TSC s ERP, WMS alebo vrátnicou cez OData a API

Prepojenie rezervačného systému s ERP, WMS alebo aplikáciou vrátnice nemusí začínať ako veľký integračný projekt. Pre praktický scenár pri vjazde stačia štyri API volania: získať Bearer token, vyhľadať rezerváciu podľa jej čísla, zapísať príchod a neskôr odchod.

Pracovník vrátnice pritom nemusí poznať interný identifikátor rezervácie v Time Slot Control. Pracuje s údajom, ktorý už má vodič na potvrdení alebo v QR kóde: ReservationNumber. TSC cez OData vráti zodpovedajúci záznam a jeho identifikátor Id; rovnaký identifikátor Id sa potom použije pri stavových akciách.

OData a API: dve časti jedného rozhrania

Time Slot Control kombinuje štandard OData v4 s bežnými API endpointmi. Rozdelenie úloh je jednoduché:

  • autentizačný endpoint vydá JWT Bearer token,
  • OData umožní filtrovať a načítať iba potrebné údaje,
  • viazané OData akcie vykonajú konkrétny krok procesu, napríklad GateArrival alebo GateDeparture.

Token sa teda nezískava „OData dotazom“. Vydáva ho autentizačný endpoint toho istého TSC API a následne sa posiela v hlavičke každej OData požiadavky. Pre ERP a WMS sú cez OData dostupné aj spoločnosti, objednávky a položky objednávok; IntegrationId umožňuje prepojiť identifikátory TSC s kľúčmi zdrojového systému.

Päť krokov prepojenia vrátnice s Time Slot Control: číslo rezervácie, Bearer token, OData dotaz, príchod a odchod

Praktický scenár: vrátnica zapíše vjazd a výjazd

Vodič príde k vrátnici a predloží číslo rezervácie. Pracovník ho načíta skenerom alebo zadá do existujúcej aplikácie. Aplikácia overí rezerváciu v TSC, môže porovnať evidenčné číslo vozidla, dopravcu a plánovaný čas a po povolení vjazdu zapíše, že dopravca je v areáli. Pri výjazde použije rovnaký identifikátor Id a označí, že dopravca areál opustil.

Nasledujúce príklady používajú sandbox na adrese https://api.tscsandbox.com. Zástupný text {tenant} nahraďte názvom svojho prostredia. Produkčné API má rovnakú štruktúru na adrese https://api.timeslotcontrol.com.

Skôr než začnete

V TSC vytvorte vyhradený API účet. Účet potrebuje rolu pre prístup k API a iba oprávnenia, ktoré integrácia skutočne využíva—najmä čítanie rezervácií a vykonávanie akcií príchodu a odchodu. Heslo neukladajte priamo do zdrojového kódu; použite správcu tajomstiev alebo zabezpečenú konfiguráciu integračnej platformy.

1. Získajte Bearer token

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

Odpoveď obsahuje token:

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

V ďalších volaniach použite túto hodnotu ako Authorization: Bearer <token>. Pre každé vozidlo netreba vytvárať nový token. Integrácia ho môže bezpečne uchovávať v pamäti a obnoviť po skončení platnosti alebo po odpovedi 401 Unauthorized.

2. Načítajte rezerváciu podľa ReservationNumber

OData filter vyhľadá rezerváciu podľa jej čísla. Pomocou $select si aplikácia vrátnice načíta iba polia, ktoré potrebuje:

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"

Typická odpoveď obsahuje OData obálku a pole 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
    }
  ]
}

V produkcii pokračujte iba vtedy, keď dotaz vráti práve jeden záznam, ktorý zodpovedá prevádzkovým pravidlám. Ak sa nenájde žiadny záznam, prípad patrí na ručné overenie. Ak dotaz vráti viac záznamov, integrácia nesmie automaticky vybrať prvý. Použitie $top=2 umožní takúto situáciu rozpoznať s malými nákladmi.

3. Označte, že dopravca je v areáli

Po overení rezervácie použite vrátený identifikátor Id vo viazanej akcii GateArrival:

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

Úspešné volanie vráti 204 No Content. TSC uloží skutočný čas príchodu a zmena sa okamžite zobrazí pri rezervácii. Nadväzujúce workflow, oznámenia a integrácie sa potom môžu riadiť bežnou konfiguráciou zákazníckeho prostredia.

4. Pri odchode označte, že dopravca opustil areál

Pri výjazde aplikácia použije rovnaký identifikátor Id. Hodnota null určí, že TSC má použiť aktuálny čas servera:

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

Ak má integračné zariadenie vlastný dôveryhodný čas udalosti, môže namiesto null odoslať UTC hodnotu vo formáte ISO 8601, napríklad 2026-09-01T14:32:00Z. Úspešné volanie opäť vráti 204 No Content.

Celý minimálny príklad v PowerShelli

Rovnaký postup možno zapísať do krátkeho skriptu. Volania príchodu a odchodu sa v praxi spúšťajú v rôznych okamihoch, ale používajú rovnaký identifikátor rezervácie 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)

Ukážka zámerne neobsahuje skutočné heslo, konkrétneho tenanta ani zákaznícke údaje. Produkčná aplikácia musí navyše zabezpečiť bezpečné uloženie tajomstiev, časové limity, riadené opakovanie požiadaviek, zaznamenávanie korelačného identifikátora a spracovanie 401, 403, 404, 429 a ďalších chybových odpovedí.

Prečo je rovnaký vzor praktický aj pre ERP a WMS

Vrátnica je názorný príklad, pretože výsledok je viditeľný okamžite. Rovnaký princíp však funguje aj v ERP alebo WMS:

  • ERP môže cez OData synchronizovať spoločnosti, objednávky a položky objednávok,
  • WMS môže načítať aktuálnu rezerváciu a pripraviť rampu alebo skladovú operáciu,
  • vrátnica môže zapísať príchod a odchod bez prepínania do inej aplikácie,
  • BI nástroje môžu čítať plánované aj skutočné časy na vyhodnotenie čakania a priepustnosti areálu,
  • odchádzajúce webhooky môžu informovať nadväzujúce systémy o zmenách bez pravidelného dopytovania.

Integrácia teda nemusí kopírovať celý dátový model. Každý systém načíta iba údaje potrebné pre svoj krok a TSC zostáva dôveryhodným zdrojom údajov o rezervácii a jej logistických míľnikoch.

Od prototypu k bezpečnej prevádzke

Prvú verziu overte v sandboxe. Interaktívna API dokumentácia na api.tscsandbox.com umožňuje prechádzať endpointy, zadať Bearer token a okamžite získať príklady volaní. Presný postup prihlásenia opisuje referenčná príručka autentizácie a možnosti filtrovania vysvetľuje príručka OData.

V produkcii dodržujte niekoľko pravidiel: jeden vyhradený účet pre každú integráciu, iba minimálne potrebné oprávnenia, heslo v bezpečnom úložisku, opakované použitie platného tokenu, požiadavka na práve jeden výsledok a jednoznačné spracovanie každej chyby. Volania príchodu a odchodu navrhnite tak, aby sa dali bezpečne opakovať—po úspechu uložte identifikátor Id; pri neistom výsledku najskôr znova načítajte aktuálny stav rezervácie.

Jedno číslo rezervácie, jeden aktuálny stav v celom procese

Najväčší prínos nespočíva v samotných štyroch HTTP požiadavkách. Podstatné je, že vrátnica, sklad, dispečing a ERP pracujú s rovnakou rezerváciou a rovnakými časovými údajmi. Odpadá ručné prepisovanie, telefonické overovanie a oneskorená aktualizácia stavov.

Ďalšie možnosti nájdete na stránke API & Integrácie Time Slot Control. Ak chcete podobný scenár vyskúšať pre svoje ERP, WMS, skener alebo vrátnicu, začnite jedným konkrétnym procesom v sandboxe. Prvé funkčné prepojenie často vyžaduje iba niekoľko presne definovaných API volaní.

Späť na novinky