SemaShipping PPL

1. Požadavky

• Joomla 4.x nebo 5.x (VirtueMart zatím Joomlu 6 nepodporuje)
• VirtueMart 4.x
• PHP 8.0 nebo novější, s rozšířením cURL
• MySQL 5.7+ / MariaDB 10.3+
• Aktivní zákaznický účet PPL se smlouvou o přepravě
• Povolený přístup k CPL API (myAPI2) a vlastní API klíč mapového widgetu

3. Instalace

1. Stáhněte instalační ZIP plg_vmshipment_semappl_X.Y.Z.zip.
2. Přihlaste se do administrace Joomla.
3. Přejděte do System → Install → Extensions.
4. Nahrajte ZIP soubor.
5. Po úspěšné instalaci se zobrazí hláška o nainstalování pluginu.

Upgrade: stejný postup jako instalace. Joomla použije method="upgrade" a zachová všechna existující data i nastavení.

Součástí balíčku je systémový plugin plg_system_semappl, který se nainstaluje a povolí automaticky. Zajišťuje nabídku PPL v přehledu objednávek VirtueMart (viz sekce 11).

5. Globální konfigurace

V nastavení pluginu (Extensions → Plugins → klik na název) vyplňte parametry, které platí pro všechny metody dopravy postavené na tomto pluginu:

Bez Client ID a Client Secret nepůjde exportovat ani tisknout štítky. Bez API klíče widgetu se zákazníkovi nezobrazí mapa. Obojí je potřeba vyplnit.

Adresa odesílatele

PPL vyžaduje adresu odesílatele u každé zásilky. Plugin ji bere z adresy prodejce ve VirtueMartu (Prodejce → fakturační adresa), takže obvykle nemusíte vyplňovat nic.

Záložka Adresa odesílatele slouží k přepsání — vyplňte ji jen tehdy, odesíláte-li odjinud, než je fakturační adresa obchodu (například z externího skladu). Prázdné pole vždy znamená „vzít z VirtueMartu".

Zkontrolujte, že adresa prodejce ve VirtueMartu je skutečná česká adresa. Výchozí ukázková adresa z instalace VirtueMartu (Sample Company, Seattle) projde ve VirtueMartu bez povšimnutí, ale PPL export odmítne s chybou Sender.Country: Invalid value.

7. Typ doručení a kód produktu

Každá metoda má dva klíčové parametry, které spolu musí ladit.

Typ doručení

Kód produktu PPL

Textové pole, kam patří kód přepravní služby. Musí odpovídat typu doručení:

Kombinace, které si neodpovídají (např. PRIV u metody s mapou), skončí chybou při exportu. Seznam produktů vašeho účtu vrací GET /codelist/product — viz sekce 2.

Vedle něj je pole Kód produktu PPL pro dobírku. Nechte ho prázdné — plugin si dobírkový kód odvodí sám. Vyplňte ho jen tehdy, má-li vaše smlouva nestandardní kódy; podrobnosti v sekci 13.

Ostatní omezení metody

9. Cena dopravy

Výsledná cena je Cena dopravy + Poplatek za balení, nebo 0 při překročení limitu pro dopravu zdarma.

11. Hromadný export

Po instalaci přibude v přehledu VirtueMart → Orders tlačítko PPL v horní liště. Rozbalí se pod ním nabídka všech funkcí rozšíření:

Nabídka je schválně jedna a zabalená pod jedno tlačítko: e-shopy běžně vozí víc dopravců a kdyby si každé rozšíření přidalo vlastní tlačítka, lišta by nestačila. Ke každé položce se po najetí myší ukáže krátká nápověda, co dělá.

Nabídku zavřete kliknutím mimo ni nebo klávesou Esc; po spuštění akce se zavře sama, aby nepřekrývala výpis výsledku.

Poslední položka Nápověda otevře panel s přehledem všech funkcí a jejich popisem — totéž, co je v nápovědě pod myší, jen pohromadě. Je v něm i upozornění, že zásilky založené rozšířením nejsou vidět v klient.ppl.cz, a odkaz na stránku s postupem k přístupovým údajům.

Export do PPL

Odešle jednou dávkou všechny dosud neexportované objednávky ve zvoleném stavu. Výsledek se vypíše přímo nad seznamem — u úspěšných čísla zásilek, u neúspěšných důvod. Chyba u jedné objednávky ostatní nezastaví.

Stav objednávek, ze kterého se bere seznam, nastavíte v globální konfiguraci (Výchozí stav pro export, výchozí C). Stavů může být víc, oddělených čárkou (C,Q) — pak se do dávky vezmou objednávky ze všech vyjmenovaných stavů.

Stáhnout štítky

Stáhne štítky ke všem zásilkám, které jsou u PPL založené a nejsou stornované — bez ohledu na stav objednávky. Je to schválně stejný výběr, jaký ukazuje Nepodané zásilky: co je v tom seznamu, to se vytiskne.

Na stav objednávky se to nedá vázat: export ji vzápětí přepne do stavu po exportu, takže by z výběru vypadla přesně v okamžiku, kdy je štítek potřeba.

Najednou se stáhne nejvýš 50 dávek, od nejnovější. Víc dávek přijde jako ZIP — PPL je do jednoho PDF sloučit neumí.

Před stažením se plugin zeptá, od které pozice na archu tisknout — v dialogu vyberete pole 1 až 4 podle toho, kolik etiket už je z archu odlepených. Nabídne se jen u formátu PDF na stránku A4; u ostatních nastavení je na stránce jeden štítek a není co vybírat.

V dialogu je obrázek archu — čtyři pole leží tam, kde jsou fyzicky, a když na některé najedete myší, ta dřívější zešednou, protože se přeskočí. Arch je A4 na šířku a PPL čísluje pole po sloupcích zprava:

Tisk pokračuje v tomto pořadí, takže etikety se z archu odlepují od pole 1 dál — pozice, kterou v dialogu zvolíte, je první ještě nepoužité pole.

Když žádné štítky ke stažení nejsou, řekne to hláška „Žádné štítky ke stažení nejsou" — dřív se v takovém případě nestalo nic viditelného.

Samostatná stránka hromadného exportu

Pokud potřebujete přepínat mezi stavy objednávek, otevřete odkaz Otevřít hromadný export ze spodní části nastavení pluginu. Stránka umí totéž a navíc má filtr stavu.

13. Dobírka

1. Zjistěte ID dobírkové platební metody: VirtueMart → Shop → Payment Methods, otevřete metodu a přečtěte virtuemart_paymentmethod_id z URL.
2. Zadejte ho do parametru ID plateb = dobírka v globální konfiguraci pluginu. Více ID oddělte čárkou (např. 3,7).

Plugin pak u objednávek s touto platbou automaticky vyplní částku dobírky, měnu objednávky a variabilní symbol.

Variabilní symbol smí podle PPL obsahovat pouze číslice a nejvýše 10 znaků. Plugin ho odvodí z čísla objednávky tak, že z něj vypustí všechny nečíselné znaky a ponechá posledních deset. Pokud vaše čísla objednávek žádnou číslici neobsahují, použije se interní ID objednávky.

Kód produktu se u dobírky mění sám

PPL má pro dobírku samostatné kódy produktů a dobírku u běžného kódu odmítne. Plugin to řeší za vás: u dobírkové objednávky přepne kód automaticky.

Má-li vaše smlouva jiné kódy, zadejte ten správný do pole Kód produktu PPL pro dobírku v nastavení metody dopravy. Vyplněné pole má přednost před automatikou; prázdné znamená „přepni podle tabulky". Skutečné kódy vaší smlouvy vrací metoda /codelist/product.

U metody s mapou zapněte i Jen místa s dobírkou (sekce 8) — jinak si zákazník může vybrat místo, které dobírku nepřijímá.

Velmi dlouhý e-mail zákazníka

Do PPL se e-mail vejde na 50 znaků. Delší adresa se neposílá vůbec — ořezaná by vypadala platně, ale patřila by někomu jinému. Plugin to u exportu ohlásí s číslem objednávky; taková zásilka projde normálně, jen k ní PPL nepošle e-mailová oznámení. Zákazníka zastihne dopravce telefonicky.

Jak dobírka vypadá na etiketě

Dobírková zásilka má na etiketě dole černý pruh „Dobirka/COD". Částka dobírky se na etiketu netiskne — PPL ji vede ve svém systému a řidič ji vidí ve skeneru.

15. Přehled zásilek a svoz

V administraci PPL (klient.ppl.cz) zásilky založené pluginem neuvidíte — PPL potvrdilo 28. 8. 2026, že tam jsou vždy jen zásilky vytvořené přímo v jejich aplikaci. Přehled, kontrola stavů i objednávka svozu jsou proto tady, v administraci e-shopu.

Čísla zásilek přímo v přehledu objednávek

Pod číslem objednávky se ukazuje číslo zásilky PPL a její poslední známý stav. Stornovaná zásilka je přeškrtnutá červeně. Nemusíte kvůli tomu otevírat detail objednávky.

Nepodané zásilky

Položka Nepodané zásilky vypíše všechny zásilky, které jsou u PPL založené a nejsou stornované — tedy to, co čeká na předání řidiči. Filtr stavu objednávky se tu záměrně nepoužívá: zásilka čeká na podání bez ohledu na to, jaký stav mezitím objednávka dostala.

Zásilky u PPL

Položka Zásilky u PPL vypíše zásilky, které PPL eviduje na vašem zákaznickém účtu za zvolené období. Na rozdíl od Nepodaných zásilek, které čtou data e-shopu, se tenhle přehled ptá přímo PPL — a to je jediné místo, kde uvidíte i zásilky, které v tomhle e-shopu nevznikly: z dřívějšího řešení, z jiného e-shopu na témže účtu nebo zadané ručně. Takové řádky jsou podbarvené a označené štítkem mimo e-shop.

Nahoře se vybere období (předvyplněný je poslední měsíc) a volitelně stav. Tabulka pak ukazuje:

Pod tabulkou je součet za celé období: kolik zásilek, kolik stála doprava a kolik je v dobírkách.

Ceny jsou skutečné nacenění od PPL, ne to, co jste vybrali od zákazníka. Dají se tedy použít na porovnání výnosu z dopravy s náklady. Vyplňují se s odstupem — u čerstvé zásilky bývá cena ještě prázdná.

Tlačítkem Tisk se seznam vytiskne tak, jak je zrovna načtený — na šířku, s hlavičkou tabulky opakovanou na každé stránce, s obdobím nahoře a součtem i časem tisku dole. Netiskne se administrace kolem, jen samotný přehled.

Přehled najednou stáhne nejvýš 500 zásilek; když jich je v období víc, řekne to a stačí zvolit kratší období.

Zkontrolovat stavy

Položka Zkontrolovat stavy se doptá PPL na skutečný stav všech nepodaných zásilek a uloží ho. Používá se, když se se zásilkou stalo něco mimo e-shop — typicky když ji někdo stornoval jinudy. Takovou zásilku plugin označí jako stornovanou a z přehledu nepodaných zmizí.

Stavy se vypisují česky (čeká na podání, doručeno, stornováno, …). Na kód, který zatím neznáme, můžete narazit — vypíše se tak, jak přišel z API, anglicky. Když takový uvidíte, dejte nám vědět a doplníme překlad.

Zásilka, kterou PPL zrovna nevrátí, nezmizí. Rozhraní PPL odpovídá z víc serverů a čerstvě založená nebo čerstvě stornovaná zásilka se pár minut může tvářit různě. Plugin proto stav jen doplňuje, nikdy neruší — když se u zásilky objeví hláška, že ji PPL nevrátilo, zkuste kontrolu za chvíli znovu.

Objednání svozu

Položka Objednat svoz otevře formulář: datum, počet balíků, volitelně čas od–do a poznámka pro řidiče. Počet balíků se předvyplní podle toho, kolik zásilek čeká na podání.

Adresa svozu se bere ze stejného nastavení jako adresa odesílatele u zásilek — co je vyplněné v konfiguraci pluginu, platí i tady.

Po odeslání se vypíše číslo svozu od PPL a rovnou se otevře přehled objednaných svozů. Svoz není navázaný na konkrétní zásilky, říká jen „přijeďte tehdy a tehdy pro tolik balíků".

⚠️ Svoz je skutečná objednávka dopravy. Objednávejte ho, až budete mít balíky připravené.

Objednané svozy

Položka Objednané svozy vypíše svozy za posledních 14 dní — datum, číslo od PPL, počet balíků a stav. U svozu, který ještě nejel, je tlačítko Zrušit; potvrzuje se druhým kliknutím, aby se nedalo zrušit omylem.

Zrušit jde jen svoz objednaný odsud — ruší se podle reference, kterou mu plugin při objednání dal. Svoz zadaný jinudy (telefonicky, v aplikaci PPL) se v seznamu sice může objevit, ale tlačítko u něj nebude; ten se ruší tam, kde vznikl.

17. Stav objednávky po exportu

Plugin umí objednávku po úspěšném exportu sám přepnout do jiného stavu — typicky do vlastního stavu „Předáno PPL", podle kterého pak v přehledu objednávek poznáte, co je odbavené.

Ve výchozím nastavení je volba prázdná a plugin stav objednávky nemění.

Nastavení

1. Založte si stav objednávky ve VirtueMart → Konfigurace → Stavy objednávek. Zvolte volný jednopísmenný kód (T, L, M…) a název, například Předáno PPL.
2. Ten kód zapište do parametru Stav objednávky po exportu v globální konfiguraci pluginu.

Kdy se stav změní

V okamžiku, kdy zásilka dostane od PPL číslo — ne při odeslání dávky. To je podstatný rozdíl:

• Objednávka, kterou PPL odmítne, v původním stavu zůstane a půjde exportovat znovu.
• Platí to stejně pro export jedné objednávky, hromadný export i dohledání čísla tlačítkem Obnovit stav.
• Objednávka, která už v cílovém stavu je, se znovu nepřepisuje.

Zadáte-li kód stavu, který ve VirtueMartu neexistuje, plugin to ohlásí varováním a stav nezmění — export tím nespadne.

Pošle se zákazníkovi e-mail?

Rozhoduje o tom VirtueMart, ne plugin. Notifikace se rozesílají u stavů zaškrtnutých v konfiguraci VirtueMartu (Stavy objednávky, o kterých se informuje zákazník). Nový stav tam ve výchozím stavu není, takže se neodešle nic. Chcete-li zákazníkovi po předání dopravci psát, zaškrtněte tam nový stav.

Storno stav nevrací. Objednávka zůstane v „Předáno PPL", dokud ji ručně nepřepnete jinam.

19. Řešení problémů

Mapa se nezobrazuje

1. Ověřte, že je plugin povolený.
2. Ověřte, že metoda dopravy má typ doručení Výdejní místo / box, ne Doručení na adresu.
3. Zkontrolujte, že je vyplněný API klíč mapového widgetu.
4. Zkontrolujte seznam povolených domén u klíče v klient.ppl.cz/widgetadmin. Tohle je zdaleka nejčastější příčina — widget se na neuvedené doméně prostě nenačte. example.cz a www.example.cz jsou dvě různé domény.
5. Otevřete konzoli prohlížeče (F12) a podívejte se na chyby JavaScriptu.
6. Ověřte, že stránku neblokuje Content Security Policy pro doménu www.ppl.cz.

Když se mapa nenačte, zákazník uvidí pod tlačítkem červenou hlášku, že mapu nelze otevřít. Tlačítko, které jen mlčí, znamená starší verzi než 1.2.12.

Zákazník nemůže dokončit objednávku

• U metody s mapou zákazník musí vybrat místo. Hláška „Prosím vyberte výdejní místo PPL" je správné chování.
• U metody s doručením na adresu se žádné místo nevyžaduje — pak je problém jinde.

Chyba při exportu zásilky

1. Ověřte Client ID a Client Secret v globální konfiguraci.
2. Ověřte, že je zvolené správné Prostředí API — produkční údaje v testovacím prostředí nefungují a naopak.
3. Ověřte kód produktu u metody dopravy. Musí být z vaší smlouvy a musí odpovídat typu doručení (sekce 7).
4. Přečtěte si chybovou hlášku — plugin zobrazuje odpověď PPL API včetně jednotlivých vadných polí.
5. Podrobnosti požadavku a odpovědi najdete v tabulce #__sema_ppl_log.

Chyba přihlášení k API

• Zkontrolujte, že vám PPL přístup k CPL API skutečně povolila. Samotné zákaznické číslo nestačí, přístup se zřizuje na vyžádání.
• Ověřte, že údaje patří ke zvolenému prostředí.
• PPL omezuje vydávání tokenů na 12 za minutu. Když si s pluginem hrajete a přepínáte údaje, počkejte chvíli.

Objednávka zůstává ve stavu „PPL dávku zpracovává"

• Klikněte na Obnovit stav. Zpracování obvykle trvá jednotky sekund, u velkých dávek déle.
• Když stav trvá dlouho, zkontrolujte #__sema_ppl_log — v odpovědi bude buď InProcess, nebo chyba.

Štítek se nestáhne

1. Ověřte, že zásilka má číslo zásilky. Bez něj štítek neexistuje.
2. Zkontrolujte, že formát štítku v nastavení odpovídá vaší tiskárně.
3. Podívejte se do #__sema_ppl_log na odpověď u akce downloadLabel nebo getBatchLabel.

U hromadného stahování se důvod vypíše rovnou nad seznam objednávek — červeně, jedna řádka na dávku. Když se stáhla jen část, je v ZIPu soubor PRESKOCENE-DAVKY.txt se seznamem toho, co chybí.

Tlačítka hromadného exportu se nezobrazují

1. Ověřte, že systémový plugin plg_system_semappl je nainstalovaný a povolený (Extensions → Plugins, skupina system).
2. Ověřte, že jste na stránce VirtueMart → Orders — jinde se nabídka PPL nezobrazuje.
3. Zkontrolujte konzoli prohlížeče na chyby JavaScriptu.
4. Běží-li na webu i SemaShipping Packeta, musí být PPL na verzi 1.2.19 nebo vyšší a Packeta na 1.4.13 nebo vyšší — viz níž.

Tlačítko PPL zmizelo a pod tabulkou „vyteklo" kus skriptu

Stává se to jen tam, kde vedle sebe běží SemaShipping PPL i SemaShipping Packeta a aspoň jeden z nich je starší. Oba pluginy se do administrace vkládají před uzavírací značku stránky a ve starších verzích si při tom navzájem rozbily blok skriptu; konzole hlásí SyntaxError.

Řešení je aktualizovat obojí: PPL na 1.2.19 a výš, SemaShipping Packeta na 1.4.13 a výš. Novější PPL si poradí i se starší Packetou, ale spolehlivé je to teprve tehdy, když jsou aktuální oba.

Dobírka se nenastavuje

• Ověřte ID platební metody v parametru ID plateb = dobírka. Musí odpovídat virtuemart_paymentmethod_id z URL platební metody.
• Více ID oddělujte čárkou bez mezer.
• Ověřte, že váš účet PPL má dobírku povolenou a že ji podporuje zvolený produkt.
• Skončí-li export chybou „Unable to get shipment number" (MyApi2.Error.UnableToGetShipmentNumber), není chyba v datech objednávky: váš účet PPL nemá pro dobírkové produkty přidělenou číselnou řadu zásilek. Požádejte o ni svého obchodního zástupce PPL se svým zákaznickým číslem.

Metoda dopravy se nezobrazuje v košíku

• Ověřte nastavení zemí (povolené i blokované).
• Ověřte váhové omezení.
• Ověřte, že metoda je ve VirtueMart Published a plugin Enabled.