Získané schopnosti:
znalosť dostupných URL parametrov ABRA Flexi
znalosť najzložitejších konštrukcií URL
V predchádzajúcej veľmi teoretickej kapitole sme si ukázali, ako sa tvorí a z akých častí sa skladá URL pre volanie Flexi. V tomto tréningu si ukážeme zložitejšie i veľmi obratné chvaty, ako získať dáta cez API Flexi.
V zásade budeme riešiť dve časti URL adresy, parametre na konci adresy a filtráciu dát. Teda kombináciu viacerých parametrov naraz a zložené filtre, ktoré preveria aj logické myslenie, ktoré API Ninja musí mať. Opäť si ukážeme príklady v troch úrovniach zložitosti, poďme na to!
Úroveň: Učeň
Zostaviť korektnú URL pre Flexi už vieme. Prejdeme teda rovno k príkladom filtrácie. Jednoduchá filtrácia je možná prakticky nad všetkými poľami danej evidencie. Ako sme si ukázali v predchádzajúcej kapitole, polia danej evidencie nájdeme v /properties, ktoré je možné volať nad každou evidenciou z /evidence-list.
Umiestnenie filtrácie v URL tiež poznáme z minulého článku, skúsme teda prvý jednoduchý príklad: vyfiltrovať objednávky v EUR. Podľa /properties objednávky prijatej vidíme, že pole mena nadobúda hodnoty IdMeny, musíme teda najprv zistiť, aké ID má mena EUR. Poznáme kód meny EUR, môžeme teda použiť jednoduchý filter:
Ďalšia zložitejšia konštrukcia nie je potrebná. Získame tak záznam danej meny v číselníku mien, vrátane 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>
Teraz vieme, že ID meny je 11, môžeme teda zostaviť dotaz na objednávky, ktoré sú v eurách.
Príklad ukazuje, že kľúčový je pre nás nielen názov poľa, ale aj hodnoty, aké pole nadobúda. Dôležité je teda zadanie hľadaných hodnôt, čísla môžeme jednoducho zapísať samostatne, texty (reťazce) je nutné zapísať do úvodzoviek či apostrofov. Je tak možné zadať čísla, textové reťazce, logické hodnoty. Dátum, dátum+čas a ďalšie funkcie si ukážeme ďalej.
Môže sa nám hodiť vyfiltrovať objednávky (alebo iné doklady) pre konkrétnu firmu, avšak nepoznáme jej celé IČO ani názov spoločnosti, vieme len náhodou, že IČO začínalo číslom 9, ako na to? Uvažujme príklad, vieme o objednávkach od firmy Kolbas, avšak volanie nič s podobným kódom firmy nevracia:
Všimnite si, že kód z inej evidencie je nutné uviesť pomocou “code:”
K tomu, aby sme našli údaje, o ktorých máme len časť informácií, môžu poslúžiť filtre begins, ends, between, like, in a ďalšie. Pre nás teraz zafunguje begins (začína) alebo like (obsahuje) “Kol”:
Ďalší príklad volania:
Volaním získame všetky objednávky odberateľa, ktorý má IČO začínajúce na číslo deväť. Avšak takých môže byť viac, než len hľadaný Kolbas, ako teda vyfiltrovať viac informácií naraz? To si ukážeme v poslednej úrovni.
Učedník, to sú základy filtrovania,
vyskúšaj si ďalšie príklady, filtrov je mnoho.
Ďalším mocným nástrojom každého API Ninju sú parametre. Výsledky je vhodné radiť tak, ako potrebujeme, zobraziť si iba množstvo dát, ktoré potrebujeme alebo napríklad zistiť, koľko výsledkov sme získali. Zoraďme si objednávky podľa dátumu vystavenia, stačia nám iba základné informácie o objednávkach a informácia, koľko objednávok vlastne je. Volanie je nasledujúce:
Teraz si ho vysvetlíme. Hneď za kódom evidencie nasleduje rovno formát “.xml”, keďže chceme všetky objednávky, nie je potrebná ďalšia informácia ohľadom filtrov. Ako už vieme, parametre sa uvádzajú za otáznikom. Parameter “order” prijíma hodnotu poľa z danej evidencie, podľa ktorej chceme radiť, a informáciu o smere radenia @A - ascending, čiže vzostupne, @D - descending, teda zostupne. Ďalší parameter do adresy zapojíme pomocou znaku “&”, ktorý uvádza každý ďalší parameter. Ďalším je “detail=summary”, ktorý hovorí, že požadujeme iba základný prehľad informácií o objednávkach.
Posledným parametrom je špeciálny parameter “add-row-count=true”. Touto formuláciou získame v koreňovom elemente <winstrom> informáciu rowCount=počet výsledkov volania.
Najzaujímavejší použitý parameter je “detail”. Jeho pokročilejšie a odporúčané použitie je “detail=custom( … )”, ktoré si ukážeme nižšie. V minulom článku sme si ukázali, ako získať PDF cez API, teraz môžeme príklad rozšíriť o PDF v angličtine.
Získame cez API doklad pre klienta v angličtine?
A anglické doklady pre klienta Kolbas, o ktorom sme si už informácie zistili vyššie, takže vieme, ako filtrovať. Získame dve PDF:
Kde sme prišli na obchodDokladVystupniOBP? To už vieme z minula, učedník. :-)
Úroveň: Bojovník
Bojovník s API Flexi musí ísť hlbšie a osvojiť si ďalšie zaujímavé chvaty pre potreby stať sa API Ninjom. Ukážeme si pokročilejšie parametre a filtrácie, pokročilejšie pre následné využitie, nie v pochopení. Pustime sa do toho.
Bojovník, ktorý už pozná API Flexi lepšie, si iste kladie otázku, ako pracovať s dátumom, väzbami a rozsiahlymi výsledkami, ktorých môže byť aj tisíce. Väzby sme už naznačili v predchádzajúcom tréningu, teraz si ukážeme príklady. Ako teda vyfiltrovať cenník s väzbou na jeho skladové karty?
Dotazom získame všetky cenníkové položky, vrátane ich skladových kariet. Avšak keď je výsledkov mnoho, využijeme stránkovanie pomocou parametrov “limit” a “start”.
Tento dotaz na API nám vráti 3 výsledky, avšak prvé tri preskočí. Ak skutočne chceme všetky výsledky, musíme vždy uviesť limit=0, štandardný výpis totiž ponúka iba 20 výsledkov.
Ktoré prvé tri preskočil? (Implicitne bez radenia je radené podľa ID, teda prvé tri s najnižším ID)
Ak budete programovať vlastné skripty, iste využijete špeciálne funkcie, implementované v API FlexiBee. Prvou z nich je funkcia me(), pomocou ktorej získame všetky (limit = 0) záznamy prihláseného používateľa.
Ďalšie pracujú s dátumami. Ak chceme dynamicky získať záznamy, ktoré sú staršie než aktuálny dátum a čas, poslúži nám funkcia now(). Ak chceme dynamicky získať záznamy pre aktuálny rok, poslúži nám funkcia currentYear() - využiteľné pre platnosť niektorých záznamov napríklad v číselníkoch.
Zostáva nám na úrovni bojovník preveriť, ako zavolať podľa konkrétneho dátumu. Dátum sa zadáva v tvare YYYY-MM-DD, napr. 2018-11-01, dátum a čas v tvare YYYY-MM-DD'T'HH:MM:SS[.sss], napr. 2018-11-03T12:30:00. Ak teda chceme vyfiltrovať objednávky, ktoré nám prišli do valentínskeho predpoludnia a stihneme ich vybaviť, bude volanie vyzerať takto:
Teraz nám už zostáva všetky poznatky skombinovať. Všemožné parametre a obsiahle filtre, úloha ako stvorená pre API Ninju.
Úroveň: Ninja
Všetky dôležité možnosti poznáme z predchádzajúcich úrovní, teraz nám zostáva ich už len skombinovať. Bez dlhých rečí sa vrhneme na prvú úlohu, ktorou je kombinácia filtrov. Začne to hneď zostra, veľkou kombináciou.
Predstavme si situáciu, že chceme nájsť všetky (koľko) zálohové a “ostré” faktúry, ktoré sú k dnešnému dňu po splatnosti a nemajú priradený štítok indikujúci, že sa nemajú upomínať, a boli už raz upomenuté. Zároveň nás zaujímajú iba vlastné súhrnné informácie, vrátane názvu dlžníka, a koľko nám dlží. A to všetko pekne zoradené od najstaršej a s najvyššou dlžnou čiastkou. K tomu, aby sme mohli dosiahnuť taký dotaz, je potrebné využiť logické operátory or a and a bežné operátory rovná sa, nerovná sa. Bez kódovania medzier vyzerá dotaz takto:
Zložité, Ninja? Nie, len je dôležité utriediť si vstupné informácie.. Na poradí filtrov a parametrov nezáleží. Musíme však myslieť na niekoľko vecí, ktoré už poznáme:
logické uvažovanie :-)
Chceme získať doklady FAKTURA alebo ZÁLOHA, zároveň ich splatnosť je v minulosti, zároveň už majú dátum prvej upomienky vyplnený, zároveň nemajú konkrétny štítok NEUPOMÍNAŤ, zároveň nie sú stornované, zároveň stav úhrady je prázdny alebo je iba čiastočne uhradené. Detail dotazu máme vlastný, zaujímavý je vnorený detail “firma(nazev)”, hovoríme tým, že z includes=faktura-vydana/firma chceme zobraziť iba názov firmy. Potom už len zoradiť a vypísať počet záznamov.
Príklad bol vyčerpávajúci, alebo vymyslíš ďalší, napríklad zaujímavý dotaz do skladu, Ninja?
Čo vyššie uvedený zakódovaný dotaz znamená, API Ninja iste odhalí.
Existujú ďalšie špeciálne parametre, ktoré by mal API Ninja poznať, ak chce napríklad integrovať Flexi s inými systémami. Výstupy z Flexi vypisujú pri každom objekte identifikátory. Môže byť vhodné tieto identifikátory odstrániť, na čo slúži parameter “?no-ids=true”. Našli ste aj parameter ?only-ext-ids=true. Aký je medzi nimi rozdiel?
Parameter “?only-ext-ids=true” ovplyvňuje aj podevidencie, vyskúšajte zakomponovať do predchádzajúceho príkladu a porovnajte výsledky.
Do rovnakej skupiny parametrov by sa dal zaradiť parameter “?code-as-id=true”. Tento parameter zabezpečí, že vypíše kód záznamu ako ID. Môžete tak kombináciou parametrov “?only-ext-ids=true&code-as-id=true” optimalizovať výkon a pripraviť dáta na import do iného systému bez ID z Flexi.
Posledné parametre, ktoré si v tomto tréningu ukážeme, sú “?dry-run=true” a “?auth”. Predstavte si situáciu, kedy vykonávame pokročilú akciu so zápisom do Flexi, ale nie sme si istí výsledkom alebo potrebujeme len získať vypočítanú hodnotu. Na to slúži práve parameter “?dry-run=true”. Vykoná sa akcia, avšak nedôjde k jej uloženiu do Flexi. Overíme si tak výsledok. Navyše získate v tagu <content /> výslednú reprezentáciu záznamu tak, ako by vyzeral, keby sme ho uložili.
Zachovanie autentizácie z aplikácie pri volaní API Flexi v našom skripte je šikovný chvat každého API Ninju. Chceme v externej aplikácii využiť prihlásenie do Flexi pre viacero volaní, na to nám poslúži tzv. autentizačný token. Získame ho volaním metódou POST na adresu: https://developer.flexibee.eu//login-logout/login.json
Telo požiadavky musí obsahovať:
{
"username": "ninja",
"password": "heslo"
}
Ninja, vyskúšaj si v Postman alebo pomocou cURL!
API Flexi nám ako odpoveď vráti spomínaný token:
{
"authSessionId":"fd574d06addd928bd059e50ff51ab966764873d5fe5598cece77ce7bb49674ae",
"refreshToken":"quTDI5rkBkoZ6czPOH1wM/lFzbPEVJhyFat5ju4hF2g=",
"csrfToken":"78feef28-7343-4f32-bac5-ff2ad03703fd",
"success":true
}
Uvedený authSessionId potom môžeme využiť v našom skripte, napríklad v PHP, na prihlasovanie k Flexi. Ak využijeme v skoršom tréningu spomínané HTTPFul, potom to môže vyzerať nasledovne.
$cenik = \Httpful\Request::get ('https://developer.flexibee.eu/c/ninja/cenik.xml?only-ext-ids=true')
->sendsJson()
->withoutStrictSsl()
->addHeader('X-authSessionId', $authSessionId)
->send();
Ako dlho môžem token používať? Vydrží prihlásenie večne?
Token je občas nutné obnoviť. Aby ste udržali token platný, je potrebné udržiavať spojenie pomocou občasného zavolania GET /login-logout/session-keep-alive.js.
Malo by stačiť približne každých 30 minút.
API Ninja báda a skúma ďalej! Čo tak odhlásenie používateľa?
V tréningu sú spomenuté základné, najpoužívanejšie parametre a filtre. Ďalšie nájdete v našej štandardnej nápovede Filtrovanie, Zostavovanie URL a detaily k autentizácii. Teraz sa pozrieme na podporované formáty a možnosti ich zasielania.