Ak vám účtovníctvo vedie účtovníčka v KROSe (v cloudovej službe KROS Fakturácia), nemusíte jej faktúry z e-shopu posielať e-mailom ani ich prepisovať. Branike PDF Faktúry pošle každú vystavenú faktúru do KROSu samo — a keď v KROSe uvidia, že zákazník zaplatil, plugin to zistí a objednávku na webe posunie ďalej.
Tento návod vysvetľuje, čo prepojenie robí, čo na to potrebujete, ako ho nastaviť krok za krokom, čo sa deje automaticky a čo robiť, keď niečo nefunguje. Na konci je aj zoznam vecí, ktoré prepojenie nerobí — aby ste ich nečakali.
1. Ako to funguje: faktúru vystavuje web, KROS má kópiu
Najdôležitejšia vec na začiatok: faktúru vystavuje váš web, nie KROS. Číslo faktúry, variabilný symbol, PDF aj QR kód na platbu vzniknú v plugine. Do KROSu potom odíde presná kópia s tým istým číslom. Hovoríme tomu zrkadlo.
Z toho vyplýva jedno pravidlo: faktúry upravujte len na webe, nikdy v KROSe. Každá faktúra, ktorá príde z webu, má v KROSe internú poznámku „Vystavené e-shopom — upravovať len vo Woo.” Keby ste ju v KROSe zmenili, zákazník by mal v rukách iný doklad, než aký máte v účtovníctve.
Prepojenie funguje oboma smermi:
| Smer | Čo sa prenáša |
|---|---|
| Web → KROS | každá vystavená faktúra; voliteľne aj úhrada kartou |
| KROS → web | potvrdenie, že KROS faktúru prijal; informácia, koľko je na faktúre zaplatené |
2. Čo potrebujete
- Účet v KROS Fakturácii s prístupom k API. API je „dvere” do programu, cez ktoré si dva systémy vymieňajú údaje bez človeka. Keď KROS odmietne prístup s hlásením o licencii (HTTP 402), vaša licencia KROSu na to nestačí alebo vypršala — to rieši KROS, nie plugin.
- API token z KROSu. Token (niekedy „API kľúč”) je dlhý tajný reťazec, ktorým sa plugin v KROSe preukazuje — ako heslo, ale len pre jeden účel. Kto ho má, môže do vašej firmy v KROSe zapisovať faktúry, preto ho nikomu neposielajte.
- Číselný rad faktúr v KROSe, do ktorého budú faktúry z webu padať. Jeho kód má najviac 5 znakov (napríklad
ESH). - Autorizačný kľúč pre notifikácie — vymyslíte si ho sami (viac v kroku 4).
- Administrátorský prístup k webu. Nastavenia prepojenia vidí a mení len administrátor.
- Prepojenú banku v KROSe, ak chcete, aby sa platby prevodom párovali samy. Plugin sa do banky nepozerá — pýta sa KROSu. Keď KROS o platbe nevie, nevie o nej ani web.
3. Nastavenie krok za krokom
Krok 1: vygenerujte token v KROSe
V KROS Fakturácii otvorte Nastavenia firmy → API prepojenia a vygenerujte token. Token sa zobrazí len raz — skopírujte si ho hneď. Ak ho stratíte, vygenerujete nový.
Krok 2: pripravte číselný rad
V KROSe založte číselný rad faktúr pre e-shop a zapamätajte si jeho kód. Formát čísla v tomto rade musí zodpovedať formátu, v akom čísluje faktúry plugin (PDF Faktúry → Číselné rady) — do KROSu totiž ide naše číslo a KROS ho musí vedieť prijať.
Kód radu KROSu viete zadať na dvoch miestach:
- pri konektore KROS v poli Kód číselného radu v KROSe — platí pre všetky faktúry,
- alebo priamo pri číselnom rade v plugine v poli Kód radu v účtovníctve — ten má prednosť. Hodí sa, keď máte viac činností (napríklad e-shop a poradenstvo) a každá má v KROSe vlastný rad.
Krok 3: vyplňte konektor na webe
Otvorte PDF Faktúry → Nastavenia → záložka Integrácie a nájdite blok KROS Fakturácia.
- Zaškrtnite Automaticky odosielať po vystavení dokladu. Bez tohto zaškrtnutia je prepojenie vypnuté celé — neodosielajú sa faktúry a nebeží ani párovanie úhrad.
- Do poľa API token (Bearer) vložte token z kroku 1.
- Vyplňte Kód číselného radu v KROSe (povinné) (ak ste ho nezadali pri rade).
- Do poľa Webhook secret (povinné) zadajte autorizačný kľúč (vysvetlenie v kroku 4).
- Pole ID bankového účtu v KROSe (voliteľné) nechajte prázdne — plugin si hlavný účet nájde sám. Vyplníte ho len vtedy, keď máte v KROSe viac účtov a posielate do KROSu platby kartou.
- Kliknite Uložiť nastavenia a až potom Test pripojenia. Zelená správa „Token akceptovaný — pripojenie funguje.” znamená, že KROS token pozná.
Kľúče sa ukladajú zašifrované a po uložení sa už nezobrazujú. Keď ich chcete zmeniť, pole jednoducho prepíšte; prázdne pole ponechá pôvodný kľúč. Na tej istej záložke je rámček Bezpečnosť API kľúčov s tlačidlom Zabezpečiť kľúče — jedným klikom nastaví samostatný šifrovací kľúč a stačí ho stlačiť raz. Potom tlačidlo zmizne a rámček ukáže, že kľúče sú zabezpečené.
Krok 4: nastavte notifikácie v KROSe
Notifikácia (odborne webhook) je krátka správa, ktorú KROS sám pošle na váš web, keď sa niečo stane — napríklad keď faktúru spracoval. Web ju prijíma na konkrétnej adrese.
Aby nikto cudzí nemohol na web posielať falošné správy „faktúra je v poriadku”, každá notifikácia je podpísaná. Podpis vzniká z autorizačného kľúča, ktorý poznáte len vy, KROS a váš web. Je to tajný text, ktorý si vymyslíte — čím dlhší a náhodnejší, tým lepšie.
Pod konektorom KROS nájdete riadok Nastavenie v KROSe. V ňom je:
- URL pre príjem notifikácií z API — tučne, s tlačidlom Kopírovať. V KROSe ju vložte do poľa pre URL notifikácií vo vašom API prepojení.
- Autorizačný kľúč — v KROSe zadajte presne ten istý text, aký máte na webe v poli Webhook secret. Uložte na oboch stranách.
- V KROSe zapnite oba prepínače notifikácií (o platbách aj o zmenách dokladov) a prepojenie uložte.
Dôležité: bez vyplneného Webhook secret web odmietne každú notifikáciu. Kým pole nevyplníte, administrátor uvidí v administrácii upozornenie.
Krok 5: overte prvú faktúru
Vystavte faktúru (alebo počkajte na prvú objednávku). Potom:
- v PDF Faktúry → Všetky doklady by mala mať faktúra pod číslom zelený štítok ✓ KROS Fakturácia (znamená, že KROS faktúru prijal),
- v nastaveniach konektora v riadku Posledné notifikácie z KROSu pribudne záznam s časom a počtom dokladov a úhrad („doklady: 1, úhrady: 0″),
- faktúra sa objaví v KROSe v zvolenom rade s rovnakým číslom.
Ak sa v notifikáciách objaví červený riadok odmietnuté (HTTP 401), kľúč v KROSe a na webe sa nezhoduje. Pozrite si ich znova — stačí jeden znak navyše.
4. Čo sa deje automaticky a kedy
Po vystavení faktúry
Hneď ako plugin faktúru vystaví — z objednávky, ručne cez Nová faktúra alebo opakovanú faktúru — pošle ju do KROSu. Ide tam:
- odberateľ s adresou, e-mailom, telefónom, IČO, DIČ a IČ DPH,
- všetky položky vrátane poštovného a poplatkov, sumy s DPH a sadzba DPH,
- naše číslo faktúry, variabilný symbol, dátum vystavenia, dátum dodania (rovnaký ako dátum vystavenia), splatnosť, mena, číslo objednávky a spôsob platby.
KROS doklady spracúva s oneskorením (asynchrónne): najprv ich prijme do poradia a až potom zapíše. Zelený štítok ✓ v zozname dokladov preto svieti už vtedy, keď KROS faktúru prijal do poradia. Či ju naozaj zapísal, potvrdí až jeho notifikácia; keby zápis zlyhal, štítok sa zmení na červený ✗ s dôvodom od KROSu. Pri potvrdzujúcej notifikácii si web zároveň zapamätá, pod akým číslom faktúru eviduje KROS. Bez toho by sa neskôr nevedel spýtať na úhradu.
Kontrola súčtu pred odoslaním
Skôr než faktúra odíde, plugin skontroluje, či súčet riadkov sedí so sumou faktúry a pri objednávke z e-shopu aj so sumou objednávky. Keď nesedí, neodošle nič a dôvod napíše k faktúre. Zrkadlo so zlou sumou by bolo horšie ako žiadne.
Rozdiel pol centa, ktorý vzniká pri zaokrúhľovaní DPH na riadkoch, plugin dorovná sám — pripočíta ho k najväčšiemu riadku. Väčší rozdiel už nie je zaokrúhlenie a faktúra sa zastaví.
Automatika úhrad (každých 15 minút)
Toto je časť, pre ktorú si väčšina e-shopov prepojenie zapína. Zákazník zaplatí prevodom, banka platbu pošle do KROSu, KROS ju podľa variabilného symbolu priradí k faktúre — a web sa to dozvie sám.
- Každých 15 minút sa web pýta KROSu, koľko je zaplatené na každej ešte nezaplatenej faktúre.
- Sleduje faktúry 30 dní od vystavenia. Staršie sa už nepýta.
- Na jedno kolo sa pýta najviac na 25 faktúr, od najstaršej. Ďalšie prídu na rad o 15 minút.
- Keď je suma pokrytá celá, faktúra sa označí ako zaplatená a objednávka na webe sa dokončí rovnako, ako keby prišla platba cez bránu. K objednávke pribudne poznámka „Platbu potvrdil KROS (banka ju spárovala s faktúrou).”
- Keď príde len časť sumy, úhrada sa zaeviduje, objednávka ostáva čakať na platbu a web sa pýta ďalej, kým sa suma nedorovná.
- Na stornovanú alebo vrátenú objednávku sa nesiaha.
Nezáleží na tom, či úhradu v KROSe spárovala banka, alebo ju tam zapísala účtovníčka — web sa pýta na stav faktúry v KROSe, nie na banku.
Kontrola beží ako plánovaná úloha WordPressu a zapne sa sama, keď je konektor KROS zapnutý a má token. Samostatný prepínač nemá.
Pozor na jednu vec: sledujú sa len faktúry, nie zálohové faktúry. Ak váš e-shop vystavuje pri objednávke zálohovú faktúru a ostrú faktúru až po zaplatení, KROS nemá čo spárovať — ostrá faktúra ešte neexistuje. Aby automatika fungovala, nastavte v PDF Faktúry → Nastavenia → WooCommerce vystavenie faktúry na stav, do ktorého objednávka prejde hneď po objednaní s platbou prevodom.
Variabilný symbol
Pri objednávke z e-shopu je variabilný symbol číslo objednávky bez písmen. Rovnaký symbol je na faktúre, v QR kóde aj v e-maile, ktorý zákazník dostane. KROS prijme variabilný symbol najviac s 10 číslicami — s dlhším by ho banka nespárovala, a preto plugin takú faktúru do KROSu vôbec nepošle.
Platby kartou (voliteľné)
Ak zaškrtnete Posielať platby kartou do KROSu, plugin po zaplatení objednávky kartou (alebo inou online bránou) pošle do KROSu aj úhradu — raz, hneď po zaplatení. Prevod, dobierku a šek neposiela nikdy; tie do KROSu prinesie banka. Úhrada kartou odíde len vtedy, keď je faktúra v KROSe; inak sa k objednávke zapíše poznámka, že platba odoslaná nebola. Predvolene je táto voľba vypnutá.
5. Kde vidíte, či všetko beží
Pri faktúre v zozname dokladov (PDF Faktúry → Všetky doklady):
- ✓ KROS Fakturácia (zelená) — KROS faktúru prijal (po myši: „odoslané”),
- · KROS Fakturácia (sivá) — ešte neodoslaná (po myši: „neodoslané”),
- ✗ KROS Fakturácia (červená) — chyba. Keď na štítok prejdete myšou, uvidíte jej presné znenie.
Pri sivom a červenom štítku je tlačidlo ↻ (Odoslať znova) — faktúru pošle znova. Použiť ho môže administrátor.
Pod konektorom KROS v nastaveniach sú tri diagnostické riadky:
- Nastavenie v KROSe — adresa pre notifikácie a postup.
- Automatika úhrad — kedy kontrola bežala naposledy, na koľko faktúr sa pýtala, koľko úhrad zaevidovala a koľko bolo chýb („dotazovaných faktúr: …, zaevidovaných úhrad: …, chýb: …”). Pri chybe je pod tým červený riadok Posledná chyba: s interným označením dokladu (#…) a textom od KROSu. Ak ešte nebežala, uvidíte „Zatiaľ sa nespustila.”
- Posledné notifikácie z KROSu — posledných 10 správ, ktoré KROS poslal (s obsahom na rozkliknutie), a nad nimi červené riadky s odmietnutými pokusmi.
Tieto riadky vidí len administrátor.
6. Keď niečo zlyhá
| Čo vidíte | Čo to znamená | Čo urobiť |
|---|---|---|
| Test pripojenia: „Neplatný alebo chýbajúci token (HTTP 401).” | KROS token nepozná | vygenerujte nový token a vložte ho znova |
| „Nedostatočná alebo vypršaná licencia KROS (HTTP 402).” | licencia KROSu na API nestačí | riešte s KROSom |
| „KROS: príliš veľa požiadaviek, skúste to neskôr (HTTP 429).” | KROS dočasne obmedzil počet volaní | počkajte a skúste ↻ neskôr |
| „KROS: duplicitná požiadavka alebo konflikt čísla dokladu (HTTP 409).” | v rade KROSu už je doklad s týmto číslom | skontrolujte číselný rad v KROSe |
| „KROS: chýba kód číselného radu alebo má viac ako 5 znakov — doklad sa neodoslal.” | chýba kód radu KROSu | doplňte ho (krok 2) |
| „KROS: číslo dokladu je prázdne alebo dlhšie ako 20 znakov — doklad sa neodoslal.” | formát čísla je pre KROS príliš dlhý | skráťte formát radu v plugine |
| „KROS: variabilný symbol je prázdny alebo má viac ako 10 číslic, banka by platbu nespárovala — nič sa neodoslalo.” | VS by banka nespárovala | skontrolujte číslovanie objednávok |
| „KROS: súčet riadkov (…) nesedí so sumou dokladu (…)” alebo „KROS: suma dokladu (…) nesedí so sumou objednávky (…)” | doklad si protirečí | nič neodišlo; opravte príčinu a pošlite znova cez ↻ |
| „KROS spracovanie zlyhalo (status …).” alebo iný text od KROSu | KROS doklad prijal, ale nezapísal | text je priamo od KROSu — podľa neho opravte a pošlite znova |
| V notifikáciách: odmietnuté (HTTP 401) | autorizačný kľúč sa nezhoduje | zjednoťte ho v KROSe aj na webe |
| V notifikáciách: odmietnuté (HTTP 403) | na webe chýba Webhook secret | vyplňte ho |
| „Faktúry, na ktoré sa nedá spýtať, lebo KROS ešte neposlal ich ID: N” | KROS nepotvrdil faktúru notifikáciou | skontrolujte krok 4; kým notifikácia nepríde, úhradu nevie web zistiť |
| „Automatika úhrad” dlho ukazuje ten istý čas | plánovaná úloha nebeží | otvorte hocijakú stránku webu; ak čas stále nerastie, požiadajte hosting o kontrolu plánovaných úloh WordPressu |
Faktúra, ktorá sa neodoslala, sa nestratí. Ostane na webe, zákazník ju má, a do KROSu ju pošlete tlačidlom ↻, keď príčinu odstránite.
7. Čo prepojenie nerobí
- Neposiela zálohové faktúry ani dobropisy. Do KROSu ide zatiaľ len faktúra. Dobropis a zálohovú faktúru zaevidujte v KROSe inak (napríklad exportom).
- Neprenáša zmeny z KROSu späť na web. Úprava alebo storno faktúry v KROSe sa na web nedostane. Opravujte na webe — a opravu robte dobropisom.
- Nesleduje faktúry staršie ako 30 dní. Úhradu, ktorá príde neskôr, spárujte ručne a objednávku prepnite sami.
- Nepozerá sa do banky. Všetko, čo web o platbe prevodom vie, vie od KROSu.
- Neposiela do KROSu platby prevodom, dobierkou ani šekom — ani vtedy, keď máte zapnuté posielanie platieb kartou.
- Nehádže úhradu na jednu z dvoch faktúr s rovnakým variabilným symbolom. Keď KROS pošle úhradu, ktorú web vie priradiť len podľa variabilného symbolu, a ten symbol má viac faktúr, web radšej nezapíše nič, než by zapísal úhradu na nesprávnu faktúru.
- Nenahrádza účtovníctvo. Plugin doklady vystaví a doručí; účtovanie, výkazy a priznania ostávajú v KROSe a na účtovníčke.
8. Tipy z praxe
- Pred ostrým spustením vystavte jednu faktúru na seba a sledujte ju celú cestu: ✓ v zozname dokladov, záznam v notifikáciách, faktúra v KROSe, a po zaplatení poznámka v objednávke.
- Nemeňte formát číselného radu po tom, čo ste ho zladili s KROSom. Keď ho zmeníte na jednom mieste, zmeňte ho aj na druhom.
- Autorizačný kľúč si uložte do správcu hesiel. Keď budete prepojenie v KROSe nastavovať znova, bude sa vám hodiť.
- Pozrite sa raz za čas na riadok „Automatika úhrad”. Nula chýb a rastúci čas znamenajú, že všetko beží.