Získané schopnosti:
znalost dostupných URL parametrů ABRA Flexi
znalost nejsložitějších konstrukcí URL
V předchozí velmi teoretické kapitole jsme si ukázali, jak se tvoří a z jakých částí se skládá URL pro volání Flexi. V tomto tréninku si ukážeme složitější i velmi obratné chvaty, jak získat data přes API Flexi.
V zásadě budeme řešit dvě části URL adresy, parametry na konci adresy a filtraci dat. Tedy kombinaci více parametrů najednou a složené filtry, které prověří i logické myšlení, které API Ninja musí mít. Opět si ukážeme příklady ve třech úrovních složitosti, jdeme na to!
Úroveň: Učeň
Sestavit korektní URL pro Flexi již umíme. Přejdeme tedy rovnou k příkladům filtrace. Jednoduchá filtrace je možná prakticky nad všemi políčky dané evidence. Jak jsme si ukázali v předchozí kapitole, pole dané evidence nalezneme v /properties, které lze volat nad každou evidencí z /evidence-list.
Umístění filtrace v URL také známe z minulého článku, zkusme tedy první jednoduchý příklad. vyfiltrovat objednávky v EUR. Dle /properties objednávky přijaté vidíme, že pole mena nabývá hodnot IdMeny, musíme tedy nejprve zjistit, jaké ID má měna EUR. Známe kód měny EUR, můžeme tedy použít jednoduchý filtr:
Další složitější konstrukce není třeba. Získáme tak záznam dané měny v číselníku měn, včetně ID.
<winstrom version="1.0">
<!-- Měny -->
<mena>
<!-- ID (celé číslo) - -->
<id>11</id>
<!-- Poslední změna (datum a čas) - -->
<lastUpdate>2006-10-20T00:00:00+02:00</lastUpdate>
<!-- Zkratka (řetězec) - max. délka: 20 -->
<kod>EUR</kod>
<!-- Název (řetězec) - max. délka: 255 -->
<nazev>Euro</nazev>
</mena>
</winstrom>
Nyní víme, že ID měny je 11, můžeme tedy sestavit dotaz na objednávky, které jsou v eurech.
Příklad ukazuje, že klíčový je pro nás nejen název pole, ale také hodnoty, jakých pole nabývá. Důležité je tedy zadání hledaných hodnot, čísla můžeme jednoduše zapsat samostatně, texty (řetězce) je nutné zapsat do uvozovek či apostrofů. Lze tak zadat čísla, textové řetězce, logické hodnoty. Datum, datum+čas a další funkce si ukážeme dále.
Může se nám hodit vyfiltrovat objednávky (nebo jiné doklady) pro konkrétní firmu, nicméně neznáme její celé IČ ani název společnosti, víme jen náhodou, že IČ začínalo číslem 9, jak na to? Uvažujme příklad, víme o objednávkách od firmy Kolbas, nicméně volání nic s podobným kódem firmy nevrací:
Všimněte si, že kód z jiné evidence je nutné uvést pomocí “code:”
K tomu, abychom nalezli údaje, o kterých máme jen část informací, mohou posloužit filtry begins, ends, between, like, in a další. Pro nás nyní zafunguje begins (začíná) nebo like (obsahuje) “Kol”:
Další příklad volání:
Voláním získáme všechny objednávky odběratele, který má IČ začínající na číslo devět. Nicméně takových může být více, než jen hledaný Kolbas, jak tedy vyfiltrovat více informací najednou? To si ukážeme v poslední úrovni.
Učedníku, to jsou základy filtrování,
vyzkoušej si další příklady, filtrů je mnoho.
Dalším mocným nástrojem každého API Ninji jsou parametry. Výsledky je vhodné řadit jak potřebujeme, zobrazit si pouze množství dat, které potřebujeme nebo třeba zjistit, kolik výsledku jsme získali. Seřaďme si objednávky podle data vystavení, stačí nám pouze základní informace o objednávkách a informace kolik objednávek vlastně je. Volání je následující:
Nyní si ho vysvětlíme. Hned za kódem evidence následuje rovnou formát “.xml”, jelikož chceme všechny objednávky, není potřeba další informace ohledně filtrů. Jak již víme, parametry se uvádějí za otazník. Parametr “order” přijímá hodnotu pole z dané evidence, podle které chceme řadit a informaci o směru řazení @A - ascending, neboli vzestupně, @D - descending, tedy sestupně. Další parametr do adresy zapojíme pomocí znaku “&”, který uvozuje každý další parametr. Dalším je “detail=summary”, který říká, že požadujeme pouze základní přehled informací o objednávkách.
Posledním parametrem je speciální parametr “add-row-count=true”. Touto formulací získáme v kořenovém elementu <winstrom> informaci rowCount=počet výsledků volání.
Nejzajímavější použitý parametr je “detail”. Jeho pokročilejší a doporučené použití je “detail=custom( … )”, který si ukážeme níže. V minulém článku jsme si ukázali, jak získat PDF přes API, nyní můžeme příklad rozšířit o PDF v angličtině.
Získáme přes API doklad pro klienta v angličtině?
A anglické doklady pro klienta Kolbas, o kterém už jsme si info zjistili výše, takže víme, jak filtrovat. Získáme dvě PDF:
Kde jsme přišli na obchodDokladVystupniOBP? To už víme z minula učedníku. :-)
Úroveň: Válečník
Válečník s API Flexi musí jít hlouběji a osvojit si další zajímavé chvaty pro potřeby stát se API Ninjou. Ukážeme si pokročilejší parametry a filtrace, pokročilejší pro následné využití nikoliv v pochopení. Pusťme se do toho.
Válečník, který již zná API Flexi lépe, si jistě klade otázku, jak pracovat s datem, vazbami a rozsáhlými výsledky, kterých může být i tisíce. Vazby jsme již naznačili v předchozím tréninku, nyní si ukážeme příklady. Jak tedy vyfiltrovat ceník s vazbou na jeho skladové karty?
Dotazem získáme všechny ceníkové položky, včetně jejich skladových karet. Nicméně, když je výsledků mnoho, využijeme stránkování pomocí parametrů “limit” a “start”.
Tento dotaz na API nám vrátí 3 výsledky, nicméně první tři přeskočí. Pokud skutečně chceme veškeré výsledky, musím vždy uvést limit=0, standardní výpis totiž nabízí pouze 20 výsledků.
Které první tři přeskočil? (Implicitně bez řazení je řazeno dle ID, tedy první tři s nejnižším ID)
Pokud budete programovat vlastní skripty, jistě využijete speciální funkce, implementované v API FlexiBee. První z nich je funkce me(), pomocí které získáme všechny (limit = 0) záznamy přihlášeného uživatele.
Další pracují s datumy. Chceme-li dynamicky získat záznamy, které jsou starší než aktuální datum a čas, poslouží nám funkce now(). Chceme-li dynamicky získat záznamy pro aktuální rok, poslouží nám funkce currentYear() - využitelné pro platnost některých záznamů například v číselnících.
Zbývá nám na úrovni válečník prověřit, jak zavolat dle konkrétního data. Datum se zadává ve tvaru YYYY-MM-DD, např. 2018-11-01, datum a čas ve tvaru YYYY-MM-DD'T'HH:MM:SS[.sss], např. 2018-11-03T12:30:00. Pokud tedy chceme vyfiltrovat objednávky, které nám dorazily do valentýnského dopoledne a stihneme je vyřídit, bude volání vypadat takto:
Nyní už nám zbývá všechny poznatky zkombinovat. Všemožné parametry a obsáhlé filtry, úkol jako stvořený pro API Ninju.
Úroveň: Ninja
Všechny důležité možnosti známe z předchozích úrovní, teď nám zbývá je pouze zkombinovat. Bez dlouhých řečí se vrhneme na první úkol, kterým je kombinace filtrů. Začne hned zostra, velkou kombinací.
Představme si situaci, že chceme nalézt veškeré (kolik) zálohové a “ostré” faktury, které jsou k dnešnímu dni po splatnosti a nemají přiřazen štítek indikující, že se nemají upomínat a byly již jedenkrát upomenuty. Zároveň nás zajímají pouze vlastní souhrnné informace, včetně názvu dlužníka, a kolik nám dluží. A to všechno hezky seřazeno od nejstarší a s nejvyšší dlužnou částkou. K tomu, abychom mohli dosáhnout takového dotazu, je potřeba využít logické operátory or a and a běžné operátory rovno, nerovno. Bez kódování mezer vypadá dotaz takto:
Složité, Ninjo? Nikoliv, jen je důležité utřídit si vstupní informace.. Na pořadí filtrů a parametrů nezáleží. Musíme však myslet na několik věcí, které už známe:
logické uvažování :-)
Chceme získat doklady FAKTURA nebo ZÁLOHA, zároveň jejich splatnost je v minulosti, zároveň již mají datum první upomínky vyplněno, zároveň nemají konkrétní štítek NEUPOMÍNAT, zároveň nejsou stornované, zároveň stav úhrady je prázdný nebo je pouze částečně uhrazeno. Detail dotazu máme vlastní, zajímavý je vnořený detail “firma(nazev)”, říkáme tím, že z includes=faktura-vydana/firma chceme zobrazit pouze název firmy. Pak už jen seřadit a vypsat počet záznamů.
Příklad byl vyčerpávající, nebo vymyslíš další, například zajímavý dotaz do skladu, Ninjo?
Co výše uvedený zakódovaný dotaz znamená, API Ninja jistě odhalí.
Existují další speciální parametry, které by měl API Ninja znát, pokud chce například integrovat Flexi s jinými systémy. Výstupy z Flexi vypisují u každého objektu identifikátory. Může být vhodné tyto identifikátory odstranit, k čemuž slouží parametr “?no-ids=true”. Našli jste i parametr ?only-ext-ids=true. Jaký je mezi nimi rozdíl?
Parametr “?only-ext-ids=true” ovlivňuje i podevidence, vyzkoušejte zakomponovat do předchozích příkladu a porovnejte výsledky.
Do stejné skupiny parametru by se dal zařadit parametr “?code-as-id=true”. Tento parametr zajistí to, že vypíše kód záznamu jako ID. Můžete tak kombinací parametrů “?only-ext-ids=true&code-as-id=true” optimalizovat výkon a připravit data na import do jiného systému bez ID z Flexi.
Poslední parametry, které si v tomto tréninku ukážeme, jsou “?dry-run=true” a “?auth”. Představte si situaci, kdy provádíme pokročilou akci se zápisem do Flexi, ale nejsme si jisti výsledkem nebo potřebujeme jen získat vypočtenou hodnotu. K tomu slouží právě parametr “?dry-run=true”. Provede se akce, nicméně nedojde k jejímu uložení do Flexi. Ověříme tak výsledek. Navíc získáte v tagu <content /> výslednou reprezentaci záznamu tak, jak by vypadal, kdybychom ho uložili.
Zachování autentizace z aplikace při volání API Flexi v našem skriptu je šikovný chvat každého API Ninji. Chceme v externí aplikaci využít přihlášení do Flexi pro více volání, k tomu nám poslouží tzv. autentizační token. Získáme ho volání metodou POST na adresu: https://developer.flexibee.eu//login-logout/login.json
Tělo požadavku musí obsahovat:
{
"username": "ninja",
"password": "heslo"
}
Ninjo, vyzkoušej si v Postman nebo pomocí cURL!
API Flexi nám jako odpověď vrátí zmíněný token:
{
"authSessionId":"fd574d06addd928bd059e50ff51ab966764873d5fe5598cece77ce7bb49674ae",
"refreshToken":"quTDI5rkBkoZ6czPOH1wM/lFzbPEVJhyFat5ju4hF2g=",
"csrfToken":"78feef28-7343-4f32-bac5-ff2ad03703fd",
"success":true
}
Uvedený authSessionId pak můžeme využít v našem skriptu například v PHP pro přihlašování k Flexi. Pokud využijeme v dřívějším tréninku zmíněné HTTPFul, pak to může vypadat následovně.
$cenik = \Httpful\Request::get ('https://developer.flexibee.eu/c/ninja/cenik.xml?only-ext-ids=true')
->sendsJson()
->withoutStrictSsl()
->addHeader('X-authSessionId', $authSessionId)
->send();
Jak dlouho můžu token používat? Vydrží přihlášení věčně?
Token je občas nutné obnovit. Abyste udrželi token platný, je potřeba udržovat spojení pomocí občasného zavolání GET /login-logout/session-keep-alive.js.
Mělo by stačit přibližně každých 30 minut.
API Ninja bádá a prozkoumává dál! Co třeba odhlášení uživatele?
V tréninku jsou zmíněny základní, nejpoužívanější parametry a filtry. Další naleznete v naší standardní nápověď Filtrování, Sestavování URL a detaily k autentizaci. Nyní se podíváme na podporované formáty a možnosti jejich zasílání.