¶ Základní informace
¶ Způsob komunikace
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 a výměnu dat. Za specifikací ODATA protokolu stojí lídři trhu s ERP (Microsoft, SAP, CA Technologies, Citrix Systems, IBM, Red Hat a další), je podporován téměř ve všech produktech těchto společností nativně.
¶ Reference
https://en.wikipedia.org/wiki/Open_Data_Protocol
https://www.odata.org/
¶ Vlastní REST koncové body
Specifické rozhraní pro kontrolu registračních značek z kamer podporující jejich čtení (LPR), změna stavu worfklow rezervace (dopravce přijel, zahájení zpracování, ukončení zpracování atd.)
¶ Prostředí aplikace Time Slot Control
Aplikace Time Slot Control nabízí dvě prostředí pro webovou aplikaci i pro API:
- Produkční
- Vývojové (sandbox)
¶ Produkční
https://api.timeslotcontrol.com
¶ Vývojové (sandbox)
Sand box prostředí není automaticky zakládáno v rámci produkčního prostředí. Do tohoto prostředí se v čase jeho vytváření kompletně zkopíruje prostředí produkční. Následně tato prostředí nejsou synchronizována. Prostředí má deaktivované emailové i SMS notifikace, aby nedocházelo k matení koncových uživatelů a je vhodné pro vývoj integrace nebo funkcí bez vlivu na produkci.
¶ Autentifikace
¶ Podporované metody autentifikace
- Basic authentication
- JWT token
Obě metody vyžadují vytvoření dedikovaného API uživatelského účtu a veškerá komunikace mezi klientem a API musí probíhat pouze na protokolu HTTPS.
¶ 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@[vaše_doména].com")
- Křestní jméno a příjmení můžete zvolit libovolně (příklad "API")
- Vyberte svoji vlastní společnost
- Odeberte příznak "Automaticky vygenerovat heslo" a zadejte svoje vlastní, které budete používat pro komunikaci s ODATA službou
- Odeberte příznak "Odeslat uvítací email"
- V sekci "Uživatelské role" vyberte uživatelskou 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) pomocí funkce: https://api.timeslotcontrol.com/v3/{tenant}/Token, kde {tenant} je název zákazníka uvedený URL adrese Time Slot Control, například: https://lotraco.timeslotcontrol.com (název domény 3. řádu).
Příklad volání z příkazové řádky s JSON požadavkem:
curl -X POST "https://api.tscsandbox.com/v3/{tenant}/Token" -H "accept:application/json" -H "Content-Type:application/json;odata.metadata=minimal;odata.streaming=true" -d "{ \"username\":\"user@customer.com\", \"password\": \"password\"}"
Pokud je jméno a heslo správné, služba vrátí token, který je možné používat v dalších dotazech (není nutné pro každý požadavek generovat nový token).
JSON odpověď:
{ "token": "...." }
Následně všechny další HTTP volání API provádět s přidanou hlavičkou "Authorization: Bearer [YourToken]".
curl -X GET "https://api.tscsandbox.com/v3/{tenant}/Ping" -H "accept: application/json" -H "Authorization: Bearer [YourToken]"
Získání tokenu je možné vyzkoušet i v UI:
Získaný token následně vložit přes akci "Authorize" do UI:
Do pole Bearer vložit složený text z "Bearer [získaný token]" (bez hranatých závorek).
Následně je již možné volat jakékoliv API i ze Swagger UI.
¶ ODATA
¶ Integrace Time Slot Control s ERP
V systému Time Slot Control je pro integraci vytvořen modul Zásobník zakázek, do kterého se replikují objednávky přeprav ze systému třetí strany. Objednávku přepravy na straně Time Slot Control reprezentují objekty Order a OrderRow, které definují klíčová metadata jako jsou dopravce, objednatel, příjemce, zákazník, číslo objednávky, dodací podmínky a mnoho dalších, včetně samotných řádků objednávky, tedy toho, co bude obsahem transportu. Dle těchto informací následně uživatel vytváří rezervaci v systému Time Slot Control, kdy z 1 až n objednávek zásobníku vytvoří jednu rezervaci a tu zaplánuje. Uživatelé tak nemusí nic ručně přepisovat, pouze vloží objednávku(y) do košíku a najdou vhodný čas pro vytvoření rezervace.
Pro integraci Time Slot Control se systémem třetí strany jsou klíčové tři entity, dostupné pro CRUD3 v OData:
- Company - číselník společností
- Order – objednávka přepravy
- OrderRow – řádky objednávky přepravy
Mimo standardní funkce GET/POST/PUT/DELETE jsou v rozhraní implementovány funkce nad rámec OData specifikace se sufixem ByIntegrationId, například PutCompanyByIntegrationId, které provádějí aktualizaci existujícího záznamu na základě identifikátoru protistrany, tedy ERP. ERP tak nemusí nejprve provádět $select dotaz do Time Slot Control pro zjištění primárního klíče (Id) v systému Time Slot Control a následné volání dané akce, ale může tuto akci provést přímo s vlastním PK.
Podporované OData funkce:
- $select
- $orderby
- $top
- $skip
- $count
- $filter
Nepodporované OData funkce:
- $expand
HTTP metody:
- POST - vytvoření
- PUT – aktualizace
- PATCH – aktualizace jen vybraných vlastností (nikoliv celého objektu)
- DELETE - smazání
- GET - získání dat
Jak s daty pracovat je detailně popsáno samotnou specifikací protokolu, včetně ukázek:
https://www.odata.org/getting-started/basic-tutorial/
K testování a ověření je rovněž dostupný Swagger, viz sekce „Playground“
¶ Doporučený postup integrace
- V aplikaci Time Slot Control vytvořit obalové jednotky dle ERP a přiřadit jim ERP identifikátor (společný identifikátor bude nutný pro vytváření řádků v objednávce a správné párování jednotek).
- První integraci provést nad entitou Company a synchronizovat číselník společností ERP s Time Slot Control, minimálně společnosti, pro které se budou vytvářet objednávky (nezapomenout vyplnit IntegrationId – PK v ERP).
- Integrace entity Order – většina metadat je v systému Time Slot Control nepovinná, doporučená metadata uvádíme níže
- Integrace entity OrderRow
¶ Doporučená metadata pro integraci
Detailní specifikace těchto i ostatních entit je dostupná OData metadatech na URL adrese:
https://api.timeslotcontrol.com/odata/v1/{tenant}/$metadata
¶ Doporučená metadata Order
- Id - typ "Edm.Guid" - PK v Time Slot Control - při vytváření nevyplňovat
- IntegrationId - typ "Edm.String" - PK v ERP
- OrderDate - typ "Edm.DateTimeOffset" - datum kdy byla provedena objednávka v ERP
- DeliveryDate - typ "Edm.DateTimeOffset" - plánované datum doručení
- OrderNumber - typ "Edm.String" - číslo objednávky
- OrderType - typ "TSC.API.ODATA.OrderType" - nákupní / prodejní
- PaymentTerms - typ "Edm.String" - platební podmínky
- PurchaseOfficer - typ "Edm.String" - jméno uživatele, který objednávku vytvořil v ERP
- Supplier / Recipient / Customer / Carrier – při vyplnění *Id nebo *IntegrationId, není nutné vyplňovat ostatní metadata pokud existuje daná společnost v číselníku společností Time Slot Control
- Id - typ "Edm.Guid" – PK v Time Slot Control při vytváření nevyplňovat
- IntegrationId - typ "Edm.String" – PK v ERP – nutné pro vazbu a zpětné dohledání záznamu z ERP
- Name - typ "Edm.String" – název společnosti
- Street - typ "Edm.String" – ulice
- City - typ "Edm.String" - město
- PostalCode - typ "Edm.String" - PSČ
- Country - typ "Edm.String" - stát
- IdentificationNumber - typ "Edm.String" - IČ
- VAT - typ "Edm.String" – DIČ
- TermsOfDelivery - typ "Edm.String" – incoterms
¶ Doporučená metadata OrderRow
Description - typ "Edm.String" – popis řádku
IntegrationId - typ "Edm.String" – ID ERP
NumberOfUnits - typ "Edm.Int32" – počet jednotek (obalových, dle UnitId)
OrderId - typ "Edm.Guid" – ID objednávky ke které řádek patří
OrderIntegrationId - typ "Edm.String" – ERP ID – je možné řádek svázat i pomocí identifikátoru objednávky dle ERP
UnitId - typ "Edm.Guid" – ID obalové jednotky
UnitIntegrationId - typ "Edm.String" – ERP ID obalové jednotky
Order - typ "Edm.Int32" – pořadí řádků v objednávce
¶ Playground
Pro vlastní REST rozhraní i ODATA, Time Slot Control API poskytuje Swagger UI, kde je možné si jednotlivé funkce vyzkoušet i bez programování, stačí vygenerovat JWT token nebo se přihlásit pomocí basic autentifikace dedikovaným API účtem, následně je možné jednotlivé funkce volat identicky jako z kódu a i tak získat případné CURL query.
Stačí ve webovém prohlížeči otevřít URL adresu: https://api.tscsandbox.com/
Vybrat OData nebo TSC REST definici:
Přihlásit se pomocí "Authorize"
Následně již můžete procházet a testovat jednotlivé funkce.
OData:
¶ Ukázky
¶ Připojení Microsoft Excel kanálem 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".
4. Do textového pole "Adresa" URL" zadejte: https://api.timeslotcontrol.com/odata/v1/[názevtenantu]
5. Přepněte ověření uživatele na "Základní".
6. Vyplňte uživatelské jméno a heslo vytvořeného API účtu a následně klikněte na "Připojit".
7. Následně se vám zobrazí seznam povolených entit systému Time Slot Control pro další zpracování.
8. Z vybrané jedné nebo více entit můžete načítat data do samostatných tabulek nebo z nich generovat kontingenční tabulky a graf.
9. Po vytvoření a uložení vzorového dokumentu můžete kdykoliv data aktualizovat dle skutečnosti v aplikaci Time Slot Control online, pomocí "Aktualizovat vše" na záložce "Data".
Aplikace Microsoft Excel podporuje pouze čtení dat, je možné se tak připojit rovnou k produkčnímu prostředí Time Slot Control bez nutnosti testování na sandbox prostředí.
Obdobně lze připojit i ostatní aplikace, například Power BI a vytvářet tak interaktivní sestavy.