Balíkobot AE140

Balíkobot #

Toto rozšíření umožňuje v prostředí dynamics 365 business central používat služby programu Balíkobot. Balíkobot umožňuje odesílání dat přepravcům v rámci unifikované komunikace a zjednoduššuje tak celkový proces zasílání dat přepravních jednotek.

Modul obsahuje obecnou funckionalitu pro práci s jakýmkoliv přepravcem v rámci API komunikace Balíkobotu, aktuálně však podporuje pouze vybrané přepravce, viz níže. Každý přepravce podporovaný tímto rozšířením má založenou vlastní implementaci modulu přepravních jendotek AE056, kterou lze při vytvoření přepravce na stránce Přepravci přiřadit v poli Implementace Přepravce, více informací o přepravních jednotkách se dozvíte v modulu AE056.

Aktuálně podporovaní přepravci: #

  • Zásilkovna - v poli Implementace Přepravce nazváno Balíkobot - Zásilkovna
  • PPL - v poli Implementace Přepravce nazváno Balíkobot - PPL
  • Geis - v poli Implementace Přepravce nazváno Balíkobot - Geis

Z uživatelského hlediska se proces vytvoření přepravních jednotek a jejich funkcionalita nemění, je však nutné mít správně nastavené přepravce.

Nastavení #

Před používáním Balíkobotu je potřeba si sjednat s Balíkobotem smlouvu a vyjednat si údaje k jejich API, bez kterých tento modul nefunguje.

Služby přepravců #

Při prvním založení přepravce je nejprve nutné si založit prázdné nastavení přepravce, a zde vyplnit pouze údaje k API. Poté je možné v seznamu přeravců přes akci Stáhnout Služby stáhnout a založit služby zvoleného přepravce. Před stažením si musí uživatel zvolit zemi, pro kterou chce stáhnout dané služby, a po stažení je zobrazeno okno, kde si uživatel vybere, jaké konkrétní služby chce založit.

Tato akce stáhne pouze služby, je poté nutné manuálně založit nastavení přepravce pro každou službu a vyplnit potřebná pole k fungování přepravních jednotek (lokace, číslování, nastavení uzávěrek). Prázdné nastavení je poté možné smazat. Všechna nastavení přepravce musí obsahovat údaje k API Balíkobotu, jinak nebude daná služba fungovat.

Pobočky přepravců #

Pobočky přepravců jsou například Z-BOXy, PPL parcelshopy nebo jiná místa, kam umožňuje daná služba přepravce zasílat balíky, pokud se nejedná o zaslání přímo na adresu.

Je-li správně nastavené a založené nastavení pro službu přepravce, je možné přes akci Stáhnout trasy přepravců stáhnout pobočky pro danou službu, pokud to služba podporuje. Před stažením si musí uživatel zvolit země, pro které chce stáhnout dané pobočky.

Poznámka - V rámci Balíkobotích přepravců je možné mít pouze jednu verzi tras přepravce, neboť pobočky se při každém stažení promažou. Předejde se tak nežádoucím chybám nebo duplikacím v datech.

Používání poboček #

Pobočky je nutné plnit v prodejních objednávkách a v přepravních jednotkách pro služby, které to vyžadují. Zda-li služna vyžaduje pobočky je nutné manuálně nastavit přímo v dané službě, v poli Pobočka povinná.

Zadá-li se do prodejní objednávky přepravce, který implementuje služby Balíkobotu, zobrazí se u pole ID příjemce přepravce možnost rozkliknout dané pole, a ručně vybrat pobočku. Toto pole je u služeb, které pobočku vyžadují, povinné. Pokud tedy objednávka obsahuje službu, která vyžaduje pobočky, nelze takovou objednávku vydat, pokud má toto pole prázdné. Hodnota pole se dále dědí do pole ID příjemce přepravce v přepravních jednotkách, kde jí lze případně upravit.

Přepravní jednotky #

Balíkobot vytváří štítky po obrdžení dat. Při zabalení balíku dojde k pokusu o odeslání dat přepravní jednotky do API Balíkobotu. Pokud je odeslání úspěšné, stáhnou a uloží se potřebná data (do nových polí Balíkobot ID, Externí Číslo Jednotky, ZPL Definice štítku, vše viditelné na kartě). V případě vícekusových zásilek se zabalí/rozbalí všechny související přepravní jednotky a budou odeslána data všech takovýchto přepravních jednotek najednou.

Tisk štítku lze provést pouze v případě, že pro přepravní jednotku existuje zpracovatelná ZPL definice.

Připravit zásilku k odeslání lze pouze v případě, že má vyplněné pole Balíkobot ID. V případě vícekusových zásilek jsou k odeslání automaticky připraveny všechny související přepravní jednotky.

Při odeslání dat přepravci si každá zásilka uloží:

  • Balíkobot ID Zásilky - ID pro identifikaci svozu dané přepravní jednotky nebo jednotek v API Balíkobotu a daného přepravce
  • Balíkobot URL Svozu - Odkaz na svoz dané přepravní jednotky nebo jednotek

Na kartě uzávěrky lze v sekci Otevřené přepravní jednotky vedle akce Položky protokolu odeslaných dat přes tři tečky rozkliknout sekci Balíkobot, kde jsou k vidění akce:

  • Upravit definici - Touto akcí lze zobrazit, upravit nebo smazat ZPL definici štítku.

Stejné akce lze také nalézt a použít na kartě přepravní jednotky, v sekci Akce / Balíkobot.

Nová pole a hodnoty se přenášejí do zapsaných přepravních jednotek a i v zapsaných přepravních jednotkách je možné si zobrazit ZPL. ZPL v zapsaných přepravních jednotkách nelze upravovat.

V případě vícekusových zásilek se kopírují položky protokolu odeslaných dat do všech souvisejících zásilek.

Vícekusové zásilky #

V případě vícekusových zásilek se proces nemění, nicméně při zabalení přepravní jednotky a tedy při odesílání dat do API Balíkobotu, probíhají další kontroly. Tyto kontroly ověřují, že v rámci dané vícekusové zásilky již byly vytvořeny všechny potřebné balíky, a že všechny tyto balíky je možné odeslat. Výsledek se loguje do všech balíku v rámci dané vícekusové zásilky, a ve všech takových balících je možné zpracovat odpověď balíkobotu ručne pro případ, že by zpracování spadlo chybou.

Technická dokumentace (pro vývojáře) #

Modul využívá Balíkobot API v2, dokumentace k API je dostupná zde.

Veškerá logika je obsažena v objeku codeunit 80216 "ART AA Balikobot Management". Jedná se o knihovnu funkcí, které umožňují plynulé volání API pro jakéhokoliv podporovaného přepravce a metodu. Objekt obsahuje funkce rozdělené do sekcí pro lepší čitelnost.

Každý aktuálně podporovaný přepravce má vlastní implementaci na interface Shipping Agent Provider z AE056. V implementaci každého přepravce lze zároveň nalézt funkci na vytvoření těla ADD requestu.

V rámci celé extensiony je naprogramováno dynamické zobrazování Balíkobotích polí a akcí, zda-li se tato pole zobrazí je ovlivněno funkcí IsBalikobotProvider() z již zmíněné knihovny BalikobotManagement.

Aktuálně podporované API metody + popis: #

  • ADD - Zaslání dat přepravní jednotky do Balíkobotu a následné stažení potřebých ID, odkazů a definice štítku pro tisk. Umožňuje vytisknout štítek ihned při stažení.
  • DROP - Odstranění dat přepravní jednotky z Balíkobotu
  • ORDER - Odeslání dat přepravní jednotky z Balíkobotu danému přepravci. Vyžaduje aby byla data již v pořádku zaslána přes metodu ADD.
  • SERVICES - Stažení služeb přepravce, pokud je přepravce podporuje.
  • BRANCHES - Stažení poboček přepravce (do stránky Trasy Přepravce) pro danou službu přepravce, pokud je daná služba podporuje.
  • MANIPULATIONUNITS - Stažení typů přepravních jednotek pro danou službu přepravce, pokud je daná služba podporuje.

Requesty ADD, DROP a ORDER lze volat a logovat do přepraní jednotky nebo do uzávěrky. Requesty SERVICES, BRANCHES a MANIPULATIONUNITS vyhazují chybu rovnou při zavolání a nelogují se nikam.