Dokumentace pluginu Toret Balíkobot

Nacházíte se na stránkách dokumentace pluginu WooCommerce Balíkobot, který propojuje e-shop a systém Balíkobot.cz.

Instalace pluginu

Po zakoupení pluginu obdržíte e-mailem licenční klíč a odkaz na stažení zip souboru s pluginem. Detailní návod, jak do WordPress nainstalovat plugin z počítače, najdete zde.

Aktivace pluginu

Po instalaci pluginu si otevřete plugin, do příslušného pole vložte licenční klíč a uložte.

Nastavení pluginu (videonávod)

Následující série videí vás provede nastavením a používáním pluginu Balíkobot krok za krokem. K dispozici je také nápověda přímo v nastavení pluginu Balíkobot (WooCommerce > Nastavení > Balíkobot).

Prvotní nastavení pluginu Balíkobot

Spárování doprav v e-shopu s pluginem

Princip nastavení údajů, editace v objednávce

Generování štítků pro dopravce po jednom

Hromadné generování štítků pro dopravce

Odeslání dat dopravcům

Sledování zásilek Balíkobot ve WooCommerce

Podpora jiných pluginů

Automatizace úkonů

Akce a filtry

Plugin WooCommerce Balíkobot přidává několik akcí a filtrů, pomocí kterých lze modifikovat jeho chování, a nebo je využít např. v šabloně.

Poznámka: V některých filtrech se parametrem předává objekt třídy WBAL_Order. Jedná se o jednoduchý objekt reprezentující jednu objednávku. Pro svoje účely budete pravděpodobně chtít spíš objekt třídy WC_Order, tedy standardní WooCommerce reprezentaci objednávky. Tu získáte snadno. Pokud $order je objekt třídy WBAL_Order reprezentující nějakou objednávku, pak WC_Order této objednávky získáte jako $order->wc_order.

Akce

• woocommerce_balikobot_loaded –Voláno těsně po inicializaci pluginu při každém načtení stránky.
  Definice: do_action( ‘woocommerce_balikobot_loaded’ );

• wbal_label_created – voláno při úspěšném vytvoření štítku.
  Definice: do_action(‘wbal_label_created’, array(‘carrier_ids’ => $m_cid, ‘order’ => $order));
  Jediný parametr obsahuje informace k tomuto štítku. Je to array s klíči
  ‘carrier_ids’ – pole dopravcových ID pro všechny štítky vzniklé operací vytvoření štítků (ve vícekusové zásilce jich může být několik).
  ‘order’ – objekt třídy WBAL_Order reprezentující objednávku, ke které byl právě štítek vygenerován.

Filtry

• wbal_add_operation_item – Voláno při žádosti o založení štítku, před odesláním dat na Balíkobot. Umožňuje změnit data posílaná Balíkobotu do operace ADD. Pokud jde o vícekusovou zásilku, volá se filtr pouze na data k první (té základní) položce.Definice: $item = apply_filters(‘wbal_add_operation_item’, $item, $wbal_order);$item jsou data pro Balíkobot – pole se stringovými klíči. Klíče odpovídají datovým položkám operace ADD popsané v dokumentaci Balíkobot API.
  $wbal_order je objekt třídy WBAL_Order, reprezentující objednávku, kterou na balíkobot posíláme.Filtr by měl vrátit případně upravená data $item.
• wbal_add_operation_all_items – Voláno při žádosti o založení štítku, těsně před odesláním dat na Balíkobot. Umožňuje změnit data posílaná Balíkobotu do operace ADD. Narozdíl od wbal_add_operation_item je tento filtr volán na kompletní data posílaná na Balíkobot – Je to tedy pole jedné, či (v případě vícekusové zásilky) několika sad dat stejného typu, jako je $item ve wbal_add_operation_item.Definice: $result = apply_filters(‘wbal_add_operation_all_items’, $result, $wbal_order);$result je pole dat pro ADD.
  $wbal_order je objekt třídy WBAL_Order, reprezentující objednávku, kterou na Balíkobot posíláme. Filtr by měl vrátit data $result, případně upravená.
• wbal_objednavka_prefill – Voláno hned poté, co zákazník založí novou objednávku. Náš plugin objednávce určí vlastnosti pro Balíkobot – dopravce, službu, pobočku a doplňující data – na základě nastavení. Následně volá tento filtr, kterým je možné vlastnosti změnit, předtím než budou uloženy k objednávce. Typickým použitím je např. dodání hmotnosti zásilky do doplňujících údajů na základě objednaného zboží. Definice: $defs = apply_filters(‘wbal_objednavka_prefill’, $defs, $order_id);
  $defs jsou hodnoty dopravce, služby a pobočky, které by objednávce přiřadil systém automatické předvyplňování (podle nastavení). Je to array s klíči ‘wbal_carrier’ (kód dopravce), ‘wbal_service’ (kód služby), ‘wbal_branch’ (id pobočky), ‘addit’ (pole doplňujících údajů)$order_id je ID objednávky. Filtr by měl vrátit $defs, případně upravené, aby se předvyplnilo něco jiného.
• wbal_tracking_url – filtr, který na základě id objednávky vrátí url stránky pro sledování doručenosti zásilky. Pomocí filtru lze toto url změnit, ale to obvykle nemá smysl dělat. Tento filtr obvykle budete spíš volat (apply_filters()) např. ze šablony e-mailu, abyste url získali. Definice: $url = apply_filters(‘wbal_tracking_url’, $order_id)$order_id je id objednávky, pro kterou se má trackovací url vrátit.

Doplňkové údaje

Kdykoli se generuje štítek (což take znamená založení objednávky na Balíkobotu), je potřeba Balíkobotu poslat sadu dat, které zásilku popisují. Základními daty jsou požadovaný dopravce, jeho služba, a případně pobočka. Náš plugin k nim automaticky dodává další standardně vyžadované údaje, jako např. doručovací adresu, cenu dobírky a podobně. Kromě toho ale e-shop může chtít využívat další dopravce nebo služby, které vyžadují další specifické datové položky (např. rozměry zásilky, hmotnost, celní informace atd.) K doplnění těchto datových položek slouží doplňkové údaje.

Doplňkové údaje jsou datově uložené jako meta záznam, který je pod klíčem “wbal_addit” připojený k objednávce. Hodnotou tohoto meta záznamu je asociativní pole. Pole obsahuje položky klíč:hodnota, přičemž je možné použít několik typů klíčů:

• _klíč (začíná na _, např. _autosizes) – jde o speciální klíče, které budou před posláním dat do balíkobotu vyhodnoceny v našem pluginu, a do dat pro balíkobot přidají jednu nebo několik dalších položek. Např. _autosizes (s hodnotu 1 nebo true ) způsobí automatické vložení datových položek width, length a height s rozměry dle velikostí položek zboží v zásilce.
• klíč#2 (normální text nezačínající na _, ale obsahuje na konci # a číslo) – klíče, které se přímo přenesou do dat pro balíkobot I se svou hodnotu, ale bez koncového # a čísla. Číslo udává do kolikátého kusu vícekusové zásilky se data mají přenést. Takže např. weight#2: 10 znamená předání datové položky „weight“ s hodnotou 10 do druhého kusu vícekusové zásilky. Tímto způsobem lze např. určit hmotnost každého jednotlivého kusu vícekusové zásilky.
• klíč#a (za # je „a“, a ne číslo) – klíče, které se zapíšou do všech kusů vícekusové zásilky. Např. weight#a: 10 znamená, že každý kus vícekusové zásilky bude mít udanou hmotnost 10.
• klíč (nezačíná na _ a neobsahuje #) – je totéž jako klíč#1 . Jedná se tedy o kratší a jednodušší zápis klíče, který se má vložit do prvního kusu vícekusové zásilky. Pokud neposíláte vícekusovou zásilky, můžete pro přehlednost a jednoduchost používat přímo tyto klíče.

Které datové položky chcete předávat do Balíkobotu (a tedy které klíče potřebujete mít v doplňkových údajích) si můžete zjistit v manuálu Balíkobotu, v popisu operace ADD pro vašeho dopravce.

Náš plugin automaticky vyplňuje tyto datové položky (takže tyto položky NENÍ TŘEBA zadávat do doplňujících údajů):

• service_type – podle vybrané služby
• branch_id – podle vybrané pobočky, pokud je nějaká
• order_number – automaticky od 1 podle kusů vícekusové zásilky
• cod_price – pro dobírku cena celé objednávky
• cod_currency – pro dobírku měna objednávky
• vs – VS dle čísla objednávky v eshopu
• rec_name – dle doručovací adresy
• rec_firm – dle doručovací adresy
• rec_email – dle doručovací adresy
• rec_phone – dle doručovací adresy
• rec_street – dle doručovací adresy
• rec_city – dle doručovací adresy
• rec_zip – dle doručovací adresy
• rec_country – dle doručovací adresy
• real_order_id – dle čísla objednávky v eshopu
• eid – automaticky generováno z kódu eshopu a čísla objednávky
• return_full_errors – vždy 1, aby se umožnilo hlášení chyb

Pokud chcete do Balíkobotu předat jakékoli další položky, už musíte použít doplňkové údaje.

Doplňkové údaje se v administraci (v detailu objednávky nebo nastavení Balíkobotu) editují pomocí klikacího nástroje a v JSON formátu. JSON formát je tam ale JEN pro potřebu ruční úpravy. V samotných meta objednávky žádný JSON není, je to přímo PHP asociativní pole.

Pokud chcete doplňkové údaje při vytvoření objuednávky nějak dogenerovat automaticky (a předvyplnění v Nastavení na to nestačí), použijte filtr wbal_objednavka_prefill.