SemaShipping PPL

Plugin pro dopravu PPL ve VirtueMart. Zákazník si v košíku vybere výdejní místo, ParcelBox nebo AlzaBox z mapy PPL, e-shop pak zásilky exportuje přímo do PPL (jednotlivě i hromadně) a tiskne štítky — bez ručního přepisování do klientské sekce.

2. Přístupové údaje od PPL

Plugin používá dvě nezávislé sady údajů. Nezaměňujte je — každá se získává jinde a slouží k něčemu jinému.

Client ID a Client Secret (CPL API)

Nejsou samoobslužné — nevygenerujete si je v klientské sekci. Požádejte o ně svého obchodního zástupce PPL (nebo zákaznickou podporu) o povolení přístupu k OAuth 2.0 pro CPL API (myAPI2) a o vydání klientských údajů. Uveďte své zákaznické číslo PPL a to, že jde o integraci e-shopu přes schválené řešení SemaShipping PPL od Semakin.cz — PPL toto řešení eviduje a přidělení přístupů to urychlí.

• Údaje pro produkci a pro testovací prostředí jsou samostatné. Pokud chcete napřed testovat, vyžádejte si rovnou obojí a řekněte, že jde o integraci e-shopu.
• Plugin si přihlašovací token drží v paměti a obnovuje ho, až když vyprší (platnost 30 minut). PPL povoluje jen 12 vydaných tokenů za minutu, proto se token nezískává znovu při každém requestu.

API klíč mapového widgetu

Tenhle si vytvoříte sami:

1. Přihlaste se do klient.ppl.cz/widgetadmin stejnými údaji jako do klientské sekce PPL.
2. Vytvořte nový widget a vygenerujte k němu API klíč — začíná předponou ak_.
3. Přidejte domény, na kterých se mapa smí načíst.

Pozor na domény. Widget se načte jen na doméně, která je u klíče výslovně uvedená. Zástupné znaky (*) zatím nefungují, a example.cz a www.example.cz se počítají jako dvě různé domény — přidejte obě. Pokud testujete na testovací doméně nebo subdoméně, musíte přidat i tu.

Kódy produktů

Kód produktu určuje službu, kterou se zásilka pošle, a liší se podle vaší smlouvy s PPL. Nastavuje se u každé metody dopravy zvlášť (viz sekce 7).

Nejběžnější kódy:

Skutečný seznam produktů vašeho účtu vrací metoda GET /codelist/product v CPL API. Pokud si nejste jistí, zeptejte se svého obchodního zástupce PPL, které produkty máte nasmlouvané.

Ještě předtím zkontrolujte

• Adresa prodejce ve VirtueMartu je kompletní — plugin ji posílá do PPL jako adresu odesílatele a zásilku bez ní PPL odmítne.
• Váš účet má povolenou dobírku, pokud ji chcete nabízet.

4. Aktivace pluginu

Po instalaci je nutné plugin dopravy ručně povolit:

1. Přejděte do Extensions → Plugins.
2. Vyhledejte semappl nebo PPL.
3. Klikněte na název SemaShipping PPL – doručení na adresu a výdejní místa pro VirtueMart (skupina vmshipment) a nastavte Status = Enabled.
4. Uložte.

Systémový plugin plg_system_semappl se povoluje sám při instalaci — ručně ho zapínat nemusíte.

Samotný plugin na e-shopu nic nezobrazí. Doprava se objeví až po vytvoření metody dopravy ve VirtueMart (viz sekce 6).

6. Vytvoření metody dopravy

Jednu instalaci pluginu lze použít pro libovolný počet metod dopravy — typicky jednu pro výdejní místa a jednu pro doručení na adresu.

1. V administraci VirtueMart přejděte do Shop → Shipment Methods.
2. Klikněte na New.
3. Vyplňte:
   • Shipment Name: název viditelný zákazníkovi (např. „PPL — výdejní místo")
   • Published: Yes
   • Shipment Method: zvolte SemaShipping PPL – doručení na adresu a výdejní místa pro VirtueMart
4. Přejděte na záložku Configuration.
5. Nastavte parametry z následujících sekcí.
6. Uložte.

8. Mapa výdejních míst

Plugin používá mapový widget PPL 2.0. Otevírá se jako překryvné okno po kliknutí na tlačítko „Vybrat výdejní místo".

Nastavení mapy u metody

Co si plugin z výběru uloží

Kód místa, název, typ (ParcelShop / ParcelBox / AlzaBox) a adresu. Kód místa se pak posílá do PPL, zbytek slouží k zobrazení — zákazníkovi v rekapitulaci objednávky, vám v administraci.

Výběr přežije změnu v košíku

Vybrané místo se ukládá do relace. Když zákazník změní platbu, dopravu nebo obsah košíku, výběr zůstane zachovaný. Po dokončení objednávky se relace vyčistí.

Verze widgetu 1.x končí 31. 8. 2026. Plugin používá výhradně verzi 2.0, takže se vás konec podpory netýká — jen nezapomeňte, že klíč ak_… je pro verzi 2.0 povinný.

10. Export zásilek do PPL

Jak PPL zpracovává zásilky

Na rozdíl od většiny přepravců PPL zásilky přijímá v dávkách a zpracovává je na pozadí. Plugin dávku odešle, dostane její identifikátor a pak se PPL doptává, jestli je hotová. Obvykle to trvá jednotky sekund.

Proto má objednávka v administraci tři možné stavy:

Export jedné objednávky

1. Otevřete objednávku ve VirtueMart → Orders.
2. V panelu dopravy klikněte na Vytvořit zásilku v PPL.
3. Po dokončení se zobrazí číslo zásilky a tlačítko pro štítek.

Pokud se místo čísla zásilky objeví hláška, že PPL dávku ještě zpracovává, počkejte pár sekund a klikněte na Obnovit stav.

Co se do PPL odesílá

• Číslo objednávky jako reference zásilky
• Jméno a adresa příjemce, telefon, e-mail
• U firemní objednávky jde firma na první řádek a jméno osoby jako kontakt
• Kód výdejního místa (u metod s mapou)
• Číslo objednávky ještě jednou jako externí číslo (kód CUST) — PPL ho tiskne na etiketu a propisuje do fakturace
• Dobírka, pokud je objednávka dobírková
• Poznámka zákazníka

Adresa odesílatele se posílá vždy — PPL request bez ní odmítne. Plugin ji bere z prodejce ve VirtueMart, přepsat ji jde v globální konfiguraci.

Když export skončí chybou

Chybová hláška z PPL se zobrazí přímo v administraci. Zásilka, kterou PPL odmítne, u nich neexistuje, takže se objednávka vrátí mezi neexportované a po opravě dat můžete export zopakovat.

12. Tisk štítků

Jedna zásilka

V detailu objednávky tlačítko Stáhnout štítek.

Více zásilek najednou

Tlačítko Stáhnout štítky v přehledu objednávek. Chování závisí na tom, kolika dávkami zásilky vznikly:

• Objednávky z jedné dávky → jeden soubor se všemi štítky.
• Objednávky z více dávek → ZIP archiv, v něm jeden soubor na dávku.

PPL neumí sloučit štítky napříč dávkami do jednoho souboru. Pokud chcete tisknout na jeden zátah, exportujte objednávky pohromadě — jeden běh exportu = jedna dávka.

Nastavení tisku

Formát, velikost stránky a počáteční pozici najdete v globální konfiguraci (sekce 5). Při A4 se na list vejdou čtyři etikety; Počáteční pozice 1–4 umožní dotisknout na arch, ze kterého jste už část odlepili.

14. Storno zásilky

Zásilku, která nepůjde do přepravy — zákazník objednávku zrušil, zboží není skladem, export proběhl omylem — je potřeba v PPL stornovat. Není to volitelný úklid: jakmile zásilka v datech vznikne, PPL ji vede jako čekající na podání, dokud ji nestornujete.

Stornovat jde jen zásilku, kterou jste ještě fyzicky nepředali řidiči.

Jedna objednávka

1. Otevřete objednávku ve VirtueMart → Orders.
2. V panelu dopravy klikněte na Stornovat zásilku v PPL.

Panel pak místo štítku ukáže Stornováno s datem a časem. Storno je nevratné — zpět už zásilku neoživíte, dá se jen vytvořit nová.

Více objednávek najednou

V přehledu objednávek zaškrtněte objednávky, které chcete stornovat, a klikněte na Storno v PPL v horní liště. Tlačítko se pak zeptá Opravdu stornovat (počet)? — teprve druhé kliknutí storno provede. Když do šesti sekund nekliknete, otázka zmizí.

Objednávky bez zásilky v PPL se ve výběru přeskočí, nemusíte je odškrtávat. Výsledek se vypíše nad seznamem, u každé objednávky zvlášť.

Hromadné storno záměrně nepracuje s filtrem stavu jako hromadný export. Storno je nevratné, takže se stornují jen ty objednávky, které opravdu zaškrtnete.

Vytvoření nové zásilky po stornu

U stornované objednávky nabídne panel dopravy tlačítko Vytvořit novou zásilku. Použije se, když se zásilka nakonec pošle — typicky po opravě adresy nebo výdejního místa. Původní číslo zásilky tím zmizí z objednávky; dohledatelné zůstává v logu komunikace s PPL.

Co PPL vrátí

Storno je u PPL asynchronní: API potvrdí přijetí okamžitě, ale v jejich systému se zásilka na Stornováno přepne až za nějakou dobu. Plugin proto po úspěšném stornu jen zapíše datum a čas — kdyby storno na straně PPL neprošlo, dozvíte se to z jejich systému, ne z administrace obchodu.

16. Odinstalace

1. Extensions → Manage → Extensions
2. Vyhledejte semappl.
3. Odinstalujte plugin dopravy SemaShipping PPL – doručení na adresu a výdejní místa pro VirtueMart.

Co se smaže

• Plugin dopravy (PHP, JS, CSS, jazykové soubory)
• Systémový plugin plg_system_semappl (odstraní se automaticky)
• Tabulka #__virtuemart_shipment_plg_semappl (data o zásilkách v objednávkách)

Co zůstane

• Tabulka #__sema_ppl_log — auditní záznamy o komunikaci s PPL API

Proč se log nemaže? Slouží jako doklad o tom, co a kdy se do PPL odeslalo. Smazat ho můžete ručně:

DROP TABLE IF EXISTS `#__sema_ppl_log`;

(nahraďte #__ skutečným prefixem svých tabulek)

Kontrolní seznam pro spuštění

• Přístup k CPL API vyžádán u podpory PPL a schválen
• Client ID a Client Secret vyplněny
• Prostředí API odpovídá vydaným údajům
• API klíč widgetu vytvořen v klient.ppl.cz/widgetadmin
• Domény e-shopu přidány k API klíči widgetu (včetně varianty s www)
• Výchozí adresa odesílatele nastavená v klientské sekci PPL
• Plugin nainstalován a povolen
• Metoda dopravy vytvořena ve VirtueMart a publikována
• Typ doručení zvolen
• Kód produktu vyplněn a odpovídá typu doručení
• Země a typy míst pro mapu nastaveny
• ID dobírkových plateb vyplněno (pokud dobírku nabízíte)
• Formát a velikost štítku zvoleny
• Výchozí stav pro export nastaven
• Testovací objednávka provedena a zásilka úspěšně exportována
• Štítek stažen a vytištěn
• Hromadný export vyzkoušen v přehledu objednávek

PPL® je registrovaná ochranná známka PPL CZ s.r.o., společnosti skupiny DHL Group. Tento produkt je nezávislé rozšíření a není s PPL CZ s.r.o. ani DHL Group spojen ani jimi schválen.