Tento implementační manuál je praktickým průvodcem pro vývojáře a integrátory, kteří napojují své systémy (například ERP, WMS nebo e-shopové platformy) na Balíkobot API. Balíkobot pomáhá automatizovat expedici, snižuje chybovost a zajišťuje přímé datové napojení na vybrané dopravce. Manuál přináší přehled klíčových metod, business logiky, sekvence volání a doporučení pro práci s dopravci.

Veškerá komunikace probíhá přes resource orientované URL adresy protokolem HTTPS a standardní Basic Access Authentication. Odezva (timeout) všech metod je 30 sekund. Detailní technická specifikace, včetně přesných JSON payloadů a datových typů, je vedena v technické dokumentaci. Tento manuál se zaměřuje na integrační postup a business logiku.

Integrace začíná testovacím API klíčem a loginem. V testovacím prostředí se chování liší podle dopravce a podle stavu jeho implementace u konkrétního zákazníka. Balíkobot nastavuje přihlašovací údaje na pozadí. Pokud má dopravce zákazníkovi vystavené testovací údaje a zákazník už vyplnil konfiguraci dopravce, komunikace skutečně směřuje do API dopravce v testovacím režimu pod údaji zákazníka. Některé odpovědi jsou simulované, ve většině případů ale odpověď reálně prochází testovacím prostředím dopravce. Po dokončení testování se klíče vymění za produkční, které už zakládají reálné zásilky.

Tisk etiket z API je podporovaný u všech dopravců. Klíčové informace k práci s etiketami:

• Formáty: Balíkobot podporuje tři základní formáty: PDF A4 (pozicovatelné, obvykle 4 etikety na stránku, na výšku nebo na šířku podle dopravce), PDF pro termotiskárny (jednotlivé etikety, například tiskárny Zebra) a formát ZPL.

• Rozměry: Standardní termoetikety mají obvykle 100x125 mm nebo 100x148 mm. Konkrétní velikosti a orientace se u jednotlivých dopravců liší (například Mail Order a InTime používají 1/8 A4).

• Konfigurace: Formát etiket se pro produkční klíče nastavuje přímo v klientské zóně Balíkobotu. U testovacích API klíčů formát nastavuje tým Balíkobotu, je proto potřeba kontaktovat podporu (balikobot@balikobot.cz).

• Neměnnost: Vygenerovanou etiketu už nelze upravit. Pokud je potřeba změnit data, zásilku je nutné smazat (DROP) a založit znovu (ADD). Velikost i obsah etiket navíc schvalují dopravci, vlastní vizuální úpravy proto nejsou možné.

Životní cyklus zásilky v Balíkobotu obvykle sleduje tuto sekvenci volání API:

1. Příprava (nepovinná): Před založením zásilky si můžete načíst dostupné služby, výdejní místa nebo si ověřit data pomocnými metodami SERVICES, BRANCHES nebo CHECK.

2. Založení: Metodou ADD založíte zásilku. API validuje data a okamžitě vrací sledovací číslo a odkaz na přepravní etiketu.

3. Úprava (nepovinná): Pokud vznikla chyba, lze zásilku smazat metodou DROP, dokud nejsou data uzavřená.

4. Uzavření: Metodou ORDER uzavřete dávku pro daného dopravce. Tím se zbývající data odešlou dopravci a nastartuje se sledování. Po volání ORDER už zásilku nelze smazat.

5. Sledování: Po uzavření lze cestu zásilky sledovat metodami TRACK nebo TRACKSTATUS.

Pro úspěšnou integraci Balíkobotu jsou některé metody striktně vyžadované, jiné přinášejí rozšířenou funkcionalitu.

Open

Níže je souhrnný textový přehled klíčových endpointů a jejich business účelu.

• ADD: Zakládá konkrétní zásilky u daného dopravce. Každá zásilka vyžaduje unikátní eid (identifikátor e-shopu). U vícekusových zásilek se jednotlivé kusy seskupují atributem order_number. Metoda vrací URL etikety, URL pro sledování, ID u dopravce a interní package ID.

• DROP: Maže zásilku. Je to možné pouze před voláním metody ORDER, tedy dokud nejsou data odeslána dopravci. Zásilky se mažou podle package_id.

• ORDER: Uzavírá dávku/svoz pro daného dopravce, odesílá zbývající data a nastartuje sledování. Po jejím zavolání už zásilky nelze mazat. Pozor, neznamená to nutně objednání fyzického svozu kurýrem, to se dělá metodou ORDERPICKUP.

• TRACK / TRACKSTATUS: Vrací historii sledování, respektive poslední známý stav zásilky. Funguje pouze u zásilek uzavřených metodou ORDER. Pro integrace na API v2 doporučujeme TRACKSTATUS.

• CHECK: Validuje data zásilky, aniž by ji reálně založil.

• SERVICES: Vrací seznam všech podporovaných služeb daného dopravce.

• BRANCHES / FULLBRANCHES: Vrací seznam dostupných výdejních míst nebo dep u služeb, které je podporují.

• MANIPULATIONUNITS: Vrací dostupné manipulační jednotky (například palety) u paletových dopravců.

• ADDATTRIBUTES: Dynamicky vrací seznam dostupných vstupních atributů metody ADD pro konkrétního dopravce, včetně datových typů a délkových limitů.

• WHOAMI: Vrací základní informace o API klíčích, jménu odesílatele na etiketách a aktivních dopravcích.

• LABELS: Vrací hromadné PDF s etiketami pro vybraná package ID.

Pro stabilní a spolehlivou integraci doporučujeme držet se těchto technických a provozních pravidel:

• Denní aktualizace číselníků: Data z metod BRANCHES a SERVICES je potřeba obnovovat minimálně jednou denně. Zastaralý seznam výdejních míst nebo kódů služeb může vést k chybám API nebo k nedoručení zásilky.

• Sledování změn API: Pokud dopravce změní požadavky na napojení (například přidá nový povinný atribut), je potřeba změnu implementovat i ve vašem systému. Programově se dají změny hlídat metodou CHANGELOG, případně sledováním dokumentace.

• Přidání a odebrání služeb: Když dopravce zavede novou službu nebo zruší starou, projeví se to v metodě SERVICES. Váš systém by měl tyto změny zvládat dynamicky.

Pro zrychlení implementace je k dispozici několik open source knihoven. Upozorňujeme, že tyto knihovny spravují externí implementátoři a komunita, nikoliv přímo Balíkobot:

• PHP: inspirum/balikobot-php

• .NET: msigut/BalikoBotSharp (knihovna pro .NET Standard 2.0 v C#)

• Java: nuty456/BalikobotApi

• Ruby: kuba108/balikobot_api

• Magento 2: beecomprg/magento2-balikobot (open source modul od Beecomu)