Balíkovna for WooCommerce WP Registry grade A. No security issues foundWP RegistryNo security issues foundOpen the reportA

Open-source WooCommerce plugin pro integraci služeb České pošty – Balíkovna, Balík na adresu, Balíkovna plus, Balík Do ruky a Balík Na poštu.

Komunikace s výdejními místy probíhá přes oficiální widget České pošty (b2c.cpost.cz/locations). Plugin nastavuje stabilní messageId=pickerResult a pro zpětnou kompatibilitu přijímá také historickou hodnotu pickResult.

Funkce

• Pět shipping metod:
  • Balíkovna – výdejní místa včetně partnerských míst a samoobslužných boxů
  • Balík na adresu (Balíkovna) – doručení produktu Balíkovna na adresu
  • Balíkovna plus – větší a těžší zásilky na adresu; standardně do 31,5 kg, smluvně do 50 kg
  • Balík Do ruky – doručení na adresu
  • Balík Na poštu – doručení na vybranou pobočku České pošty
• Výběr výdejního místa přes oficiální widget v přístupném modálním okně (parametry type=BALIKOVNY|POST_OFFICE, skipLocation=false, volitelně phone=true); vrácený telefon doplní chybějící billing_phone
• Serverové ověření ID, typu a kanonických údajů pobočky proti veřejně dostupnému JSON seznamu používanému widgetem ČP
• Samostatný výběr pro každý WooCommerce shipping package a přesnou instanci shipping metody
• Podpora klasického checkoutu (wp-admin → WooCommerce → checkout shortcode) i Block Checkoutu (Store API extension)
• Cenotvorba per metoda: fixní cena / podle hmotnosti (tabulka max_kg|cena) / volitelný práh „zdarma od“ z mezisoučtu celého košíku napříč shipping packages
• Produkty Balíkovna se nabízejí jen pro CZ zásilky do 15 kg a 50 × 50 × 50 cm. Známé parametry se vždy kontrolují; u fixní ceny chybějící katalogový údaj sazbu neskryje, váhová cenotvorba však vyžaduje vyplněnou hmotnost.
• Doprava zdarma nemění dostupnost metody: ve váhovém režimu musí být hmotnost známá a pokrytá platnou váhovou tabulkou i po dosažení finančního prahu.
• Checkout pro Balíkovnu vyžaduje platný e-mail a české mobilní číslo s předvolbou +420 nebo 00420
• Kódy služeb ČP (CSV sloupec I) konfigurovatelné per metoda v admin nastavení
• Uložení místa k objednávce, sloupec v přehledu objednávek, zobrazení v e-mailech a na stránce „Děkujeme"
• Ruční podací číslo pro každou zásilku České pošty; odkaz na oficiální Track & Trace v administraci, zákaznickém e-mailu a detailu objednávky
• Automatická synchronizace stavů zásilek přes oficiální B2B-ZSK/CIS nAPI přibližně každých 30 minut:
  • využívá stávající podací číslo na konkrétním shipping itemu a podporuje všech pět shipping metod,
  • stav, čas události a čas poslední kontroly ukládá samostatně ke každé zásilce,
  • odmítá odpovědi s jiným nebo chybějícím podacím číslem; při této chybě zachová poslední známý stav a pokus zopakuje při další synchronizaci,
  • jednotlivý běh má rozpočet 25 sekund a nejvýše 10 dotazů na zásilky; před dalším dotazem ponechává 17 sekund na HTTP timeout a uložení výsledku. Rozpočet zahrnuje i obnovu číselníku. Nejde o násilné přerušení běžícího PHP nebo databázového dotazu,
  • zbývající objednávky i dokončené zásilky aktuální objednávky ukládá průběžně. Po vyčerpání rozpočtu plánuje pokračování přes Action Scheduler nejdříve za minutu; při přerušení procesu nebo nedostupném plánovači uloženou práci převezme další pravidelný či ruční běh,
  • souběžné běhy chrání zámkem s atomickou kontrolou původní hodnoty při převzetí, prodloužení i uvolnění. Proces, který ztratí zámek během API volání, odpověď neuloží a skončí,
  • dynamicky načítá číselník agregovaných stavů přes statusesOverview a bezpečně zachovává poslední funkční cache,
  • umí volitelně mapovat stabilní kódy ČP na libovolné stavy z wc_get_order_statuses(), včetně stavů registrovaných jiným pluginem,
  • mění stav přes standardní WC_Order::update_status(), takže existující WooCommerce e-maily reagují přirozeně a plugin je neduplikuje,
  • u více zásilek postupuje konzervativně; chybějící sledovací číslo u kterékoli zásilky České pošty blokuje automatickou změnu stavu. Smíšené objednávky s jinými dopravci se automaticky nemění bez explicitního souhlasu koordinující integrace.
• Hromadný CSV export pro Podání Online – jeden řádek pro každou zásilku, formát sloupců A–O, Windows-1250, středník
  • Pro typ NB (Balíkovna): adresa Balíkova + ID balíkovny v PSČ dle pokynů ČP
  • Pro typ NP (Balík Na poštu): adresa, PSČ a město vybrané pošty
  • Hodnota obsahu a hmotnost se ukládají samostatně pro každý shipping package; neúplná objednávka zastaví celý export
  • Bloková pokladna obnovuje hmotnost i hodnotu obsahu také při zachování stejné sazby dopravy. Snapshoty jsou vázané na obsah objednávky; po jeho změně se jediná zásilka přepočítá z položek, ale u více balíků se export zastaví, protože nové rozdělení obsahu nelze spolehlivě určit. Prosté uložení položek v administraci snapshoty nemění.
  • Příjemce a adresa se přebírají jako celek z dodacích údajů; fakturační údaje se použijí jen při chybějících dodacích údajích. Prázdná dodací firma nebo druhý řádek adresy se nedoplňuje z fakturace.
  • Finanční částky se exportují pouze v CZK, dobírka v celých korunách a jen na první zásilce objednávky
  • Telefon ve sloupci K používá mezinárodní zápis 00420… namísto +420…, bez vloženého apostrofu. Ochrana ostatních hodnot CSV proti vzorcům zůstává aktivní.
  • Import v Podání Online musí být nakonfigurovaný pro uvedené sloupce A–O a kódy odpovídající smlouvě odesílatele
• HPOS ready (High-Performance Order Storage), kompatibilní s Cart/Checkout blocks
• Diagnostický mód (WP_DEBUG nebo filtr) vypisuje jen pevné stavové zprávy, nikdy payload widgetu, telefon ani výdejní místo
• Logo služby ČP v shipping metodě (klasický checkout)
• Automatické aktualizace z GitHub Releases (knihovna Plugin Update Checker, MIT) – v admin Pluginy se nové verze zobrazují jako u pluginů z wordpress.org
• Aktualizace se nabízí pouze s přiloženým instalačním souborem balikovna-woocommerce.zip; chybějící release asset se nenahrazuje zdrojovým archivem tagu ani větve.
• Připraveno pro i18n (languages/balikovna-wc.pot)

Kompatibilita

Instalace

Z GitHub releasu (doporučeno)

1. Stáhněte balikovna-woocommerce.zip z posledního releasu. (Pozor – ne „Source code (zip)", ten má v názvu složky verzi a rozbije aktualizace.)
2. WordPress admin → Pluginy → Přidat nový → Nahrát plugin → vyberte ZIP → Instalovat → Aktivovat.

Z gitu (pro vývoj)

cd wp-content/plugins
git clone https://github.com/luberan/balikovna-woocommerce.git

Konfigurace

1. WooCommerce → Nastavení → Doprava → vyberte zónu → Přidat dopravu → zvolte jednu z pěti služeb ČP.
2. Editujte metodu a nastavte:
   • Název zobrazený zákazníkovi
   • Typ ceny (fixní / podle hmotnosti)
   • Cena nebo váhová tabulka (řádky max_kg|cena, např. 5|79)
   • Zdarma od částky (volitelně, vyhodnocuje se z celého košíku)
   • Kódy služeb ČP (např. 7+45+S+41 – dle označení ve vaší smlouvě s ČP; použije se ve sloupci I exportu)
   • U produktů používaných s Balíkovnou vyplňte hmotnost, délku, šířku a výšku pro úplnou automatickou kontrolu. Známý nadlimitní parametr dopravu vždy skryje; neznámý údaj ji u fixní ceny sám o sobě neskryje.
   • U Balíkovny plus vyberte smluvní typ zásilky DR/DV/DE a limit 31,5 nebo 50 kg. Limit 50 kg zapněte pouze při sjednané smlouvě; žádná strana nesmí překročit 200 cm a součet tří rozměrů 300 cm.
3. Zákazníci ve checkoutu uvidí novou shipping metodu; u Balíkovny a Balíku Na poštu kliknou „Vybrat výdejní místo" → vybere v iframe widgetu → potvrdí objednávku.
4. V detailu objednávky lze ke každému shipping itemu České pošty zadat podací číslo. Uloží se před změnou stavu objednávky, takže jej následně odeslaný e-mail obsahuje spolu s odkazem Track & Trace.
5. Pro automatické stavy otevřete WooCommerce → Nastavení → Doprava → Sledování stavu zásilek:

• v uživatelské aplikaci Pošta Online si vygenerujte přihlašovací údaje Api-Token a secretKey pro B2B nAPI; uložené hodnoty se v administraci znovu nezobrazují,
• zvolte produkční nebo oficiální testovací prostředí, údaje uložte a klikněte na Otestovat připojení; test ověří přístup k CIS a načtení číselníku, nikoli ZSK stav konkrétní zásilky,
• zapněte sledování, nastavte počet objednávek na běh (výchozí 100), stáří objednávek (výchozí 14 dní) a stavy objednávek, které mají být sledovány,
• zvolte agregované stavy ČP, které se mají dál dotazovat; nový reason kód známého agregovaného stavu bezpečně převezme pouze jednomyslné nastavení skupiny, při nejednoznačnosti se dál kontroluje bez automaticky odhadnutého mapování,
• volitelně zapněte změny stavů objednávek a nastavte mapování Česká pošta status → WooCommerce status.

6. Doporučené stavy wc-shipped a wc-ready-pickup plugin sám neregistruje. Pokud existují, objeví se automaticky ve volbách a bezpečných výchozích mapováních. Totéž platí pro jakýkoli jiný stav vrácený wc_get_order_statuses().
7. V přehledu objednávek (WC → Objednávky) je hromadná akce Export Balíkovna (CSV Podání Online).

Výchozí automatické mapování používá pouze jednoznačné agregované významy z aktuálního číselníku: PODÁNO a V PŘEPRAVĚ → wc-shipped (pokud existuje), ULOŽENO → wc-ready-pickup (pokud existuje) a DORUČENO → wc-completed. Předaná/zpracovaná data, vratky a neznámé stavy výchozí změnu objednávky neprovádějí. Správce může mapování změnit.

Filtry pro vývojáře

Akce balikovna_wc_shipment_status_changed se spustí po skutečné změně kódu zásilky. Akce balikovna_wc_order_status_mapped se spustí po provedené standardní změně stavu objednávky.

Česká pošta nAPI

Implementace vychází z aktuálních oficiálních specifikací B2B-ZSKService 1.13.0, B2B-CISService 1.2.0 a dokumentu nAPI – nejčastější dotazy a vyskytující se chyby.

Použité read-only operace:

• ZSK GET /parcelStatuses/current/idParcel/{idParcel} (statusInfo) – aktuální agregovaný stav jedné zásilky,
• CIS GET /statusesOverview – číselník kombinací status/reason a jejich agregovaného názvu.

Oba GET požadavky používají hlavičky Api-Token, Authorization-Timestamp a Authorization. Plugin vygeneruje UUIDv4 nonce; pro požadavek bez těla podepisuje řetězec ;Authorization-Timestamp;nonce pomocí HMAC-SHA256 a secretKey, výsledek Base64 vloží do Authorization: CP-HMAC-SHA256 nonce="…", signature="…". secretKey požadavek nikdy neobsahuje. Časové razítko je UTC Unix timestamp; specifikace toleruje nejvýše 60 sekund a nepovoluje budoucí čas.

Použité hosty:

• produkce: https://b2b.postaonline.cz:444/restservices/ZSKService/v1 a https://b2b.postaonline.cz:444/restservices/CISService/v1,
• test: https://b2b-test.postaonline.cz:444/restservices/ZSKService/v1 a https://b2b-test.postaonline.cz:444/restservices/CISService/v1.

Oficiální FAQ doporučuje aktuální stav kontrolovat přibližně každých 30 minut. Samotné FAQ neuvádí číselný limit volání; plugin přesto omezuje počet objednávek na běh, neopakuje chyby agresivně a po globální chybě autentizace nebo omezení zastaví celý batch.

Diagnostika synchronizace

• Na stránce nastavení je čas poslední úspěšné synchronizace, poslední globální chyba a příští naplánovaný běh.
• Ruční tlačítko Synchronizovat nyní spouští stejný omezený batch jako plánovaná akce a používá stejný zámek.
• Ve WooCommerce → Stav → Naplánované akce hledejte hook balikovna_wc_sync_shipment_statuses ve skupině balikovna-woocommerce.
• Do WooCommerce logu se zapisují sanitizované dočasné chyby pod zdrojem balikovna-woocommerce-tracking; podací čísla, autentizační hlavičky ani tajný klíč se nelogují.
• Při DISABLE_WP_CRON=true musí provozovatel pravidelně volat standardní wp-cron.php; plugin nepřidává vlastní veřejný cron endpoint.

Vývoj

Repo používá Conventional Commits a release-please pro automatické generování changelogu a bumpování verze. Detaily v CONTRIBUTING.md.

Po composer install jsou dostupné příkazy:

composer test   # regresní a metadata testy
composer lint   # WordPress Core, security sniffs a PHP 7.4+ kompatibilita
composer pot    # regenerace languages/balikovna-wc.pot
composer build  # čistý staging do build/balikovna-woocommerce

CI běží PHP lint matrix 7.4–8.5 a blokující QA na PHP 7.4 i 8.5. Release ZIP se skládá stejným reprodukovatelným build skriptem.

Jednotkové testy používají izolované runtime stuby. Samostatná integrační CI matice spouští skutečný WordPress 7.1 a WooCommerce 11.1.0 na PHP 7.4/8.5, nad MariaDB 11.4.9 s CPT i HPOS. Playwright dokončuje Classic/Block Checkout s jedním i dvěma balíky a ověřuje trvalá metadata i CSV. Náhrada widgetu v těchto testech nepředstavuje autentizovaný import do Podání Online. Postup lokálního spuštění a přesný rozsah je v tests/README.md.

PHPCompatibility je připnuté na 10.0.0-alpha2 a PHPCompatibilityWP na 3.0.0-alpha2, protože stabilní řada 9 nezná moderní PHP. Jde pouze o vývojové nástroje; nedistribuují se s pluginem. Rozšíření kontroly PHP nenahrazuje integrační a browserové testy. Přibalený Parsedown 1.8.0 je namespacovaný, běží v safe mode a jeho zdroj i licence se kontrolují proti Composer locku příkazem composer vendor:check.

Externí služby a soukromí

Picker otevírá iframe https://b2c.cpost.cz/locations/, takže Česká pošta obdrží běžná HTTP metadata návštěvy. Polohu pro funkci „Moje poloha“ předá prohlížeč widgetu pouze po souhlasu zákazníka. Pokud správce zapne phone=true, zákazník zadává telefon přímo ve widgetu České pošty; plugin jej následně převezme a může uložit jako WooCommerce billing_phone. Server pluginu stahuje z téhož hostu veřejně dostupný JSON seznam poboček pro ověření výběru; do tohoto požadavku neposílá údaje zákazníka ani objednávky. Endpoint seznamu nemá zveřejněný verzovaný integrační kontrakt, proto lze zdroj nahradit filtry balikovna_wc_points_api_url nebo balikovna_wc_points_directory a nouzová data se přijímají nejvýše 30 dní.

Při zapnutém nAPI sledování server e-shopu posílá na výše uvedený pevný ZSK host pouze podací číslo potřebné pro statusInfo a autentizační hlavičky (Api-Token, timestamp, nonce a podpis). Uložené přihlašovací údaje se v HTML nevypisují. V databázi jsou chráněné AES-256-GCM; původní plaintext se automaticky migruje jen při dostupném platném klíči a OpenSSL, s atomickou kontrolou proti souběžnému uložení. secretKey se používá lokálně jako HMAC klíč a neposílá se. CIS statusesOverview neposílá podací číslo ani údaje zákazníka. Plugin ukládá jen aktuální kód/název stavu, čas události a časy kontroly ke konkrétnímu WooCommerce shipping itemu; neukládá kompletní API odpověď. Podmínky zpracování provozovatele jsou na webu České pošty.

Ochrana přihlašovacích údajů

• BALIKOVNA_WC_API_TOKEN a BALIKOVNA_WC_SECRET_KEY lze definovat jako konstanty v konfiguraci WordPressu nebo proměnné prostředí. Mají přednost před databází a jejich hodnoty se do ní nekopírují. Prázdná explicitní hodnota daný údaj vypne.
• Volitelný BALIKOVNA_WC_ENCRYPTION_KEY obsahuje Base64 zápis 32 náhodných bajtů. Bez něj se šifrovací klíč odvozuje z platných AUTH_KEY a AUTH_SALT WordPressu pomocí HKDF. Klíč uchovávejte odděleně od databázových záloh a nikdy jej necommitujte.
• Změna šifrovacího klíče nebo použitých WordPress salts zneplatní dříve uložené šifrované hodnoty. Obnovte původní klíč nebo zadejte nAPI údaje znovu. Plugin nečitelné hodnoty sám nepřepíše prázdným řetězcem a zobrazí chybu v nastavení.
• Bez použitelného šifrovacího klíče a OpenSSL se nové databázové údaje neuloží v plaintextu. Existující nechráněné údaje zůstanou zachované pro řízenou migraci, ale nAPI z nich neběží, dokud není ochrana dostupná. Externě definované údaje šifrování databáze nepotřebují.
• Odinstalace přes WordPress smaže API nastavení, pracovní dávky, zámky a cache na všech webech multisite. Objednávky, jejich výdejní místa, tracking a nastavení dopravních zón zůstávají zachované. Samotná deaktivace údaje nemaže. Smazání adresáře mimo WordPress odinstalační postup nespustí.

Pravidla synchronizace a exportu

• Zápis výsledku API a automatického stavu používá krátkou transakci s řádkovými zámky InnoDB. Pod zámkem porovnává aktuální stav objednávky, úplný seznam shipping itemů a jejich podací čísla i stavová metadata. Síťové požadavky probíhají mimo transakci.
• Při souběžném stornu, změně zásilky, nedostupném zámku, netransakční tabulce nebo již otevřené cizí transakci se zápis odloží; nevytváří se nechráněný fallback. Pro nAPI zápisy jsou potřebné InnoDB objednávkové a shipping-item tabulky. Chyba order_write_deferred se objeví ve WooCommerce logu.
• Smíšené objednávky s dalšími dopravci standardně nemění celkový stav. Vlastní koordinátor může udělit souhlas filtrem balikovna_wc_allow_mixed_carrier_mapping až po ověření ostatních zásilek.
• Kurzor synchronizace uchovává zbytek nedokončené stránky a znovu ověřuje jeho způsobilost, takže oříznutí dávky nezahazuje objednávky.
• Export odmítne neúplnou, neplatnou nebo nadlimitní hmotnost. Nové sazby ukládají efektivní smluvní limit balikovna_max_weight_kg; starší Balíkovna plus bez snapshotu používá konzervativně 31,5 kg. Historický vyšší smluvní limit lze potvrdit uložením metadat příslušného shipping itemu přes WooCommerce CRUD.
• Pro více kusů se kontroluje konzervativní stohovaný obal: maxima dvou delších stran a součet nejkratších stran všech kusů. Nehledá se optimální balení. Obchod s vlastní balicí logikou může dodat skutečné rozměry filtrem balikovna_wc_package_metrics; katalogové údaje nezahrnují automaticky tloušťku obalu.
• Obnova seznamu poboček je chráněná sdíleným zámkem. Po selhání následuje pětiminutový odstup; během něj se použije pouze ještě povolená nouzová cache. Denní workflow Pickup Directory Contract sleduje velikost a parsovatelnost obou veřejných seznamů.

Rozsah a známá omezení

• Plugin aktuálně končí vytvořením objednávky a CSV pro Podání Online; zásilku automaticky nezakládá u České pošty.
• nAPI integrace je pouze pro čtení stavů. Není implementováno automatické podání/vytvoření zásilky, tisk štítků, storno, vratka, svoz, manifest ani jiná write operace.
• Synchronizace začíná až po ručním nebo jiným systémem provedeném uložení platného podacího čísla ke shipping itemu a vyžaduje smluvní B2B nAPI přístup České pošty.
• Vzácné nebo nově přidané agregované stavy bez jednoznačně zveřejněné sémantiky zůstávají bez výchozí změny objednávky a nadále se kontrolují. Správce je může namapovat po ověření významu.
• Běh závisí na Action Scheduleru/WP-Cronu. Na webu bez návštěv je nutné spouštět wp-cron.php externě.
• Produktové prefixy a kódy doplňkových služeb závisejí na smlouvě odesílatele a musí odpovídat jeho konfiguraci Podání Online.
• Veřejně dostupný JSON seznam bodů funguje se současným widgetem, ale není publikovaný jako verzované veřejné API; plugin toto riziko omezuje validací, cache limitem a možností nahradit zdroj filtrem.
• Plugin neregistruje wc-shipped, wc-ready-pickup ani vlastní zákaznické e-mailové šablony. Použije je pouze tehdy, když je poskytuje jiný plugin nebo vlastní kód webu.

Roadmap

• [ ] B2B-ZSK nAPI – idempotentní vytvoření zásilek a uložení přidělených podacích kódů
• [ ] Tisk PDF štítků, storna, svozy, manifesty a podací reporty
• [ ] Vratky a související B2B workflow
• [ ] Alternativní picker až nad stabilním a dokumentovaným číselníkem výdejních míst
• [x] Reálné integrační a end-to-end testy Classic/Block Checkoutu, CPT a HPOS
• [ ] Akceptační testy skutečných platebních bran, nAPI a importu Podání Online
• [ ] Integrace s Block Checkoutem na úrovni logo/branding shipping metody

Bezpečnost

Bezpečnostní problémy hlaste prosím privátně – viz SECURITY.md.

Licence

GPL-3.0-or-later. Loga České pošty / Balíkovny jsou majetkem Česká pošta, s.p., a jsou použita v souladu s jejich veřejnou dostupností pro implementaci výdejních míst.