¶ Referenční příručka API - OData
¶ 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í.
Tento převod "košík → rezervace" je v současnosti ruční krok v uživatelském rozhraní (přetažení z košíku objednávek na plán). Vytvoření záznamů
Order/OrderRowpřes OData automaticky nevytvoří odpovídající rezervaci - poleExistsInReservationzůstáváfalse, dokud k převodu nedojde. Pro vyvolání převodu programově zavolejtePOST /v3/{tenant}/Reservations/CreateFromOrdersna REST API v3 - podrobný formát požadavku najdete v Referenční příručce API.
Samotná entita
Reservationje přes OData také dostupná, ale pouze pro čtení a pro zápis poznámky / vlastních polí (přes bound akciPatch). Vytvoření rezervace nebo zápis polí jako dopravce, typ vozidla, řidič či registrační značky vyžaduje endpointy REST API v3 (POST/PUT /v3/{tenant}/Reservations) popsané v Referenční příručce API.
¶ 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.