Prodej vašich výrobků nebo služeb stojí na e-shopu a nechcete udržovat stejná data na dvou místech? ABRA Flexi má REST API, přes které si napojení můžete postavit sami.

Tento návod vás provede celým napojením od rozhodnutí o architektuře, přes přenos katalogu, cen a stavů skladu, až po zakládání objednávek a jejich fakturaci. Je určený vývojářům – předpokládáme základní znalost práce s HTTP a XML nebo JSON.

💡 Nastavení samotné ABRA Flexi (sklady, rezervace, ceník, formy úhrady) tento návod neřeší – popisuje ho článek Mám e-shop – jak nastavit ABRA Flexi? Projděte si ho ještě před psaním prvního řádku kódu; bez správně nastaveného skladového hospodářství vám integrace nepomůže.

ℹ️ Nechcete programovat? Pro většinu běžných e-shopových platforem existují hotové můstky našich partnerů. Přehled možností a toku dat najdete v článku Napojení libovolného e-shopu na ABRA Flexi.

Než začnete

Následující tři věci si vyřešte dřív, než napíšete první dotaz. Ušetří vám to většinu problémů, se kterými se na nás vývojáři obracejí.

Autentizace a bezpečnost

Způsoby přihlášení k API popisuje článek Autentizace. Při návrhu integrace se držte těchto pravidel:

Komunikujte vždy přes HTTPS, aby byla data při přenosu šifrovaná.
Nikdy neposílejte hesla v URL – zůstávají v logech serveru i v historii prohlížeče.
Vytvořte si samostatného uživatele pro API a dejte mu jen ta práva, která integrace skutečně potřebuje.
Neukládejte přihlašovací údaje do kódu. Použijte konfiguraci nebo správce tajemství a hesla pravidelně obměňujte.

Testovací prostředí

Nikdy nevyvíjejte proti ostrým účetním datům. Vytvořte si testovací firmu z zálohy ostré firmy a integraci ladějte na ní.

Všechny ukázkové dotazy v tomto návodu si můžete rovnou vyzkoušet na naší demo instanci demo.flexibee.eu – odkazy pod jednotlivými příklady vedou přímo na živý výstup.

Denní limity požadavků

Počet požadavků na API je omezen denním limitem podle vaší licence – u ABRA Flexi Premium je výchozích 20 000 dotazů denně, u nižších edic méně. Aktuální hodnoty a možnosti navýšení najdete v ceníku.

Kolik jste už vyčerpali, zkontrolujete přímo ve webové aplikaci. Sledujte to od začátku – limit se nejsnáz vyčerpá špatně navrženou synchronizací, která stahuje celý katalog každých pět minut.

⚠️ Při extrémní zátěži provoz z naší strany omezujeme, aby neohrozil dostupnost účetnictví ostatním zákazníkům. Odblokování je pak potřeba řešit s podporou. Návrhu, který generuje lavinu paralelních dotazů, se proto vyhněte už na papíře.

Jakou architekturu propojení zvolit

První rozhodnutí, které vás čeká, je, jak úzkou vazbu má e-shop na účetnictví mít. Nabízejí se tři přístupy a v praxi se nejlépe osvědčuje jejich kombinace.

Přístup	Jak funguje	Vhodné pro	Zátěž API
Dávková synchronizace	V pravidelném intervalu se přenesou data v obou směrech	Většinu e-shopů, provoz v cloudu, dotazování na stav skladu položek	Nízká
Online dotazování	Každá akce zákazníka vyvolá dotaz do Flexi	Privátní cloud, menší objem dat, real-time přenos objednávek	Vysoká
Webhooky a Changes API	E-shop se dozví jen o tom, co se skutečně změnilo	Doplnění dávky, potřeba aktuálních dat	Velmi nízká

Dávková synchronizace

Jednou za určitou dobu, obvykle jednou denně nebo několikrát denně, se přenesou data z e-shopu do účetnictví a zpět. Do Flexi typicky putují nové objednávky nebo faktury a záznamy o zákaznících, opačným směrem aktuální ceník a stavy skladu.

Tato varianta je jednodušší na vytvoření a doporučujeme ji všude, kde běží účetnictví v cloudu – je výrazně méně datově náročná a snadno se vejde do denního limitu požadavků.

Online propojení

Při online propojení vyvolá každá akce zákazníka na e-shopu sadu dotazů do Flexi. Když například zákazník klikne na tlačítko objednat, e-shop si z Flexi načte aktuální formy dopravy a úhrady, aby si mohl vybrat.

Výhodou je, že zákazník vždy vidí aktuální data a e-shop si sám drží jen malou množinu údajů. Nevýhodou je velké množství dotazů a s tím spojená datová náročnost.

Tento typ napojení může být vhodný pro např. real-time přenos objednávek - tedy po vytvoření objednávky na e-shopu každou přenést do ABRA Flexi. Zbytek údajů pak může být přenášen v dávce.

⚠️ Kompletní online propojení nedoporučujeme, pokud máte účetnictví ve veřejném cloudu. Dřív nebo později narazíte na limity a budeme vás muset požádat o utlumení provozu; při setrvalém přetěžování hrozí omezení dostupnosti účetnictví. Pokud tuto variantu volíte, doporučujeme provoz spíše v tzv. privátním cloudu - kontaktujte nás pro více informací.

Webhooky a Changes API

Nejefektivnější způsob, jak se e-shop dozví o změnách ve Flexi, je nechat si je oznámit. K tomu slouží webhooky – Flexi samo zavolá vaši adresu, jakmile se něco změní.

Druhou možností je delta synchronizace řízená vaší stranou: místo stahování celé agendy si vyžádáte jen záznamy změněné od poslední synchronizace pomocí pole lastUpdate. Uložte si čas posledního běhu a od něj načítejte jen změny.

💡 Nejlepší výsledky dává kombinace: dávka pro velké málo se měnící seznamy (ceník, strom kategorií, číselníky) a webhooky nebo delta export pro to, co se mění průběžně (stavy skladu, stav objednávek).

Co přenášet z ABRA Flexi do e-shopu

Z Flexi budete potřebovat načítat seznam zboží včetně stromu kategorií a příloh, prodejní ceny, stavy skladu a několik číselníků. Postupně si projdeme každou z těchto oblastí.

Ceník

Katalog zboží žije v evidenci cenik. Dotaz na něj může vypadat 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

Co jednotlivé části dotazu dělají:

Filtr (exportNaEshop=true) vrátí jen zboží, které má v ceníku zaškrtnuté pole Export na e-shop. Díky tomu si můžete v Flexi vést i položky, které na e-shop nepatří.
Úroveň detailu custom umožňuje vyjmenovat konkrétní sloupce. Menší odpověď znamená nižší latenci – nestahujte pole, která nepoužijete.
Parametr relations doplní do výsledku navázané záznamy: poplatky, přílohy, příslušenství, podobné zboží a atributy.
Parametr limit=0 znamená „vrať všechny záznamy, které odpovídají filtru“. Bez něj dostanete jen první stránku, tedy 20 položek.

Výstup dostanete v XML, stejně dobře ale funguje i JSON – stačí změnit příponu na .json. Dotaz si můžete vyzkoušet na demo instanci.

⚠️ Nepoužívejte místo limit=0 vysoké číslo jako limit=99999. Je to častá chyba a jednoho dne se katalog přes tuto hranici dostane – integrace pak začne tiše přenášet nekompletní data.

Obrázky a přílohy

Obrázky produktů, manuály a podobné dokumenty se ve Flexi ukládají do evidence priloha. Pro e-shop si je vytáhnete takto:

GET /c/{firma}/priloha/(exportNaEshop=true and cenik is not empty).xml
    ?detail=custom:content,cenik
    &limit=0

Filtr zajistí, že se přenesou jen přílohy určené pro e-shop, které jsou zároveň navázané na nějakou položku ceníku. Ukázka je opět dostupná na demo instanci.

Strom kategorií

Stromové rozdělení produktů získáte dvojicí dotazů. Prvním si vytáhnete samotnou strukturu stromu:

GET /c/{firma}/strom/(strom='code:STR_CEN').xml?detail=full&limit=0

Druhým pak vazby mezi jednotlivými uzly a položkami ceníku:

GET /c/{firma}/strom-cenik.xml?detail=full&limit=0

Z těchto dvou výstupů zrekonstruujete celý strom. U záznamů evidence strom je klíčový element otec, který určuje nadřazený uzel – vrchol stromu poznáte podle toho, že má otec prázdný. Evidence strom-cenik pak nese vazbu mezi uzlem a položkou ceníku: element idZaznamu obsahuje vnitřní identifikátor položky, element uzel identifikátor uzlu.

Vyzkoušet si to můžete na demo instanci – struktura stromu a vazby na ceník.

ℹ️ Když zjišťujete obsah nějakého uzlu, nezapomeňte započítat i jeho poduzly. Zákazník očekává, že v kategorii uvidí i zboží zařazené v jejích podkategoriích.

Prodejní ceny

Pro jednoduchý e-shop bez cenotvorby vystačí elementy cenaZaklBezDph a cenaZaklVcDph přímo z ceníku. Výhoda je zřejmá – nepotřebujete žádný další dotaz.

Jakmile ale chcete dávat stálým zákazníkům lepší ceny nebo pracovat s akčními cenami, přestane tato varianta stačit. Pak potřebujete evidenci individuální ceník, která zohledňuje celou cenotvorbu ve Flexi a umí vrátit ceny pro konkrétního zákazníka nebo pro skupinu zákazníků.

GET /c/{firma}/cenikova-skupina/code:GOLD/individualni-cenik.xml
    ?date=2026-01-01     <!-- datum výpočtu, výchozí je dnešek -->
    &currency=EUR        <!-- požadovaná měna -->
    &centre=ESHOP        <!-- zkratka střediska, nepovinné -->

Živou ukázku najdete na demo instanci.

Doporučujeme si definovat omezený počet ceníkových skupin a zákazníky do nich zařazovat – například GOLD, SILVER, BRONZE a BEZNA, kde skupina GOLD má dvacetiprocentní slevu z ceníkových cen. Ceny pro všechny zákazníky e-shopu pak získáte čtyřmi dotazy místo tisíců.

Chcete-li mít na e-shopu jiné ceny než na kamenných prodejnách, využijte střediska. Vytvořte si středisko pro každou provozovnu a jedno s označením ESHOP – parametrem centre pak vyžádáte ceny právě pro něj.

⚠️ Dotaz do individuálního ceníku je výpočetně náročný, protože pod ním běží složené SQL. Nestránkujte ho, výsledek si na straně e-shopu cachujte a aktualizaci pouštějte v noci nebo v době nízkého provozu. Počítejte také s tím, že sazba DPH není ve výstupu uvedena číselně – místo hodnoty 21 % dostanete identifikátor typSzbDph.dphZakl.

Stavy skladu

Stavy skladu nese evidence skladova-karta. Můžete si ji nechat doplnit rovnou k ceníku jako relaci:

GET /c/{firma}/cenik.xml?relations=skladKarty

Z kolekce skladových karet si pak musíte odfiltrovat ty, které patří k jiným než aktuálním účetním obdobím. Ukázka je na demo instanci.

Druhou možností je samostatný dotaz do evidence skladových karet:

GET /c/{firma}/skladova-karta.xml

Ten má tu výhodu, že neaktuální účetní období odfiltrujete už v dotazu a nemusíte tak data zbytečně přenášet. Vyzkoušet si ho můžete zde.

⚠️ Nepoužívejte pro tento účel evidenci stav-skladu-k-datu. Stojí za ní stejně složené SQL jako za individuálním ceníkem a její volání je výpočetně velmi náročné. Pravidelná synchronizace stavů skladu přes tuto evidenci je jedním z nejčastějších důvodů, proč integrace narazí na limity.

Číselníky a atributy

Aby zákazník mohl objednávku dokončit, potřebuje vybrat způsob dopravy a úhrady. Oba číselníky získáte přímočaře:

GET /c/{firma}/forma-dopravy.xml?detail=full&limit=0
GET /c/{firma}/forma-uhrady.xml?detail=full&limit=0

Obojí si vyzkoušejte na demo instanci – formy dopravy a formy úhrady. Jsou to typická data, která se téměř nemění – cachujte je.

Poslední užitečnou evidencí jsou atributy ceníku. Pokud u zboží potřebujete vést informace, pro které ve Flexi není standardní pole – třeba úhlopříčku u monitorů – použijte právě je. Doplníte je do ceníku jako relaci nebo se na ně zeptáte samostatně:

GET /c/{firma}/atribut.xml?detail=full&limit=0

Co přenášet z e-shopu do ABRA Flexi

Zákazník svou cestu po e-shopu zakončil objednávkou. Tu je teď potřeba dostat do Flexi, vyskladnit zboží, vyfakturovat a spárovat úhradu.

Objednávka, nebo přímo faktura?

Většina napojení nezakládá ve Flexi záznamy do evidence objednavka-prijata, ale vytváří rovnou faktury nebo výzvy k platbě – sníží se tím počet dokladů, které je potřeba zpracovat. Vytvořit nejdřív objednávku a tu následně vyfakturovat je samozřejmě také možné a dává smysl tam, kde chcete mít v Flexi přehled o rozpracovaných objednávkách a rezervacích.

Do objednávek i faktur můžete zadávat položky z ceníku i bez vazby na ceník, skladové i neskladové. Zákazníka buď vyberete z adresáře firem, nebo jeho údaje vyplníte přímo na dokladu.

Struktura objednávky

Na straně e-shopu sestavte XML nebo JSON a pošlete ho do Flexi metodou PUT nebo POST. Struktura objednávky vypadá takto:

<?xml version="1.0"?>
<winstrom>
  <objednavka-prijata>
    <id>ext:OBP-ESHOP:123</id>
    <typDokl>code:OBP-ESHOP</typDokl>
    <stredisko>code:ESHOP</stredisko>
    <firma>code:FIRMA</firma>
    <polozkyDokladu removeAll="true">
      <objednavka-prijata-polozka>
        <id>ext:OBP-POL-ESHOP:234</id>
        <cenik>code:CENIK</cenik>
        <sklad>code:SKLAD</sklad>
        <mnozMj>1</mnozMj>
        <cenaMj>100</cenaMj>
      </objednavka-prijata-polozka>
    </polozkyDokladu>
  </objednavka-prijata>
</winstrom>

Význam jednotlivých elementů:

id – identifikátor objednávky, za dvojtečkou použijte vnitřní identifikátor objednávky ve vašem e-shopu
typDokl – zkratka typu dokladu, který se má na objednávku použít
stredisko – vyplňte, pokud používáte střediskovou cenotvorbu
firma – zkratka firmy pro výběr zákazníka z adresáře
cenik a sklad – zkratka objednaného zboží a skladu, ze kterého se bude vyskladňovat
mnozMj a cenaMj – objednané množství a jednotková cena

ℹ️ Vyplňujte jen pole, o kterých víte, co znamenají a co ovlivňují. Doklad ve Flexi má desítky polí, která na sebe navazují – nastavením něčeho „pro jistotu“ si můžete rozbít zaúčtování.

Externí identifikátory a idempotence

Vždy, když posíláte data do Flexi, používejte externí identifikátory v elementu id ve tvaru ext:PREFIX:číslo. Má to dva důvody.

Prvním je možnost pozdějších změn – zákazník změní objednané množství nebo dodací adresu a vy pošlete stejný dokument znovu; Flexi podle externího ID najde existující doklad a upraví ho.

Druhým, a v účetnictví důležitějším, je idempotence. Když spadne spojení a vy si nejste jisti, zda požadavek prošel, pošlete ho znovu. Bez externího ID tak vznikne druhá faktura; s externím ID Flexi rozpozná, že jde o týž doklad, a duplicitu nezaloží.

⚠️ Integrace bez externích identifikátorů je nejčastější příčinou duplicitních dokladů v účetnictví. Opravy duplicitních faktur už jsou po zaúčtování a odevzdání přiznání k DPH nepříjemná práce – řešte to hned při návrhu.

Kde zjistíte dostupná pole

Kompletní seznam polí každé evidence vám vypíše sama aplikace, stačí za název evidence doplnit /properties. Pro objednávky přijaté tedy:

GET /c/{firma}/objednavka-prijata/properties

Na demo instanci si výpis prohlédnete zde.

Realizace objednávky a fakturace

Realizací se ve Flexi rozumí proces, kdy z objednávky vznikne výdejka, faktura nebo obojí. Provést ji lze ručně v aplikaci, nebo automatizovaně přes API – a právě to je u e-shopu obvyklé.

Automatická realizace

Pro realizaci objednávky pošlete do Flexi následující XML:

<?xml version="1.0"?>
<objednavka-prijata>
  <id>ext:OBP-ESHOP:123</id>
  <realizaceObj type="faktura-vydana">
    <id>ext:FAV-ESHOP:123</id>
    <polozkyObchDokladu>
      <polozka>
        <cisRad>1</cisRad>
        <mj>1</mj>
      </polozka>
    </polozkyObchDokladu>
  </realizaceObj>
</objednavka-prijata>

Element realizaceObj určuje, jaký doklad se má z objednávky vytvořit. Vnořené id je nepovinné, ale doporučujeme ho vyplnit – vznikající faktuře tím přidělíte vlastní externí identifikátor a budete s ní moci dál pracovat, například si vyžádat její PDF nebo ji nechat odeslat zákazníkovi. Element cisRad odkazuje na číslo řádku v objednávce, mj na realizované množství.

Odeslání faktury e-mailem

Pokud chcete zákazníkovi poslat fakturu e-mailem, označte ji po úspěšné realizaci k odeslání:

<?xml version="1.0"?>
<winstrom>
  <faktura-vydana>
    <id>ext:FAV-ESHOP:123</id>
    <stavMailK>stavMail.odeslat</stavMailK>
  </faktura-vydana>
  </winstrom>

Samotné rozeslání všech faktur označených k odeslání pak vyvoláte voláním:

PUT|POST /c/{firma}/faktura-vydana/automaticky-odeslat-neodeslane

Aby odesílání fungovalo, musí být ve Flexi nastavený SMTP server. Nechcete-li rozesílání řešit ve vlastním kódu, existuje na to i hotový doplněk.

Další možnosti

Následující dvě funkce nejsou pro napojení nutné, ale v praxi se často hodí.

Přihlašování zákazníků e-shopu

Přemýšlíte, kde bezpečně držet uživatelská jména a hesla zákazníků? Můžete pro to využít evidenci kontakt. Pro každého zákazníka založíte záznam s vyplněnými poli username a password:

PUT /c/{firma}/kontakt.xml

<?xml version="1.0"?>
<winstrom>
  <kontakt>
    <id>ext:KONTAKT-ESHOP:123</id>
    <firma>code:FIRMA</firma>
    <username>jan</username>
    <password>heslo</password>
  </kontakt>
</winstrom>

Přihlášení zákazníka pak proti tomuto záznamu ověříte:

POST /c/{firma}/kontakty/{id}/authenticate

username=jan&password=heslo

Uživatelské dotazy

Zdají se vám některá volání zbytečně složitá nebo pomalá, případně nevracejí data přesně tak, jak potřebujete? Pak se podívejte na uživatelské dotazy. Umožňují do Flexi doplnit vlastní SQL a získat tak data, která přes standardní API nejsou dostupná, nebo si jejich čtení optimalizovat.

GET|POST /c/{firma}/uzivatelsky-dotaz/{id}/call.{xml|json}
    ?parametr=hodnota&detail=…&start=…&limit=…

⚠️ Uživatelské dotazy vyžadují znalost databázového schématu ABRA Flexi a na rozdíl od API u nich negarantujeme stabilitu mezi verzemi. Po aktualizaci systému je proto vždy otestujte.

Optimalizace a provoz

Cílem není stáhnout všechno, ale rychle získat přesně to, co potřebujete, s minimální zátěží pro síť i server. Následující pravidla platí pro jakoukoliv integraci:

Dotazujte se jen na potřebná pole pomocí úrovní detailu.
Filtrujte a stránkujte – přenášejte jen relevantní záznamy (filtrace, stránkování).
Posílejte dávky. Jedna hromadná dávka je vždy efektivnější než stovky samostatných požadavků.
Cachujte odpovědi u číselníků a málo se měnících seznamů.
Čtěte jen změny pomocí pole lastUpdate místo opakovaného stahování celé agendy.
Nespouštějte lavinu paralelních dotazů. U náročnějších operací, jako je párování plateb nebo přepočet dokladů, vyčkejte na odpověď před odesláním dalšího požadavku.

Když API vrátí chybu

Rozlišujte chyby 4xx, tedy chybu na straně klienta, kterou musíte opravit (chybějící parametr, neplatná hodnota, chybějící oprávnění), a 5xx, tedy dočasný problém na straně serveru, kde má smysl akci zopakovat později.

Zvláštní pozornost si zaslouží kód 429 – Too Many Requests. Znamená, že se zpracovává příliš mnoho dřívějších požadavků. Nezkoušejte požadavek okamžitě znovu, tím zátěž jen zvýšíte – použijte exponenciální backoff a čekací dobu postupně prodlužujte, například 1 s, 2 s, 4 s, 8 s.

Logujte si odeslané požadavky i přijaté odpovědi, alespoň po omezenou dobu. Když budete řešit problém s naší podporou, konkrétní požadavek a odpověď hledání příčiny výrazně zkrátí.

ℹ️ Podrobná doporučení pro provoz integrací včetně tabulky všech chybových kódů a jejich vysvětlení najdete v článku Jak používat API?

Nejčastější chyby při napojení

Tyto situace řešíme s vývojáři nejčastěji. Vyhnete-li se jim, máte většinu problémů za sebou.

Chyba	Proč je to problém	Jak správně
`limit=99999` místo `limit=0`	Jednou katalog hranici přeroste a data začnou tiše chybět	Používat `limit=0`
Doklady bez externího ID	Opakovaný požadavek založí duplicitní fakturu	Vždy vyplnit `ext:` identifikátor
Stavy skladu z `stav-skladu-k-datu`	Výpočetně velmi náročné, rychle vyčerpá limity	Použít `skladova-karta`
Individuální ceník volaný při každém zobrazení produktu	Nejnáročnější dotaz v API, zpomalí e-shop i účetnictví	Cachovat, aktualizovat v noci po ceníkových skupinách
Okamžité opakování po chybě 429	Zátěž se dál zvyšuje a hrozí omezení provozu	Exponenciální backoff
Zálohování dat přes API	API k tomu není určené, zbytečně spotřebuje limit	Stahovat zálohy z webové aplikace

FAQ

Kde najdu seznam všech evidencí a jejich polí?

Evidence popisuje dokumentace REST API, aktuální seznam polí konkrétní evidence vám vypíše samotná aplikace přes /properties.

Funguje API i na vlastním serveru?

Ano, REST API je stejné pro cloud i pro lokální instalaci. Rozdíl je v limitech a v tom, že u vlastního serveru zodpovídáte za jeho výkon sami – tam je také jediné místo, kde má smysl uvažovat o online propojení.

Jak zjistím, kolik požadavků jsem už spotřeboval?

Ve webové aplikaci v licenci a předplatném.

Nechci napojení psát sám. Co mám dělat?

Podívejte se na hotové můstky na e-shopy. Nejrozsáhlejší portfolio má společnost Dativery.

Kam dál

Základy REST API:

Dokumentace REST API – kompletní přehled evidencí a operací
Jak používat API? – doporučené postupy, limity a chybové kódy
Autentizace a často kladené dotazy k API

Nastavení Flexi pro e-shop:

Mám e-shop – jak nastavit ABRA Flexi? – co nastavit v aplikaci, než začnete integrovat
Napojení libovolného e-shopu na ABRA Flexi – přehled možností v obecné rovině
Napojení na internetový obchod

💡 Nejste si jistí, jak API využít ve svém konkrétním scénáři? Můžeme se na návrh integrace podívat společně – domluvte si individuální konzultaci. Hodina nad architekturou na začátku se vyplatí víc než týden ladění v provozu.

Související články

Jak napojit e-shop na ABRA Flexi přes REST API