Allimedia ICO Lookup for WooCommerce – dokumentace

K čemu plugin slouží

Allimedia ICO Lookup for WooCommerce přidává do pokladny WooCommerce pole IČO a DIČ. Zákazník může podle českého IČO vyhledat firmu ve veřejném registru ARES a automaticky doplnit její název a fakturační adresu.

Plugin podporuje klasickou pokladnu vytvořenou shortcode i moderní blokovou pokladnu WooCommerce. Údaje ukládá prostřednictvím WooCommerce API a je kompatibilní s High-Performance Order Storage (HPOS).

Hlavní funkce

• pole IČO a DIČ v klasické i blokové pokladně;
• ruční vyhledání firmy tlačítkem Doplnit z ARES;
• volitelné automatické vyhledání po zadání osmi číslic IČO;
• kontrola formátu a kontrolního součtu českého IČO;
• ověření formátu českého DIČ;
• doplnění názvu firmy, ulice, čísla domu, města, PSČ a země;
• uložení IČO a DIČ k objednávce;
• předvyplnění IČO a DIČ přihlášenému zákazníkovi při příštím nákupu;
• zobrazení IČO a DIČ ve formátované fakturační adrese objednávky;
• samostatný sloupec IČO v seznamu objednávek;
• podpora klasického úložiště objednávek i HPOS;
• cache úspěšných odpovědí ARES a ochrana proti nadměrnému počtu požadavků;
• integrace s nástroji WordPressu a WooCommerce pro ochranu osobních údajů;
• volitelné a bezpečně validované nastavení vzhledu polí a tlačítka.

Požadavky

• WordPress 6.0 nebo novější;
• WooCommerce 7.2 nebo novější;
• PHP 8.1 nebo novější;
• HTTPS připojení serveru k veřejnému API na doméně ares.gov.cz.

Plugin ve verzi 1.1.14 je testovaný do WordPressu 7.1 a WooCommerce 11.1.

Instalace

Instalace z adresáře WordPress.org

1. Přihlaste se do administrace WordPressu.
2. Otevřete Pluginy → Instalace pluginů.
3. Vyhledejte Allimedia ICO Lookup for WooCommerce.
4. Klikněte na Instalovat a následně na Aktivovat.
5. Zkontrolujte, že je aktivní také WooCommerce.

Instalace ze ZIP souboru

1. V administraci WordPressu otevřete Pluginy → Instalace pluginů.
2. Klikněte na Nahrát plugin.
3. Vyberte ZIP soubor pluginu a spusťte instalaci.
4. Po dokončení plugin aktivujte.
5. Zkontrolujte, že je aktivní také WooCommerce.

Po aktivaci není potřeba vytvářet pole ručně. Plugin je automaticky přidá do podporované pokladny WooCommerce.

Rychlé zprovoznění

1. Otevřete WooCommerce → Nastavení → Allimedia ICO Lookup for WooCommerce.
2. Ponechte zapnutou volbu Zobrazit tlačítko Doplnit.
3. Rozhodněte, zda má být IČO povinné.
4. Volitelně zapněte automatické vyhledávání.
5. Nastavení uložte.
6. Otevřete pokladnu jako zákazník a otestujte vyhledání pomocí platného českého IČO.

Nastavení pluginu

Nastavení najdete v administraci na stránce WooCommerce → Nastavení → Allimedia ICO Lookup for WooCommerce.

Zobrazit tlačítko Doplnit

Zapne nebo skryje tlačítko Doplnit z ARES v pokladně.

Výchozí hodnota: zapnuto.

Pokud tlačítko skryjete a současně nepovolíte automatické vyhledávání, zákazník může IČO a DIČ stále zadat ručně, ale údaje firmy se z ARES automaticky nedoplní.

Automatické doplnění

Po zadání osmi číslic IČO automaticky spustí vyhledání firmy. Stejné IČO se během práce s formulářem zbytečně nevyhledává opakovaně.

Výchozí hodnota: vypnuto.

IČO povinné

Pokud je tato volba aktivní, objednávku nelze dokončit bez platně vyplněného IČO. DIČ zůstává nepovinné.

Výchozí hodnota: vypnuto.

Vlastní vzhled polí a tlačítka

Ve výchozím stavu přebírá plugin vzhled aktivní WordPress šablony. Po zapnutí vlastních stylů lze samostatně nastavit:

• zaoblení polí;
• zaoblení tlačítka;
• barvu pozadí tlačítka;
• barvu textu tlačítka;
• šířku a barvu rámečku tlačítka;
• barvy a rámeček tlačítka po najetí kurzorem.

Hodnoty jsou validované a plugin z nich výsledný styl vytvoří automaticky. Plugin neobsahuje pole pro vkládání libovolného CSS kódu.

Použití v pokladně

Postup zákazníka

1. Zákazník zadá své osmimístné české IČO.
2. Klikne na Doplnit z ARES. Pokud je zapnuté automatické vyhledávání, spustí se dotaz sám po zadání osmé číslice.
3. Plugin ověří základní formát a kontrolní součet IČO.
4. Server obchodu vyhledá subjekt ve veřejném registru ARES.
5. Do pokladny se doplní dostupné firemní údaje.
6. Zákazník může doplněné hodnoty před odesláním objednávky zkontrolovat a upravit.

Doplňované údaje

Podle dat dostupných v ARES může plugin doplnit:

• název společnosti;
• DIČ;
• ulici a číslo domu;
• město;
• PSČ;
• zemi Česká republika.

Jméno, příjmení, e-mail a telefon zákazníka plugin nemění. Pokud ARES některý údaj neposkytne, příslušné pole zůstane beze změny a zákazník jej může vyplnit ručně.

Klasická pokladna

V klasické pokladně jsou IČO a DIČ součástí fakturačních polí. Vyhledané údaje se doplní do fakturační adresy.

Bloková pokladna

V blokové pokladně se panel IČO a DIČ zobrazuje nad doručovací adresou, takže je viditelný i při zapnuté volbě pro použití stejné doručovací a fakturační adresy.

Pokud zákazník používá stejnou adresu pro doručení a fakturaci, plugin doplní údaje firmy do obou adres. Pokud má zákazník samostatnou fakturační adresu, údaje z ARES se doplní pouze do fakturační adresy.

Přepnutí mezi společnou a samostatnou fakturační adresou nesmaže již zadané IČO ani DIČ.

Validace IČO a DIČ

IČO

Plugin před dotazem do ARES i před uložením objednávky ověřuje, že IČO:

• obsahuje osm číslic;
• není tvořeno pouze nulami;
• odpovídá kontrolnímu součtu českého IČO.

Mezery a jiné oddělovací znaky se při zpracování odstraní. IČO se ukládá v normalizovaném osmimístném tvaru.

DIČ

České DIČ musí mít tvar CZ následovaný 8 až 10 číslicemi, například CZ12345678. Mezery se odstraní a písmena se převedou na velká.

DIČ není povinné. Pokud je však vyplněné, musí odpovídat podporovanému českému formátu.

Ukládání a zobrazení údajů

Platné IČO a DIČ se uloží k objednávce přes WooCommerce CRUD API. Díky tomu plugin podporuje klasické úložiště objednávek i HPOS.

Údaje se následně zobrazují:

• ve formátované fakturační adrese objednávky;
• v e-mailech a dokumentech, které používají standardní formátovanou fakturační adresu WooCommerce;
• v administraci objednávky;
• IČO také v samostatném sloupci seznamu objednávek.

U přihlášeného zákazníka se platné IČO a DIČ uloží také do jeho fakturačního profilu a při příštím nákupu se automaticky předvyplní. U nákupu bez registrace se údaje ukládají pouze k objednávce.

Kompatibilita s fakturačními a účetními pluginy závisí na tom, zda daný plugin používá standardní fakturační adresu WooCommerce nebo umí načíst metadata objednávky _billing_ico a _billing_dic.

Napojení na ARES

Plugin používá veřejné REST API ARES provozované Ministerstvem financí České republiky. Pro jeho používání není potřeba účet ani API klíč.

Dotaz do ARES se odešle pouze po ručním spuštění vyhledání nebo po zadání kompletního IČO, pokud je povoleno automatické vyhledávání. Komunikaci s ARES provádí server e-shopu, nikoli společnost Allimedia.

Cache odpovědí

Úspěšné odpovědi ARES se ukládají do WordPress transients na 24 hodin. Opakovaný dotaz na stejné IČO se během této doby obvykle načte z cache a nezatěžuje ARES.

Omezení počtu požadavků

Nezacachované požadavky jsou ve výchozím nastavení omezeny na:

• 10 požadavků za minutu pro jednoho zákazníka;
• 120 požadavků za minutu pro celý obchod.

Po dosažení limitu je potřeba počkat do začátku dalšího minutového okna. Limity chrání web i veřejnou službu ARES před zneužitím.

Ochrana soukromí

Plugin neobsahuje sledování návštěvníků, nepoužívá licenční server a neposílá data společnosti Allimedia.

Při vyhledání firmy se do ARES odešle zadané IČO. Standardní HTTP hlavička WordPressu může obsahovat také verzi WordPressu a URL obchodu. ARES vrátí veřejné identifikační a adresní údaje firmy.

Dočasný limit požadavků pro jednoho zákazníka používá pouze hash identifikátoru WooCommerce session, případně IP adresy. Tento údaj expiruje po skončení minutového okna. IČO ani DIČ se neukládají do cookies.

Plugin přidává doporučený text do průvodce Nastavení → Soukromí → Průvodce zásadami ochrany osobních údajů. Provozovatel e-shopu by měl text zkontrolovat a přizpůsobit konkrétním podmínkám svého webu.

IČO a DIČ jsou zahrnuty do exportu osobních údajů WordPressu. Schválený požadavek na výmaz je odstraní z fakturačního profilu zákazníka. Jejich anonymizace nebo odstranění z objednávek se řídí nastavením WooCommerce pro výmaz osobních údajů a dobou uchování objednávek.

Doporučený text do zásad ochrany osobních údajů

Při použití vyhledání firmy odešle náš server zadané IČO do veřejné služby ARES provozované Ministerstvem financí České republiky. ARES vrátí veřejné identifikační a adresní údaje firmy. Standardní HTTP hlavička může obsahovat verzi WordPressu a adresu našeho webu. Úspěšné odpovědi mohou být v databázi webu uloženy po dobu 24 hodin. IČO a DIČ ukládáme jako fakturační údaje k objednávce a u přihlášených zákazníků také do jejich zákaznického profilu pro budoucí nákupy. Data nejsou odesílána společnosti Allimedia.

Řešení problémů

Pole IČO a DIČ se v pokladně nezobrazují

• Ověřte, že jsou aktivní WooCommerce i Allimedia ICO Lookup for WooCommerce.
• Zkontrolujte, že stránka používá standardní klasickou nebo blokovou pokladnu WooCommerce.
• Vymažte cache webu, optimalizačního pluginu, CDN a prohlížeče.
• Pokud používáte vlastní checkout builder nebo výrazně upravenou šablonu pokladny, otestujte standardní pokladnu WooCommerce. Nestandardní struktura může vyžadovat individuální kompatibilitu.

Nezobrazuje se tlačítko Doplnit z ARES

• V nastavení pluginu zapněte volbu Zobrazit tlačítko Doplnit.
• Vymažte cache stránky a minifikovaných JavaScript souborů.
• Zkontrolujte, zda tlačítko neskrývá CSS aktivní šablony.

ARES firmu nenajde

• Zkontrolujte, že zadáváte platné osmimístné české IČO.
• Ověřte, zda je subjekt dohledatelný přímo ve veřejném registru ARES.
• Zkuste vyhledání později; služba ARES může být dočasně nedostupná.

Zobrazí se chyba připojení k ARES

• Ověřte, že server může navázat odchozí HTTPS spojení na ares.gov.cz.
• Zkontrolujte firewall, bezpečnostní plugin a pravidla hostingu.
• Ověřte platnost SSL certifikátů a správné datum a čas serveru.

Byl překročen limit požadavků

Počkejte do dalšího minutového okna a poté vyhledání zopakujte. Výsledky, které již jsou v cache, se do limitu nezapočítávají.

Údaje se doplní, ale objednávku nelze odeslat

• Ověřte, že používáte aktuální verzi pluginu.
• Vymažte cache webu, CDN a prohlížeče, aby se načetl aktuální JavaScript.
• Zkontrolujte platnost IČO a případně ručně zadaného DIČ.
• Dočasně vypněte optimalizaci nebo slučování JavaScriptu a otestujte pokladnu znovu.
• Otestujte konflikt s jiným pluginem upravujícím pokladnu.

Vzhled polí nebo tlačítka neodpovídá šabloně

Nejprve vypněte vlastní vzhled pluginu a ověřte výchozí styl aktivní šablony. Poté zapínejte jednotlivé vizuální volby postupně. Pokud problém zůstává, zkontrolujte vlastní CSS šablony nebo page builderu.

WordPress hlásí aktivní starší kopii pluginu

Na stránce Pluginy deaktivujte starší kopii se slugem ico-lookup-for-woocommerce a ponechte aktivní pouze aktuální plugin allimedia-ico-lookup-for-woocommerce. Plugin z bezpečnostních důvodů nenačítá dvě kopie současně.

Časté dotazy

Potřebuji účet nebo API klíč ARES?

Ne. Plugin používá veřejné API ARES bez registrace a bez API klíče.

Funguje plugin pro slovenské nebo jiné zahraniční firmy?

Ne. Vyhledávání a validace jsou určeny pro české IČO a české DIČ.

Může zákazník zadat údaje ručně?

Ano. IČO, DIČ i všechny fakturační údaje lze upravit ručně. Vyhledání v ARES je pomocná funkce, nikoli podmínka, pokud správce nenastaví IČO jako povinné.

Funguje plugin pro nepřihlášené zákazníky?

Ano. Vyhledání i uložení údajů k objednávce funguje také pro nákup bez registrace. Předvyplnění při příštím nákupu je dostupné pouze přihlášeným zákazníkům.

Podporuje plugin HPOS?

Ano. Plugin deklaruje kompatibilitu s HPOS a data objednávek ukládá přes WooCommerce CRUD API.

Podporuje klasickou i blokovou pokladnu?

Ano. Oba typy standardní pokladny WooCommerce jsou podporované.

Co se stane při deaktivaci nebo odinstalaci?

Deaktivace pluginu zachová jeho nastavení i uložené údaje. Při odinstalaci se odstraní nastavení pluginu. IČO a DIČ již uložené v objednávkách a zákaznických profilech zůstávají součástí obchodních a fakturačních záznamů a jejich odstranění se řídí nástroji ochrany osobních údajů a retenčními pravidly WooCommerce. Dočasné cache ARES automaticky expirují.

Informace pro vývojáře

Plugin nabízí následující filtry:

• allimedia_woo_ico_lookup_ares_cache_ttl – délka cache úspěšné odpovědi ARES v sekundách; výchozí hodnota je 86 400 sekund a minimální hodnota 60 sekund;
• allimedia_woo_ico_lookup_ares_client_rate_limit – počet nezacachovaných požadavků jednoho klienta za minutu; výchozí hodnota je 10;
• allimedia_woo_ico_lookup_ares_rate_limit – celkový počet nezacachovaných požadavků webu za minutu; výchozí hodnota je 120;
• allimedia_woo_ico_lookup_billing_fields – úprava polí IČO a DIČ v klasické pokladně.

Metadata objednávky:

• _billing_ico – IČO;
• _billing_dic – DIČ.

Metadata zákazníka:

• billing_ico – IČO;
• billing_dic – DIČ.

Plugin používá vlastní REST endpoint pod namespace allimedia-woo-ico-lookup/v1. Požadavky z pokladny jsou chráněné WordPress REST nonce.

Externí zdroje

• Informace a provozní podmínky ARES
• Dokumentace REST API ARES
• Informace Ministerstva financí o zpracování osobních údajů

Podpora

Pokud potřebujete pomoc s instalací, nastavením nebo kompatibilitou pluginu, kontaktujte nás:

Allimedia.cz
E-mail: info@allimedia.cz
Web: https://allimedia.cz