SemaShipping Packeta

1. Požadavky

• Joomla 4.x nebo 5.x (VirtueMart zatím Joomlu 6 nepodporuje)
• VirtueMart 4.x
• PHP 8.0 nebo novější
• MySQL 5.7+ / MariaDB 10.3+
• Aktivní účet u Zásilkovny / Packety s přístupem k API

Checkout: Plugin funguje ve standardním checkoutu VirtueMartu i v One Page Checkoutu od RuposTelu (com_onepage) – od verze 1.4.0 bez dalšího nastavování. Viz One Page Checkout v sekci 8.

Údaje z Packety, které budete potřebovat

3. Aktivace pluginu

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

1. Přejděte do Extensions > Plugins (nebo System > Manage > Plugins).
2. Vyhledejte semazasilkovna nebo Zasilkovna.
3. Klikněte na název pluginu SemaShipping Packeta - Zásilkovna pro VirtueMart (skupina vmshipment) a nastavte Status = Enabled.
4. Uložte.

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

Plugin sám o sobě nic nezobrazuje – až po vytvoření metody dopravy ve VirtueMart (viz sekce 5).

5. Vytvoření metody dopravy

Plugin se ve VirtueMart používá jako základ pro metody dopravy. Jednu instalaci pluginu můžete použít pro libovolný počet metod – např. jednu pro výdejní místa v ČR a další pro doručení na adresu v každé zahraniční zemi.

Postup

1. V administraci VirtueMart přejděte do Shop > Shipment Methods.
2. Klikněte na New.
3. Vyplňte:
   • Shipment Name: Název zobrazený zákazníkovi (např. "Zásilkovna – výdejní místo")
   • Published: Yes
   • Shipment Description: Volitelný popis
   • Shipment Method: Zvolte SemaShipping Packeta - Zásilkovna pro VirtueMart

VirtueMart v tomto rozbalovači zobrazuje u některých instalací místo názvu holý jazykový klíč PLG_VMSHIPMENT_SEMAZASILKOVNA. Je to kosmetická vlastnost VirtueMartu (nenačítá jazykové soubory pluginu do tohoto seznamu) – vyberte tuto položku, je to správný plugin. V Extensions > Plugins se název zobrazuje správně.

1. Přejděte na záložku Configuration (per-method nastavení).
2. Nastavte parametry popsané v následujících sekcích.
3. Uložte.

7. Doručení na adresu (HD)

Doručení na adresu funguje bez widgetu – zásilka se odesílá na dodací adresu z objednávky. Každá metoda dopravy ale nese jedno HD Carrier ID, které platí pro jednu zemi a jednoho dopravce.

Pravidlo: jedna země = jedna metoda dopravy. Pro doručení do pěti zemí vytvořte pět metod, každou s vlastním Carrier ID a vlastním omezením země.

Postup pro jednu zemi

1. Vytvořte novou metodu dopravy podle sekce 5.
2. Typ doručení = Doručení na adresu (hd).
3. HD Carrier ID = ID dopravce pro danou zemi (viz tabulka níže).
4. Země = pouze ta jedna země, do které metoda doručuje.
5. Nastavte cenu, daň a případně váhový rozsah (viz sekce 9).
6. Uložte.

Doporučená Carrier ID pro nejčastější země

Další dostupné varianty (pokud vám vyhovují lépe podmínky konkrétního dopravce):

Všichni uvedení dopravci mají limit 30 kg na zásilku.

Pozor na sloupec "Vlastní číslo popisné": dopravci s hodnotou "ano" (separateHouseNumber) vyžadují číslo popisné v samostatném polí. Viz Číslo popisné níže.

Jak si Carrier ID ověřit nebo najít další

Seznam dopravců se mění – ID si před nasazením ověřte ve svém účtu. Feed dopravců pro doručení na adresu stáhněte z:

https://www.zasilkovna.cz/api/v4/<API_HESLO>/branch.json?address-delivery

<API_HESLO> nahraďte svým tajným API heslem (stejným, jaké máte v globální konfiguraci pluginu – ne 16znakovým API klíčem widgetu).

Odpověď je JSON s objektem carriers. U každého dopravce jsou důležitá tato pole:

Stejný feed najdete i v klientské sekci Packety pod položkou Feed dopravců.

Číslo popisné

Někteří zahraniční dopravci (separateHouseNumber: true) vyžadují číslo popisné oddělené od ulice. Plugin ho čte z uživatelského pole objednávky s názvem house_number, které VirtueMart standardně nemá.

Pokud používáte dopravce s tímto požadavkem:

1. Přejděte do VirtueMart > Shop > User Fields.
2. Vytvořte nové pole s názvem (Name) přesně house_number.
3. Nastavte ho jako povinné a zobrazené v dodací i fakturační adrese.
4. Uložte.

Bez tohoto pole vrátí Packeta při exportu chybu PacketAttributesFault.

Měna a dobírka

Každý HD dopravce přijímá dobírku v jedné pevné měně (sloupec Měna v tabulkách výše). Pokud objednávku vystavíte v jiné měně, Packeta dobírku odmítne.

• Buď pro danou zemi nastavte ve VirtueMart odpovídající měnu,
• nebo u této metody dopravy dobírku nenabízejte.

Viz také sekce 15.

9. Cena dopravy

Každá metoda dopravy má vlastní cenové nastavení:

Cena se zadává BEZ DPH

Do pole Cena dopravy patří částka bez daně. DPH přičte VirtueMart podle zvoleného Daňového pravidla. Zadáte-li rovnou částku, kterou má zákazník zaplatit, naúčtujete mu ji navýšenou o DPH.

Převodní tabulka pro sazbu 21 %:

Obecné: cena bez DPH = cena s DPH / 1.21.

Cenu vyplňte hned při zakládání metody dopravy. První uložení drží, ale pozdější změny pole Cena dopravy se u existující metody nemusí projevit (VirtueMart u této položky přepočítává měny a při ukládání sáhne po uložené hodnotě). Pokud potřebujete cenu změnit a změna se neprojeví, metodu dopravy smažte a založte znovu se správnou cenou.

Omezení zobrazení metody

Země a Blokované země najdete na první záložce metody dopravy ("Informace o způsobu dopravy"), ne v záložce Configuration mezi ostatními parametry pluginu. Používají se jádrová pole VirtueMartu – omezení funguje stejně, jen se nastavuje jinde. Pokud pole v konfiguraci pluginu hledáte marně, je to tím.

11. Hromadný export a štítky

Pro odbavení více objednávek najednou slouží tlačítka přímo v přehledu objednávek VirtueMart. Zajišťuje je systémový plugin plg_system_semazasilkovna, který se instaluje automaticky spolu s pluginem dopravy.

Postup

1. Přejděte do VirtueMart > Orders.
2. V horní liště (vedle tlačítka "Aktualizovat objednávky") uvidíte tlačítko "Zásilkovna"; rozbalí se pod nim nabídka s položkami Export do Zásilkovny, Stáhnout štítky (PDF), Zkontrolovat stavy a Nápověda.
3. Kliknutím odešle plugin do Packety všechny dosud neexportované objednávky ve stavech nastavených v parametru Stav objednávek pro export. Stavů může být více, oddělených čárkou (např. E,Q) – viz sekce 4.
4. Výsledek se zobrazí v proužku pod listou – pro každou objednávku úspěch s číslem zásilky, nebo chybová hláška.
5. Položka "Stáhnout štítky (PDF)" stáhne štítky ke vsem zasilkam, které jsou v Zasilkovne založené a nejsou stornované – bez ohledu na stav objednávky. Nejdřív se zeptá, od kterého pole na archu se má tisknout, aby sel dotisknout načatý arch.

Co je dobré vědět

• Objednávka, která už byla exportována, se přeskočí – opakovaný export nic nezdvojí. Pokud není co exportovat, zobrazí se "Žádné neexportované objednávky".
• Chyba u jedné objednávky nezastaví zpracování ostatních. Nepodařené objednávky vyřešíte jednotlivě z detailu objednávky.
• Hromadné štítky pokrývají výdejní místa i doručení na adresu. Packeta má ale na každý druh vlastní metodu a do jednoho PDF je nesloučí, takže když je v dávce obojí, stáhnou se dva soubory: první rovnou, druhý tlačítkem, které se objeví ve výpisu výsledků. Zvolená pozice na archu platí pro první soubor, druhý začíná na novém archu.
• Počet polí na archu se řídí formátem štítků v konfiguraci: A6 on A4 má 4 pole, A7 on A4 osm, A6 on A6 a A7 on A7 po jednom (tam se na pozici neptáme a stahuje se rovnou).
• Pokud máte vyplněný parametr Stav objednávky po exportu, přepne se každá úspěšně exportovaná objednávka do tohoto stavu – viz sekce 10.
• Nevidíte-li žádné objednávky k exportu, zkontrolujte nejdřív Stav objednávek pro export. Výchozí C u většiny e-shopů neodpovídá žádné objednávce.
• Stránka hromadného exportu má nahoře rozbalovač stavu. Máte-li v konfiguraci více stavů oddělených čárkou, nabídne se celá kombinace jako první položka (např. "Vyřizuje se + Čeká na vyřízení") a je předvybrána. Výběr jednotlivého stavu pod ni filtr zúží jen na něj; ke kombinaci se vrátíte zpětným výběrem první položky.
• Export i stahování štítků je přístupné jen uživatelům s oprávněním do administrace a je chráněno CSRF tokenem.

13. Čísla a stavy zásilek v přehledu objednávek

Od verze 1.6.0 vypisuje plugin přímo v přehledu objednávek VirtueMart číslo zásilky pod číslem objednávky a pod nim stav zásilky. Detail objednávky už tedy nemusíte otvírat jen kvůli tomu, abyste zjistili, jestli je zásilka založena a kde je.

Odznak s číslem zásilky

• Objeví se u každé objednávky, která má v Packetě založenou zásilku – bez ohledu na stav objednávky.
• Stornovaná zásilka má číslo přeškrtnuté a v bublinové nápovědě je vysvětlení.
• Odznak se načítá spolu s přehledem objednávek a nevyžaduje žádné nastavení.

Zkontrolovat stavy

Stav zásilky se nenačítá sám při každém zobrazení přehledu – znamenalo by to jeden dotaz do Packety na každou zásilku a stránka by se otvírala pomalu. Vyžádáte si ho ručně:

1. Přejděte do VirtueMart > Orders.
2. V nabídce pod tlačítkem "Zásilkovna" zvolte "Zkontrolovat stavy".
3. Plugin se zeptá Packety na stav založených nestornovaných zásilek a uloží ho k objednávce.

Co je dobré vědět

• Packeta nemá hromadnou obdobu dotazu na stav, takže jde o jeden dotaz na každou zásilku. Plugin proto zpracuje nejvýše 40 zásilek na jedno kliknutí a vypíše "Zbývá N zásilek – klikněte na Zkontrolovat stavy znovu." Klikněte tolikrát, kolikrát je potřeba.
• Přednost dostávají zásilky, na jejichž stav se nejdéle nikdo neptal, takže opakovaným klikáním projdete celý seznam.
• Stavy se překládají do češtiny, slovenštiny, angličtiny, němčiny a polštiny. Stav, který plugin nezná, se vypíše tak, jak přišel z Packety – nikdy nezůstane prázdno.
• Zjištěný stav "stornovaná" se k zásilce jen doplní, nikdy neruší. Čerstvě stornovaná zásilka se první minuty vrací z různých replik Packety nejednotně, takže by se příznak jinak sám odmazal.
• Není-li co kontrolovat, plugin napíše "Není co kontrolovat – žádná založená nestornovaná zásilka."
• Výpis stavu je přístupný jen uživatelům s oprávněním do administrace a je chráněný CSRF tokenem, stejně jako export a štítky.

15. Měny a zaokrouhlování

Plugin posílá do Packety menu 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.

17. Ř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 15.
• Nesouhlasí Označení odesílatele s klientskou sekci 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 format š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ě.

Hromadný export hlásí "Unexpected response" nebo chybu 500

Toto je opravené ve verzi 1.4.3. Příčinou byl konflikt při načítání pluginu dopravy (Joomla naimportuje celou skupinu vmshipment a jádrový plugin VirtueMartu weight_countries spadne, pokud se načte dříve než náš plugin – chyba Class "vmPSPlugin" not found).

1. Aktualizujte plugin na 1.4.3 nebo novější.
2. Ověřte, že systémový plugin plg_system_semazasilkovna je povolený – opravu zajišťuje právě on.
3. Projev chyby závisí na pořadí pluginů, takže se může objevit i na webu, kde předtím vše fungovalo.

Hromadný export nenajde žádné objednávky

• Zkontrolujte parametr Stav objednávek pro export. Výchozí C (Zaplaceno) u většiny e-shopů neobsahuje nic – dobírkové objednávky se do něj nedostanou nikdy.
• Správný kód najdete ve VirtueMart > Objednávky > Stavy objednávek.
• Více stavů oddělte čárkou (E,Q). Prázdná nebo chybná hodnota záměrně neexportuje nic.

Kontrola stavu hlásí, že tabulka nemá sloupce pro stav

Hláška "Tabulka metody dopravy nemá sloupce pro stav zásilky" znamená, že web byl aktualizovan na 1.6.0, ale VirtueMart si ještě nedoplnil nové sloupce. Otevřete a uložte kterékoli metodu dopravy Zásilkovny – VirtueMart je při uložení doplní. Je to tataz situace jako u storna, viz sekce 2.

Storno zásilky končí chybou o neexistujícím sloupci

Aktualizace pluginu nová pole v tabulce zásilek nevytvoří. Otevřete kteroukoli metodu dopravy ve VirtueMart a uložte ji – VirtueMart tím sjednotí schema tabulky. Viz sekce 2.

Zásilku nelze stornovat (CancelNotAllowedFault)

Packeta storno odmítá, jakmile byla zásilka fyzicky předána dopravci. V takovém případě řešte situaci přímo v klientské sekci Packety.

Stav objednávky se po exportu nemění

1. Ověřte, že je vyplněný parametr Stav objednávky po exportu (prázdné = stav se záměrně nemění).
2. Ověřte, že zadaný kód odpovídá existujícímu stavu ve VirtueMart > Objednávky > Stavy objednávek.
3. Objednávka, která už v cílovém stavu je, se přeskakuje.
4. Chybí-li zákazníkovi e-mail o změně stavu, jde o nastavení VirtueMartu (Konfigurace > Objednávky), ne pluginu.

Widget se v One Page Checkoutu otevírá dvakrát nebo bod mizí

• Aktualizujte plugin na 1.4.0 nebo novější – starší verze One Page Checkout nepodporovaly.
• Ověřte, že jsou povolené systémové pluginy OPC (zejména plg_system_opc).
• Vyčistěte cache Joomly i OPC.

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.