Tento návod vysvětluje všechny obrazovky pluginu krok za krokem. Nepotřebujete žádné programování – stačí mít přístup do WordPress administrace. Příručka je psaná pro běžné uživatele e-shopu, kteří chtějí zvládnout kompletní nastavení sami.
1. Přehled funkcí
- Automatické vystavování proforma i finálních faktur podle stavu objednávky.
- Ukládání dokladů k objednávkám a posílání PDF nebo bezpečných odkazů zákazníkům.
- Propojení se Fakturoidem přes API v3 včetně reakce na platby (webhooky).
- Automatizace refundů (dobropisy, storna) a možnost storna proformy při zrušení objednávky.
- Přehledné administrační tlačítko pro ruční akce a bezpečný download odkaz s náhodným saltem.
2. Co si připravit před instalací
- Přístup do WordPressu s rolí Správce.
- Aktivní WooCommerce (doporučená verze 7.0+).
- Firemní účet ve Fakturoidu s aktivovaným API v3.
- OAuth aplikace typu „Client credentials“ (Client ID a Client Secret, Account slug, kontaktní e-mail).
- Přehled platebních metod v e-shopu (bankovní převod, karta, dobírka…).
3. Instalace pluginu
- Získejte instalační balíček (
wc-fakturoid.zip). - Ve WordPressu otevřete Pluginy → Instalace pluginů → Nahrát plugin.
- Nahrajte soubor
wc-fakturoid.zipa klikněte na Instalovat. - Po instalaci stiskněte Aktivovat plugin.
- Po aktivaci najdete nastavení v menu České pluginy → Fakturoid pro WooCommerce.
Poznámka: Při instalaci se automaticky vytvoří bezpečnostní salt pro stahovací tokeny i tajný klíč pro webhooky. V nastavení je můžete kdykoli obnovit.
4. Struktura administrační stránky
Nastavení je rozdělené do tematických sekcí. Projděte je shora dolů a na konci klikněte na Uložit změny.
- Napojení na API – přístupové údaje a párování plateb.
- Nastavení proforma faktur – kdy se tvoří proformy a co se stane po zaplacení.
- Vytváření faktur – pravidla pro finální faktury a režim OSS.
- Webhooky – bezpečný přístup z Fakturoidu zpět do e-shopu.
- E-maily a bezpečné odkazy – přílohy PDF, webové odkazy a bezpečnostní salt.
- Refundy a vrácení objednávek – automatické dobropisy a poznámky.
- Zrušení objednávky – automatické storno proformy.
- Diagnostika a logování – debug režimy a retenční politika.
- Licence a aktualizace – práce s licenčním klíčem a podporou.
- Export a import nastavení – záloha konfigurace do JSON.
Niže najdete detailní popis každé sekce.
5. Napojení na API
Detailní návod → Tato část je nezbytná pro jakoukoli komunikaci s Fakturoidem.
| Pole | Popis | Doporučení |
|---|---|---|
| Slug Fakturoid účtu | Krátký identifikátor účtu v URL (např. moje-firma). | Zkopírujte ze stránky Nastavení → Účet ve Fakturoidu. |
| E-mail Fakturoid účtu | E-mail, který Fakturoid vidí v User-Agent hlavičkách. | Použijte technický nebo účetní kontakt, který máte pod kontrolou. |
| Client ID | Identifikátor OAuth aplikace. | Vložte bez mezer, nejlépe pomocí kopírování. |
| Client Secret | Tajný klíč OAuth aplikace. | Uložte na bezpečné místo, bez něj se plugin nepřipojí. |
| Spárování platebních metod | Přiřazení WooCommerce plateb k typům ve Fakturoidu (bank, cash, cod, card). | Nastavte pro všechny aktivní platební brány, ovlivňuje popisky a automatické uzavření dokladů. |
Po vyplnění klikněte na Uložit změny. Plugin:
- ověří připojení k API a stáhne dostupné číselné řady,
- uloží token platný cca 2 hodiny (automaticky se obnovuje),
- v případě chyby zobrazí varování nahoře.
Řešení potíží: Chybová hláška „Access token missing“ znamená nesprávné Client ID/Secret nebo blokovaný odchozí požadavek. Zkontrolujte údaje, případně firewall serveru.
6. Nastavení proforma faktur
Detailní návod → Použijete, pokud chcete vystavovat zálohové faktury před finálním dokladem.
| Pole | Co dělá | Jak nastavit |
|---|---|---|
| Vystavení proforma faktury | Stav objednávky, při kterém se proforma vytvoří. | Pro bankovní převod doporučujeme Čeká na platbu nebo Probíhá zpracování. |
| Zaplacení proforma faktury | Stav, který označí proformu jako uhrazenou. | Typicky Probíhá zpracování (po ověření platby) nebo Dokončeno u dobírky. |
| Po zaplacení proforma faktury vytvořit | Následná akce po zaplacení. | „Zaplacená faktura“ – klasický finální doklad. „Daňový dokument“ – vhodné pro zálohové platby. |
| Číselná řada proforma faktur | Výběr řady stažené z Fakturoidu. | Pokud nic nevidíte, uložte stránku – tím se řady načtou. |
Tip: Pokud žádné pole nevyplníte, proformy se nebudou tvořit a plugin přejde rovnou na finální faktury (viz další sekce).
7. Vytváření faktur
Detailní návod → Určuje, kdy vznikne finální faktura a kdy se označí jako zaplacená.
| Pole | Co dělá | Doporučené nastavení |
|---|---|---|
| Vystavení faktury | Stav WooCommerce, při kterém se vytvoří faktura ve Fakturoidu. | Online platby → Probíhá zpracování; dobírka → Dokončeno (po doručení). |
| Zaplacení faktury | Stav, kterým WooCommerce fakturu označí jako uhrazenou. | Online platby → Probíhá zpracování; dobírka → Dokončeno. |
| Režim OSS | Zobrazení informací o režimu One Stop Shop. | Vyberte „Služby“ nebo „Zboží“, pokud reportujete OSS, jinak ponechte „Vypnuto“. |
| Číselná řada faktur | Řada načtená z Fakturoidu. | Vyberte řadu, která odpovídá roku nebo typu dokladu. |
Pokud kombinujete proforma workflow a přímé faktury, plugin vyhodnotí situaci automaticky: pokud proforma existuje a je uhrazená, vytvoří finální fakturu podle tohoto nastavení.
8. Webhooky – reakce na platby z Fakturoidu
- V sekci „Webhooky“ najdete Webhook URL s tajným parametrem
key=.... - Klikněte na tlačítko Kopírovat a adresu vložte ve Fakturoidu do Nastavení → Webhooky.
- Doporučené události:
invoice_paid,payment_received. - Detailní návod →
- Webhook Secret – pouze pro čtení. Potřebuje ho Fakturoid pro podepsání zpráv.
- Tlačítko Znovu vygenerovat vygeneruje nové tajemství. Po kliknutí je nutné znovu uložit webhook ve Fakturoidu!
- Změna stavu po zaplacení – nastavte cílový stav pro každou přepravu (např. Balík do ruky →
Probíhá zpracování).
Bezpečnost: Webhook URL a secret chrání přístup zvenčí. Pokud URL náhodou zveřejníte, regenerujte secret jedním kliknutím.
9. E-maily a bezpečné stahování
| Pole | Co dělá | Doporučení |
|---|---|---|
| Přikládat PDF | Připojí PDF fakturu do e-mailu „Objednávka dokončena“. | Zapněte, pokud vaši zákazníci vyžadují PDF okamžitě. |
| Preferovat Webfakturu | Do e-mailu přidá odkaz na webovou fakturu místo PDF. | Vhodné, pokud nechcete zatěžovat e-maily velkými přílohami. |
| Bezpečnostní salt pro tokeny stažení | Tajný řetězec pro výpočet HMAC tokenu. | Salt se generuje při instalaci automaticky. Pokud chcete nový, klikněte na tlačítko Znovu vygenerovat – hodnota se doplní bez reloadu stránky. |
Bezpečnostní salt zvyšuje ochranu odkazů ke stažení. Odkazy jsou vázané na e-mail zákazníka a platí minimálně 24 hodin. Pokud salt změníte, staré odkazy přestanou fungovat (doporučujeme informovat zákazníky, pokud takovou změnu provedete).
10. Refundy a vrácení objednávek
Detailní návod → Automatizuje tvorbu dobropisů a storen.
| Pole | Co dělá | Vysvětlení |
|---|---|---|
| Zapnout automatizaci refundů | Aktivuje automatické doklady při refundu ve WooCommerce. | Po zapnutí plugin reaguje na každou refundaci. |
| Poznámka k opravnému dokladu | Text, který se propíše do komentáře dobropisu. | Např. „Vráceno do 14 dnů bez udání důvodu.“ |
| Číselná řada opravných dokladů | (Jen pro plátce DPH) – řada pro dobropisy. | Vyberte ze seznamu načteného z Fakturoidu. |
- Úplný refund (plátce DPH) → vystaví se opravný daňový doklad.
- Úplný refund (neplátce) → původní faktura se stornuje.
- Částečný refund → vytvoří se jeden opravný daňový doklad, další už Fakturoid nepovolí; další postup je nutné řešit ručně.
11. Zrušení objednávky
Detailní návod → Sekce „Zrušení objednávky“ obsahuje volbu Automaticky stornovat proformu při zrušení objednávky.
- Pokud je zaškrtnutá a objednávka se zruší, plugin najde neuhrazenou proformu.
- Odešle do Fakturoidu požadavek na storno.
- Zapíše poznámku do objednávky.
Pokud volbu necháte vypnutou, proformy zůstávají v Fakturoidu aktivní a případné storno provedete ručně.
12. Diagnostika a logování
Detailní návod → Tato sekce slouží k řešení problémů a sledování API komunikace.
| Pole | Co dělá | Kdy použít |
|---|---|---|
| Zapnout debug logování | Zapisuje diagnostické informace do souboru wp-content/debug.log. | Dočasně při hledání chyby. Nechte vypnuté v běžném provozu. |
| Logování volání Fakturoid API | Ukládá žádosti do databázové tabulky wc_fakturoid_api_logs. | „Pouze chyby“ je bezpečné; „Všechny požadavky“ berte jako krátkodobý režim. |
| Automatické mazání API logů | Četnost mazání záznamů (7, 30, 90 dní…). | Vyberte interval podle interní politiky – delší období = více dat v databázi. |
| Smazat data při odinstalaci | Zajistí kompletní odstranění nastavení, tokenů, tabulek i metadat při odinstalaci pluginu. | Zapínejte pouze tehdy, pokud opravdu chcete při odinstalaci vyčistit veškeré stopy pluginu. |
Pozor: Pokud zapnete debug logování nebo logování všech požadavků, sledujte velikost logů. Velké soubory mohou zpomalit server.
13. Licence
- Vložte licenční klíč do pole Licence.
- Klikněte na Aktivovat licenci.
- Úspěšná aktivace uzamkne pole pro úpravy a zobrazí datum expirace.
- Před přesunem na jiný web klikněte na Deaktivovat licenci.
Bez platné licence plugin funguje, ale nedostanete automatické aktualizace a podporu.
14. Export a import nastavení
Detailní návod → Ve spodní části stránky najdete dvě karty:
- Export do JSON – stáhne soubor se všemi nastaveními (bez licenčních údajů).
- Import z JSON – nahraje dříve uložený soubor a přepíše aktuální konfiguraci.
Vždy po importu zkontrolujte sekci Napojení na API a e-maily – zejména pokud přenášíte nastavení mezi produkcí a testem.
15. Ověření funkčnosti (doporučený postup)
- Vytvořte testovací objednávku s vlastní e-mailovou adresou.
- Změňte její stav podle nastavovaných pravidel (např.
Čeká na platbu→Probíhá zpracování). - V detailu objednávky najdete box Fakturoid s číslem faktury a odkazy.
- Otevřete e-mail „Objednávka dokončena“ a zkontrolujte přílohu nebo odkaz.
- Pokud používáte webhooky, označte fakturu ve Fakturoidu jako zaplacenou – WooCommerce by měl stav změnit do několika sekund.
16. Jak zákazník obdrží fakturu
- V e-mailu „Objednávka dokončena“ je přiložené PDF nebo tlačítko/odkaz „Stáhnout fakturu“.
- Odkaz vede na adresu
https://vas-web.cz/fakturoid-invoice/...a je zabezpečený HMAC tokenem. - Token je vázaný na e-mail zákazníka a čas objednávky. Pokud změníte salt, staré odkazy přestanou fungovat.
- V účtu zákazníka na vašem webu se zobrazí stejné odkazy v detailu objednávky.
17. Nejčastější potíže a řešení
- „Required Fakturoid API credentials are missing“ – některé pole v sekci Napojení na API je prázdné. Doplňte slug, Client ID a Client Secret a uložte.
- Faktura se nevystavila – stav objednávky neodpovídá spouštěči nebo už existuje číslo faktury. Zkontrolujte sekce Proforma/Faktury a případně smažte
_fakturoid_invoice_id. - PDF se nepřiložilo – mohla nastat dočasná chyba při stahování z Fakturoidu. Zkuste ruční stažení přes tlačítko v detailu objednávky nebo používejte webové odkazy.
- Webhook hlásí neplatný podpis – reaktivujte secret jedním kliknutím a aktualizujte URL ve Fakturoidu.
- Refund neproběhl – Fakturoid povoluje jen jeden opravný doklad na fakturu. Další refund řešte ručně a informaci zapište do objednávky.
- Salt se zdá prázdný – klikněte na „Znovu vygenerovat“ v sekci E-maily; hodnota se vyplní okamžitě bez přenačtení stránky.
18. Diagnostika problémů
- Při chybě otevřete detail objednávky. Plugin zapisuje poznámky typu „Fakturoid: …“ s detaily.
- Pokud máte zapnutý debug, zkontrolujte
wp-content/debug.log(vyžaduje přístup k souborům na serveru). - U webhostingu požádejte o povolení odchozího HTTPS. Plugin potřebuje komunikaci na
https://api.fakturoid.cz. - Máte-li podezření na vypršení přihlášení, jednoduše znovu uložte sekci Napojení na API – token se obnoví.
- Při blokaci kvůli limitům API počkejte pár minut a zkuste akci znovu. Informace o limitech je vidět v logu, pokud je zapnutý.
19. Často kladené dotazy
- Mohu fungovat bez proform? Ano, prostačí nevyplnit sekci Proforma a nastavit pouze sekci Vytváření faktur.
- Pracuji na více webech – potřebuji více saltů? Každá instalace pluginu má vlastní salt. Pokud kopírujete databázi, klikněte na „Znovu vygenerovat“, aby měl každý web unikátní hodnotu.
- Jak ručně znovu vystavit fakturu? V detailu objednávky klikněte na tlačítko „Vystavit znovu“. Předtím doporučujeme případnou starou fakturu ve Fakturoidu stornovat.
- Co když zákazník nedostal e-mail? Zkontrolujte log e-mailů ve WordPressu nebo pošlete fakturu ručně z detailu objednávky pomocí tlačítka „Odeslat e-mail znovu“.
- Jak dlouho mám uchovávat logy? Doporučené minimum je 30 dní, ale řiďte se interní politikou firmy. Přepněte volbu Automatické mazání podle potřeby.
20. Kde získat pomoc
- Oficiální web: https://ceskepluginy.cz/produkt/wc-fakturoid/
- E-mail podpory: podpora@ceskepluginy.cz
- Při kontaktování podpory si připravte číslo objednávky, popis problému a poslední poznámku z objednávky (pokud obsahuje chybové hlášení).
S touto příručkou zvládnete běžnou správu i pokročilejší scénáře. Pokud potřebujete konzultaci nebo nastavení na míru, obraťte se na dodavatele pluginu.