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. Pro použití přepravce balíkobotu je třeba na stránce přepravci přiřadit v poli Implementace Přepravce hodnotu Balíkobot.

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 novém poli Balíkobotí 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 Balíkobotí Přepravce nazváno Zásilkovna
  • PPL - v poli Balíkobotí Přepravce nazváno PPL
  • Geis Cargo - v poli Balíkobotí Přepravce nazváno Geis Cargo
  • Česká pošta - v poli Balíkobotí Přepravce nazváno Česká pošta
  • Slovenská pošta - v poli Balíkobotí Přepravce nazváno Slovenská pošta
  • DPD - v poli Balíkobotí Přepravce nazváno DPD
  • DHL Express - v poli Balíkobotí Přepravce nazváno DHL Express
  • DHL Parcel - v poli Balíkobotí Přepravce nazváno DHL Parcel
  • DHL Freight Euroconnect - v poli Balíkobotí Přepravce nazváno DHL Freight Euroconnect
  • Gebrüder Weiss - v poli Balíkobotí Přepravce nazváno Gebrüder Weiss

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.

Prodejní Objednávky #

Při vydání objednávky s Balíkobotím přepravcem probíhá kontrola dat potřebných pro daného přepravce. V případě, že kontrola neprojde, skončí vydání chybou.

Většina přepravců vyžaduje jméno, email, telefonní číslo, a adresu.

V případě, že přepravce používá pobočky (viz níže) je nutné vyplnit ID příjemce přepravce, které představuje pobočku pro vyzvednutí zásilky.

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.

Doplňkové služby přepravců #

Něktěří přepravci, jako například Česká pošta, vyžadují nebo poskytují doplňkové služby. Tyto služby se konfigurují v novém stejnojmenném poli na stránce Nastavení přepravce. Doplňkové služby jsou dostupné pouze pro některé služby přepravce, a tím pádem je možné je nastavit pouze pro určité služby.

Doplňkové služby se dále nikam nepropisují, jsou přímo svázané s danou službou přepravce a při odeslání dat přepravní jednotky pro danou službu jsou odeslány pro onu službu nastavené doplňkové služby.

Nastavení přepravců #

Obecně lze v nastavení přepravců balíkobotu nastavit Kontrolovat před vydáním. Pokud je nastaveno, při vydání objednávky s přepravcem z tohoto nastavení, se vytvoří dočasná přepravní jednotka, která se zašle do balíkobotu pro kontrolu. Pokud balíkobot vyhodnotí tuto přepravní jednotku jako chybovou, systém vypíše danou chybu. Tato funkcionalita slouží k odchycení potencionálních chyb přepravních jednotek ještě před jejich samotným vytvořením, aby nedocházelo ke komplikacím při zabalení a odesílaní.

Někteří přepravci, jako například DHL Freight Euroconnect, vyžadují nebo poskytují další nastavení na kartě Nastavení přepravců v sekci balíkobot. U DHL Freight Euroconnect jsou to například Obchodní podmínky.

V zásilkách se nastavují hodnoty s daného nastavení, při prvním založení nastavení jsou přednastaveny výchozí hodnoty u polí jako jsou Obchodní podmínky apod.

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.

Zároveň je možné nastavit úlohu, která bude pravidelně pobočky stahovat. Jedná se o sestavu 80058 "ART AA Branch Download". Na sestavě lze nafiltrovat nastavení přepravce a kód země oblasti.

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 #

Někteří přepravci vyžadují další nastavení na přepravních jednotkách, například DHL Express vyžaduje vyplnit hodnotu Popis obsahu zásilky.

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.

Podpora vícekusových zásilek u přepravců :

  • Zásilkovna - všechny služby, nelze vytvářet/zasílat vícekusové zásilky s dobírkou !
  • PPL - všechny služby
  • Geis - všechny služby
  • Česká pošta - všechny služby kromě:
    • VL (Doporučené psaní)
    • RR (Doporučená zásilka)
    • BB (Cenný balík)
  • Slovenská pošta - pouze služby:
    • EXA (Expres Kurýr na adresu)
    • EXP (Expres Kurýr na poštu)
  • DPD - všechny služby
  • DHL Express - všechny služby
  • DHL Parcel - nelze vytvářet/zasílat vícekusové zásilky
  • DHL Freight Euroconnect - všechny služby
  • Gebrüder Weiss - všechny služby

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

Disclaimer #

Jakékoliv úpravy a implementace tohoto rozšíření u nových zákazníků MUSÍ být před předáním otestovány s údaji od zákazníka. Autoři rozšíření nezodpovídají za chyby nebo problémy způsobené nedostatečným testováním u nových zákazníků.

Popis rozšíření pro vývojáře #

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

Testovací údaje pro balíkobot API VÝLUČNĚ PRO ÚČELY TESTOVÁNÍ jdou dostupné v uložených heslech artexu, a měly by být zpřístupněné veškeré služby a requesty.

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 balíkobotí interface, přičemž balíkobot obsahuje jednu společnou implementaci Shipping Agent Provider z AE056. V implementaci každého přepravce lze mimo jiné 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.

Upozornění #

Před úpravami tohoto rozšíření je nutné brát v potaz aktuální stav a limitace našich čteček a logiky, jakou čtečky pracují s vícekusovými zásilkami. Důležité je to zejména proto, že zdánlivě jednoduchá úprava určitých funkcí může vyžadovat rozsáhlé úpravy ve čtečkách.

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í.
  • CHECK - Kontrola dat přepravní jednotky, struktura identická k tělu requestu ADD. Kontrola momentálně probíhá před vydáním objednávky s Balíkobotím přepravcem. Při vydání dojde k vygenerování temporary přepravní jednotky, ze které se přeparsují data do těla CHECK requestu a odešlou. V případě, že kontrola neprojde, vydání skončí chybou, a vypíše se daná chyba.
  • 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. Ostatní requesty vyhazují chybu rovnou při zavolání a nelogují se nikam.