Woo - Variabilní symbol - dokumentace

K čemu plugin slouží

Plugin používá číslo WooCommerce objednávky, které vidí zákazník, jako variabilní symbol pro platbu. Zobrazuje jej přímo v podrobnostech objednávky, v zákaznickém účtu a ve WooCommerce e-mailech.

Číslo objednávky získává přes standardní metodu WooCommerce WC_Order::get_order_number(). Díky tomu podporuje také většinu pluginů, které nahrazují běžná ID vlastní číselnou řadou objednávek.

Plugin kontroluje, zda výsledný variabilní symbol:

obsahuje pouze číslice;
má délku 1 až 10 číslic;
nepoužívá jiná objednávka.

Pokud číslo objednávky nelze bezpečně použít, plugin zvolí interní ID objednávky. Správce může variabilní symbol také nastavit ručně.

Hlavní funkce

Variabilní symbol odpovídající zákazníkem viditelnému číslu objednávky.
Podpora pluginů pro vlastní číslování objednávek.
Automatické odstranění prefixů, písmen, mezer a oddělovačů.
Kontrola bankovního formátu 1 až 10 číslic.
Ochrana proti duplicitním variabilním symbolům.
Bezpečný fallback na interní ID objednávky.
Ruční nastavení hodnoty u konkrétní objednávky.
Výběr podporovaných platebních metod.
Zobrazení na děkovací stránce a v zákaznickém účtu.
Zobrazení v zákaznických i administračních e-mailech.
Volitelné zvýraznění a vlastní barvy.
Stabilní CSS třídy pro vlastní vzhled.
Shortcode pro ruční umístění.
Podpora klasického ukládání objednávek i HPOS.
Vlastní licence a aktualizace přes Allimedia.cz.

Požadavky

WordPress 6.2 nebo novější
WooCommerce 8.0 nebo novější
PHP 8.1 nebo novější
Aktivní licence pluginu

Instalace

Nainstalujte a aktivujte WooCommerce.
V administraci WordPressu otevřete Pluginy → Instalace pluginů.
Klikněte na Nahrát plugin a vyberte instalační ZIP.
Plugin nainstalujte a aktivujte.
Otevřete WooCommerce → Variabilní symbol → Licence.
Zadejte licenční klíč a klikněte na Aktivovat licenci.
Na záložce Nastavení vyberte platební metody a místa zobrazení.

Aktivace licence

Licence se váže na doménu webu. Pokud chcete plugin přesunout na jinou doménu, nejprve licenci na původním webu deaktivujte.

Plugin kontroluje stav licence jednou denně. Při dočasném výpadku licenčního serveru může využít ochrannou lhůtu v délce až 14 dnů od posledního úspěšného ověření.

Bez platné licence:

se nevytvářejí nové variabilní symboly;
nelze měnit již uložené hodnoty;
nelze stahovat nové aktualizace pluginu.

Variabilní symboly uložené u existujících objednávek zůstávají zákazníkům zobrazené, aby nezmizely jejich platební instrukce.

Nastavení

Nastavení najdete na stránce WooCommerce → Variabilní symbol → Nastavení.

Popisek

Určuje text zobrazený před hodnotou variabilního symbolu. Výchozí hodnota je Variabilní symbol.

Popisek lze změnit například na:

VS
Variabilní symbol platby
Referenční číslo platby

Platební metody

Vyberte platební metody, u kterých se má variabilní symbol používat. Ve výchozím nastavení je povolený přímý bankovní převod (bacs).

Variabilní symbol se nezobrazí u objednávek vytvořených pomocí nepovolené platební metody.

Více platebních metod vyberete pomocí klávesy Ctrl ve Windows a Linuxu nebo Cmd v macOS.

Místa zobrazení

Samostatně můžete povolit následující místa:

děkovací stránka po vytvoření objednávky;
detail objednávky v zákaznickém účtu;
zákaznické e-maily;
e-maily správci obchodu.

Na děkovací stránce a v zákaznickém účtu je variabilní symbol součástí podrobností objednávky. V zákaznickém e-mailu je umístěn za bankovními údaji a před rekapitulací objednávky.

Zvýraznění symbolu

Vestavěné zvýraznění lze zapnout nebo vypnout. Při zapnutém zvýraznění můžete nastavit:

barvu pozadí;
barvu textu;
barvu rámečku.

Barvy se zadávají ve formátu HEX, například #eaf5ec.

Po vypnutí zvýraznění zůstane variabilní symbol běžně čitelný, ale bez barevného štítku. Jeho vzhled potom můžete upravit vlastním CSS.

Jak se variabilní symbol vytváří

Český variabilní symbol může obsahovat pouze 1 až 10 číslic.

Viditelné číslo objednávky	Výsledný variabilní symbol	Způsob zpracování
`123456`	`123456`	Přesná shoda
`OBJ-2026-1234`	`20261234`	Odstranění prefixu a oddělovačů
`OBJEDNAVKA`	interní ID objednávky	Číslo neobsahuje použitelnou číselnou část
`20260000001234`	interní ID objednávky	Číselná část je delší než 10 číslic

Automaticky vytvořený symbol si pamatuje původní zobrazené číslo objednávky. Pokud je plugin pro vlastní číslování později změní, variabilní symbol se při dalším použití přepočítá. Ručně nastavená hodnota se automaticky nemění.

Ochrana proti duplicitám

Po odstranění písmen a oddělovačů mohou dvě různá čísla objednávek vytvořit stejnou hodnotu.

Například:

CZ-2026-100
SK-2026-100

Obě čísla by se převedla na 2026100. Plugin proto před uložením ověřuje, zda stejný symbol již nepoužívá jiná objednávka. Při kolizi použije interní ID objednávky, aby bylo možné platby jednoznačně párovat.

Vlastní čísla objednávek

Plugin pracuje s hodnotou vrácenou standardní metodou WooCommerce:

WC_Order::get_order_number()

Díky tomu podporuje většinu rozšíření, která mění čísla objednávek standardním způsobem.

Pokud vlastní číslo obsahuje písmena, prefix nebo oddělovače, plugin použije jeho číselnou část. Pokud výsledná hodnota nesplňuje pravidlo 1 až 10 číslic, použije interní ID objednávky.

Ruční nastavení variabilního symbolu

Otevřete objednávku v administraci WooCommerce.
Vyhledejte část Variabilní symbol.
Zadejte hodnotu obsahující 1 až 10 číslic.
Zaškrtněte Použít tuto hodnotu ručně.
Objednávku uložte.

Ruční hodnota musí být platná a nesmí ji používat jiná objednávka.

Chcete-li se vrátit k automatické hodnotě, zrušte zaškrtnutí možnosti Použít tuto hodnotu ručně a objednávku znovu uložte.

Pro vytvoření nebo změnu variabilního symbolu je nutná platná licence.

Sloupec v seznamu objednávek

Plugin přidává do seznamu WooCommerce objednávek sloupec VS. Správce v něm rychle uvidí aktuální variabilní symbol a po najetí také způsob jeho vytvoření.

Sloupec funguje v klasickém ukládání objednávek i při zapnutém HPOS.

Zobrazení v e-mailech

Zákaznické e-maily

Variabilní symbol se zobrazuje za bankovními údaji a před rekapitulací objednávky. Toto pořadí platí pro HTML i čistě textové e-maily.

Výstup respektuje nastavený popisek, zapnutí zvýraznění i vlastní barvy.

E-maily správci

V e-mailech správci se variabilní symbol zobrazuje v metadatech objednávky. Toto zobrazení lze samostatně vypnout v nastavení pluginu.

Shortcode

Variabilní symbol můžete vložit ručně pomocí shortcodu:

[allimedia_wvs_variabilni_symbol]

Na děkovací stránce nebo v detailu objednávky plugin automaticky rozpozná aktuální objednávku.

Zobrazení bez popisku

[allimedia_wvs_variabilni_symbol show_label="no"]

Vlastní CSS třída

[allimedia_wvs_variabilni_symbol class="moje-trida"]

Konkrétní objednávka

[allimedia_wvs_variabilni_symbol order_id="123"]

Z bezpečnostních důvodů se konkrétní objednávka zobrazí pouze:

jejímu vlastníkovi;
správci WooCommerce;
návštěvníkovi s platným klíčem objednávky v URL.

Shortcode proto nelze použít k zobrazení cizích objednávek.

Vlastní vzhled pomocí CSS

Plugin používá následující stabilní CSS třídy:

.allimedia-wvs-payment-reference {}
.allimedia-wvs-variable-symbol__value {}
.allimedia-wvs-payment-reference__hint {}
.allimedia-wvs-payment-reference--highlighted {}

Příklad vlastního vzhledu:

.allimedia-wvs-payment-reference {
    padding: 16px;
    border-radius: 6px;
}

.allimedia-wvs-variable-symbol__value {
    color: #222222;
    font-size: 20px;
    font-weight: 700;
    letter-spacing: 0.08em;
}

.allimedia-wvs-payment-reference__hint {
    display: block;
    margin-top: 5px;
    color: #666666;
}

Styl pluginu je ve WordPressu registrován pod označením allimedia-wvs-frontend. Vývojář jej může standardním způsobem odebrat nebo nahradit.

Aktualizace pluginu

Dostupné aktualizace se zobrazují standardně na stránce Pluginy v administraci WordPressu. Pro stažení aktualizace je nutná platná licence.

Aktualizační balíčky jsou přijímány pouze přes zabezpečené HTTPS spojení z povolené domény Allimedia.cz.

Pokud se očekávaná aktualizace nezobrazuje:

ověřte platnost licence;
otevřete Nástěnka → Aktualizace;
spusťte novou kontrolu aktualizací;
případně znovu ověřte licenci.

Externí služba a ochrana soukromí

Plugin neodesílá objednávky ani osobní údaje zákazníků.

Pro aktivaci licence, její pravidelnou validaci a kontrolu aktualizací komunikuje přes HTTPS s licenčním API:

https://allimedia.cz/wp-json/allimedia-lmfw/v1

Odesílány jsou pouze technické údaje potřebné pro licenci a aktualizace:

licenční klíč;
doména a URL webu;
identifikace pluginu;
nainstalovaná verze pluginu.

Odinstalování

Před úplným odinstalováním doporučujeme licenci nejprve deaktivovat. Tím se její aktivace uvolní pro použití na jiném webu.

Při běžném odinstalování plugin odstraní:

své nastavení;
licenční údaje;
cache aktualizací;
naplánovanou kontrolu licence.

Variabilní symboly uložené u historických objednávek zůstanou zachované.

Pokud chcete při odinstalování odstranit také všechna objednávková metadata pluginu, přidejte před odinstalováním do souboru wp-config.php:

define( 'ALLIMEDIA_WVS_REMOVE_ORDER_DATA_ON_UNINSTALL', true );

Tuto možnost používejte pouze tehdy, pokud historická data skutečně nechcete zachovat.

Řešení problémů

Variabilní symbol se nezobrazuje

Ověřte:

zda je licence aktivní;
zda objednávka používá povolenou platební metodu;
zda je dané místo zobrazení zapnuté;
zda má objednávka uložený nebo platně vytvořený symbol.

Pokud licence skončila, zobrazují se pouze dříve vytvořené a uložené symboly. Nové symboly bez platné licence nevznikají.

Variabilní symbol se liší od čísla objednávky

Zobrazené číslo pravděpodobně obsahuje písmena, oddělovače nebo více než 10 číslic. Plugin musí vytvořit hodnotu odpovídající bankovnímu formátu, proto odstraní nečíselné znaky nebo použije interní ID objednávky.

Podrobnosti o způsobu vytvoření najdete v administraci konkrétní objednávky.

Plugin použil interní ID objednávky

K tomu dojde, pokud:

číslo objednávky neobsahuje žádné číslice;
výsledná číselná hodnota má více než 10 číslic;
stejný variabilní symbol již používá jiná objednávka;
nelze bezpečně vytvořit jinou jedinečnou hodnotu.

Správce může následně nastavit vlastní ruční variabilní symbol.

Ruční hodnotu nelze uložit

Ruční hodnota musí:

obsahovat pouze číslice;
mít délku 1 až 10 číslic;
být jedinečná;
nepoužívat ji jiná objednávka.

Pro změnu je nutná platná licence.

Po skončení licence se symbol stále zobrazuje

Jde o správné chování. Plugin zachovává zobrazení dříve uložených symbolů, aby zákazníkům nezmizely platební instrukce existujících objednávek.

Bez licence se však nevytvářejí nové hodnoty a nelze měnit stávající.

Pro vývojáře

Plugin poskytuje následující filtry:

allimedia_wvs_visible_order_number – úprava zdrojového čísla objednávky;
allimedia_wvs_generated_result – úprava vygenerovaného výsledku;
allimedia_wvs_payment_methods – změna podporovaných platebních metod;
allimedia_wvs_variable_symbol_html – úprava HTML výstupu shortcodu;
allimedia_wvs_license_api_url – změna URL licenčního API;
allimedia_wvs_update_cache_ttl – změna doby uložení informací o aktualizaci v cache.

Technická kompatibilita

Plugin podporuje:

klasické ukládání WooCommerce objednávek;
WooCommerce HPOS;
klasickou i blokovou děkovací stránku;
HTML i čistě textové e-maily;
vlastní číslování objednávek založené na standardním WooCommerce API.

Podpora

Allimedia.cz
info@allimedia.cz
https://allimedia.cz

Woo – Variabilní symbol – dokumentace