URL adresa je srdcom každého volania REST API. Určuje, ku ktorej firme a evidencii pristupujete, ktorý záznam vás zaujíma a v akom formáte ho chcete dostať. V tomto diele si prejdeme, ako ju poskladať a ako ju doplniť o parametre pre filtrovanie, stránkovanie a úroveň detailu.
ℹ️ Ukážkové adresy v tomto článku smerujú na našu verejnú demo inštanciu. Ak sa prehliadač opýta na prihlásenie, použite meno winstrom a heslo winstrom. Vo svojich adresách potom nahraďte demo.flexibee.eu adresou svojho servera a demo identifikátorom svojej firmy.
Štruktúra URL adresy
Základný tvar adresy vyzerá takto:
/c/<identifikátor firmy>/<evidence>/<ID záznamu>.<výstupní formát>
identifikátor firmy jednoznačne určuje firmu, ku ktorej pristupujete. Nájdete ho v adrese webového rozhrania po prihlásení, viac v článku o identifikátore firmy.
evidencia je typ agendy, napríklad adresár, objednávka alebo faktúra. Kompletný zoznam evidencií si môžete vypísať; do adresy uvádzajte hodnotu elementu
evidencePath.ID záznamu je identifikátor konkrétneho záznamu. Okrem interného čísla je možné použiť aj kód, externé ID alebo EAN, pozri identifikátory záznamov.
výstupný formát určuje podobu odpovede, napríklad
xmlalebojson. Pokiaľ ho neuvediete, server sa riadi hlavičkouAccept.
Príklad
demo.flexibee.euje adresa servera, v tomto prípade našej demo inštanciedemoje identifikátor firmyfaktura-vydanaje evidencia vydaných faktúr15je identifikátor záznamu; nájdete ho vo výstupe v elementeidalebo v aplikácii po pridaní stĺpca IDxmlje formát dát
Táto adresa teda zobrazí vo formáte XML vydanú faktúru s ID 15 vo firme demo.
Adresa pri vlastnom serveri a lokálnej inštalácii
Pri vlastnej inštalácii sa mení iba adresa servera a port, zvyšok adresy zostáva rovnaký. Predvolený port servera ABRA Flexi je 5434.
https://localhost:5434/c/testovaci/faktura-vydana/15.xml
Ak pristupujete na server po sieti, použite jeho adresu alebo meno. Konkrétny port a jeho sprístupnenie zvonka má na starosti váš správca siete.
https://vas-server.cz:5434/c/testovaci/faktura-vydana/15.xml
💡 Kompletný prehľad všetkých podporovaných častí adresy a parametrov nájdete v referenčnej dokumentácii k skladaniu URL.
Prehľad atribútov evidencie
Pre každú evidenciu si môžete vypísať zoznam všetkých atribútov, ktoré obsahuje. Tento prehľad navyše zohľadňuje vaše prístupové práva a licenciu.
/c/<identifikátor firmy>/<evidence>/properties
Názvy atribútov z tohto prehľadu potom používate ako elementy v XML alebo JSON požiadavke. Napríklad atribút kod nesie kód, teda skratku záznamu.
Vysvetlivky k stĺpcom v prehľade properties:
Značka | Význam |
| Požadovaná položka. Vnútorné väzby môžu spôsobiť, že povinnú položku vypĺňať nemusíte. |
| Položka je zapisovateľná. |
| Položka je iba na čítanie. |
| Položka je súčasťou úrovne detailu |
| Položka je súčasťou úrovne detailu |
| Položka je súčasťou úrovne detailu |
| Podľa položky je možné radiť a filtrovať. |
Filtrovanie záznamov
Pokiaľ identifikátor záznamu neuvediete, vráti server výpis celej evidencie. Ten je možné obmedziť filtrom, ktorý sa zapisuje do zátvoriek:
/c/<identifikátor firmy>/<evidence>/(<filtr>)
Príklad vyfiltruje všetky vydané faktúry, ktorých kód začína na VF:
/c/demo/faktura-vydana/(kod begins 'VF')
Podmienky je možné kombinovať logickými operátormi and, or a not.
Príklad č. 1 vráti faktúry, ktorých kód začína na VF a zároveň končí na 2018:
/c/demo/faktura-vydana/(kod begins 'VF' and kod ends '2018')
Príklad č. 2 vráti faktúry, ktorých kód začína na FV alebo na VF:
/c/demo/faktura-vydana/(kod begins 'FV' or kod begins 'VF')
⚠️ Filtre musia byť v URL správne zakódované. Medzery, zátvorky a apostrofy prehliadač nepovoľuje zapísať priamo, preto sa v adrese objavia znaky ako %20. Najjednoduchšia cesta je napísať filter nezakódovane v prehliadači a adresu si skopírovať, prehliadač ju prekóduje sám.
Okrem porovnávania je možné filtrovať aj podľa štítkov, vnorených väzieb alebo zaradenia do stromovej štruktúry. Úplný prehľad operátorov a zástupných hodnôt ako now() nájdete v článku o filtrovaní záznamov. Výpis je tiež možné zoradiť parametrom order.
Úroveň detailu
Kvôli rýchlosti odpovede sa v predvolenom stave nevypisujú všetky údaje, ktoré pri zázname evidujeme. Rozsah dát určíte parametrom detail:
idvráti iba identifikátor: faktura-vydana.xml?detail=idsummaryvrátiid,lastUpdateakod: faktura-vydana.xml?detail=summaryfullvráti všetky položky záznamu: faktura-vydana.xml?detail=fullcustomvráti iba vymenované položky: faktura-vydana.xml?detail=custom:kod,nazev,firma,varSym,datVyst
💡 Pri integráciách sa oplatí siahnuť po detail=custom a vypísať si len tie polia, ktoré naozaj potrebujete. Menšia odpoveď znamená rýchlejšiu odozvu a nižšiu záťaž servera. Viac v článku o úrovniach detailu.
Stránkovanie
Kvôli výkonu sa zoznam záznamov vracia po stránkach. Správanie riadia tieto parametre:
Parameter | Význam |
| Maximálny počet záznamov na jednej stránke. Ak nie je uvedený, vracia sa 20 záznamov. Hodnota |
| Koľko záznamov sa má preskočiť. Nie je závislý na parametri |
| Doplní do výstupu celkový počet záznamov v evidencii so zohľadnením filtrov. |
Príklad: faktura-vydana.xml?limit=25&start=10 preskočí prvých 10 záznamov a vráti nasledujúcich 25, teda 11. až 35. záznam.
Podrobnosti popisuje článok o stránkovaní.
Sumácie a podevidencie
Pokiaľ vás nezaujímajú jednotlivé záznamy, ale ich súčet, použite sumáciu:
/c/<identifikátor firmy>/<evidence>/$sum
Sumáciu je možné skombinovať aj s filtrom:
/c/<identifikátor firmy>/<evidence>/(<filtr>)/$sum
Každá evidencia môže mať podevidencie, teda relácie. Príkladom sú položky faktúry alebo kontakty pri adresári. Ich prehľad získate takto:
/c/<identifikátor firmy>/<evidence>/relations
Ak chcete dáta z relácií vypísať priamo pri zázname, doplňte parameter relations. Nasledujúca adresa vypíše všetky väzby k faktúre s ID 15:
Export tlačových zostáv do PDF
Pri každej evidencii si môžete vypísať zoznam podporovaných tlačových zostáv:
/c/<identifikátor firmy>/<evidence>/reports
Konkrétnu zostavu potom vyexportujete do PDF pomocou parametra report-name. Nasledujúca adresa vytlačí dodací list k faktúre s ID 1:
/c/firma/faktura-vydana/1.pdf?report-name=dodaciList
Rovnakým spôsobom je možné exportovať aj vlastné používateľské zostavy, stačí uviesť ich skratku. Nasledujúca adresa vytlačí upravenú zostavu so skratkou stitky pre cenníkovú položku s ID 15:
/c/firma/cenik/15.pdf?report-name=stitky
Viac o možnostiach exportu, vrátane voľby jazyka zostavy a elektronického podpisu, nájdete v článku export tlačových zostáv.
Ďalšie diely série
Skladanie URL adresy (tento článok)