Dokumentace pluginu Toret iDoklad

Nacházíte se na stránkách dokumentace Toret pluginu WooCommerce iDoklad, který propojuje e-shop a fakturační systém iDoklad.

Pro použití pluginu je nutností účet v systému iDoklad s tarifem, který umožňuje využívat propojení přes API.

Instalace pluginu

Po zakoupení pluginu iDoklad obdržíte emailem licenční klíč a odkaz na stažení zip souboru s pluginem. Detailní návod, jak do WordPress nainstalovat plugin z počítače, najdete zde.

Aktivace pluginu

Po instalaci pluginu si otevřete plugin WooCommerce iDoklad, do příslušného pole vložte licenční klíč a ověřte licenci.

Videonávod

Základní nastavení – Propojení s iDokladem

Prvním krokem, který je potřeba udělat pro propojení pluginu s iDokladem, je registrovat se na stránkách www.idoklad.cz.

Pozor! iDoklad je dostupný ve více tarifech. Ověřte, zda vámi vybraný tarif umožňuje propojení přes API, které je pro propojení nezbytné.

Po vytvoření vašeho účtu a přihlášení se, přejděte do Nastavení (ikona ozubeného kolečka v levém menu) > Aplikace. Zde v záložce API vygenerujete přístupové klíče k propojení.

Zde si kliktnutím na tlačítko Generovat vygenerujete Vaše Client ID  a Client Secret a uložíte.

Tyto dva vygenerované údaje poté zadáte do pluginu iDoklad (Toret plugins -> iDoklad). Ve starších verzích se pro propojení používalo přihlašovací jméno a heslo na iDoklad.

Upozornění: Pokud bude zadání těchto údajů nesprávné, nebude možné vybrat platební metodu a přiřadit ji k objednávce.

Číselné řady

Pro správnou evidenci, fungování a párování zálohových a běžných faktur je nutné nastavení číselných řad. Je potřeba si uvědomit, že číselné řady se načítají automaticky.

Nejprve je nutné nastavit číselné řady na portále iDoklad a poté je synchronizovat v pluginu.

Po přihlášení jdeme do Nastavení > Prodej. Zde zvolte záložku Číslování.

Doporučujeme si pozorně přečíst veškeré komentáře a informace o tom, jak se číselné řady v iDokladu generují a nastavují, než tak učiníte a začnete faktury vystavovat.

Nejprve si nastavíme běžné faktury. Po kliknutí na tlačítko Nová (ikona s dokumentem se znaménkem +) se do přehledu přidá nový prázdný řádek pro číslování. Zde je potřeba vyplnit všechna pole. Vysvětlivky k jednotlivým polím se Vám zobrazí po kliknutí na ikonku otazníku.

Stejný postup zvolíme i u nastavení číselných řad pro zálohovou fakturu a dobropis, které najdete níže na stránce.

Pro běžné faktury a dobropisy lze vložit více číselných řad. Uplatňovat se bude ta, která je označená jako vybraná. Na závěr nezapomeňte provedené změny uložit – tlačítko Uložit najdete vpravo dole.

Po vytvoření a uložení číselných řad v iDokladu přejdeme k jejich propojení v pluginu. V administraci v menu otevřeme záložku Toret plugins > iDoklad.

Nastavení musí proběhnout ve 2 krocích. Aby vůbec bylo možné v polích pro číselné řady zvolit nějakou hodnotu, musí být nejprve vytvořené číselné řady načteny z iDokladu. To znamená, že v prvním kroku pouze klikneme na tlačítko Uložit.

Poté by již měly být k dispozici jednotlivé číselné řady. Sekce Výběr číselné řady pro fakturu, zálohou fakturu a dobropis najdete níže na stránce. Vyberte ty, které chcete používat a znovu klikněte na tlačítko Uložit.

DPH

IDoklad při generování faktury si sám spočítá DPH položek, podle přiřazených DPH sazeb v nastavení pluginu (viz přiřazování sazeb DPH).

Je důležité, aby v nastavení WooCommerce na kartě Obecné byla nastavena dvě desetinná místa. (WooCommerce > Nastavení > Obecné > Počet desetinných míst) Pokud zde bude nastaveno nula desetinných míst, tak je možné, že iDoklad bude počítat se zaokrouhlenou částkou a celková částka na faktuře nebude souhlasit s částkou v objednávce ve WooCommerci.

Pokud nechcete na webu zobrazovat desetinná místa u cen při nastavení dvou desetinných míst ve WooCommerci, tak do child šablony vložte script pro skrytí nul za desetinnou čárkou.

Režim OSS (One Stop Shop)

Plugin umí pracovat s režimem OSS. Povolíte jej v hlavním nastavení pluginu (Toret Plugins > iDoklad). Provedené změny nezapomeňte uložit.

Nastavení bankovních účtů pro různé měny

V nastavení pluginu pro iDoklad existuje také možnost nastavit bankovní účty pro různé měny, pokud prodáváte i do cizích zemí a máte pro vaše zákazníky tyto účty k dispozici.

Přejděte v administraci do Toret plugins > iDoklad. Ve spodní části stránky najdete následující tabulku.

Zadejte měnu, číslo účtu, kód banky, IBAN a příslušný SWIFT. Kliknutím na tlačítko Přidat řádek můžete přidat libovolný počet řádků pro další účty. Po zadání dat nezapomeňte vše uložit.

V praxi to znamená, že pokud bude objednávka např. v eurech, na faktuře bude uveden bankovní účet v eurech, tedy v měně objednávky.

IČ a DIČ

Vzhledem k tomu, že WooCommerce nativně neobsahuje pole pro IČ a DIČ, je nutné použít plugin. Pokud ho použijete, musí být zadána vlastní pole pro údaje IČ, DIČ a SK DIČ (u slovenských klientů), která umožní zákazníkům uvést tuto informaci na objednávkách.

Nastavení naleznete v menu pod záložkou Toret plugins > iDoklad.

Automatická kontrola plateb

Aplikace iDoklad obsahuje funkci kontroly plateb. Pokud nastavíte propojení bankovního účtu s iDokladem, v momentě, kdy bude na váš účet připsána platba s určitým variabilním symbolem, tento mechanismus je schopen tuto částku spárovat s příslušnou fakturou či proformou v iDokladu a potvrdit její zaplacení.

Pro přebírání informací o uhrazení faktury/proformy do WooCommerce lze využít cron, který bude v pravidelných intervalech uhrazení kontrolovat.

Pro nastavení automatické kontroly plateb vstupte do nastavení pluginu Toret plugins > iDoklad. Níže na stránce v sekci Změna stavu objednávky po uhrazení faktury najdete URL adresu, kterou zadáte do cronu na svém hostingu a zvolíte interval spouštění. Doporučená doba spouštění je 1x za hodinu. To znamená, že 1x za hodinu se bude automaticky kontrolovat uhrazení faktur.

Zde také nastavte, do jakého stavu se přepne objednávka po zjištění uhrazení faktury/proformy. Provedené změny uložte.

PDF doklady

Veškeré vystavené dokumenty k platbám, ať už se jedná o zálohovou fakturu, fakturu – daňový doklad nebo dobropis lze zobrazit a odeslat zákazníkovi ve formátu PDF.

Všechny PDF doklady je možné zobrazit v seznamu objednávek v menu pod záložkou WooCommerce – Objednávky, kliknutím na příslušný odkaz ve sloupci ID faktury.

V případě, že byla k objednávce vystavena i příslušná prodejka, tento odkaz je k dispozici ve stejném sloupci společně s fakturou.

Příklady PDF dokladů

Zálohová faktura

Faktura

Přiřazení daňových sazeb

Nastavení daňových sazeb pro váš e-shop je velmi důležité spárovat dle názvosloví/sazeb v iDokladu.

Standartní sazbu, obě snížené a nulovou je potřeba přiřadit pouze v případě, že tyto sazby daně používáte. To samé platí u daňových sazeb pro dopravu, kupóny a příplatky.

Nastavení pluginu najdeme v administraci v menu pod záložkou Toret plugins > iDoklad.

Vystavování faktur

V této kapitole si vysvětlíme vystavování faktur. Nejprve je třeba nastavit faktury v iDokladu. Po přihlášení do iDokladu přejdete do Nastavení > Prodej.

Na kartě Výchozí nastavení vyplňte údaje podle vašich potřeb. S vyplněním vám pomůže nápověda pod ikonami otazníků. Provedené změny uložte.

Na kartě Vzhled a tisk dokladů > Vydané faktury pak upravíte podobu, text a jazyk faktur. Provedené změny uložte.

Nastavení číslování faktur jsme se věnovali zde.

Po nastavení faktur v iDokladu je nutné ještě propojit vše s pluginem. Možnosti najdete v administraci v menu po levé straně v záložce Toret plugins > iDoklad.

Zde si můžete nastavit u každé platební metody, zda a v jakém stavu objednávky generovat fakturu.

Zákazník bude mít fakturu ke stažení v emailu objednávky.

Vy budete mít fakturu u objednávky ve WooCommerci ve sloupci ID faktury.

Své faktury najdete také a v administraci svého účtu na idoklad.cz.

Vystavování zálohových faktur

V této kapitole si vysvětlíme vystavování zálohových faktur (proforem). Nejprve je potřeba nastavit zálohové faktury v iDokladu. Zde si po přihlášení přejdete do Nastavení > Prodej > Vzhled a tisk dokladů > Zálohové faktury.

Zde upravíte podobu, text a jazyk faktur. Provedené změny uložte.

Po nastavení zálohových faktur v iDokladu je nutné ještě propojit vše s pluginem. Možnosti najdete v administraci v menu po levé straně v záložce Toret plugins > iDoklad v sekci Vytvoření proforma faktury.

Zde si můžete nastavit u každé platební metody, zda a v jakém stavu objednávky generovat zálohovou fakturu. Logicky vyplývá, že proforma by se měla generovat u platebních metod, kde nejsou finance připsány na váš účet okamžitě nebo jsou složeny v hotovosti, ale je zapotřebí určitý čas pro jejich převod na váš účet.

V tomto případě se u těchto platebních metod (např. Platba na dobírku a Bankovní převod) nastaví pro objednávku stav Čeká na vyřízení (viz obrázek níže) a příslušná zálohová faktura je zákazníkovi automaticky vygenerována a zaslána spolu s potvrzením objednávky e-mailem.

Odkaz na zálohovou fakturu v potvrzovacím e-mailu.

Jakmile je na Váš účet připsána částka a tím pádem se spáruje platba s příslušnou proforma fakturou, je automaticky vystavena faktura – daňový doklad v iDokladu a ve WooCommerce se stav objednávky změní na Dokončená (viz obrázek níže).

Každý zákazník také může kontrolovat stav svých objednávek po přihlášení se ke svému účtu na vašich webových stránkách po kliknutí na detail objednávky pod Můj účet – Objednávky.

Vystavování dobropisů

Stejně jako při vystavování faktur a proforem, i automatické vystavování dobropisů lze navázat na konkrétní stavy objednávek u jednotlivých platebních metod.

Uhrazování zálohových faktur

Uhrazení proformy a automatické vytvoření faktury.

Uhrazení faktur

Zde si vysvětlíme, jak nastavit uhrazení faktur v pluginu. V administraci si opět přejdeme do menu po levé straně, do záložky Toret plugins > iDoklad > Ve kterém stavu uhradit fakturu.

Nejprve je třeba si uvědomit, že vystavení faktury neznamená automaticky její zaplacení.

To je například zřejmé u platební metody Platba na dobírku, kdy je faktura vystavena při potvrzení objednávky a odeslána jak v potvrzovacím e-mailu, tak poté i společně s produktem v dobírce. Faktura je zaplacena teprve při převzetí zásilky zákazníkem a objednávka se mění do stavu Dokončeno.

Pokud chcete fakturu vystavit i uhradit zároveň, je potřeba mít hodnoty pro platební metodu, jak ve Vystavovat fakturu tak v Kdy uhradit fakturu, stejné. Viz obrázek níže.

Jediná výjimka je, pokud se rozhodnete vystavovat zálohové faktury. V tomto případě se po spárování této zálohové faktury s platbou okamžitě vytvoří již zaplacená odpovídající faktura – daňový doklad.

Přiřazení platebních metod

V této stručné kapitole si ukážeme, kde přiřadit druhy platby z iDokladu k jednotlivým platebním metodám v pluginu.

Opět si vyhledáme v menu po levé straně záložku Toret plugins > iDoklad.

Jak je již poznamenáno v samotném pluginu, pro správné označení faktur v iDokladu musí být každá platební metoda v e-shopu spárována s druhem platby.

Zobrazení v seznamu objednávek

Jakmile si zákazník zakoupí jakýkoliv produkt ve vašem e-shopu a dokončí objednávku, bude tato objednávka okamžitě viditelná v administraci pod záložkou WooCommerce > Objednávky. Zákazníkovi je také automaticky odeslán potvrzovací e-mail o dané objednávce.

Ve sloupci ID faktury najdete číslo příslušné faktury/proformy, pokud byla k objednávce vystavena. Kliknutím na číslo fakturu zobrazíte. V tomto sloupci uvidíte také případnou prodejku.

Ve sloupci iDoklad se zobrazují ikony pro vystavení faktury nebo proformy (čtverec se šipkou u objednávek bez vytvořené faktury), stažení faktury (PDF soubor), editaci faktury (tužka) a vystavení dobropisu (dvě šipky). Pro odeslání objednávek do iDokladu lze využít také hromadné akce.

V detailu objednávky je k dispozici iDoklad metabox, ve kterém můžete také vytvářet faktury, proformy a dopropisy, stáhnout je, či upravit.

Zobrazení názvu varianty na faktuře

Dalším důležitým prvkem v nastavení pluginu iDoklad je zobrazení názvu varianty produktu na faktuře. To znamená, jak bude produkt specifikován na faktuře včetně jeho vlastností jako např. barva a velikost.

Nejprve je tedy důležité mít již vytvořený primární produkt a jeho různé varianty dle vlastností. Jak si tedy tyto varianty nastavíte v menu pod Produkty, tak je budete mít k dispozici zde pro výběr názvu, který se bude zobrazovat na fakturách vystavovaných zákazníkům.

Příklad: Primární produkt je Tričko, varianty budou dle barvy a velikostí. Zákazník si zakoupí toto tričko v modré barvě a velikosti XXL. Na příslušné faktuře můžeme tedy zobrazit buď variantu „Tričko, Modrá XXL“  nebo včetně názvů vlastností „Tričko Barva: Modrá, Velikost: XXL“.

Zobrazení jednotky na faktuře

V pluginu je možné nastavit vlastní jednotku produktu, dopravy, nebo poplatku. Vlastní jednotky se propíšou na proforma fakturu i na běžnou fakturu. 

Pokud pole nebudou vyplněna, bude se používat výchozí hodnota „ks“.

Funkce je určena například pro e-shopy, které prodávají zboží na metry, kg ap.

Příklad nastavení:

Příklad produktu na faktuře: 

Nastavení odesílání e-mailů

V následující sekci si můžete přizpůsobit odesílání e-mailů s fakturami, proformami a dobropisy.

Checkboxy Zobrazit ikonu pro odeslání… slouží k zobrazení ikony pro manuální odeslání v přehledu objednávek (symbol obálky).

Při zaškrtnutí checkboxů Odeslat automaticky e-mail s… budou dané dokumenty odesílány e-mailem automaticky při jejich vytvoření. Dalšími checkboxy pak určíte, zda je chcete zasílat zákazníkovi, účetní a na firemní e-mail.

O něco níže můžete v nastavení upravit obsah e-mailů s fakturami a proformami.

Nastavení synchronizace skladu

V administraci iDokladu můžete využít funkce evidování skladových zásob a propojit je s položkami faktury. Pokud se na webu provede objednávka, tak se položka automaticky odečte ze skladu v administraci iDokladu.

Nastavení si projdeme v několika krocích:

Aktivace funkce v pluginu

Na webu přejděte do nastavení iDokladu v pluginu (Toret plugins > iDoklad).

V části nastavení pluginu Synchronizace skladu WooCommerce -> iDoklad aktivujte tuto funkci checkboxem, nastavte typ synchronizace a uložte. Rozdíl mezi typy synchronizace si vysvětlíme.

Pohyb skladu (i manuální) – To znamená, že skladovost (počet kusů skladem) se u importovaného produktu v iDokladu upraví i když ji manuálně upravíte u produktu ve WooCommerce.

Např. manuálně doplníte sklad daného produktu. Zároveň se bude počet kusů skladem synchronizovat i při objednávce nebo zrušení objednávky.

Snížení úrovně skladu (používá objednávka) – Tato funkce upraví počet kusů skladu v iDokladu jen objednávkou. Při manuální změně stavu skladu se sklad na straně iDokladu nesynchronizuje.

Po uložení nastavení se v levém menu administrace pod Toret plugins zobrazí karta iDoklad sync stock – pokud se po uložení tato karta nezobrazí aktualizujte stránku např. klávesou F5.

Export produktů z WooCommerce do iDokladu

Na stránce iDoklad sync stock je vypsán se seznam produktů ve WooCommerce. Tlačítkem „Exportovat položku do iDokladu“ se vytvoří produkt se skladovou zásobou ve službě iDoklad. Jako hodnota „Kód“ ve službě iDoklad se převede ID produktu nebo katalogové číslo (SKU), pokud je vyplněné.

Exportovat produkty z WooCommerce do iDokladu můžete také po 500 položkách pomocí tlačítka, které je na konci tabulky. 

Párování produktů

V případě, že máte v iDokladu již vytvořené produkty a chcete je spárovat s produkty z WooCommerce, postačí před exportem produktů v tabulce iDoklad sync stock upravit „iDoklad ID položky“ na hodnotu již vytvořeného ID produktu na straně iDokladu.

ID produktu v iDokladu najdete za lomítkem na konci URL v detailu iDoklad produktu (viz obr. níže)

Zkopírujte ID v detailu produktu ve službě iDoklad.

Vložte ID do pole iDoklad ID položky k produktu, který chcete spárovat, uložte a poté klikněte na tlačítko pro export produktu.

Jakmile dojde ke spárování produktu, tak se v iDokladu aktualizuje hodnota skladu, ceny a čárového kódu na hodnoty produktu z WooCommerce. 

Mazání exportovaných produktů – DŮLEŽITÉ

POZOR! Exportované produkty vždy mažte přes tabulku iDoklad sync stock pomocí červeného tlačítka „Odstranit položku v iDokladu“. Pokud byste smazali exportovaný produkt přes administraci služby iDoklad, nebylo by již možné smazat produkt přes tabulku v pluginu, dokud by nebyla promazaná databáze (a to není úkon pro běžného uživatele). V případě, že by byl exportovaný produktu smazán přes službu iDoklad, tak pro znovu exportování produktu je nutné v databázi smazat metadata _idoklad_id_polozky a _idoklad_nazev_polozky.

Oboustranné párování skladu

Ve výchozím nastavení je párování skladu pouze jednosměrné z WooCommerce do iDokladu. V případě, že chcete párovat sklad také ve WooCommerce podle skladu produktů v iDokladu, tak je nutné mít v pluginu aktivní funkci Aktivovat synchronizaci v sekci Synchronizace skladu iDoklad -> WooCommerce. Funkce byla do pluginu přidána od verze 2.4.0

Po aktivaci funkce oboustranné synchronizace je nutné vyčkat 24 hodin, než se sklad ve WooCommerce začne synchronizovat se skladem v iDokladu. Jedná se o ochranu, aby souhlasily hodnoty skladů. Po 24 hodinách bude synchronizace probíhat automaticky jednou za hodinu.

Druhou možností je načítat stav skladu v iDokladu pomocí cronu. V tom případě je nutné potvrdit checkbox Aktivovat WP cron. Na sém hostingu pak vložíte URL pro vlastní cron do cronu a nastavíte interval jeho opakování. Tento interval můžete nastavit podle své potřeby.

Deaktivace synchronizace skladu pro platební metodu

V této sekci můžete vybrat platební metody, při jejichž použití nebude sklad synchronizován a položky se ze skladu v iDokladu neodečtou.

Filtry

Jak změnit jazyk faktury

Faktury jsou vystavovány v českém jazyce, vzhledem k tomu, že plugin je primárně určen pro Českou republiku. Přestože je jej možné používat i na Slovensku, tak se objevil požadavek, aby bylo možné vystavit faktury i v jiném jazyce.
V tomto případě je důležitá informace, že WordPress neumí jazykové mutace. Je buď v jednom jazyce, nebo v druhém.

Avšak, existují pluginy, jenž umožňují mutace vytvářet. Bohužel, není možné, připravit plugin tak, aby byl kompatibilní se všemi pluginy.

Proto je v pluginu vložen filtr, jenž umožňuje změnit jazyk pro odeslanou fakturu, nebo zálohovou fakturu.

$lang = 'cs-CZ';
$data['LanguageCode'] = apply_filters( 
    'idoklad_language_code', 
    $lang, 
    $order_id, 
     $order 
);

Jak můžete vidět, defaultní hodnota je cs-CZ a do filtru je doplněno id objednávky a celý objekt objednávky.

Upozornění: Pokud máte možnost přepínat jazyky, tak je třeba v okamžiku vytvoření objednávky, uložit aktuální jazyk do post meta objednávky. Pak již jen pomocí filtru získáte jeho hodnotu a vrátíte jazyk, který potřebujete.

Vzorová ukázka kompletní změny jazyka na fakturách:

add_filter( 'idoklad_language_code', 'toret_net_custom_idoklad_language', 10, 3 );
function toret_net_custom_idoklad_language( $lang, $order_id, $order ){

return 'en-US';

}

add_filter( 'idoklad_request_language_code', 'toret_net_custom_idoklad_language2', 10, 1 );
add_filter( 'idoklad_language_code_faktura', 'toret_net_custom_idoklad_language2', 10, 1 );

function toret_net_custom_idoklad_language2( $lang ){

return 'en-US';

}

Ovlivnění odeslání faktury/proformy do iDokladu

V případě, že potřebujete nějakým způsobem ovlivnit odesílání faktur a proforem do iDokladu,  můžete použít dva filtry, jenž jsou k dispozici:

Změna jazyku pdf faktury a proformy

Na rozdíl od filtru, který určuje, v jakém jazyce je doklad vystavován, tak tento filtr umožňuje změnit výchozí jazyk, v kterém je získáván pdf soubor.

Při vytvoření proformy, nebo faktury, odesílá plugin informaci o tom v jakém jazyce je doklad. Při requestu pro zobrazení pdf souboru se odesílá header s defaultně nastavenou češtinou. Pokud z nějakého důvodu potřebujete změnit tuto hodnotu, použijte následující filtr:

Nastavení stavu zaplacené faktury

Pokud používáte pro kontrolu zaplacenosti faktur soubor control.php, můžete potřebovat změnit stav, na který se objednávky při spárování změní. Ve výchozím stavu to je completed. Pro změnu použijte následující filtr:

Změna popisu faktury a proformy

V případě, že potřebujete nějakým způsobem ovlivnit popis faktury, nebo proformy, můžete použít následující filtry:

apply_filters('idoklad_invoice_description', $description, $order_id)
apply_filters( 'idoklad_proforma_description', $description, $order_id );

Změna čísla objednávky faktury

Jako číslo objednávky se do iDokladu zasílá $order_id. V případě, že to potřebujete ovlivnit, použijte tento filtr:

Přidání kurzu měny do faktury

API iDokladu obsahuje pro faktury a proformy možnost přidat kurz měny a jeho číselnou hodnotu – ExchangeRate a ExchangeRateAmount.

Protože měny a jejich přepínání nejsou ve WooCommerce ve výchozím stavu, je v pluginu způsob, jak do faktur pomocí filtrů tyto hodnoty přidat.

ExchangeRateAmount určuje, zda je kurz počítaný pro 1, 10, nebo 100 ekvivalentů měny. Například ruský rubl bude mít rate amount 100.

Přidání prodejky

Filtr do iDokladu pro aktivaci prodejky:

$stvrzenka = apply_filters( 'idoklad_pdf_with_stvrzenka', false );

Časté dotazy

Debugování chyb

Vzhledem k tomu, že se vždy může něco pokazit, má plugin vestavěný způsob zachytávání chyb.

V detailu objednávky, kde se vyskytla chyba, najdete v pravém horním rohu iDoklad log, který se vztahuje pouze na konkrétní otevřenou objednávku.

V přehledu pluginů od Toretu najdete iDoklad log, který obsahuje všechny objednávky najednou.

Do iDoklad.cz se posílají špatně zaokrouhlené částky

Zkontrolujte nastavení WordPress a ujistěte se, že je ve WooCommerce povoleno pracovat s alespoň dvěma desetinnými místy.

Nastavení najdete ve WooCommerce → Nastavení, záložka Obecné, položka Počet desetinných míst.