Napojení rezervačního systému na ERP, WMS nebo aplikaci závodové ochrany nemusí začínat velkým integračním projektem. Pro praktický scénář u vjezdu stačí čtyři API volání: získat Bearer token, vyhledat rezervaci podle jejího čísla, zapsat příjezd a později zapsat odjezd.

Obsluha přitom nemusí znát interní identifikátor rezervace v Time Slot Control. Pracuje s údajem, který už má řidič na potvrzení nebo v QR kódu: ReservationNumber. TSC pomocí OData vrátí odpovídající záznam a jeho Id; stejné Id se potom použije pro stavové akce.

OData a API: dvě části jednoho rozhraní

Time Slot Control kombinuje standard OData v4 s běžnými API endpointy. Rozdělení je jednoduché:

autentizační endpoint vydá JWT Bearer token,
OData umožní filtrovat a načítat pouze potřebná data,
vázané OData akce provedou konkrétní procesní krok, například GateArrival nebo GateDeparture.

Token se tedy nezískává „OData dotazem“. Vydává jej autentizační endpoint stejného TSC API a následně se posílá v hlavičce všech OData požadavků. Pro ERP a WMS jsou přes OData dostupné také společnosti, objednávky a položky objednávek; díky IntegrationId lze propojit identifikátory TSC s klíči zdrojového systému.

Pět kroků napojení závodové ochrany na Time Slot Control: číslo rezervace, Bearer token, OData dotaz, příjezd a odjezd

Praktický scénář: závodová ochrana zapíše vjezd a odjezd

Řidič přijede k vrátnici a předloží číslo rezervace. Obsluha je načte skenerem nebo zadá do existující aplikace. Aplikace ověří rezervaci v TSC, může porovnat SPZ, dopravce a plánovaný čas a po povolení vjezdu zapíše, že je dopravce v areálu. Při výjezdu použije stejné Id a označí, že dopravce areál opustil.

Následující příklady používají sandbox https://api.tscsandbox.com. Zástupný text {tenant} nahraďte názvem svého prostředí. Produkční API má stejnou strukturu na https://api.timeslotcontrol.com.

Než začnete

V TSC vytvořte vyhrazený API účet. Účet potřebuje roli pro API přístup a jen ta oprávnění, která integrační scénář skutečně využije — zejména čtení rezervací a akce pro označení příjezdu a odjezdu. Heslo neukládejte přímo do zdrojového kódu; použijte správce tajemství nebo zabezpečenou konfiguraci integrační platformy.

1. Získejte 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>"
  }'

Odpověď obsahuje token:

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

Hodnotu použijte v dalších voláních jako Authorization: Bearer <token>. Token není nutné vytvářet pro každé vozidlo. Integrace jej může bezpečně držet v paměti a obnovit po vypršení platnosti nebo po odpovědi 401 Unauthorized.

2. Načtěte rezervaci podle ReservationNumber

OData filtr vyhledá rezervaci podle čísla. Pomocí $select si závodová ochrana stáhne jen pole, která potřebuje:

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á odpověď má 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 produkčním řešení pokračujte pouze tehdy, když dotaz vrátí právě jeden záznam a ten odpovídá pravidlům provozu. Nulový výsledek patří do ručního ověření. Stejně tak integrace nemá automaticky vybírat první položku, pokud by dotaz vrátil více záznamů. Hodnota $top=2 umožní takovou situaci levně rozpoznat.

3. Označte, že je dopravce v areálu

Po ověření rezervace použijte vrácené Id ve vázané akci GateArrival:

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

Úspěšná odpověď je 204 No Content. TSC uloží skutečný čas příjezdu a změna se okamžitě projeví u rezervace. Navazující workflow, notifikace nebo integrace se potom mohou řídit běžnou konfigurací zákaznického prostředí.

4. Při odjezdu označte, že dopravce areál opustil

Při výjezdu použije aplikace stejné Id. Hodnota null říká TSC, aby použilo aktuální čas serveru:

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

Pokud má integrační zařízení vlastní důvěryhodný čas události, lze místo null poslat UTC hodnotu ve formátu ISO 8601, například 2026-09-01T14:32:00Z. Úspěch opět vrací 204 No Content.

Celý minimální příklad v PowerShellu

Stejný postup lze zapsat do krátkého skriptu. Volání příjezdu a odjezdu jsou v praxi spuštěna v různých okamžicích, ale používají stejné Id rezervace:

$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ázka záměrně neobsahuje konkrétní heslo, tenant ani zákaznická data. Produkční aplikace navíc doplní bezpečné uložení tajemství, timeouty, řízené opakování požadavků, logování korelačního identifikátoru a obsluhu stavů 401, 403, 404, 429 a dalších chybových odpovědí.

Proč je tento vzor praktický i pro ERP a WMS

Závodová ochrana je názorný příklad, protože výsledek je okamžitě viditelný. Stejný princip ale funguje i uvnitř ERP nebo WMS:

ERP může přes OData synchronizovat společnosti, objednávky a položky objednávek,
WMS může načíst aktuální rezervaci a připravit rampu nebo skladovou operaci,
vrátnice může zapsat příjezd a odjezd bez přepínání do další aplikace,
BI nástroje mohou číst plánované i skutečné časy pro vyhodnocení čekání a průchodnosti areálu,
outbound webhooky mohou navazující systémy informovat o změnách bez pravidelného pollingu.

Integrace tak nemusí kopírovat celý datový model. Každý systém si načte pouze údaje, které pro svůj krok potřebuje, a TSC zůstává zdrojem pravdy pro rezervaci a její logistické milníky.

Od prototypu k bezpečnému provozu

První variantu ověřte v sandboxu. Interaktivní API dokumentace na api.tscsandbox.com umožní endpointy procházet, zadat Bearer token a rovnou získat ukázky volání. Přesný popis přihlášení najdete v referenční příručce autentizace a možnosti filtrování v příručce OData.

Pro produkční nasazení doporučujeme držet se několika pravidel: jeden vyhrazený účet pro konkrétní integraci, nejmenší potřebná oprávnění, heslo v bezpečném úložišti, opětovné použití platného tokenu, kontrola právě jednoho výsledku a jednoznačné zacházení s chybovými stavy. Volání příjezdu a odjezdu lze bezpečně navrhnout jako opakovatelné — po úspěchu si integrace uloží Id a při nejistém výsledku nejdříve znovu načte aktuální stav rezervace.

Jedno číslo rezervace, aktuální stav v celém procesu

Největší přínos není v samotných čtyřech HTTP požadavcích. Je v tom, že závodová ochrana, sklad, dispečink i ERP pracují se stejnou rezervací a stejnými časy. Odpadá ruční přepisování, telefonické ověřování a zpožděná aktualizace stavů.

Více možností najdete na stránce API & Integrace Time Slot Control. Chcete-li podobný scénář ověřit pro své ERP, WMS, skener nebo vrátnici, začněte jedním konkrétním procesem v sandboxu. Často se ukáže, že první funkční propojení je otázkou několika přesně definovaných API volání.