¶ Referenční příručka API
¶ Způsob komunikace
Time Slot Control poskytuje programové rozhraní (API) pro integraci s externími systémy - ERP, WMS, BI nástroje a kamerové systémy. Veškerá komunikace probíhá výhradně přes HTTPS.
Programové rozhraní aplikace Time Slot Control nabízí dva rozdílné způsoby komunikace a využití:
- OData v4
- Vlastní REST koncové body (endpoints)
¶ OData v4
-
Primární rozhraní pro integraci s ERP systémy. Umožňuje čtení i zápis dat - práci s entitami Company, Order a OrderRow. Specifikaci OData podporují nativně lídři trhu - Microsoft, SAP, CA Technologies, Citrix Systems, IBM, Red Hat a další.
-
Více informací: https://www.odata.org/
¶ Vlastní REST koncové body
Specifické rozhraní pro tři účely:
- LPR - automatické čtení registračních značek z kamer (příjezd / odjezd vozidla do areálu)
- Workflow - programová změna stavu rezervace (dopravce přijel, zahájení zpracování, ukončení zpracování, odjezd...)
- Rezervace - programové vytvoření rezervace přímo z externího systému
¶ Vytvoření rezervace
Endpoint: POST /v3/{tenant}/Reservations
Tělo požadavku je přímý JSON objekt (bez wrapperu). Minimální povinná pole:
| Pole | Typ | Popis |
|---|---|---|
ResourceId |
Guid |
ID nakládací rampy / zdroje |
Start |
DateTimeOffset |
Datum a čas zahájení (ISO 8601 UTC, např. 2026-04-15T08:00:00Z) |
UnitId |
Guid |
ID obalové jednotky |
NumberOfUnits |
int |
Počet obalových jednotek |
Příklad volání (cURL s Basic auth):
curl -X POST "https://api.tscsandbox.com/v3/{tenant}/Reservations" \
-H "Content-Type: application/json" \
-u "api@vasedomena.com:heslo" \
-d "{\"ResourceId\": \"<resource-guid>\", \"Start\": \"2026-04-15T08:00:00Z\", \"UnitId\": \"<unit-guid>\", \"NumberOfUnits\": 10}"
¶ Prostředí aplikace Time Slot Control
Aplikace Time Slot Control nabízí dvě prostředí - pro webovou aplikaci i pro API:
- Produkční - https://api.timeslotcontrol.com
- Vývojové (sandbox) - https://api.tscsandbox.com
Sandbox prostředí je jednorázovou kopií produkce. Má deaktivované e-mailové a SMS notifikace - nedochází k matení uživatelů. Je ideální pro vývoj a testování integrace bez dopadu na produkci.
Sandbox není průběžně synchronizován s produkcí - jde o kopii vytvořenou v čase jeho zakládání.
¶ Autentizace
¶ Podporované metody
- Basic authentication - uživatelské jméno a heslo přenášené v každém volání
- JWT Bearer Token - token vygenerovaný jednorázově, použitý v hlavičce dalších volání
Obě metody vyžadují dedikovaný API uživatelský účet s rolí „API přístup".
¶ Vytvoření API účtu
- Přejděte do sekce Administrace
- Zvolte Nový uživatel
- Zadejte uživatelské jméno nového API účtu (příklad:
api@vasedomena.com) - Jméno a příjmení zvolte libovolně (např. „API")
- Vyberte svoji vlastní společnost
- Odeberte příznak „Automaticky vygenerovat heslo" a nastavte vlastní heslo
- Odeberte příznak „Odeslat uvítací email"
- V sekci Uživatelské role vyberte roli „API přístup"
- Odeberte příznak „Emailové notifikace"
- Nového uživatele uložte
¶ Vygenerování JWT tokenu
Pro komunikaci s API je nutné nejprve získat Bearer Token (JWT) voláním:
POST https://api.timeslotcontrol.com/v1/{tenant}/Token
Kde {tenant} je název zákazníka v URL adrese Time Slot Control - například pro https://lotraco.timeslotcontrol.com je tenant lotraco.
Příklad volání (cURL):
curl -X POST "https://api.tscsandbox.com/v1/{tenant}/Token" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"username\": \"api@vasedomena.com\", \"password\": \"heslo\"}"
JSON odpověď:
{ "token": "eyJhbGciOi..." }
Získaný token použijte v hlavičce každého dalšího volání:
curl -X GET "https://api.tscsandbox.com/v1/{tenant}/Ping" \
-H "Authorization: Bearer eyJhbGciOi..."
Není nutné generovat nový token pro každé volání - token zůstává platný po omezenou dobu.
Vygenerování tokenu a autentizace v API Reference:
Otevřete API Reference na adrese https://api.tscsandbox.com/ a klikněte v levém menu na Token. Endpoint POST /v1/{tenant}/Token zobrazí formulář pro zadání přihlašovacích údajů.
Získaný token vložte do pravého panelu Authentication → Bearer: header → Value:
Následně je možné volat jakékoliv API endpointy přímo z rozhraní.
¶ OData integrace
¶ Integrace Time Slot Control s ERP
Pro integraci se systémem třetí strany jsou klíčové tři entity dostupné pro CRUD operace přes OData:
- Company - číselník společností
- Order - objednávka přepravy
- OrderRow - řádky objednávky přepravy
Uživatelé ze zásobníku zakázek vkládají objednávky do košíku a vytvářejí rezervaci - nemusí nic ručně přepisovat, data se automaticky předvyplní.
¶ Speciální funkce *ByIntegrationId
Funkce se sufixem ByIntegrationId (např. PutCompanyByIntegrationId) umožňují aktualizaci záznamu přímo pomocí ERP identifikátoru - ERP nemusí nejprve zjišťovat primární klíč záznamu v TSC.
¶ Podporované OData operátory
Podporované: $select, $orderby, $top, $skip, $count, $filter
Nepodporované: $expand
¶ HTTP metody
GET- získání datPOST- vytvoření záznamuPUT- aktualizace celého záznamuPATCH- aktualizace vybraných vlastností (nikoliv celého objektu)DELETE- smazání záznamu
Detailní popis práce s daty: https://www.odata.org/getting-started/basic-tutorial/
¶ Doporučený postup integrace
- Vytvořit obalové jednotky v aplikaci Time Slot Control dle ERP a přiřadit jim ERP identifikátor (nutný pro správné párování jednotek v řádcích objednávky)
- Synchronizovat číselník společností - entita
Company, nezapomenout vyplnit poleIntegrationId(PK v ERP) - Integrovat entitu
Order- většina metadat je nepovinná, doporučená pole viz níže - Integrovat entitu
OrderRow
¶ Doporučená metadata
Detailní specifikace entit je dostupná v OData metadatech na adrese:
https://api.timeslotcontrol.com/odata/v1/{tenant}/$metadata
¶ Entita Order
Id(Edm.Guid) - PK v TSC, při vytváření nevyplňovatIntegrationId(Edm.String) - PK v ERPOrderDate(Edm.DateTimeOffset) - datum objednávky v ERPDeliveryDate(Edm.DateTimeOffset) - plánované datum doručeníOrderNumber(Edm.String) - číslo objednávkyOrderType(TSC.API.ODATA.OrderType) - nákupní / prodejníPaymentTerms(Edm.String) - platební podmínkyPurchaseOfficer(Edm.String) - jméno uživatele, který objednávku vytvořil v ERPTermsOfDelivery(Edm.String) - IncotermsSupplier/Recipient/Customer/Carrier(objekt) - při vyplnění*Idnebo*IntegrationIdnení nutné vyplňovat ostatní metadata, pokud společnost existuje v číselníku TSC
Pole pro společnosti (Supplier, Recipient, Customer, Carrier):
Id(Edm.Guid) - PK v TSC, při vytváření nevyplňovatIntegrationId(Edm.String) - PK v ERPName(Edm.String) - název společnostiStreet(Edm.String) - uliceCity(Edm.String) - městoPostalCode(Edm.String) - PSČCountry(Edm.String) - státIdentificationNumber(Edm.String) - IČVAT(Edm.String) - DIČ
¶ Entita OrderRow
Description(Edm.String) - popis řádkuIntegrationId(Edm.String) - ID v ERPNumberOfUnits(Edm.Int32) - počet obalových jednotekOrderId(Edm.Guid) - ID objednávky (TSC PK)OrderIntegrationId(Edm.String) - ID objednávky (ERP PK), alternativa kOrderIdUnitId(Edm.Guid) - ID obalové jednotky (TSC PK)UnitIntegrationId(Edm.String) - ID obalové jednotky (ERP PK), alternativa kUnitIdOrder(Edm.Int32) - pořadí řádků v objednávce
¶ API Reference (Scalar UI)
Time Slot Control poskytuje interaktivní API dokumentaci postavenou na Scalar - moderním rozhraní pro procházení a testování API endpointů přímo v prohlížeči bez nutnosti programování.
URL: https://api.tscsandbox.com/
Rozhraní obsahuje 205 endpointů ve 44 sekcích (Token, Reservation, Order, Company, Driver, Visitor a další). V levém panelu je navigace, uprostřed detail endpointu včetně příkladu volání, vpravo panel pro autentizaci a ukázky kódu.
Postup:
- Otevřete
https://api.tscsandbox.com/ve webovém prohlížeči - V levém menu procházejte dostupné entity a endpointy
- Přihlaste se vyplněním tokenu v pravém panelu Authentication → Bearer: header → Value (nebo přihlašovacích údajů v sekci Basic: basic)
- Klikněte na endpoint, vyplňte parametry a otestujte volání - rozhraní vygeneruje i odpovídající cURL příkaz
Příklad OData volání (entita Reservation):
¶ Ukázky
¶ Připojení Microsoft Excel přes OData
- Spusťte aplikaci Microsoft Excel
- Přepněte na záložku Data
- Z menu vyberte Načíst data > Z jiných zdrojů > Z kanálu OData
- Do pole „Adresa URL" zadejte:
https://api.timeslotcontrol.com/odata/v1/[názevtenantu]
- Přepněte ověření uživatele na „Základní"
- Vyplňte uživatelské jméno a heslo API účtu a klikněte „Připojit"
- Zobrazí se seznam dostupných entit Time Slot Control:
- Z jedné nebo více entit načtěte data do tabulek nebo generujte kontingenční tabulky a grafy
- Po uložení sešitu lze data kdykoliv aktualizovat přes Aktualizovat vše (záložka Data)
Microsoft Excel podporuje pouze čtení dat - lze se připojit přímo na produkční prostředí bez nutnosti testovat na sandboxu.
¶ Připojení Power BI přes OData
Postup je analogický jako u Microsoft Excel. Power BI umožňuje vytvářet interaktivní sestavy a dashboardy nad daty z Time Slot Control v reálném čase.