SemaShipping Packeta

Plugin pro dopravu přes Zásilkovnu / Packetu ve VirtueMart. Umožňuje zákazníkům vybrat výdejní místo nebo Z-Box přímo v košíku, e-shopu exportovat zásilky do Packety (jednotlivě i hromadně) a tisknout štítky.

2. Instalace

1. Stáhněte instalační ZIP soubor plg_vmshipment_semazasilkovna_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.

Součástí balíčku je i systémový plugin plg_system_semazasilkovna, který se nainstaluje a povolí automaticky. Zajišťuje tlačítka pro hromadný export v přehledu objednávek VirtueMart (viz sekce 11).

4. Globální konfigurace

V nastavení pluginu (Extensions > Plugins > klik na název) vyplňte globální parametry, které platí pro všechny metody dopravy založené na tomto pluginu:

Důležité: Bez vyplněného API klíče a API hesla nebude plugin funkční. API klíč je nutný pro widget na frontendu, API heslo pro export zásilek a tisk štítků v administraci.

6. Typ doručení

Každá metoda dopravy má parametr Typ doručení (radio):

Výdejní místa + Z-Boxy (pickup)

• Na frontendu se zobrazí widget pro výběr výdejního místa.
• Zákazník musí vybrat bod před odesláním objednávky.
• Podporuje interní body Zásilkovny i externí (Z-Boxy, Alzaboxy apod.).
• Podrobnosti viz sekce 8.

Doručení na adresu (hd)

• Na frontendu se zobrazí jen radio button s cenou – bez widgetu.
• Adresa se přebírá z objednávky (dodací adresa, při jejím chybění fakturační).
• Vyžaduje vyplnění HD Carrier ID – viz sekce 7.

Parametry související s typem doručení

8. Widget pro výběr výdejního místa

U metod s typem doručení Výdejní místa + Z-Boxy se na frontendu zobrazí tlačítko "Vybrat výdejní místo", které otevře interaktivní mapu Packeta Widget v6.

Jak to funguje

1. Zákazník v košíku zvolí metodu dopravy se Zásilkovnou.
2. Klikne na tlačítko "Vybrat výdejní místo".
3. Otevře se widget s mapou a seznamem bodů.
4. Po výběru bodu se jeho název zobrazí pod tlačítkem.
5. Výběr se uloží a přežije změnu platební metody, aktualizaci košíku i přechod mezi kroky objednávky.

Session persistence

Vybraný bod se ukládá do PHP session. Díky tomu:

• Výběr přežije změnu platební metody nebo jiného nastavení košíku.
• Při AJAX přenačtení stránky se bod automaticky obnoví.
• Session se vyčistí až po úspěšném odeslání objednávky.

Filtrování bodů

• Země: Parametr "Země pro widget" omezí body na konkrétní zemi (např. cz pro ČR, sk pro Slovensko).
• Dopravci: Parametr "Filtr dopravců" umožní zobrazit jen určité typy bodů (např. jen Z-Boxy, jen Alzaboxy). ID dopravců výdejních míst získáte ze stejného feedu jako u HD, jen s hodnotou pickupPoints: true – viz sekce 7.

Validace: Pokud zákazník nevybere výdejní místo a pokusí se dokončit objednávku, zobrazí se hláška "Prosím vyberte výdejní místo Zásilkovny."

10. Export zásilek do Packety

Po přijetí objednávky s dopravou přes Zásilkovnu můžete zásilku exportovat do systému Packety přímo z administrace VirtueMart.

Postup

1. Přejděte do VirtueMart > Orders.
2. Otevřete detail objednávky.
3. V sekci dopravy uvidíte informace o vybraném bodě (nebo adrese u HD).
4. Klikněte na tlačítko "Vytvořit zásilku v Packetě".
5. Plugin odešle data do Packeta API a zobrazí potvrzení s číslem zásilky.

Co se exportuje

• Výdejní místo: ID bodu, jméno příjemce, e-mail, telefon, váha, hodnota.
• Externí bod (Z-Box): ID dopravce + ID bodu, plus údaje příjemce.
• Doručení na adresu: ID dopravce + kompletní adresa (ulice, číslo popisné, město, PSČ).
• Dobírka: Pokud je platební metoda dobírka, nastaví se dobírková částka.

Bezpečnost

• Každý export je chráněný CSRF tokenem.
• API heslo se nikdy nezobrazuje na frontendu.
• Všechny API požadavky a odpovědi se logují do tabulky #__sema_zasilkovna_log (API heslo je v logu maskované).
• Zásilku nelze exportovat dvakrát – pokud už byla exportována, zobrazí se hláška "Zásilka již byla exportována."

12. Tisk štítků

Po úspěšném exportu zásilky můžete stáhnout PDF štítek:

1. V detailu objednávky klikněte na "Stáhnout štítek (PDF)".
2. Prohlížeč stáhne PDF soubor se štítkem.

Hromadné stažení štítků pro více objednávek najednou viz sekce 11.

Formáty štítků

Formát se nastavuje v globálním nastavení pluginu:

Typy štítků

Plugin automaticky vybere správný typ štítků podle druhu doručení:

• Interní body Zásilkovny: Standardní štítek Zásilkovny (packetLabelPdf).
• Externí body (Z-Box) a HD: Kurýrní štítek (packetCourierLabelPdf) – plugin si nejdříve vyžádá trackovací číslo od Packety.

14. Měny a zaokrouhlování

Plugin posílá do Packety měnu objednávky (pole currency) spolu s hodnotou zásilky a případnou dobírkou.

• CZK a HUF nemají setinnou jednotku – Packeta u nich odmítá desetinná místa a vrací chybu PacketAttributesFault. Plugin proto hodnotu i dobírku u těchto měn automaticky zaokrouhlí na celé číslo.
• EUR, PLN a další se odesílají s desetinnými místy beze změny.
• Měna objednávky by měla odpovídat měně dopravce (sloupec Měna v tabulkách v sekci 7), jinak Packeta dobírku odmítne.

16. Řešení problémů

Widget se nezobrazuje

1. Ověřte, že plugin je povolený.
2. Ověřte, že metoda dopravy má typ doručení Výdejní místa + Z-Boxy (ne HD).
3. Zkontrolujte, že je vyplněný API klíč (Widget) v globálním nastavení pluginu.
4. Zkontrolujte konzoli prohlížeče (F12) na JavaScript chyby.
5. Ověřte, že stránku neblokuje Content Security Policy (CSP) pro doménu widget.packeta.com.

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

• U metody typu "Výdejní místa" zákazník MUSÍ vybrat bod. Hláška "Prosím vyberte výdejní místo Zásilkovny" se zobrazuje správně.
• U metody typu "Doručení na adresu" se žádná validace bodu neprovádí – pokud zákazník nemůže dokončit objednávku, problém je jinde.

Chyba při exportu zásilky

• Ověřte, že je vyplněné API heslo v globálním nastavení pluginu.
• Ověřte, že Označení odesílatele přesně odpovídá názvu odesílatele v klientské sekci Packety.
• Zkontrolujte hlášení chyby – plugin zobrazuje přesnou odpověď Packeta API.
• Zkontrolujte log v tabulce #__sema_zasilkovna_log pro detaily požadavku a odpovědi.

Chyba PacketAttributesFault

Nejčastější příčiny:

• Chybí číslo popisné u dopravce s separateHouseNumber: true – viz Číslo popisné.
• Desetinná místa v CZK nebo HUF – řeší zaokrouhlení v sekci 14.
• Nesouhlasí Označení odesílatele s klientskou sekcí Packety.
• Chybí telefon nebo e-mail u dopravce s requiresPhone / requiresEmail.
• Přetečení limitu váhy dopravce (maxWeight, zpravidla 30 kg).

Metoda dopravy pro doručení na adresu neposílá správného dopravce

• Ověřte, že HD Carrier ID odpovídá zemi nastavené v parametru Země.
• Ověřte, že dopravce má ve feedu apiAllowed: true – např. "Packeta večerní doručení Bratislava HD" (ID 132) přes API použít nelze.
• Ověřte, že Typ doručení je nastaven na hd (ne pickup).

Štítek se nestáhne

1. Ověřte, že zásilka byla úspěšně exportována (musí existovat číslo zásilky).
2. Zkontrolujte, že formát štítků v nastavení pluginu je platný.
3. Pro externí body a HD: plugin potřebuje získat trackovací číslo od Packety. Pokud selže, zkontrolujte API log.
4. U hromadného stahování: externí body a HD nejsou součástí hromadného PDF, stáhněte je jednotlivě.

Tlačítka hromadného exportu se nezobrazují

1. Ověřte, že systémový plugin plg_system_semazasilkovna je nainstalovaný a povolený (Extensions > Plugins, skupina system).
2. Ověřte, že jste na stránce VirtueMart > Orders (tlačítka se jinde nezobrazují).
3. Zkontrolujte konzoli prohlížeče na JavaScript chyby.

Dobírka se nenastavuje

• Ověřte, že ID platební metody dobírky je správně zadané v parametru "ID plateb = dobírka".
• ID musí být číslo odpovídající virtuemart_paymentmethod_id v URL platební metody.
• Více ID oddělujte čárkou bez mezer (např. 3,7).
• Ověřte, že dopravce dobírku vůbec podporuje (disallowsCod: false).

Metoda dopravy se nezobrazuje

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