Každý provozovatel eshopu by si měl v první řadě rozmyslet jak moc úzkou vazbu má eshop na účetní program mít. V podstatě se dá říct, že existují dvě možnosti jak účetnictví s eshopem propojit. První možnost je synchronizační a druhá online. O tom, kterou možnost zvolit rozhoduje několik faktorů. Jedním z faktorů je zkušenost programátorů. Dalším například to, zda se prodává „jen“ přes eshop nebo i v nějaké kamenné prodejně.
Synchronizační propojení eshopu a účetnictví
Tato varianta spočívá v tom, že se jednou za určitou dobu (většinou jednou denně) přenesou data z eshopu do účetnictví a opačně. Do FlexiBee se většinou z eshopu přenáší nové objednávky nebo faktury a záznamy o zákaznících a nazpátek je potřeba přenést aktuální ceník a stav skladu.
Tato varianta je většinou jednodušší na vytvoření a FlexiBee ji doporučuje pokud své účetnictví provozujete v cloudu. Je totiž méně datově náročná a FlexiBee provozované v cloudu je omezováno počtem požadavků za den.
Online propojení eshopu a účetnictví
Při použití této varianty propojení se dá říct, že každý požadavek klienta eshopu provádí nějakou sadu dotazů do FlexiBee. Například, pokud se vytváří objednávka, tak kliknutí na tlačítko objednat načte z FlexiBee aktuální sadu forem úhrady a dopravy aby si mohl zákazník vybrat jakou zvolí.
Tato forma propojení má výhodu v tom, že zákazník vždy vidí aktuální data (stavy skladů, dostupné zboží atd.) a v eshopu je udržována jen malá množina dat. Další výhodou může být také to, že FlexiBee přes API umožňuje řešit EET a není tedy nutné hledat samostatné řešení.
Nevýhodou je vysoká datová náročnost tohoto propojení a velké množství dotazů, které jdou do FlexiBee. Tuto variantu FlexiBee nedopručuje pokud máte účetnictví ve veřejném cloudu. Dřív nebo později by se Vám někdo z FlexiBee ozval a požadoval by utlumení provozu z důvodu překračování limitů. Při nesnížení zátěže hrozí nedostupnost účetnictví.
Pokud se rozhodnete pro tuto variantu propojení, je dobré mít FlexiBee server nainstalován na stejném serveru jako eshop. Minimalizují se tak časy odezvy. Také server musí být výkonný aby tuto zátěž zvládnul.
Jaká data z FlexiBee nás zajímají?
Z FlexiBee v obou případech budeme potřebovat načítat seznam zboží (ceník, strom, přílohy), individuální ceník pro konkrétní skupiny zákazníků, kontakty na zákazníky a skladové karty.
Do FlexiBee potřebujeme zapisovat objednávky nebo faktury a nové zákazníky.
Export seznamu zboží
Pokud chcete z FlexiBee do eshopu načítat seznam zboží, bude nás zajímat evidence cenik.
Dotaz na tuto evidenci by měl vypadat například takto:
GET /c/{firma}/cenik/(exportNaEshop=true).xml?detail=custom:nazev,kod,skupZboz,sumStavMj,cenaBezna,mj1,cenaZaklBezDph,cenaZaklVcDph,zaruka,mjZarukyK,popis,cenJednotka,eanKod,kratkyPopis,klicSlova,techParam,dodaciLhuta,mjDodaciLhuta&relations=poplatky,prilohy,prislustenstvi,atributy,podobne-zbozi&limit=0
Data z tohoto dotazu budou ve formátu XML, ale je možné použít i JSON. Dotaz vrátí jen zboží, které se má exportovat na eshop (na záznamu v ceníku je zaškrtnuto zaškrtávátko exportovat na eshop). Také je použita úroveň detailu custom. Tato úroveň umožňuje nadefinovat si, které sloupce budou součástí výstupu. Dalším parametrem, který je v dotazu použit je parametr relations, který umožní do výsledku doplnit i navázané záznamy (poplatky, přílohy, příslušenství, podobné zboží a atributy). Posledním parametrem limit=0 dáváme FlexiBee vědět, že chceme všechny záznamy, které vyhovují daným pravidlům (filtrace). Tento parametr je velmi důležitý, protože standardně FlexiBee vrací jen první stránku záznamů, která obsahuje 20 položek. Hodnota 0 říká: „chci všechno“. Pokud použijete nějaké číslo (např. 99999 což se dost často stává) tak se dá předpokládat, že postupem času přijde okamžik kdy záznamů bude více, než uvedená hranice.
https://demo.flexibee.eu/c/demo/cenik/(exportNaEshop=true).xml
?detail=custom:nazev,kod,skupZboz,sumStavMj,cenaBezna,mj1,cenaZaklBezDph,
cenaZaklVcDph,zaruka,mjZarukyK,popis,cenJednotka,eanKod,kratkyPopis,
klicSlova,techParam,dodaciLhuta,mjDodaciLhuta
&relations=poplatky,prilohy,prislustenstvi,atributy,podobne-zbozi&limit=0
Export příloh pro seznam zboží
V evidenci přílohy je možné ve FlexiBee uchovávat různé obrázky, manuály a podobné dokumenty. Pokud chceme tyto přílohy pro eshop načíst, je nejjednodušší cestou dotaz do evidence prilohy.
GET /c/{firma}/priloha/(exportNaEshop=true and cenik is not empty).xml?detail=custom:content,cenik&limit=0
Opět se exportují jen přílohy určené k exportu na eshop a jen takové, které jsou navázány na nějaký záznam z eshopu. Opět je použit detail custom a limit=0.
https://demo.flexibee.eu/c/demo/priloha/(exportNaEshop=true and cenik is not empty).xml
?detail=custom:content,cenik&limit=0
Práce se stromem v ceníku
Z FlexiBee je také možné do eshopu přenášet stromovou strukturu rozdělení produktů. Načtení těchto údajů je nutné provádět dvojicí dotazů.
První dotaz je do evidence strom, abychom získali kompletní stromovou strukturu.
GET /c/{firma}/strom/(strom='code:STR_CEN').xml?detail=full&limit=0
https://demo.flexibee.eu/c/demo/strom/(strom='code:STR_CEN').xml?detail=full&limit=0
Druhým dotazem pak musíme zjistit vazby mezi jednotlivými záznamy v ceníku a uzly stromu.
GET /c/{firma}/strom-cenik.xml?detail=full&limit=0
https://demo.flexibee.eu/c/demo/strom-cenik.xml?detail=full&limit=0
Podle výsledků této dvojice dotazů jsme schopni zrekonstruovat v eshopu kompletní strom z FlexiBee.
U záznamů z evidence strom jsou důležitý především element otec, který určuje jaký uzel je nadřazený uzlu, který právě zpracováváme. Vrchol stromu pak poznáme podle toho, že element otec je prázdný.
Evidence strom-cenik pak obsahuje vazbu mezi záznamem v ceníku a uzlem stromu. Element idZaznamu obsahuje vnitřní identifikátor FlexiBee záznamu v ceníku. Uzel je pak identifikátor uzlu stromu.
Nezapomínejte na to, že pokud budete zjišťovat obsah nějakého uzlu je nutné započít i jeho poduzly 🙂.
Získání prodejních cen
Velmi důležitými daty pro eshop jsou prodejní ceny, za které pak budete zboží prodávat zákazníkům.
Pro jednoduché eshopy bez cenotvorby je možné použít elementy cenaZaklBezDph, cenaZaklVcDph z ceníku. Výhodou je, že není potřeba další dotaz do FlexiBee. Většině eshopů ovšem časem tato varianta přestane stačit.
V případě, že varianta z cenami z ceníku nestačí například pro to, že někteří zákazníci, kteří u Vás často nakupují a mají mít tedy zboží levnější nebo chcete na omezenou dobu nějakému zboží přiřadit „akční cenu“, je nutné využít dotaz do evidence individuální ceník.
Tento dotaz zohledňuje komplexní cenotvorbu ve FlexiBee. Je tak možné získat prodejní ceny pro konkrétního zákazníka nebo pro skupinu zákazníků.
FlexiBee doporučuje si definovat omezený počet ceníkových skupin a jednotlivé zákazníky do nich zařazovat, podle toho, jaké ceny mají mít. Například vytvořit si ceníkové skupiny GOLD, SILVER, BRONZE a BEZNA. Skupině GOLD pak například nastavit 20% slevu z ceníkových cen atd. Sníží se Vám tak počet dotazů do FlexiBee, kterými získáte ceny pro všechny zákazníky vašeho eshopu, na 4 (počet skupin). Pro online napojení jsou tyto dotazy dobře cachovatelné a není tedy nutné je volat stále znovu a znovu.
Pokud chcete na eshopu mít jiné ceny než v kamenných prodejnách je dobré využít střediska ve FlexiBee. Vytvořte si střediska podle toho, jaké máte provozovny a také jedno s označením ESHOP. Tak budete mít možnost nastavit pro eshop jiné ceny než v kamenných prodejnách.
GET /c/{firma}/cenikova-skupina/code:GOLD/individualni-cenik.xml?date=datum výpočtu (výchozí je dnešek)
¤cy=požadovaná měna (např. EUR)
¢re=požadované středisko (zkratka, není povinná)
https://demo.flexibee.eu/c/demo/cenikova-skupina/code:GOLD/individualni-cenik.xml
?date=2017-01-01¤cy=EUR¢re=C
Nevýhody zjišťování cen pomocí evidence individuální ceník.
1. načítání je pomalé
Dotaz využívá složité SQL s UNIONY.
Dotaz nestránkujte a cachujte v eshopu, aktualizace cen provádějte v noci nebo v době kdy je eshop málo navštěvovaný.
2. sazba DPH není uvedena číselně
Místo sazby 21% bude výsledek obsahovat jen identifikátor sazby typSzbDph.dphZakl.
Zjištění stavu skladů
Pro zjištění stavu skladů se ve FlexiBee používá evidence skladova-karta. Tato evidence může být doplněna jako relation do ceníku nebo načtena samostatným dotazem.
Pokud chcete stavy skladů načíst rovnou společně s ceníkem použijte dotaz
GET /c/{firma}/cenik.xml?relations=skladKarty
https://demo.flexibee.eu/c/demo/cenik.xml?relations=skladKarty
Z kolekce skladových karet je potřeba si pak odfiltrovat ty karty, které již nejsou aktuální (jsou pro jiná účetní období než je aktuální).
Druhou možností jak získat stavy skladů je samostatný dotaz do evidence skladova-karta.
GET /c/{firma}/skladova-karta.xml
https://demo.flexibee.eu/c/demo/skladova-karta.xml
Tento dotaz má tu výhodu, že můžete odfiltrovat skladové karty pro neaktuální účetní období již v dotazu a není tak nutné je z FlexiBee přenášet.
Zcela jistě nepoužívejte evidenci stav-skladu-k-datu!!! Tento dotaz je složitý přibližně jako individuální ceník a jeho získání je tedy výpočetně velmi náročné (opět se jedná o složité SQL).
Další potřebné číselníky
Pro vytvoření objednávky s největší pravděpodobností budete potřebovat ještě seznamy forem dopravy a úhrady. Tyto je možné získat na adresách
GET /c/{firma}/forma-dopravy.xml?detail=full&limit=0
https://demo.flexibee.eu/c/demo/forma-dopravy.xml?detail=full&limit=0
GET /c/{firma}/forma-uhrady.xml?detail=full&limit=0
https://demo.flexibee.eu/c/demo/forma-uhrady.xml?detail=full&limit=0
Další zajímavou evidencí, jsou atributy u ceníku. Pokud vaše zboží obsahuje informace, které není možné zadat do standardních polí ve FlexiBee je možné využít atributy na ceníku. Příkladem použití může být úhlopříčka u televizorů a monitorů. Atributy je možné doplnit jako relation do načítání ceníku nebo k nim přistupovat dotazem do evidence atribut.
GET /c/{firma}/atribut.xml?detail=full&limit=0
https://demo.flexibee.eu/c/demo/atribut.xml?detail=full&limit=0
Přenos objednávek z eshopu do FlexiBee
Nyní se podíváme na to, jaká data bude nutné přenášet z eshopu do FlexiBee. Zákazník svou cestu po eshopu zakončí vytvořením objednávky, kterou je nutné přenést a zpracovat ve FlexiBee. Vytvořit z ní výdejku na skladové zboží a fakturu. K této faktuře pak „napárovat“ úhrady.
Většina napojení eshopů na FlexiBee ale nevytváří ve FlexiBee záznamy do evidence objednavka-prijata, ale rovnou faktury nebo výzvy k platbě, aby se snížil počet dokladů, které je potřebné zpracovat. Ale je samozřejmě možné i vytvořit objednávku a tu vyfakturovat.
Každá objednávka, která se vytváří, musí obsahovat položky, protože jinak by nebylo jasné co si zákazník objednal. Ve FlexiBee je možné do objednávek (i faktur) zadávat položky z ceníku i bez vyplnění ceníku, skladové i neskladové.
Zákazníka lze vybrat z adresáře firem nebo vyplnit přímo na dokladu.
Pro úspěšné vytvoření objednávky potřebujete na straně eshopu nejdříve sestavit XML nebo JSON soubor a ten pak pomocí metody PUT nebo POST zaslat do FlexiBee.
Soubor pro vytvoření objednávky by měl mít strukturu například:
<winstrom>
<objednavka-prijata>
<id>ext:OBP-ESHOP:123</id> <!-- místo 123 použijte vnitřní identifikátor objendávky v eshopu -->
<typDokl>code:OBP-ESHOP</typDokl> <!-- zkratka typu dokladu, který se má použít na vytvářenou objednávku -->
<stredisko>code:ESHOP</stredisko> <!-- pokud využíváte střediskovou cenotvorbu -->
<firma>code:FIRMA</firma> <!-- zkratka firmy pro výběr firmy z adresáře -->
...
<polozkyDokladu removeAll="true">
<objednavka-prijata-polozka>
<id>ext:OBP-POL-ESHOP:234</id> <!-- místo 234 použijte vnitřní identifikátor položky objednávky v eshopu -->
<cenik>code:CENIK</cenik> <!-- zkratka objednaného zboží z ceníku-->
<sklad>code:SKLAD</sklad> <!-- zkratka skladu ze kterého bude zboží vyskladněno -->
<mnozMj>1</mnozMj> <!-- objednané množství -->
<cenaMj>100</cenaMj> <!-- jednotková cena za kterou bylo zboží objednáno -->
...
</objednavka-prijata-polozka>
</polozkyDokladu>
</objednavka-prijata>
</winstrom>
Vždy pokud posíláte nějaká data do FlexiBee, snažte se používat identifikátory (elementy id). Umožníte tím zpětné změny na objednávce pro zákazníky z eshopu (například změnu objednaného množství nebo dodací adresy).
Také vyplňujte jen pole, o kterých víte co znamenají a co se s nimi ovlivňuje. Kompletní seznam polí dostupných pro objednávky přijaté naleznete na adrese https://demo.flexibee.eu/c/demo/objednavka-prijata/properties .
Realizace objednávky
Pokud se z eshopu vytvořila objednávka, je potřeba ji zrealizovat. To je možné ve FlexiBee provést „ručně“ nebo je možné tuto činnost také zautomatizovat.
Pro zautomatizování, je potřeba do FlexiBee poslat XML které bude vypadat například takto:
<objednavka-prijata>
<id>ext:OBP-ESHOP:123</id>
<realizaceObj type="faktura-vydana">
<id>ext:FAV-ESHOP:123</id> <!-- nepovinné, id faktury, která se z objednávky vytvoří -->
<polozkyObchDokladu>
<polozka>
<cisRad>1</cisRad> <!--č. řádky v obj.-->
<mj>1</mj>
</polozka>
</polozkyObchDokladu>
</realizaceObj>
</objednavka-prijata>
Při realizaci objednávky je výhodné vytvářené faktuře rovnou přiřadit externí identifikátor, protože pak s fakturou budeme potřebovat dále pracovat (např. získat PDF tiskopis, odeslat do EET, poslat PDF zákazníkovi mailem).
V případě, že je objednávka zaplacena kartou je potřeba fakturu, vzniklou z této objednávky, odeslat do EET. Odesíláné dokladů do EET je řešeno na adrese https://www.flexibee.eu/eet-automaticky-pres-rest-api/ .
Pokud chcete poslat fakturu zákazníkovi mailem, stačí po úspěšné realizaci objednávky odeslat do FlexiBee XML soubor
<winstrom>
<faktura-vydana>
<id>ext:FAV-ESHOP:123</id>
<stavMailK>stavMail.odeslat</stavMailK> <!-- na faktuře nastaví, že má dojít k automatickému odeslání -->
</faktura-vydana>
</winstrom>
Samostatné odeslání faktur určených k odeslání se provádí pomocí volání
PUT|POST /c/{firma}/faktura-vydana/automaticky-odeslat-neodeslane
Autentizace evidencí kontaktů
Pokud přemýšlíte, kde mít bezpečně uložena uživatelská jména a hesla vašich zákazníků a jednoduchou formou, pomocí těchto údajů, umožnit uživatelům se přihlásit, je výhodné využít evidenci kontakt.
Pro každého zákazníka je potřeba vytvořit záznam do evidence kontakt s vyplněním polí username a password.
POST /c/{firma}/kontakty/{id}.xml
<kontakt>
<username>jan</username>
<password hash=”” salt=””>heslo</password>
</kontakt>
Autentizace pomocí záznamů v evidenci kontakt se pak provádí pomocí požadavkem POST na adresu
POST /c/{firma}/kontakty/{id}/authenticate
username=jan&password=heslo
Uživatelské dotazy
Pokud se vám zdá, že některá volání jsou pro vás zbytečně složitá nebo pomalá, případně nevracejí výsledky přesně tak, jak potřebujete, můžete využít evidenci uzivatelsky-dotaz.
Tato evidence umožňuje do FlexiBee doplnit vlastní SQL dotaz, který bude „ušitý“ na míru vašim požadavkům. Je díky nim možné získat z FlexiBee data, která jsou přes API nedostupná nebo optimalizovat čtení dat.
Nevýhodou tvorby uživatelských dotazů je nutná znalost databázového schématu FlexiBee a také to, že FlexiBee negarantuje na rozdíl od API stabilitu databázového schématu.
Uživatelský dotaz je pak možné přes API volat
GET|POST /c/{firma}/uzivatelsky-dotaz/{id}/call.{xml|json}?parametry=hodnoty...
&detail/start/limit
Web Hooks
Další možností, jak propojení zoptimalizovat, je využití web hooks. Je to nejlepší způsob, jakým se eshop může dozvědět o změnách ve FlexiBee v reálném čase.
Dokumentace k web hooks je dostupná na stránce https://www.flexibee.eu/api/dokumentace/ref/web-hooks/.
Díky web hookům jste schopni ušetřit si mnoho zbytečně složitých dotazů do FlexiBee a načítat si jen ta data, která se reálně změnila.
Užitečné odkazy
https://www.flexibee.eu/api/navody/napojeni-internetovy-obchod/
https://www.flexibee.eu/api/dokumentace/casto-kladene-dotazy-pro-api/
https://www.flexibee.eu/api/dokumentace/ref/index/
https://www.flexibee.eu/api/dokumentace/ref/individualni-cenik/
https://www.flexibee.eu/api/dokumentace/ref/realizace-objednavky/
https://www.flexibee.eu/api/dokumentace/ref/uzivatelske-dotazy/
