URL adresa je srdcem každého volání REST API. Určuje, ke které firmě a evidenci přistupujete, který záznam vás zajímá a v jakém formátu ho chcete dostat. V tomto díle si projdeme, jak ji poskládat a jak ji doplnit o parametry pro filtrování, stránkování a úroveň detailu.
ℹ️ Ukázkové adresy v tomto článku míří na naši veřejnou demo instanci. Pokud se prohlížeč zeptá na přihlášení, použijte jméno winstrom a heslo winstrom. Ve svých adresách pak nahraďte demo.flexibee.eu adresou svého serveru a demo identifikátorem své firmy.
Struktura URL adresy
Základní tvar adresy vypadá takto:
/c/<identifikátor firmy>/<evidence>/<ID záznamu>.<výstupní formát>
identifikátor firmy jednoznačně určuje firmu, ke které přistupujete. Najdete jej v adrese webového rozhraní po přihlášení, více v článku o identifikátoru firmy.
evidence je typ agendy, například adresář, objednávka nebo faktura. Kompletní seznam evidencí si můžete vypsat; do adresy uvádějte hodnotu elementu
evidencePath.ID záznamu je identifikátor konkrétního záznamu. Kromě interního čísla lze použít i kód, externí ID nebo EAN, viz identifikátory záznamů.
výstupní formát určuje podobu odpovědi, například
xmlnebojson. Pokud jej neuvedete, server se řídí hlavičkouAccept.
Příklad
demo.flexibee.euje adresa serveru, v tomto případě naší demo instancedemoje identifikátor firmyfaktura-vydanaje evidence vydaných faktur15je identifikátor záznamu; najdete jej ve výstupu v elementuidnebo v aplikaci po přidání sloupce IDxmlje formát dat
Tato adresa tedy zobrazí ve formátu XML vydanou fakturu s ID 15 ve firmě demo.
Adresa u vlastního serveru a lokální instalace
U vlastní instalace se mění pouze adresa serveru a port, zbytek adresy zůstává stejný. Výchozí port serveru ABRA Flexi je 5434.
https://localhost:5434/c/testovaci/faktura-vydana/15.xml
Pokud přistupujete na server po síti, použijte jeho adresu nebo jméno. Konkrétní port a jeho zpřístupnění zvenčí má na starosti váš správce sítě.
https://vas-server.cz:5434/c/testovaci/faktura-vydana/15.xml
💡 Kompletní přehled všech podporovaných částí adresy a parametrů najdete v referenční dokumentaci k sestavování URL.
Přehled atributů evidence
Pro každou evidenci si můžete vypsat seznam všech atributů, které obsahuje. Tento přehled navíc zohledňuje vaše přístupová práva a licenci.
/c/<identifikátor firmy>/<evidence>/properties
Názvy atributů z tohoto přehledu pak používáte jako elementy v XML nebo JSON požadavku. Například atribut kod nese kód, tedy zkratku záznamu.
Vysvětlivky ke sloupcům v přehledu properties:
Značka | Význam |
| Požadovaná položka. Vnitřní vazby mohou způsobit, že povinnou položku vyplňovat nemusíte. |
| Položka je zapisovatelná. |
| Položka je pouze pro čtení. |
| Položka je součástí úrovně detailu |
| Položka je součástí úrovně detailu |
| Položka je součástí úrovně detailu |
| Podle položky je možné řadit a filtrovat. |
Filtrování záznamů
Pokud identifikátor záznamu neuvedete, vrátí server výpis celé evidence. Ten lze omezit filtrem, který se zapisuje do závorek:
/c/<identifikátor firmy>/<evidence>/(<filtr>)
Příklad vyfiltruje všechny vydané faktury, jejichž kód začíná na VF:
/c/demo/faktura-vydana/(kod begins 'VF')
Podmínky lze kombinovat logickými operátory and, or a not.
Příklad č. 1 vrátí faktury, jejichž kód začíná na VF a zároveň končí na 2018:
/c/demo/faktura-vydana/(kod begins 'VF' and kod ends '2018')
Příklad č. 2 vrátí faktury, jejichž kód začíná na FV nebo na VF:
/c/demo/faktura-vydana/(kod begins 'FV' or kod begins 'VF')
⚠️ Filtry musí být v URL správně zakódované. Mezery, závorky a apostrofy prohlížeč nepovoluje zapsat přímo, proto se v adrese objeví znaky jako %20. Nejjednodušší cesta je napsat filtr nezakódovaně v prohlížeči a adresu si zkopírovat, prohlížeč ji překóduje sám.
Kromě porovnávání lze filtrovat i podle štítků, vnořených vazeb nebo zařazení do stromové struktury. Úplný přehled operátorů a zástupných hodnot jako now() najdete v článku o filtrování záznamů. Výpis lze také seřadit parametrem order.
Úroveň detailu
Kvůli rychlosti odpovědi se ve výchozím stavu nevypisují všechny údaje, které u záznamu evidujeme. Rozsah dat určíte parametrem detail:
idvrátí pouze identifikátor: faktura-vydana.xml?detail=idsummaryvrátíid,lastUpdateakod: faktura-vydana.xml?detail=summaryfullvrátí všechny položky záznamu: faktura-vydana.xml?detail=fullcustomvrátí pouze vyjmenované položky: faktura-vydana.xml?detail=custom:kod,nazev,firma,varSym,datVyst
💡 U integrací se vyplatí sáhnout po detail=custom a vypsat si jen ta pole, která opravdu potřebujete. Menší odpověď znamená rychlejší odezvu a nižší zátěž serveru. Více v článku o úrovních detailu.
Stránkování
Kvůli výkonu se seznam záznamů vrací po stránkách. Chování řídí tyto parametry:
Parametr | Význam |
| Maximální počet záznamů na jedné stránce. Není-li uveden, vrací se 20 záznamů. Hodnota |
| Kolik záznamů se má přeskočit. Není závislý na parametru |
| Doplní do výstupu celkový počet záznamů v evidenci se zohledněním filtrů. |
Příklad: faktura-vydana.xml?limit=25&start=10 přeskočí prvních 10 záznamů a vrátí následujících 25, tedy 11. až 35. záznam.
Podrobnosti popisuje článek o stránkování.
Sumace a podevidence
Pokud vás nezajímají jednotlivé záznamy, ale jejich součet, použijte sumaci:
/c/<identifikátor firmy>/<evidence>/$sum
Sumaci lze zkombinovat i s filtrem:
/c/<identifikátor firmy>/<evidence>/(<filtr>)/$sum
Každá evidence může mít podevidence, tedy relace. Příkladem jsou položky faktury nebo kontakty u adresáře. Jejich přehled získáte takto:
/c/<identifikátor firmy>/<evidence>/relations
Pokud chcete data z relací vypsat rovnou u záznamu, doplňte parametr relations. Následující adresa vypíše všechny vazby k faktuře s ID 15:
Export tiskových sestav do PDF
U každé evidence si můžete vypsat seznam podporovaných tiskových sestav:
/c/<identifikátor firmy>/<evidence>/reports
Konkrétní sestavu pak vyexportujete do PDF pomocí parametru report-name. Následující adresa vytiskne dodací list k faktuře s ID 1:
/c/firma/faktura-vydana/1.pdf?report-name=dodaciList
Stejným způsobem lze exportovat i vlastní uživatelské sestavy, stačí uvést jejich zkratku. Následující adresa vytiskne upravenou sestavu se zkratkou stitky pro ceníkovou položku s ID 15:
/c/firma/cenik/15.pdf?report-name=stitky
Více o možnostech exportu, včetně volby jazyka sestavy a elektronického podpisu, najdete v článku export tiskových sestav.
Další díly série
Sestavování URL adresy (tento článek)