Návod: eFakturuj pre WooCommerce krok za krokom

Toto je technický návod na zapojenie WooCommerce e-shopu do eFakturuj: čo sa deje pod kapotou, ako plugin nainštalovať a spárovať, ako nastaviť pravidlá fakturácie a ako celé prepojenie prevádzkovať a opraviť, keď niečo zlyhá.

Návod platí pre plugin eFakturuj for WooCommerce 1.0.1. Vyžaduje WordPress 6.5 a PHP 7.4, je otestovaný až po WordPress 7.0 a overený na WordPresse 7.0.1 s WooCommerce 10.9.4.

Čo prepojenie robí

Z objednávky vo WooCommerce vznikne v eFakturuj faktúra, z vrátenia tovaru prepojený dobropis a z potvrdenej platby záznam o úhrade. Doklady potom žijú v eFakturuj, odkiaľ ich viete odoslať aj cez Peppol.

Dôležitejšie je, ako sa to deje. Plugin počas objednávky nekomunikuje s eFakturuj vôbec.

WooCommerce hook (objednávka, platba, vrátenie)
        ↓  (žiadne HTTP volanie, iba zápis)
zašifrovaná fronta v databáze WordPressu (AES-256-GCM)
        ↓  Action Scheduler na pozadí
podpísané doručenie (HMAC-SHA256, presné bajty)
        ↓
eFakturuj: import → faktúra / dobropis / úhrada
        ↓  podpísané zisťovanie stavu
lokálna projekcia dokladov + overené odkazy v administrácii

Hook iba uloží nemennú kanonickú snímku objednávky do vlastnej tabuľky, zašifrovanú kľúčom odvodeným z AUTH_KEY vášho WordPressu. Pokladňa nečaká na sieť a výpadok eFakturuj nedokáže objednávku zdržať ani zhodiť. Fronta sa doručí, keď je spojenie znova dostupné.

Predpoklady

• WordPress 6.5 alebo novší, PHP 7.4 alebo novší;
• WooCommerce s aktívnym Action Scheduler (je jeho súčasťou);
• server, ktorý sa vie dostať na verejnú adresu API eFakturuj cez HTTPS;
• účet eFakturuj a firma, pod ktorú bude e-shop fakturovať;
• rola s oprávnením manage_woocommerce.

Prepojenie nepotrebuje ani heslo do eFakturuj, ani WooCommerce REST API kľúč. Plugin číta objednávky cez interné CRUD rozhranie WooCommerce.

Inštalácia krok za krokom

1. Nainštalujte aplikáciu WooCommerce v eFakturuj

V eFakturuj otvorte sekciu aplikácií, vyberte firmu, pod ktorú má e-shop fakturovať, a nainštalujte aplikáciu WooCommerce. Dostanete jednorazový párovací kód v tvare EFWC1:<tenant>:<secret>.

Kód platí 15 minút, ukladá sa iba ako hash a po prvom úspešnom spárovaní prestane fungovať. Ak vám medzitým vyprší, vygenerujte nový.

2. Nahrajte a aktivujte plugin

Vo WordPresse otvorte Pluginy → Pridať nový → Nahrať plugin, nahrajte archív efakturuj-for-woocommerce-1.0.1.zip, zvoľte Inštalovať a plugin aktivujte.

Cez WP-CLI je to jeden príkaz:

wp plugin install /cesta/efakturuj-for-woocommerce-1.0.1.zip --activate

Aktivácia vytvorí alebo aktualizuje tabuľku fronty. Zaradenie do katalógu pluginov na WordPress.org pripravujeme; dovtedy vám inštalačný ZIP pošleme priamo.

3. Spárujte e-shop

Otvorte WooCommerce → eFakturuj settings. Vyplňte verejnú adresu API eFakturuj bez koncovky /api/v1, vložte párovací kód a kliknite na Connect to eFakturuj.

Pri párovaní sa adresa e-shopu (home_url()) normalizuje a naviaže na spojenie. Ten istý e-shop sa preto nedá potichu prepojiť na inú firmu a skopírovaný kód neprenesie existujúci e-shop inam.

4. Nastavte, ktoré objednávky sa majú fakturovať

Plugin má tri režimy a v predvolenom nastavení je ten najopatrnejší:

1. Iba objednávky, kde zákazník o faktúru požiadal. Predvolené. Plugin vie do pokladne pridať vlastné zaškrtávacie políčko.
2. Podľa poľa z inej doplnky. Ak už políčko „chcem faktúru“ máte, zadáte kľúč jeho order-meta a plugin bude čítať ten.
3. Všetky objednávky v povolených stavoch, keď fakturujete úplne všetko.

Objednávka, ktorú zákazník neoznačil, sa označí ako skipped. Objednávka, ktorú označil, ale nemá minimálne fakturačné údaje, skončí ako needs_attention, aby ste ju videli a doplnili.

5. Skontrolujte dve nezávislé brány stavov

Toto je miesto, kde sa najčastejšie robí chyba pri nastavovaní. Sú dve brány a musia sedieť obe:

• V plugine vyberiete stavy objednávok WooCommerce, napríklad Spracováva sa alebo Dokončená.
• V eFakturuj má aplikácia vlastný zoznam povolených stavov, predvolene processing a completed.

Ak objednávka prejde bránou pluginu, ale nezodpovedá povolenému stavu v eFakturuj, doklad nevznikne. Odporúčame stav, pri ktorom sú už známe konečné položky, doprava, zľavy a fakturačné údaje.

Overenie prvej objednávky

Otvorte WooCommerce → eFakturuj invoices. Tu sa prevádzkuje celé prepojenie.

Postup overenia:

1. V sekcii Background synchronization health skontrolujte, že beží Action Scheduler a že sa zaznamenala aktivita.
2. Vytvorte skúšobnú objednávku s firemnými fakturačnými údajmi a označeným políčkom pre faktúru.
3. Presuňte ju do zvoleného stavu.
4. Kliknite na Run synchronization now, ak nechcete čakať na plánovač.
5. V zozname sa objaví doklad so stavom Completed a odkazmi Open a PDF.

V eFakturuj potom skontrolujte obchodné meno, IČO, DIČ a IČ DPH odberateľa, položky, dopravu, sadzby a sumy DPH, menu, dátumy a celkovú sumu.

Karta pri objednávke a manuálne odoslanie

Plugin deklaruje kompatibilitu s HPOS, takže karta funguje aj v novej rýchlej správe objednávok, aj v klasickom editore.

Send/update in eFakturuj obíde automatické pravidlo pluginu, nie však účtovné pravidlá eFakturuj. Akcia vyžaduje oprávnenie manage_woocommerce a platný nonce.

Vrátenia tovaru a dobropisy

Z vrátenia vo WooCommerce vzniká dobropis typu 381 prepojený s pôvodnou faktúrou. Prepojenie prevezme presné rozpisy položiek, dopravy, poplatkov a jednotlivých sadzieb DPH, takže funguje aj čiastočné vrátenie.

Dve pravidlá, ktoré stoja za pozornosť:

• Úhrada na dobropise vznikne iba vtedy, keď to dáta z WooCommerce dokazujú. Samotný záznam o vrátení ešte nie je dôkazom, že peniaze naozaj odišli.
• Nejednoznačné vrátenie skončí ako needs_review. Vrátenie zadané iba sumou, chýbajúci rozpis DPH alebo nesediaci súčet nevytvoria odhadnutý doklad. Radšej dostanete upozornenie než dobropis, ktorý by ste opravovali v účtovníctve.

Prevádzka: čo robiť, keď niečo zlyhá

Automatické doručenie má päť pokusov s narastajúcim odstupom a prijatá udalosť má až dvanásť podpísaných kontrol stavu. Ak sa ani tak nedokončí, máte v histórii dve akcie s odlišným účtovným významom.

Akcia	Čo urobí	Kedy ju použiť
Retry delivery	Pošle znova presne tie isté zašifrované bajty pod rovnakým identifikátorom udalosti.	Výpadok siete, plánovača alebo servera. Údaje sú správne, zlyhal iba prenos.
Send latest data	Načíta objednávku nanovo, vytvorí novú snímku s novým identifikátorom a pôvodný riadok ponechá ako audit.	Zdrojové údaje ste opravili, alebo doklad skončil ako needs_attention či needs_review.

Opakované doručenie zámerne nevidí opravy: posiela pôvodné bajty. Na opravu je určené Send latest data.

Ak sa udalosti hromadia, pozrite WooCommerce → Stav → Logy so zdrojom efakturuj-woocommerce. V logoch nikdy nie sú prihlasovacie údaje ani obsah faktúr.

Bezpečnosť

• Žiadne trvalé prihlasovacie údaje. Párovanie prebehne jednorazovým kódom; podpisový kľúč sa zobrazí raz a obe strany si ho uložia zašifrovaný.
• Šifrovaná fronta. Kanonická snímka objednávky leží vo vašej databáze ako AES-256-GCM šifrový text s kľúčom odvodeným z AUTH_KEY.
• Podpísané doručenie. HMAC-SHA256 sa počíta nad časovou pečiatkou, identifikátorom udalosti a presnými bajtami tela. Rovnaké ID s inými bajtami server odmietne.
• Ochrana pred opakovaním. Požiadavky mimo päťminútového okna sa zahodia a podpísané POST požiadavky nesledujú presmerovania.
• Odkazy na doklady nie sú prístupové linky. Open a PDF vedú na bežné adresy v eFakturuj, ktoré vyžadujú prihlásenie používateľa oprávneného pre danú firmu.

Odpojenie a odinštalovanie

Deaktivácia zachová nastavenia aj frontu pre neskoršie zapnutie. Disconnect zmaže lokálne prihlasovacie údaje a zruší naplánované úlohy; riadky fronty zostanú pre audit, ale bez platného spojenia sa nedoručia. Zmazanie pluginu odstráni jeho nastavenia, naplánované úlohy aj šifrovanú tabuľku fronty.

Ani jedna z týchto akcií nezmaže doklady v eFakturuj. Účtovníctvo zostáva tam, kam patrí.

Overené a neoverené

Vydanie 1.0.1 prešlo 27 izolovanými akceptačnými testami na WordPresse 7.0.1 a WooCommerce 10.9.4 vrátane oficiálneho nástroja Plugin Check bez jedinej chyby a kontroly vykreslenia administrácie v slovenčine.

Je to dôkaz z riadenej testovacej zostavy, nie dôkaz o rozsiahlom nasadení v produkcii. Jedno spojenie znamená jeden e-shop a jednu firmu v eFakturuj.

Ako začať

Založte si účet eFakturuj, otvorte sekciu Aplikácie a nainštalujte WooCommerce. Ak si netrúfate na párovanie alebo na výber stavov objednávok, prejdeme to spolu; je to súčasť podpory, nie platená služba.

Vytvoriť účet eFakturuj →

Máte neštandardné sadzby DPH, zložitejšie dopravné, vlastné úpravy pokladne alebo väčší objem objednávok? Napíšte nám a pozrieme sa na váš e-shop skôr, než čokoľvek inštalujete.