Dokumentace pluginu Toret PPL

Nacházíte se na stránkách dokumentace WooCommerce pluginu Toret PPL verze 4.0.0 a novější.

⚠️ Používáte starší verzi pluginu? Dokumentaci k verzím nižším než 4.0.0 najdete na stránce Dokumentace Toret PPL pro verze do 3.13.9.

Pro použití pluginu PPL musíte mít vytvořený účet u společnosti PPL. Dále je potřeba u PPL zažádat o přístupy do CPL API. Do žádosti uveďte, že budete využívat řešení integrátora:

Toret plugins s.r.o.
IntegrID: 4257736.

Plugin PPL zakoupíte zde: Toret PPL pro WooCommerce

Minimální požadavky

• WordPress 7.1 nebo vyšší
• WooCommerce 11.0 nebo vyšší
• PHP 8.1 nebo vyšší
• MySQL 5.7 nebo vyšší
• Účet u PPL a vydané přístupové údaje do CPL API (Client ID a Client secret)

Instalace pluginu

Po zakoupení pluginu obdržíte e-mailem licenční klíč a odkaz na stažení ZIP souboru s pluginem. Plugin nainstalujete standardně:

1. V administraci WordPressu přejděte na Pluginy → Instalace pluginů → Nahrát plugin.
2. Vyberte stažený ZIP soubor a klikněte na Instalovat.
3. Po instalaci plugin aktivujte.

Alternativně můžete obsah ZIP souboru nahrát přes FTP do složky wp-content/plugins/ a plugin aktivovat v přehledu pluginů.

Aktualizace pluginu probíhají automaticky přímo z administrace WordPressu, pokud je licence aktivní. Plugin je přeložený do češtiny, slovenštiny a polštiny.

Aktivace licence

Nastavení pluginu otevřete v menu Toret plugins → PPL. Na první záložce Připojení k PPL vložte do pole Licenční klíč klíč, který jste obdrželi e-mailem nebo který najdete v Mém účtu na toret.cz, a klikněte na Uložit.

Licence se ověří na licenčním serveru a naváže se na adresu vašeho webu. Plugin ji pak kontroluje každých 12 hodin.

Dokud licence není aktivní, zobrazují se v nastavení jen záložky Připojení k PPL a Nápověda. Pokladna funguje dál (dopravní metody, výdejní místa, poplatky, e-maily), ale odesílání zásilek, štítky, svozy, fronta, PPL log i aktualizace pluginu jsou vypnuté.

Hlášení u pole licenčního klíče vám řekne, co je špatně:

• Licence je aktivní. – vše je v pořádku.
• Neplatný licenční klíč. – klíč neodpovídá, zkontrolujte ho v Můj účet na toret.cz.
• Licenční klíč je už použitý na jiném webu. – klíč je aktivovaný jinde. Pokud jej chcete přenést, je třeba jej resetovat ve vašem Toret účtu.
• Tento licenční klíč nepatří k žádné objednávce. – klíč není v systému, kontaktujte podporu.
• Licenční server neodpověděl. – dočasný výpadek spojení, uložte nastavení za chvíli znovu.

Napojení na PPL (CPL API)

Od verze 4 pracuje plugin výhradně s PPL CPL API. Přístupové údaje získáte od PPL v zákaznické administraci nebo od svého obchodního zástupce. Do žádosti uveďte, že využíváte řešení integrátora Toret plugins s.r.o., IntegrID: 4257736.

Na záložce Připojení k PPL vyplňte:

• Client ID – identifikátor vydaný PPL.
• Client secret – heslo k API. Uložený secret se z bezpečnostních důvodů nezobrazuje; pokud ho neměníte, nechte pole prázdné.
• Prostředí – Produkce pro ostrý provoz. Test (api-dev.dhl.com) a Sandbox (x-api-sandbox.dhl.com) jsou zkušební prostředí PPL; zásilky v nich se nevozí a vyžadují vlastní testovací přístupové údaje.

Po uložení klikněte na Ověřit připojení. Plugin se přihlásí k PPL, stáhne číselníky a vypíše:

• seznam produktů povolených pro váš účet – podle smlouvy s PPL,
• několik výdejních míst v okolí vaší adresy odesílatele, čímž ověříte, že fungují i číselníky.

V hlavičce nastavení je trvale štítek CPL API s názvem zvoleného prostředí. Zelený znamená, že jsou vyplněné přístupové údaje – že spojení opravdu funguje, ověříte tlačítkem Ověřit připojení.

Adresy odesílatele

Na záložce Adresy odesílatele vyplňte alespoň jednu adresu. Tiskne se na štítky jako odesílatel a řidič na ni jezdí pro svoz.

• Adres může být více, například pro více skladů. Další přidáte tlačítkem Přidat adresu, odeberete křížkem vpravo.
• Telefon uvádějte s mezinárodní předvolbou
• E-mail je povinný – PPL na něj posílá potvrzení svozu.
• Výchozí odesílatel určuje, která adresa se použije. Když není zvolen, použije se první v pořadí.

Pozor u metod Return Connect. Zásilky Return Connect Import a Return Connect Europe jdou ze zahraničí, PPL u nich vyžaduje odesílatele mimo Českou republiku. Přidejte proto adresu odesílatele v zahraničí – plugin ji u těchto metod použije automaticky. Bez ní odeslání skončí chybou o nepovolené kombinaci země a produktu.

Dopravní metody PPL

Plugin přidává do WooCommerce devět dopravních metod:

Metoda	Popis	Země
PPL Private doručení na adresu	Doručení na adresu soukromým osobám	ČR a 24 zemí Evropy
Doručení na výdejní místo PPL	Zákazník si v mapě vybere ParcelShop, PPL ParcelBox nebo AlzaBox	CZ, SK, PL, DE, FR, IT, ES, PT, SI, HR, NL, AT, HU, RO, BG
Doručení na PPL Parcelshop	Jen kamenná výdejní místa (bez boxů)	stejné jako výdejní místo
Doručení do PPL Boxu	Jen ParcelBoxy a AlzaBoxy	CZ
PPL Parcel CZ Smart To Box	Doručení do PPL Parcel Boxu	CZ
PPL Morning doručení na adresu	Ranní doručení do 10 hodin	CZ
PPL Business doručení na adresu	Doručení firmám, volitelně jen s vyplněným názvem firmy	ČR a 25 zemí Evropy
PPL Return Connect Import	Z adresy odesílatele v zahraničí do České republiky	CZ
PPL Return Connect Europe	Z adresy odesílatele v zahraničí na SK, do PL, DE nebo AT	SK, PL, DE, AT

Dobírka je u PPL dostupná pro doručení na adresu a na výdejní místo v ČR, na Slovensku, v Polsku, Maďarsku a Rumunsku. U metod Morning, Smart To Box, Box a Business jen v ČR, u metod Return Connect vůbec.

Přidání metod do zón dopravy

Metody, které chcete nabízet, nejdřív přidejte do zón dopravy WooCommerce: WooCommerce → Nastavení → Doprava, otevřete zónu a klikněte na Přidat způsob dopravy.

U každé metody v zóně můžete nastavit:

• Povolit – zapnutí metody v této zóně.
• Název – text, který uvidí zákazník v pokladně.
• Popis – doplňkový text zobrazený zákazníkovi.
• Daňový status – zdanitelné, nebo bez daně.

Metoda se zákazníkovi nabídne jen tehdy, když je v odpovídající zóně, je zapnutá pro jeho zemi v nastavení pluginu a objednávka projde limity hmotnosti, rozměrů a košíku.

Dopravní metody a ceny

Na záložce Dopravní metody a ceny zapnete u každé metody konkrétní země a nastavíte ceny. Metody jsou rozbalovací; u každé vidíte, kolik zemí je zapnutých.

Zaškrtnutím země se rozbalí její nastavení ve třech sloupcích – Cena, Omezení a Dobírka.

TIP: Pokud některá metoda používá produkt PPL, který nemáte na účtu zapnutý, plugin ji označí varováním není zapnuto na vašem účtu PPL. Takové zásilky PPL odmítne – požádejte PPL o doplnění produktu do smlouvy.

Cena

• Ceník – Pevná cena, nebo Podle hmotnosti.
• Pevná cena – jedna částka bez ohledu na hmotnost.
• Hmotnostní pásma (kg) – každé pásmo na vlastní řádek ve tvaru od-do:cena, například:
  
  0-2:99
2-5:149
5-10:199
  
  Hmotnost se počítá z produktů v jednotce nastavené ve WooCommerce.
• Zdarma od – hodnota košíku, od které je doprava zdarma. Prázdné pole = nikdy.
• Zdarma s kupónem na dopravu zdarma – uplatní se, jen když je v sekci Pokladna a e-maily u kupónů zvoleno Zdarma jen vybrané metody.
• Podle měny – rozbalovací sekce s pevnou cenou v CZK, EUR, PLN a HUF. Hodí se, když používáte přepínač měn (WOOCS, WCML, WPML, Aelia). Zadaná cena v měně má přednost před přepočtem kurzem, a to i při ceně podle hmotnosti.

TIP: Zda ceny zadáváte s DPH, nebo bez, určuje volba Ceny v nastavení jsou včetně DPH na záložce Pokladna a e-maily.

Omezení

• Max. kg – maximální hmotnost objednávky pro tuto metodu.
• Max. rozměry a/b/c (m) – maximální rozměry zásilky.
• Limity košíku – minimální a maximální hodnota košíku, minimální a maximální počet kusů, minimální a maximální cena produktu.

Prázdné pole znamená bez limitu. Kontrola hmotnosti i rozměrů se zapne sama, jakmile limit vyplníte. Když objednávka limit nesplní, metoda se v pokladně nenabídne.

Dobírka

• Povolit – zapne dobírku pro danou zemi. U zemí, kde ji PPL nenabízí, je místo nastavení poznámka bez dobírky.
• Poplatek – Pevná částka, nebo Podle hodnoty objednávky.
• Pásma hodnoty – při volbě podle hodnoty objednávky zadejte pásma ve tvaru od-do:poplatek, například:
  
  0-1000:39
1000-3000:19
  
• Dobírka zdarma od – hodnota košíku, od které se poplatek nepočítá.
• Limit dobírky – maximální částka dobírky; nad ni se dobírka nenabídne.

Částku dobírky posílá plugin do PPL v měně, kterou PPL pro danou zemi očekává: CZK pro Česko, PLN pro Polsko, HUF pro Maďarsko a EUR pro ostatní země. Pokud kurz pro převod chybí, zásilka se nezaloží a v logu je o tom záznam.

Výdejní místa a widget PPL 2.0

Verze 4 pracuje výhradně s widgetem výdejních míst PPL 2.0. Starší widget 1.0 už není podporovaný. Bez API klíče se mapa v pokladně nenačte a zákazník si výdejní místo nevybere.

Generování API klíče pro PPL widget 2.0

1. Otevřete klient.ppl.cz/widgetadmin.
2. Vyplňte údaje, se kterými jste registrovaní u PPL – IČO, PPL ID a registrační e-mail – a klikněte na Vygenerovat API klíč.
3. Na e-mail vám přijdou přístupové údaje a aktivační odkaz. Nastavení je nutné dokončit do 60 minut.
4. V aktivačním formuláři vyplňte doménu e-shopu (například mujeshop.cz), jako typ produktu zvolte Vlastní nastavení, vyberte typy výdejních míst a dostupné země, nastavte výchozí jazyk, jako typ zobrazení zvolte Modal a klikněte na Aktivovat.
5. Vygenerovaný klíč vložte v nastavení pluginu na záložce Pokladna a e-maily do pole API klíč widgetu PPL a uložte. Po uložení plugin klíč ověří u PPL. Zkontroluje jeho platnost i to, zda je doména e-shopu povolená. Výsledek uvidíte přímo pod polem API klíč widgetu PPL a také na záložce Stav.

Doména vašeho e-shopu musí být v administraci PPL povolená. Pokud se mapa v pokladně nenačte, je to nejčastější příčina.

Pokladna a e-maily

Záložka Pokladna a e-maily řídí, jak se doprava PPL chová v pokladně a co se propisuje do zákaznických e-mailů. Nastavení funguje shodně v klasické i blokové pokladně.

Výdejní místa

• API klíč widgetu PPL – klíč z administrace PPL, viz předchozí kapitola.
• Tlačítko výdejního místa – Řádek pod metodami dopravy, nebo Přímo pod vybranou metodou.
• Mapa – otevřít mapu automaticky při výběru metody s výdejním místem.
• Boxy – skrýt boxy u obecné metody Výdejní místo, takže zákazník uvidí jen ParcelShopy.
• Hotovost na místě – skrýt dobírku, když vybrané místo nepřijímá hotovost. Zabrání objednávce, kterou by PPL nedoručilo.
• Dodací adresa – kopírovat výdejní místo do dodací adresy objednávky. Hodí se pro faktury a přehledy.

Zobrazení

• Logo PPL – zobrazit logo PPL u dopravních metod.
• PPL Business – nabízet doručení Business jen tehdy, když zákazník vyplní název firmy.

Ceny a DPH

• Zadané ceny – zaškrtávací pole Ceny v nastavení jsou včetně DPH. Zaškrtněte, pokud ceny zadané v nastavení pluginu obsahují DPH; podle toho plugin ceny dopravy a poplatků přepočítá.
• Daňová třída poplatku za dobírku – platí i pro poplatek za vratný štítek a vlastní poplatky. Volba Podle položek košíku (nejvyšší sazba) použije sazbu produktu s nejvyšší daní v košíku, což je běžná praxe českých e-shopů. Můžete zvolit i Základní sazbu nebo konkrétní daňovou třídu.
• Řádek dobírky zdarma – skrýt řádek „Dobírka: zdarma“.
• Kupón na dopravu zdarma – co udělá kupón WooCommerce s volbou „Povolit dopravu zdarma“ s metodami PPL:
  – Zdarma všechny metody PPL.
  – Zdarma jen vybrané metody (povoluje se u každé země a metody v Dopravních metodách).
  – Metody PPL ho ignorují.

E-maily

• Odkaz na sledování – vkládat do zákaznických e-mailů odkaz na sledování zásilky. Odkaz se objeví, jakmile je zásilka u PPL založená.
• Výdejní místo v e-mailech a Odkaz na sledování v e-mailech – u obou zvolíte, kam se blok v e-mailu vloží: za tabulkou objednávky, před tabulkou objednávky, do detailů objednávky, do meta objednávky nebo k údajům zákazníka. Vybrané výdejní místo se zákazníkovi zobrazuje i na děkovné stránce a v detailu objednávky v Můj účet.
• E-mail o zásilce – přidá nový automatický e-mail s číslem zásilky a sledovacím odkazem, který se odešle ve chvíli, kdy je zásilka podána. Kliknutím na Otevřít nastavení e-mailu se dostanete do nastavení, kde jej můžete zapnout/vypnout a upravit jeho obsah.

TIP: Při automatickém odesílání se do e-mailu ke zvolenému stavu (např. Zpracovává se) sledovací odkaz nepřiloží – e-mail se při změně stavu odešle dříve, než je zásilka zpracována. U automatického podávání proto doporučujeme nastavit E-mail o zásilce (viz výše).

Vratná zásilka

Zákazník si může spolu s objednávkou objednat štítek pro vrácení zboží. Buď balík odnese na výdejní místo PPL (podání na výdejním místě), nebo si pro něj přijede řidič (svoz řidičem).

Nastavuje se zvlášť pro doručení na adresu a doručení na výdejní místo, a v rámci nich pro každou zemi. Dostupnost určuje PPL:

• Podání na výdejním místě – Česko a dále SK, PL, DE, HU, AT, ES, PT, IE, FI, SE, EE, LT, LV, BG, HR, IT, LU, RO, GR, SI.
• Svoz řidičem – Česko, Slovensko, Polsko, Německo, Maďarsko, Španělsko a Portugalsko.

U každé varianty nastavíte:

• Povolit – zapne nabídku v pokladně.
• Text – popisek zaškrtávacího pole v pokladně.
• Název poplatku a Poplatek – zobrazí se jako samostatný řádek objednávky.
• Předvyplněno – volba je zaškrtnutá předem.
• Povinné – volba je v pokladně zaškrtnutá a zamčená, zákazník ji nemůže odškrtnout. Úplně skrýt ji lze až v kombinaci s volbou Skrytý.

Ve sloupci Zobrazení jsou dvě doplňkové volby: Skrytý spolu s volbou Povinné schová zaškrtávací pole i text úplně, Skrýt nulový poplatek nezobrazí řádek s nulovou částkou.

Vratný štítek se u PPL zakládá spolu s hlavní zásilkou. V detailu objednávky pak najdete jeho číslo s odkazem na sledování a v přehledu objednávek odkaz vratná zásilka vedle hlavního čísla.

Vlastní poplatky

Na záložce Vlastní poplatky přidáte k objednávkám s dopravou PPL libovolné další poplatky, například manipulační nebo balné.

Každý poplatek má název, částku a rozsah Platí pro:

• Každá objednávka PPL – poplatek se přidá vždy.
• Vybrané země – zobrazí se výběr zemí.
• Produkty, Kategorie, Varianty – poplatek se přidá, jen když je v košíku položka, u které je poplatek zaškrtnutý v detailu produktu, kategorie nebo varianty.
• Dopravní metoda – poplatek jen pro konkrétní metodu PPL.

Tři zaškrtávací pole určují chování:

• Zapnuto – vypnutý poplatek zůstane uložený, ale nepočítá se.
• Viditelný – poplatek je samostatný řádek v košíku. Skrytý poplatek se místo toho přičte k ceně dopravy.
• Za kus – poplatek se vynásobí počtem odpovídajících položek v košíku.

Poplatky se daní podle volby Daňová třída poplatku za dobírku v záložce Pokladna a e-maily.

Nastavení u produktu, varianty a kategorie

V detailu produktu najdete v Datech produktu záložku PPL. Další pole jsou i u varianty a v detailu kategorie produktů – konkrétně tabulka dopravních metod, volba Nelze doručit do boxů a vlastní poplatky. Ověření věku, HS kód a celní popis se nastavují pouze u produktu.

• Ověření věku 15+ a Ověření věku 18+ – řidič nebo obsluha výdejního místa ověří věk příjemce.
• ID check (pouze na úrovni produktu) – zpřísněné ověření věku (kontrola čísla dokladu kurýrem). Pouze pro PPL Private v ČR.
• Nelze doručit do boxů – v mapě se skryjí ParcelBoxy a AlzaBoxy, například u rozměrného zboží.
• HS kód (celní) – nejméně 6 číslic. Povinné pro zásilky mimo EU.
• Celní popis (anglicky) – nejvýše 100 znaků. Rovněž povinný pro zásilky mimo EU.
• Tabulka metod se třemi příznaky pro každou dopravní metodu:
  
  – Nenabízet – s tímto produktem v košíku se metoda v pokladně nezobrazí,
  
  – Doprava zdarma – s produktem v košíku je doprava danou metodou zdarma,
  
  – Dobírka zdarma – s produktem v košíku je dobírka u dané metody zdarma.
• Vlastní poplatky – zaškrtnutí poplatků, které mají rozsah Produkty, Kategorie nebo Varianty.

V tabulce metod jsou vypsané jen metody, které mají v nastavení pluginu zapnutou aspoň jednu zemi. Dokud není zapnutá žádná, zobrazí se všechny.

Ověření věku má u PPL omezení. Službu PPL přijímá jen u produktů PPL Parcel CZ Private, PPL Parcel CZ Smart a PPL Parcel CZ Morning, tedy u zásilek v Česku doručovaných na adresu, na výdejní místo a ranním doručením. U zásilek do zahraničí, u metody Business a u metody PPL Parcel CZ Smart To Box ji PPL nenabízí. Plugin to hlídá sám: takovou zásilku odešle bez ověření věku a k objednávce přidá poznámku, jinak by ji PPL odmítlo.

Automatizace

Záložka Automatizace řídí, co plugin dělá na pozadí sám. Všechno na této záložce běží ve frontě – pro optimální funkci doporučujeme nastavit serverový cron (viz kapitola Fronta a serverový cron).

Odesílání a svozy

• Počet balíků – ptát se na počet balíků při odeslání z administrace. Před odesláním se zobrazí stránka, kde u každé objednávky zkontrolujete počet balíků. Automatické odeslání běží dál a použije automaticky vypočtený počet.
• Automaticky objednat svoz řidičem na další pracovní den – po založení zásilky se objedná svoz na následující pracovní den, pokud na ten den ještě neexistuje.

Stavy zásilek

• Aktualizace stavů – aktualizovat stavy zásilek každou hodinu.
• Kontrolovat stavy zásilek za posledních N dní – kolik dní zpět se plugin ptá PPL. Nižší číslo znamená méně dotazů na PPL.

Balíky a celní údaje

• Těžké objednávky – rozdělit těžké objednávky na více balíků.
• Hmotnost na balík (kg) – nad tuto hmotnost se zásilka založí jako vícebalíková. Čísla dalších balíků najdete v detailu objednávky.
• Země vyžadující celní údaje – zadejte kódy zemí oddělené čárkou. Při prázdném poli se budou celní údaje vyžadovat pro zásilky do Irska, Velké Británie, Švýcarska a Norska (IE, GB, CH, NO). U zásilek do těchto zemí se do PPL posílají HS kódy a celní popisy produktů.

Mobilní aplikace

Klíč mobilní aplikace je volitelné zabezpečení pro propojení s mobilní aplikací Toret WooCommerce Manager, která může zásilky odesílat, tisknout štítky a aktualizovat stavy. Když klíč vyplníte, musí ho aplikace posílat v hlavičce X-Toret-Key nebo v parametru key.

Automatické odeslání

U každé zapnuté platební metody zvolíte stav objednávky, při kterém se zásilka odešle do PPL sama – například u platby kartou stav Zpracovává se a u dobírky Čeká na vyřízení. Objednávka se zařadí do fronty ve chvíli, kdy stav dostane, ať ho nastaví platební brána nebo obsluha.

Volba Neodesílat automaticky znamená, že objednávky s touto platbou budete odesílat ručně. Zapnuté ptaní na počet balíků se týká jen odesílání z administrace – automatické odeslání běží dál a použije vypočtený počet balíků.

TIP: Při automatickém odesílání se do e-mailu ke zvolenému stavu automatizace (např. Zpracovává se) sledovací odkaz nepřiloží – e-mail se při změně stavu odešle dříve, než je zásilka zpracována. U automatického podávání proto doporučujeme nastavit E-mail o zásilce (viz Pokladna a e-maily).

Stav objednávky podle stavu zásilky

Při hodinové aktualizaci může plugin přepnout objednávku podle stavu, který hlásí PPL – například po doručení na Dokončeno.

• Změna stavu objednávky – zaškrtnutím zapnete celé mapování.
• Nekontrolovat zásilky v těchto stavech PPL – typicky konečné stavy jako doručeno a vráceno. Zásilka v takovém stavu se už PPL nedotazuje.
• Nekontrolovat objednávky v těchto stavech – například zrušené a vrácené objednávky.
• Tabulka stavů – u každého stavu PPL zvolíte cílový stav objednávky, nebo necháte Neměnit.

Vyloučení stavů šetří dotazy na PPL a zrychluje synchronizaci. Stavy PPL se v tabulce objeví až po nastavení připojení k PPL.

Štítky a údaje zásilky

• Formát tisku – Štítek 100 × 150 mm (jeden na stránku) pro tiskárny štítků, nebo Arch A4, čtyři štítky. Výchozí je Arch A4
• Startovní pozice – výchozí první políčko na archu A4 (1 až 4). Při tisku se plugin pokaždé zeptá, které políčko je první volné, takže načatý arch dotisknete. Políčka jsou číslovaná jako u PPL: nejdřív pravý sloupec shora, pak levý.
• Data štítků z PPL – PDF, nebo ZPL (termotiskárny) pro tiskárny Zebra a kompatibilní.
• Rozlišení ZPL – 203, 300 nebo 600 dpi podle vaší tiskárny; většina termotiskáren má 203 dpi. Změna platí pro nově odeslané zásilky.
• Reference na štítku – text se zástupnými hodnotami. Reference se ukládá i k zásilce a podle ní se objednávka dohledává. Prázdné pole = číslo objednávky.
• Poznámka na štítku – stejné zástupné hodnoty, nejvýše 300 znaků.
• Kontrola adresy – neodesílat zásilku, když ulice neobsahuje číslo popisné. PPL takové zásilky vrací s chybou.

Pro referenci i poznámku je možné použít následující zástupné hodnoty:

• {order_id}
• {order_number}
• {customer_note}
• {idoklad_invoice_nr}
• {idoklad_invoice_id}
• {idoklad_proforma_nr}
• {idoklad_proforma_id}
• {idoklad_proforma_vs}

Štítky se stahují automaticky hned po založení zásilky a ukládají do složky wp-content/uploads/toret-ppl/labels. Tisk je pak na jedno kliknutí, bez čekání na PPL. U vícebalíkové zásilky obsahuje soubor štítek každého balíku.

Podání zásilky do PPL

V přehledu objednávek přibyl sloupec PPL. Ukazuje stav zásilky, číslo s odkazem na sledování, datum svozu a ikony akcí.

Stavy, které se ve sloupci objevují:

• Neodesláno – zásilka zatím neexistuje.
• Ve frontě – objednávka čeká na zpracování frontou.
• Čeká na PPL – dávka je odeslaná, čeká se na odpověď PPL.
• Založeno / Štítek připraven – zásilka existuje, u druhého stavu je stažený i štítek.
• Chyba – PPL zásilku odmítlo, text chyby je přímo v buňce a v logu.
• Po synchronizaci stavů se místo nich zobrazuje aktuální stav od PPL s datem.

Ruční podání jedné objednávky

Ve sloupci PPL klikněte na ikonu Odeslat do PPL. Objednávka se zařadí do fronty a číslo zásilky se doplní samo, jakmile PPL odpoví. Stejné tlačítko je i v metaboxu PPL v detailu objednávky.

U již odeslané zásilky se zobrazí další ikony: Štítek, Objednat svoz nebo Zrušit svoz, Aktualizovat stav a Zrušit.

U zásilky s chybou je místo nich Odeslat znovu a Odebrat.

Hromadné podání

Zaškrtněte objednávky a v hromadných akcích zvolte požadovanou akci:

• PPL: odeslat zásilky
• PPL: tisk štítků
• PPL: objednat svoz – datum a čas svozu zadáte ve vyskakovacím okně
• PPL: aktualizovat stavy
• PPL: zrušit zásilky

Odesílání běží na pozadí. Nad seznamem se zobrazí lišta s průběhem (PPL: odesílá se X, čeká na PPL Y) a čísla zásilek se do sloupce doplňují průběžně. Administrace přitom není blokovaná, můžete pracovat dál.

Nad seznamem je také filtr PPL s volbami: všechny objednávky, doručované přes PPL, neodeslané, s chybou a založené. Ve vyhledávání funguje i číslo zásilky, včetně čísel dalších balíků.

Počet balíků

Když v Automatizaci zapnete Ptát se na počet balíků, zobrazí se před odesláním stránka se seznamem vybraných objednávek: číslo, zákazník, dopravní metoda, hmotnost a pole s počtem balíků. Předvyplněná hodnota vychází z hmotnosti objednávky a nastavení hmotnosti na balík. Objednávky, které odeslat nelze (nejsou PPL, už jsou ve frontě nebo skončily chybou), jsou označené s vysvětlením.

Detail objednávky

Metabox PPL v detailu objednávky ukazuje stav a číslo zásilky, stejné akce jako přehled objednávek a dále:

• Produkt – kód produktu PPL, se kterým byla zásilka založena.
• Reference, Dávka, Stav PPL, Založeno.
• Balíky a Další balíky u vícebalíkové zásilky.
• Vratný štítek s číslem a odkazem na sledování.
• Svoz – datum a referenci objednaného svozu.
• Výdejní místo – název, adresu a kód. Dokud zásilka není u PPL založená, můžete ho tlačítkem Změnit výdejní místo vybrat znovu v mapě. U založené zásilky je potřeba ji nejdřív zrušit.
• Celní údaje (ICS2) u zásilek do zemí mimo EU.
• Odkaz Zobrazit záznamy logu k této objednávce.

Zásilka se zakládá s údaji z objednávky: dodací adresa nebo zvolené výdejní místo, telefon a e-mail příjemce, hmotnost z produktů, dobírka podle platební metody a reference s poznámkou podle nastavení štítků. Pokud PPL zásilku odmítne, text chyby najdete ve sloupci PPL i v logu; po opravě údajů objednávku odešlete znovu.

Tisk štítků

Štítek jedné zásilky vytisknete ikonou Štítek ve sloupci PPL nebo v metaboxu objednávky. Otevře se v nové záložce prohlížeče ve formátu, který máte nastavený na záložce Štítky a údaje zásilky.

Hromadný tisk spustíte akcí PPL: tisk štítků. Při formátu A4 se před tiskem zobrazí dialog, kde vyberete první volné políčko na archu – díky tomu dotisknete načatý arch a nic nezahodíte. Arch se skládá i ze zásilek odeslaných v různou dobu.

Když štítek pro některou zásilku ještě není připravený, plugin to oznámí a vytiskne zbytek. Zásilka musí být u PPL založená; u zásilek ve frontě nebo s chybou ikona štítku není.

Objednání svozu

Svoz řidičem objednáte třemi způsoby:

• U jedné objednávky – ikonou Objednat svoz ve sloupci PPL nebo v metaboxu.
• Hromadně – akcí PPL: objednat svoz. Datum a čas svozu zadáte do vyskakovacího okna. Výchozí datum je dnešní den, pokud je před 9:00 a není víkend, jinak nejbližší pracovní den.
• Automaticky – volbou Automaticky objednat svoz řidičem na další pracovní den v Automatizaci.

Na jeden den a jednu adresu odesílatele vzniká jeden svoz. Další zásilky se ke stejnému dni připojí bez dalšího volání PPL. Objednaný svoz se zobrazuje ve sloupci PPL jako datum u zásilky.

Zrušení svozu provedete ikonou Zrušit svoz. Zruší se celý svoz včetně všech zásilek, které k němu patří. PPL umožní zrušení jen do doby, než svoz zpracuje – později se obraťte na zákaznickou linku PPL.

Datum svozu musí být dnešní nebo pozdější a svoz lze objednat jen pro zásilky, které už jsou u PPL založené.

Sledování stavů zásilek

Když je v Automatizaci zapnutá Aktualizace stavů, plugin se jednou za hodinu ptá PPL na stav zásilek z posledních N dní a zapisuje ho k objednávce. Stav se zobrazuje ve sloupci PPL a v metaboxu objednávky spolu s datem poslední změny.

Aktualizaci můžete vyvolat i ručně:

• tlačítkem Synchronizovat stavy teď na záložce Stav (funguje jen při zapnuté volbě Aktualizace stavů),
• hromadnou akcí PPL: aktualizovat stavy,
• ikonou Aktualizovat stav u jednotlivé objednávky.

Synchronizace proběhne nejvýš jednou za hodinu, ať ji spustí WP-Cron nebo serverový cron. Na záložce Stav vidíte, kdy proběhla naposledy a kdy přijde na řadu příště.

Celní údaje a doklady (ICS2)

U zásilek do zemí mimo celní území EU vyžaduje PPL celní údaje. Seznam zemí nastavíte v Automatizaci (prázdné pole = IE, GB, CH, NO).

Do těchto zemí se zásilka nezaloží bez HS kódu a celního popisu (v angličtině) vyplněných u produktů. Plugin vypíše, kterým produktům údaje chybí – doplňte je v záložce PPL u produktu.

V metaboxu objednávky je u takové objednávky navíc blok Celní údaje (ICS2):

1. Vyberte typ dokladu ze seznamu, který plugin načítá z číselníku PPL (faktura, proforma a další).
2. Tlačítkem Vybrat soubor připojte doklad z knihovny médií (PDF nebo obrázek).
3. Doklad se do PPL nahraje automaticky, jakmile je zásilka založená. Tlačítko Nahrát do PPL se zobrazí až u založené zásilky a slouží k opakovanému nahrání.

Stav nahrání i případnou chybu od PPL vidíte přímo pod tlačítky.

Fronta a serverový cron

Odeslání zásilek, dotazy na stav dávky a stahování štítků běží ve frontě mimo požadavky zákazníků, takže nezdržují pokladnu ani administraci. Frontu spouští:

• Action Scheduler z WooCommerce, případně záložně WP-Cron. Obojí se ale spouští jen návštěvou webu.
• Otevřený přehled objednávek – dokud je něco ve frontě, administrace ji sama popostrkuje.
• Serverový cron – nejspolehlivější způsob.

Na záložce Stav najdete Adresu pro cron s tajným klíčem a hotový Příklad pro crontab. Volejte adresu každých 5 minut a zásilky se odbaví i v noci:

*/5 * * * * curl -fsS "https://vas-eshop.cz/?tppl_cron=VAS-TAJNY-KLIC" > /dev/null

Odpověď cronu je JSON a říká, co se stalo: kolik zásilek se zpracovalo, jestli proběhla synchronizace stavů, nebo za kolik sekund přijde na řadu (spouští se jednou za hodinu), a jestli proběhla denní údržba. Špatný klíč vrátí chybu 403. Klíč lze kdykoli vygenerovat znovu tlačítkem Vygenerovat nový klíč – stará adresa pak přestane fungovat.

Záložka Stav dále ukazuje:

• stav licence a schématu databáze,
• dostupnost Action Scheduleru,
• počty zásilek ve frontě, čekajících na PPL, založených a s chybou,
• průběh migrace z verze 3.x,
• tabulku posledních zásilek a posledních záznamů logu.

Tlačítko Spustit frontu teď udělá jeden průchod ručně.

PPL log

Stránka Toret plugins → PPL log zaznamenává komunikaci s PPL: odeslané dávky, založené zásilky, svozy a chyby.

• Filtrovat lze podle úrovně (error, warning, info, debug), ID objednávky, textu ve zprávě nebo kontextu a podle data.
• U každého záznamu lze rozbalit kontext s daty, která šla do PPL, a s odpovědí PPL.
• Tlačítko Export CSV (filtrované) stáhne aktuálně filtrované záznamy.
• Log lze vymazat celý, nebo jen filtrované záznamy.

Při hlášení potíží podpoře pošlete záznam včetně rozbaleného kontextu – řešení je pak výrazně rychlejší.

Číselníky PPL

Záložka Číselníky PPL ukazuje seznamy, které plugin stahuje z PPL: produkty povolené pro váš účet, služby a stavy zásilek. Číselníky jsou uložené na jeden den; tlačítkem Znovu načíst z PPL je stáhnete znovu – například poté, co vám PPL doplní do smlouvy nový produkt.

Podle tohoto seznamu plugin pozná, které metody na vašem účtu fungují, a v Dopravních metodách u ostatních zobrazí varování.

Přechod z verze 3.x na verzi 4

Aktualizace je bezpečná, ale počítejte s několika změnami:

• Nastavení zůstává. Přístupové údaje CPL, adresy odesílatele, ceny, dobírka, vratná zásilka i poplatky se přebírají beze změny – verze 4 čte stejné volby.
• myAPI už není podporováno. Pokud jste zásilky podávali přes uživatelské jméno a heslo, musíte mít od PPL vydané CPL Client ID a Client secret. Rozsah čísel zásilek se už nezadává.

Pozor! Dokud máte ve verzi 3.x v nastavení zvolené myAPI, aktualizace na verzi 4 se vám nenabídne, a to ani automaticky. V administraci se místo toho zobrazí upozornění s odkazem na návod. Nejdřív v nastavení pluginu přepněte na CPL API, potom se aktualizace nabídne.

• Widget 1.0 už není podporovaný. Vygenerujte API klíč pro widget 2.0.
• Večerní doručení bylo odstraněno, PPL tuto službu už neposkytuje.
• Zásilky se převedou. Po aktivaci se na pozadí načtou zásilky z objednávek za poslední 2 roky do nové evidence. U zásilek mladších 30 dní se od PPL znovu stáhnou i štítky, takže je můžete dál tisknout. Starší štítky už PPL nevydává. Průběh převodu vidíte na záložce Stav, kde ho lze spustit znovu tlačítkem Znovu projít objednávky z 3.x. Pokud se převod nedokončí, spustí se po aktualizaci pluginu sám znovu.
• Starší objednávky zůstávají čitelné, jen se u nich nesledují stavy.
• Návaznost na jiné pluginy je zachovaná – plugin zapisuje k objednávkám i údaje ve formátu verze 3.

Po aktualizaci doporučujeme projít záložky Připojení k PPL (ověřit připojení), Pokladna a e-maily (API klíč widgetu) a Stav (nastavit serverový cron).

Odinstalování a smazání dat

Ve výchozím stavu si plugin při smazání data ponechá, takže po opětovné instalaci naváže tam, kde skončil. Pokud chcete data smazat, zaškrtněte na záložce Stav volbu Při odinstalaci pluginu smazat všechna jeho data a uložte. Smaže se nastavení, záznamy zásilek, log, štítky i meta objednávek.

Časté dotazy a řešení potíží

V pokladně se nenačte mapa výdejních míst

Nejdřív se podívejte na výsledek ověření klíče pod polem API klíč widgetu PPL (záložka Pokladna a e-maily) nebo na záložce Stav. Zkontrolujte API klíč widgetu a to, že je doména e-shopu povolená v administraci PPL na klient.ppl.cz/widgetadmin. Klíč je vázaný na konkrétní doménu, takže pro testovací i produkční web potřebujete povolit obě.

Metoda PPL se v pokladně nenabízí

Projděte postupně:

• Je metoda přidaná do zóny dopravy WooCommerce, která odpovídá zemi zákazníka?
• Je v nastavení pluginu zapnutá pro jeho zemi?
• Projde objednávka limity hmotnosti, rozměrů a košíku?
• Nemá některý produkt / kategorie produktů v košíku příznak Nenabízet pro tuto metodu?
• U metody Business: je zapnutá volba Nabízet doručení Business jen s vyplněnou firmou a zákazník firmu nevyplnil?

Zásilka je dlouho „ve frontě“ nebo „čeká na PPL“

Frontu spouští návštěva webu nebo otevřený přehled objednávek. Na e-shopu s malým provozem nastavte serverový cron podle kapitoly Fronta a serverový cron. Aktuální stav fronty vidíte na záložce Stav, kde ji můžete tlačítkem Spustit frontu teď proběhnout ručně.

Zásilka skončila chybou

Text chyby je ve sloupci PPL i v PPL logu. Nejčastější příčiny jsou chybějící telefon, chybějící číslo popisné v ulici nebo PSČ, které neodpovídá zemi. Opravte údaje na objednávce a odešlete ji znovu ikonou Odeslat znovu.

PPL hlásí nevalidní produkt

Produkt PPL (například Morning, Smart nebo Business) není zapnutý na vašem účtu PPL. Plugin to hlídá už při odeslání a v Dopravních metodách označí metody, jejichž produkt v číselníku vašeho účtu chybí. Požádejte PPL o doplnění produktu do smlouvy a poté na záložce Číselníky PPL klikněte na Znovu načíst z PPL.

Na archu A4 je jen jeden štítek

Zkontrolujte Formát tisku na záložce Štítky a při tisku vyberte správné první volné políčko. Arch se sestaví jen ze zásilek, které už mají stažený štítek.

Zrušení svozu selže

Svoz lze u PPL zrušit jen do doby, než ho PPL zpracuje. Později se obraťte na zákaznickou linku PPL.

Zásilka do zahraničí mimo EU se nezaloží

Doplňte u produktů HS kód a celní popis anglicky a zkontrolujte seznam zemí vyžadujících celní údaje v Automatizaci. Plugin v hlášení vypíše, kterým produktům údaje chybí.

Zásilky Return Connect nejdou odeslat

Return Connect Import a Return Connect Europe vyžadují adresu odesílatele mimo Českou republiku. Přidejte ji na záložce Adresy odesílatele a objednávku odešlete znovu.

Chci u dobírky vlastní sazbu DPH

Ve WooCommerce v Nastavení → Daň → Daňové třídy vytvořte novou daňovou třídu s požadovanou sazbou a vyberte ji v poli Daňová třída poplatku za dobírku na záložce Pokladna a e-maily. Stejná třída platí i pro poplatek za vratný štítek a pro vlastní poplatky.

Po aktivaci nevidím většinu nastavení

Není aktivní licence. Vložte licenční klíč na záložce Připojení k PPL. Ostatní záložky, nástroje u objednávek a PPL log se zobrazí hned po aktivaci.