Na této stránce naleznete průběžně aktualizovanou sbírku příkladů využití rozhraní Web API. Pro ucelené seznámení s problematikou doporučujeme stránku Web API - dotazování a navazující kapitoly.
Pokud je při vytváření nebo změnách business objektů metodami POST nebo PUT zasíláno tělo požadavku ve formě JSON objektu, pro dosažení očekávaného výsledku může být důležité zachování pořadí (posloupnosti) jednotlivých polí. Více informací viz související upozornění v kapitole Struktura URI.
Práce s adresářem
V tomto oddíle naleznete příklady práce s Adresářem firem.
PŘÍKLAD 1 - získání všech záznamů z adresáře
Zobrazí všechny záznamy z číselníku Adresář firem se všemi údaji.
Požadavek:
GET http://localhost:81/demodata/firmsZkrácený výsledek zpracování požadavku:
Status: 200 OK
[
{
"afterdueterm": 0,
"afterduetermenabled": false,
"checkcredit": false,
"code": "111",
"commercialsagreement": 0,
"communicationtype_id": null,
"correctedat$date": null,
"taxidentnumber": "",
...
"name:": "CarComponents Corp.",
...
"turnover_id": null,
"vatcountry_id": null,
"vatidentnumber": "",
"vatpayor": false,
"wwwaddress": ""
},
{
"afterdueterm": 0,
"afterduetermenabled": false,
"checkcredit": false,
"code": "00022",
"commercialsagreement": 0,
"communicationtype_id": null,
"correctedat$date": "2006-10-24T14:27:43.451",
"correctedby_id": "1300000101",
...
"name": "Teer Corporation",
...
"taxidentnumber": "",
"turnover_id": null,
"vatcountry_id": null,
"vatidentnumber": "",
"vatpayor": false,
"wwwaddress": ""
},
...
]Zpracování tohoto dotazu může trvat dlouho, protože pro každý záznam získáváme desítky údajů, které nepotřebujeme. V dalším příkladu si ukážeme, jak omezit požadavek na výběr položek, které nás zajímají.
PŘÍKLAD 2 - získání všech záznamů z adresáře (vybraná pole)
Obdoba předchozího příkladu, nicméně tentokrát pomocí klauzule SELECT vybereme pouze pole, která nás zajímají - ID a název firmy.
GET http://localhost:81/demodata/firms?select=id,name+as+Nazev
Výsledek bude výrazně úspornější (položku name jsme si navíc přejmenovali, aby byl výsledek také srozumitelnější):
Status: 200 OK
[ { "id": "3200000101", "Nazev": "Všeobecná zdravotní pojišťovna ČR" }, { "id": "1100000101", "Nazev": "Teer Corporation" }, ... ]
PŘÍKLAD 3 - získání všech záznamů z adresáře, včetně údajů o provozovnách
Ukázka využití klauzule EXPAND, která nám umožní zobrazit detail z řádků provozoven. Pomocí tečkové notace navíc můžeme zobrazit i informace z propojeného objektu, v našem případě ulici z adresy provozovny.
GET http://localhost:81/demodata/firms?select=id,name&expand=firmoffices(name,address_id.street)Zkrácený výsledek zpracování požadavku:
Status: 200 OK
[ { "id": "3200000101", "name": "Všeobecná zdravotní pojišťovna ČR", "firmoffices": [ { "name": "Provozovna", "address_id.street": "Karlovo nám. 8" } ] }, { "id": "1100000101", "name": "Teer Corporation", "firmoffices": [ { "name": "Provozovna", "address_id.street": "Denver street 567/10" } ] }, ... ]
Další možnosti práce s klauzulí EXPAND jsou uvedeny v kapitole Příklady základního dotazování REST API IS FLORES, v sekci Rozvíjení vybraných BO (klazule EXPAND).
PŘÍKLAD 4 - smazání firmy
Smazání záznamu (obdoba mazání bez možnosti obnovení) se provádí metodou DELETE. Do cesty se zapíše třída a ID objektu, který chceme smazat. Aplikační server pak za nás ohlídá konzistenci dat a v případě, že je na záznam odkazováno z jiných tabulek, vymazání záznamu nám nepovolí.
DELETE http://localhost:81/demodata/firms/3000000101Výsledek zpracování požadavku - úspěšné odstranění firmy:
Status: 204 No Content
Pokud se odstranění firmy nezdaří, vypadá výsledek zpracování následovně:
Status: 400 Bad Request
{ "title": "Chyba při mazání objektu", "error_code": 13, "description": "Při mazání objektu došlo k chybě:\r\nPokus o porušení vnitřní konzistence databáze\r\n\"violation of FOREIGN KEY constraint \"ISSUEDCRNOTESFIRMBANKACCOUNTFK\" on table \"ISSUEDCREDITNOTES\"\r\nForeign key references are present for the record\r\nProblematic key value is (\"ID\" = '1100000101')\"\r\nSQL příkaz:\r\nDELETE FROM FirmBankAccounts WHERE ID = ?OBJID and OBJVERSION = ?OBJVERSION\r\n" }
Pokud není možné záznam odstranit, můžeme ho smazat s možností obnovení, tedy skrýt. Viz následující příklad.
PŘÍKLAD 5 - skrytí firmy
Skrytí firmy (smazání s možností obnovení) se provádí nastavením položky Hidden na hodnotu True (lze též nastavit hodnotu 'A'). Jedná se o opravu položky, proto použijeme metodu PUT a v cestě bude třída a ID objektu, který chceme změnit.
Nezapomeneme specifikovat tělo požadavku, ve kterém nastavíme hodnotu položky Hidden. Ostatní položky měnit nechceme, tak je nebudeme uvádět.
PUT http://localhost:81/demodata/firms/9000000101Tělo požadavku:
{
"hidden": true
}Výsledkem zpracování požadavku je upravený záznam (uvádíme ve zkrácené podobě).
Status: 200 OK
{
"afterdueterm": 0,
"afterduetermenabled": false,
"assortmentdiscounts": [],
...
"gdprvaliditysuspended": false,
"hidden": true,
...
"id": "9000000101",
...
"name": "Teleshop GmbH",
...
}Každý číselník má možnost smazat záznamy s možností obnovení. Jak jsme si ukázali výše, toto se provádí nastavením položky Hidden. Při zpracování požadavků se standardně vyhledávají a zobrazují pouze záznamy, které skryté nejsou, nicméně je možné využít pohled hidden, který naopak zobrazí pouze skryté záznamy.
GET http://localhost:81/demodata/firms/views/hidden?select=id,nameVýsledek zpracování požadavku:
Status: 200 OK
[
{
"id": "9000000101",
"name": "Teleshop GmbH"
}
]Alternativou k pohledu hidden je pohled all, který zobrazí všechny záznamy, neskryté i skryté. Více viz sekce BO číselníků podporujících skrývání v kapitole Struktura URI.
GET http://localhost:81/demodata/firms/views/all?select=id,nameNásledující požadavek založí osobu s doručovací adresou. NewFirmMode určuje způsob zadání nové firmy.
- 0 - založí firmu
- 1 - založí osobu jako firmu
- 2 - založí osobu jako firmu i osobu
POST http://localhost:81/demodata/firmsTělo požadavku:
{ "NewFirmMode" : 1, "InitialFirmPerson_FirstName" : "Martin", "InitialFirmPerson_LastName" : "Bohuslav", "ResidenceAddress_ID" : { "Street" : "Jeremiášova 1422/7b", "City": "Praha 13", "PostCode": "155 00", "EMail": "martin.bohuslav@abra.eu" }, "FirmOffices" : [ { "Name": "Doručovací adresa", "Address_ID": { "Recipient": "ABRA Software a.s. (Brno)", "Street" : "Sochorova 38", "City": "Brno", "PostCode": "616 00", "EMail": "martin.bohuslav@abra.eu" } } ] }
Výsledkem zpracování požadavku je opravený záznam.
I při volání metod POST nebo PUT je vhodné kvůli odezvám minimalizovat velikost odpovědi omezením množiny vracených položek vytvářeného nebo upravovaného objektu. Efektivnější varianta našeho požadavku by tedy mohla vypadat následovně:
POST http://localhost:81/demodata/firms?select=idVýsledek zpracování v tomto případě obsahuje pouze ID vytvořeného objektu, což v praxi často postačuje. V našem příkladu se vytvořil záznam v adresáři firem s ID 2A00000101:
Status: 200 OK
{
"id": "2A00000101"
}Jedná se o změnu položky na existujícím objektu. Použijeme tedy metodu PUT a do cesty uvedeme ID objektu, který chceme změnit.
PUT http://localhost:81/demodata/firms/6400000101Tělo požadavku:
{
"prefilldiscountkind": true,
"dealerdiscountkind": 1,
"dealercategory_id": "3000000101"
}Výsledkem je objekt se změněnými hodnotami (opět uvádíme ve zkrácené podobě):
{
"afterdueterm": 0,
"afterduetermenabled": false,
"assortmentdiscounts": [],
...
"dealercategory_id": "3000000101",
"dealerdiscount": 0,
"dealerdiscountkind": 1,
...
"name": "CarComponents Corp.",
...
"prefilldiscountkind": true,
...
}PUT http://localhost:81/demodata/firms/3200000101Tělo požadavku:
{
"residenceaddress_id": { "City" : "Wien" }
}
Do této sekce jsou zařazeny různé příklady související se skladovými doklady - zejména jejich vytváření a také čerpání obsahu z určitého typu dokladu do jiného (takzvaná procesní tvorba dokladů) a se skladovým hospodářstvím obecně.
Další příklady týkající se procesní tvorby dokladů naleznete v kapitole Struktura URI, v sekcích Importní manažer - běžné (hlavičkové) BO a Importní manažer - řádkové BO.
Při vytváření polohovacích dokladů je zapotřebí v těle požadavku specifikovat veškeré údaje, které se zadávají při ručním polohování, včetně polohovací strategie . Viz příklad v kapitole Struktura URI.
PŘÍKLAD 1 - vytvoření skladové příjemky
Doporučení:
- V URL používejte klauzuli SELECT ke specifikaci pouze vybraných polí, která opravdu potřebujete. Zkrátíte tím dobu celkového zpracování požadavku.
- V těle požadavku nevyplňujte zároveň celkovou a jednotkovou cenu. Business logika IS FLORES ceny automaticky dopočítává a zaokrouhluje dle nastavení. Pokud by spolu uvedené ceny nekorespondovaly, požadavek by skončil chybou.
V jednotlivých řádcích příjemky je možné uvést různé sklady. Všechny nicméně musí mít povolené používání dané řady skladových dokladů.
POST http://localhost:81/demodata/receiptcards?select=idTělo požadavku:
{ "actualizesuppliers": true, "docdate$date": "2018-08-31T00:00:00.000", "docqueue_id": "O600000101", "firm_id": "3000000101", "firmoffice_id": "3000000101", "rows": [ { "rowtype": 3, "store_id": "2100000101", "storecard_id": "2100000101", "unitquantity": 2, "qunit": "ks", "unitprice": 1500, "division_id": "2100000101" } ] }
Výsledek zpracování požadavku (byla vytvořena příjemka s ID DJ200000101):
Status: 201 Created
{
"id": "DJ20000101"
}V uvedeném příkladu jsme na řádku dokladu nastavili množství 2 a jednotkovou cenu 1500. Při ukládání se automaticky dopočítala a uložila celková cena (2 * 1500 = 3000). V praxi však může nastat případ, že je zapotřebí naopak nastavit celkovou cenu, přičemž může (v důsledku zaokrouhlování) dojít k problému s validací.
V našem konkrétním případě bychom kromě položek quantity a totalprice (celková cena) explicitně nastavili ještě nulovou unitprice, např.
{
...
"unitquantity": 2.94,
"unitprice": 0,
"totalprice": 253,
...
}Přesun mezi sklady se provádí pomocí dvojice dokladů Převodka výdej a Převodka příjem.
Převodka výdej se vytváří obdobně jako Výdejka.
POST http://localhost:81/demodata/outgoingtransfers?select=idTělo požadavku:
{ "docdate$date": "2018-08-31T00:00:00.000", "docqueue_id": "Q600000101", "firm_id": "3000000101", "firmoffice_id": "3000000101", "rows": [ { "rowtype": 3, "store_id": "2100000101", "storecard_id": "2100000101", "unituqantity": 2, "qunit": "ks", "division_id": "2100000101" } ] }
Výsledek zpracování požadavku (byla vytvořena převodka výdej s ID CJ200000101):
Status: 201 Created
{
"id": "CJ20000101"
}Převodka příjem se vždy vytváří importem existující Převodky výdej. Seznam podporovaných parametrů (uváděných v těle požadavku ve vlastnosti params) naleznete v souboru F1Doc.chm v kapitole Seznam importních managerů.
POST http://localhost:81/demodata/incomingtransfers/import/outgoingtransfers/9J20000101?select=idTělo požadavku:
{
"params": {
"docqueue_id": "S600000101",
"store_id": "3200000101"
}
}Výsledek zpracování požadavku (byla vytvořena převodka příjem s ID BJ200000101):
Status: 201 Created
{
"id": "BJ20000101"
}Vytvoření výdejky s jedním skladovým řádkem.
POST http://localhost:81/demodata/billsofdelivery?select=idTělo požadavku:
{ "docdate$date": "2018-08-31T00:00:00.000", "docqueue_id": "P600000101", "firm_id": "3000000101", "firmoffice_id": "3000000101", "rows": [ { "rowtype": 3, "store_id": "3200000101", "storecard_id": "2100000101", "unitquantity": 2, "qunit": "ks", "division_id": "2100000101" } ] }
Výsledek zpracování požadavku (byla vytvořena výdejka s ID FJ200000101):
Status: 201 Created
{
"id": "FJ20000101"
}Přidání dodavatele (existující firmy z adresáře firem) k existující
POST http://localhost:81/demodata/suppliers?select=idTělo požadavku:
{
"storecard_id": "I600000101",
"firm_id": "J000000101",
"unitpurchaseprice": 280,
"purchasecurrency_id": "0000CZK000",
"purchasecurrrate": 1,
"purchasedate$date": "2019-04-15T06:48:25.372Z",
"qunit": "l",
"unitrate": 1
}Vysvětlivky k jednotlivým položkám:
StoreCard_ID = ID
Výsledek zpracování požadavku (byl vytvořen business objekt třídy Dodavatel s ID ID00000101):
Status: 201 Created
{
"id": "ID00000101"
}V předchozím příkladu jsme k
PUT http://localhost:81/demodata/storecards/I600000101?select=id,mainsupplier_idTělo požadavku:
{
"mainsupplier_id": "ID00000101"
}Výsledek zpracování požadavku (na
Status: 200 OK
{
"id": "I600000101",
"mainsupplier_id": "ID00000101"
}Příklad demonstruje omezování záznamů podle filtrovacích podmínek s využitím klauzule WHERE. Výběr chceme omezit za skladové menu Počítačové komponenty. Klauzule ORDERBY setřídí data dle zadané položky, v našem příkladu podle kódu.
GET http://localhost:81/demodata/storecards?select=id,code,name&where=storemenuitem_id+eq+'A000000101'&orderby=codeZkrácený výsledek zpracování požadavku:
Status: 200 OK
[
{
"id": "E100000101",
"code": "09",
"name": "USB Flash Mitsumi 32 GB"
},
{
"id": "L100000101",
"code": "16",
"name": "ZIP 100CF"
},
{
"id": "Z100000101",
"code": "30",
"name": "Mainboard Shuttle 100"
},
...
]Příklad omezení počtu záznamů, pokud potřebujeme záznamy získávat po částech. Klauzule TAKE udává počet vracených záznamů, klauzule SKIP počet přeskočených záznamů. Praktickou oblastí využití této funkcionality je stránkování.
GET http://localhost:81/demodata/storecards?select=id,code,name&where=storemenuitem_id+eq+'A000000101'&orderby=code&take=3&skip=5Výsledek požadavku:
Status: 200 OK
[ { "id": "2200000101", "code": "33", "name": "HDD Seagate 250 GB" }, { "id": "3200000101", "code": "34", "name": "Case Mini 250W" }, { "id": "4200000101", "code": "35", "name": "Klávesnice CZMitsumi" } ]
Objednávky
Příklady v této sekci se věnují práci s objednávkami - podíváme se na jejich načítání, vytváření, úpravy nebo export do PDF.
PŘÍKLAD 1 - vytvoření objednávky přijaté
Vytvoření objednávky přijaté s jedním skladovým řádkem.
POST http://localhost:81/demodata/receivedorders?select=idTělo požadavku:
{ "docqueue_id": "I700000101", "firm_id": "2800000101", "ExternalNumber": "Objednávka z e-shopu č. 1", "PricesWithVAT": true, "rows": [ { "rowtype": 3, "store_id": "2100000101", "storecard_id": "Z100000101", "unitquantity": 1, "division_id": "2100000101" } ] }
Výsledek zpracování požadavku (byla vytvořena objednávka přijatá s ID 4700000101):
Status: 201 Created
{
"id": "4700000101"
}Doplnění řádku s dopravným (použijeme řádek typu 1 - částka s cenou) do existující objednávky přijaté s ID 5700000101. Jedná se o aktualizaci existujícího objektu, proto použijeme metodu PUT.
PUT http://localhost:81/demodata/receivedorders/5700000101?select=idTělo požadavku:
{ "rows": [ { "rowtype": 1, "text": "Dopravné a balné", "totalprice": 125, "vatrate_id": "02100X0000", "division_id": "2100000101" } ] }
Výsledek zpracování požadavku (byla aktualizována objednávka přijatá s ID 1700000101):
Status: 200 OK
{
"id": "1700000101"
}Tisk objednávky přijaté s ID 1700000101 do PDF souboru s využitím systémové tiskové sestavy Formulář objednávky přijaté (ID 9700000101).
GET http://localhost:81/demodata/receivedorders.pdf?select=id&report=9700000001&where=id+eq+'1700000101'Výsledkem zpracování (obsahem odpovědi na požadavek vrácené se statusem 200 OK) je vygenerovaný PDF soubor.
Podrobnější informace o možnostech volání tiskových sestav, definovatelných exportů a B2B exportů naleznete v kapitole Tisky a exporty prostřednictvím REST API IS FLORES.
PŘÍKLAD 4 - získání seznamu dosud nedodaných objednávek
Potřebujeme získat seznam objednávek přijatých, které dosud nejsou zcela vyčerpány do následných dokladů. Jedná se o další ukázku využití klauzule WHERE.
GET http://localhost:81/demodata/receivedorders?where=isavailablefordelivery+eq+'A'&select=id,externalnumber,firm_id.nameZkrácený výsledek zpracování požadavku:
Status: 200 OK
[ { "id": "4000000101", "externalnumber": "1258/X", "firm_id.name": "Stopro s.r.o." }, { "id": "5000000101", "externalnumber": "602/01", "firm_id.name": "Kofr Karel - elektro" }, ... ]
PŘÍKLAD 5 - získání seznamu objednávek určité skladové položky
Potřebujeme získat seznam objednávek přijatých od určitého odběratele (firmy), ve kterých si tento odběratel objednával určit
GET http://localhost:81/demodata/receivedorders/?select=displayname,firm_id&expand=rows(storecard_id,store_id,quantity,qunit,rowtype)&where=exists(rows where storecard_id eq '7100000101') and firm_id eq '5000000101'Výsledek zpracování požadavku (našla se jedna objednávka):
Status: 200 OK
[
{
"DisplayName": "OP-5/2006",
"Firm_ID": "5000000101",
"rows": [
{
"storecard_id": null,
"store_id": null,
"unitquantity": 0,
"qunit": "",
"rowtype": 4
},
{
"storecard_id": "8100000101",
"store_id": "2100000101",
"unitquantity": 1,
"qunit": "ks",
"rowtype": 3
},
{
"storecard_id": "7100000101",
"store_id": "2100000101",
"unitquantity": 1,
"qunit": "ks",
"rowtype": 3
}
]
}
]Omezení funguje podobně jako řádkové omezení v agendách (záložka Omezení). Vrátí se celé doklady, které obsahují alespoň jeden řádek vyhovující podmínce. Kolekce rows není nijak omezena, jak je vidět na našem příkladu - doklad obsahuje kromě řádku s hledanou položkou ještě další dva, které jsou rovněž součástí odpovědi na požadavek.
Ceníky
Příklady související s ceníky - zejména dotazování na existující záznamy.
PŘÍKLAD 1 - získání ceny z prodejního ceníku pro konkrétní Jedná se o příklad rozšířeného dotazování, kdy je dotaz předáván v těle POST požadavku.
POST http://localhost:81/demodata/storeprices/queryTělo požadavku:
{
"select" : [
"PriceList_ID",
"Storecard_ID.Name",
{
"name": "pricerows",
"value": [
"Price_ID",
"Price_ID.Name",
"Amount"
]
}
],
"where" : "StoreCard_ID='Z100000101'"
}Výsledek zpracování požadavku - k
Status: 200 OK
[ { "PriceList_ID": "2100000101", "StoreCard_ID.Name": "Mainboard Shuttle 100", "pricerows": [ { "Price_ID": "2100000101", "Price_ID.Name": "Koncová prod.cena - s DPH", "Amount":3500}, { "Price_ID": "1000000101", "Price_ID.Name": "Dealerská prod.cena - bez DPH3300} ] } ]
PŘÍKLAD 2 - získání ceny z prodejního ceníku pro konkrétní Další příklad rozšířeného dotazování (dotaz předávaný v těle POST požadavku).
POST http://localhost:81/demodata/storeprices/queryTělo požadavku:
{ "select" : [ "StoreCard_ID.Name", { "name": "Ceny", "value": { "field": "PriceRows", "query" : { "select": [ "Price_ID.Name", "Amount", { "name": "Skladová karta", "value": "Parent_ID.StoreCard_ID.Name" } ], "where": "Price_ID='2100000101'" } } } ], "where" : "StoreCard_ID='Z100000101' and PriceList_ID='2100000101'" }
Výsledek zpracování - dohledaný záznam z ceníku dle požadavku:
Status: 200 OK
[ { "StoreCard_ID.Name": "Mainboard Shuttle 100", "Ceny": [ { "Price_ID.Name": "Koncová prod.cena - s DPH", "Amount":3500, "Skladová karta": "Mainboard Shuttle 100" } ] } ]
PŘÍKLAD 3 - získání prodejní ceny pro konkrétní Příklad volání QR funkce v rámci POST požadavku. Funkce NxGetStoreCardUnitPrice vrací jednotkovou cenu v požadované měně s DPH nebo bez DPH pro zadan
POST http://localhost:81/demodata/qrexprTělo požadavku:
{ "expr" : "NxGetStoreCardUnitPrice('2800000101', NxStoreID('01'), 'Z100000101', 1, 'ks', '', NxNow, True, '', True, '', '', True, '')" }
Výsledek zpracování požadavku - dohledaná hodnota:
Status: 200 OK
{
"result": 3325
}Požadavek realizujeme prostřednictvím vytvoření (metoda POST) nového řádku v daném ceníku (v naší ukázce s ID 1200000101).
POST http://localhost:81/demodata/pricelists/1200000101/rowsTělo požadavku:
{ "validfromdate$date": "2018-01-01", "description": "Nový ceník" }
Výsledek zpracování požadavku - nově vytvořený řádkový objekt (časová platnost ceníku):
Status: 201 Created
{ "classid": "MOIGO2XD4RB4PBPCULKHOY0D04", "description": "Nový ceník", "displayname": "", "id": "1100000101", "objversion": 1, "parent_id": "1200000101", "validfromdate$date": "2018-01-01T00:00:00.000" }
PŘÍKLAD 5 - založení nových cen Zde je nutné uvědomit si strukturu cen a ceníku v IS FLORES a znát patřičná ID.
- Ceník = PriceList = 1200000101
- Časová platnost = PriceListValidity (na ceníku Rows) = 1200000101
- Skladová karta = StoreCard = 2100000101
- Definice ceny = Price = 1000000101 (deal. bez DPH), 2100000101 (konc. s DPH)
- Položka ceníku = StorePrice
- Cena v ceníku (řádek ceny) = PriceRow
Ceník je jakási obálka kolem skladových cen. Na ceníku se určuje časová platnost. Každý ceník má své časové platnosti, které není možné ceníky sdílet. Časová platnost má hodnotu ValidFrom$DATE, která určuje platnost od. Do kdy je platnost aktuální určuje až následující záznam. Pokud neexistuje, je časová platnost neomezená. Časové platnosti nejsou pro ceníky povinné.
V IS FLORES můžeme mít nadefinované neomezené množství definic cen. Součástí definice je určení, zda je cena s DPH nebo bez DPH a v jaké měně. V našem příkladu je 1. cena bez DPH v CZK a 2. cena s DPH v CZK. Založení nového záznamu k
POST http://localhost:81/demodata/storepricesTělo požadavku:
{ "PriceRows": [ { "amount": 7900, "price_id": "1000000101", "qunit": "ks", "unitrate": 1 }, { "amount": 10999, "price_id": "2100000101", "qunit": "ks", "unitrate": 1 } ], "pricelist_id": "1200000101", "pricelistvalidity_id": "1200000101", "storecard_id": "2100000101" }
Výsledek zpracování požadavku (dvě založené ceny):
Status: 201 Created
{ "@id": "/cz/storeprices/2C00000101", "displayname": "/02 TV Panasonic TX-14B", "id": "2C00000101", "classid": "GDYLVQXQ3FE13DQC01C0CX3F40", "objversion": "1", "storecard_id": "3100000101", "pricerows": [ { "@id": "/cz/storeprices/2C00000101/pricerows/3I00000101", "displayname": "/02 TV Panasonic TX-14B", "id": "3I00000101", "classid": "GHYLVQXQ3FE13DQC01C0CX3F40", "objversion": "1", "parent_id": "2C00000101", "price_id": "1000000101", "qunit": "ks", "unitrate": 1, "amount": 7900 }, { "@id": "/cz/storeprices/2C00000101/pricerows/__________", "displayname": "/02 TV Panasonic TX-14B", "id": "__________", "classid": "GHYLVQXQ3FE13DQC01C0CX3F40", "objversion": "0", "parent_id": "2C00000101", "price_id": "2100000101", "qunit": "ks", "unitrate": 1, "amount": 0 } ], "pricelist_id": "1200000101", "pricelistvalidity_id": "1200000101", "deletedfrompricelist": false }
PŘÍKLAD 6 - platnosti ceníků
Příklad zobrazí ID ceníků a jejich zadané meze platností - nejstarší a nejnovější.
Datumové hodnoty jsou v tomto případě (použití agregační funkce max) vraceny v OLE formátu (jako v MS Excelu, tj. počet dnů od 1.1.1900). Standardně jsou datumové hodnoty vraceny ve formátu ISO 8601, viz poznámka Formát zobrazení data a času v odpovědích na požadavky.
POST http://localhost:81/demodata/queryTělo požadavku:
{
"class": "PriceLists",
"select": [
"ID",
{
"name": "last_validity",
"value": {
"field": "rows",
"query": {
"select": "max(validfromdate$date)",
"groupby": "parent_id"
}
}
},
{
"name": "first_validity",
"value": {
"field": "rows",
"query": {
"select": "min(validfromdate$date)",
"groupby": "parent_id"
}
}
}
]
}Výsledek zpracování požadavku:
Status: 200 OK
[
{
"ID": "1200000101",
"last_validity": [
{
"max(validfromdate$date)": 42887
}
],
"first_validity": [
{
"min(validfromdate$date)": 42636
}
]
},
{
"ID": "2100000101",
"last_validity": [],
"first_validity": []
},
{
"ID": "3300000101",
"last_validity": [
{
"max(validfromdate$date)": 42643
}
],
"first_validity": [
{
"min(validfromdate$date)": 42643
}
]
}
]Příklady na vyhledávání položek (pozic a
PŘÍKLAD 1 - přidání Na hlavní inventární protokol s ID 1400000101 přidáme
POST http://localhost:81/demodata/maininvprotocols/1400000101/storecardsTělo požadavku:
{
"storecard_id": "2100000101",
"qunit": "kg"
}Výsledek zpracování požadavku - do hlavního inventárního protokolu byla přidána požadovaná skladová karta, nově přidaný řádek protokolu má ID 1O00000101:
Status: 201 Created
{
"miprow_id": "1O00000101"
}Pokud by parametr qunit nebyl uveden, použila by se hlavní skladová jednotka.
PŘÍKLAD 2 - dohledání Zjišťujeme, zda hlavní inventární protokol s ID 1400000101 obsahuje
GET http://localhost:81/demodata/maininvprotocols/1400000101/storecards?storecard_id=2100000101Výsledek zpracování požadavku - protokol
Status: 200 OK
{
"miprow_id": "1O00000101"
}Na hlavní inventární protokol s ID 2300000101 přidáme skladovou pozici s ID 2000000101.
POST http://localhost:81/demodata/maininvprotocols/2300000101/positionsTělo požadavku:
{
"storeposition_id":"2000000101"
}Výsledek zpracování požadavku - byla vytvořena pozice hlavního inventárního protokolu s ID 1400000101:
Status: 201 Created
{
"mipposition_id": "1400000101"
}Zjišťujeme, zda hlavní inventární protokol s ID 2300000101 obsahuje
GET http://localhost:81/demodata/maininvprotocols/2300000101/positions?storeposition_id=2000000101Výsledek zpracování požadavku - protokol skladovou pozici obsahuje, na řádku 2100000101:
Status: 200 OK
{
"mipposition_id": "2100000101"
}Na pozici dílčího inventárního protokolu s ID 2000000101 přidáme řádek s
Na dílčích inventárních protokolech lze dohledávat/přidávat
POST http://localhost:81/demodata/partialinvprotocolpositions/2000000101/storecardsTělo požadavku:
{
"storecard_id": "1J00000101",
"qunit": "kg",
"unitrealquantity": 1
}Výsledek zpracování požadavku - byl vytvořen řádek dílčího inventárního protokolu s ID 1X00000101 na pozici s ID 2000000101:
Status: 201 Created
{
"piprow_id": "1X00000101"
}Parametry qunit a unitrealquantity nejsou povinné, v případě jejich vynechání bude použita hlavní jednotka
PŘÍKLAD 6 - dohledání Zjišťujeme, zda v pozici s ID 2000000101 existuje řádek obsahující
GET http://localhost:81/demodata/partialinvprotocolpositions/2000000101/storecards?storecard_id=1J00000101Výsledek zpracování požadavku - pozice
Status: 200 OK
{
"piprow_id": "1X00000101"
}K řádku dílčího inventárního protokolu s ID 1H00000101 přidáme šarži/sériové číslo s ID AB00000101
POST http://localhost:81/demodata/partialinvprotocolrows/1H00000101/storebatchesTělo požadavku:
{
"storebatch_id": "AB00000101",
"qunit": "kg",
"unitrealquantity": 1
}Výsledek zpracování požadavku - byl vytvořen řádek k šarže/sériového čísla s ID 3100000101:
Status: 201 Created
{
"pipbatch_id": "3100000101"
}Zjišťujeme, zda na řádku dílčího inventárního protokolu s ID 1H00000101 existuje skladová šarže s ID AB00000101.
GET http://localhost:81/demodata/partialinvprotocolrows/1H00000101/storebatches?storebatch_id=AB00000101Výsledek zpracování požadavku - řádek dílčího inventárního protokolu skladovou šarži obsahuje, na řádku 3100000101:
Status: 200 OK
{
"pipbatch_id": "3100000101"
}Úvod k používání QuickReports funkcí včetně několika dalších příkladů naleznete v kapitole Struktura URI.
PŘÍKLAD 1 - Zobrazení celkové skladové dispozice pomocí QR funkce
Následující požadavek vrátí informaci o dostupném množství určité skladové položky s ID Z100000101 (snížené o případné rezervace), přes všechny sklady.
POST http://localhost:81/demodata/qrexprTělo požadavku:
{
"expr": "NxGetAvailableQuantity('Z100000101','',0)"
}Výsledek požadavku:
{
"result": 9
}Následující požadavek vrátí dostupné množství
GET http://localhost:81/demodata/qrexprTělo požadavku:
{
"expr": "NxGetAvailableQuantity('Z100000101',NxStoreID('01'),0)"
}Výsledek zpracování požadavku:
{
"result": 8
}Příklady v této sekci se týkají funkcionality obecné ochrany dat.
PŘÍKLAD 1 - přepínání příznaku Zaměstnanec/Pracovník
Příznak Zaměstnanec/Pracovník v adresáři osob není možné editovat přímo, ale je zapotřebí použít speciální funkci Hromadná oprava "Zaměstnanec/Pracovník". Stejně tak ve Web API slouží k tomuto účelu speciální metoda dataprotectionswitch.
PUT http://localhost:81/demodata/persons/5000000101/dataprotectionswitch?select=lastname,isemployeeTělo požadavku:
{
"IsEmployee": true
}Výsledek zpracování požadavku:
Status: 200 OK
{
"lastname": "Smith",
"isemployee": true
}U osob současně evidovaných v agendě Zaměstnanci není možné tento příznak měnit.
PŘÍKLAD 2 - přepínání příznaku Právnická osoba
Příznak Právnická osoba v adresáři firem není možné editovat přímo, ale je zapotřebí použít speciální funkci Hromadná úprava Právního subjektu. Stejně tak ve Web API slouží k tomuto účelu speciální metoda dataprotectionswitch.
PUT http://localhost:81/demodata/firms/6000000101/dataprotectionswitch?select=name,legalpersonTělo požadavku:
{
"LegalPerson": true
}Výsledek zpracování požadavku:
Status: 200 OK
{
"name": "Novtron GmbH",
"legalperson": true
}V rozhraní Web API je implementováno několik speciálních zdrojů, které je možné využít ke snadnému vytváření nejrůznějších přehledů v celé řadě oblastí - účetnictví, skladové hospodářství, prodej, evidence a odpisy majetku, mzdy a personalistika a další. Popis jednotlivých zdrojů s příklady použití naleznete v samostatné kapitole. Viz Web API zdroje pro funkce v MS Excelu.
Další příklady
Další příklady z praxe, které se nevešly do žádné z předchozích kategorií.
PŘÍKLAD 1 - termín plánované výroby pro Objednávku přijatou
Příklad na použití funkce NxSQLSelect.
POST http://localhost:81/demodata/qrexprTělo požadavku:
{
"expr": "CfxDateToStr(NxStrToInt(NxSQLSelect('Select JO.ScheduledAt$Date from Relations R left join PLMProduceRequests PR on PR.ID=R.RightSide_Id left join PLMJobOrders JO on JO.ID=PR.JobOrder_ID where R.REL_DEF=1620 and R.LeftSide_ID=' + NxQuotedStr('1600000101'),'',';','')),'DD.MM.YYYY','.')"
}Výsledek zpracování požadavku:
Status: 200 OK
{
"result": "17.10.2017"
}Další příklad z výroby.
POST http://localhost:81/demodata/queryTělo požadavku:
{ "class": "ReceivedOrders", "select": [ "ID", "DisplayName", { "name": "X-Vazby", "value": { "class": "Relations", "select": [ "RightSide_ID", { "name": "PLM", "value": { "class": "PLMProduceRequests", "select": "DisplayName", "where": "id = :RightSide_ID" } } ], "where": "Rel_Def=1620 and LeftSide_ID=:ID" } } ], "where": "Firm_ID = 'L000000101'" }
Výsledek zpracování požadavku:
Status: 200 OK
[ { "ID": "1600000101", "DisplayName": "OP-2/2017", "X-Vazby": [ { "RightSide_ID": "2500000101", "PLM": [ { "DisplayName": "POZ-1/2017" } ] } ] } ]
PŘÍKLAD 3 - import OP do DL
Příklad na použití importního manažeru. Seznam implementovaných parametrů je k dispozici v F1Doc.chm v kapitole Seznam importních managerů.
POST http://localhost:81/demodata/billsofdelivery/import/receivedorders/1700000101?select=id,displaynameTělo požadavku:
{
"params": {
"docqueue_id": "P600000101"
}
}Existuje i možnost importovat najednou rovnou více BO do cílového BO. Tj. v URL se neuvede ID zdrojového objektu, ale uvede se input_document s polem ID importovaných objektů:
{
"input_document": ["1700000101", "1800000101"],
"params": { ...... }
}Další příklad použití importního manažeru. Seznam implementovaných parametrů je k dispozici v F1Doc.chm, v kapitole Seznam importních managerů.
POST http://localhost:81/demodata/otherincomes?select=id,displaynameTělo požadavku (03 je kód typu dokladů Faktury vydané):
{
"DocQueue_ID": "3600000101",
"Country_ID": "00000CZ000",
"Firm_ID": "2800000101",
"FirmOffice_ID": "2800000101",
"VATDocument": 0,
"Currency_ID": "0000CZK000",
"PDocumentType": "03",
"PDocument_ID": "3L00000101",
"ElectronicPayment": 1,
"EET": 1,
"Rows": [
{
"Division_ID": "2100000101",
"TAmount": 3450
}
]
}Výsledek zpracování požadavku (vytvořený doklad typu Ostatní příjmy):
Status: 201 Created
{ "id": "1100000101", "displayname": "OSP-1/2017" }
PŘÍKLAD 5 - provedení EET
Zápis tržby do systému, získání FIK a BKP.
PUT http://localhost:81/demodata/eetturnovers/3300000101/processZkrácený výsledek zpracování požadavku:
Status: 200 OK
{
"@id": "/demodata/eetturnovers/3300000101/process/3300000101",
"displayname": "OSP-1/2017",
"id": "3300000101",
"classid": "ENOR1TF5WOFODJWGHWKOLF1BTC",
...
"bkp": "B2EC1F03-6EF27A16-F2FA8ED3-A98DDC12-39C5A5C7",
"fik": "be7cf08a-5ce7-46aa-98b8-e89fed8b2dc9-ff",
...
}Pro práci s definovatelným číselníkem prostřednictvím Web API je zapotřebí v jeho vlastnostech vyplnit položku Název kolekce ve Web API. V našem případě jsme si nadefinovali číselník barev a název kolekce nastavili na hodnotu colors.
GET http://localhost:81/demodata/colorsVýsledek zpracování požadavku:
Status: 200 OK
[ { "clsid": "AHX2WTAA0KMOB0HGBGB1OFLXKG", "code": "R", "hidden": false, "id": "1000000101", "name": "Červená", "objversion": 2 }, { "clsid": "AHX2WTAA0KMOB0HGBGB1OFLXKG", "code": "G", "hidden": false, "id": "2000000101", "name": "Zelená", "objversion": 1 }, { "clsid": "AHX2WTAA0KMOB0HGBGB1OFLXKG", "code": "B", "hidden": false, "id": "3000000101", "name": "Modrá", "objversion": 1 } ]
PŘÍKLAD 7 - zobrazení čísla dokladu
Použití neperzistentní položky DisplayName. Načítá se celý objekt z databáze a pole se vypočítává, proto zpracování trvá delší dobu, v našem případě na určité konkrétní konfiguraci 200 - 400 ms.
GET http://localhost:81/demodata/issuedinvoices?select=displaynameZkrácený výsledek zpracování požadavku:
Status: 200 OK
[ { "displayname": "FV-1/0000" }, { "displayname": "FV-2/0000" } ... ]
PŘÍKLAD 8 - zobrazení čísla dokladu, rychlejší způsob
Identický výsledek jako v předchozím příkladu lze získat také s použitím perzistentních položek. Název vrácené položky můžeme pro zvýšení srozumitelnosti přejmenovat pomocí klíčového slova as. Dotaz na stejné konfiguraci jako v předchozím příkladu trval 20 - 60 ms.
GET http://localhost:81/demodata/select=DocQueue_ID.Code || '-' || OrdNumber || '/' || Period_ID.Code+as+DisplayNameZkrácený výsledek zpracování požadavku:
Status: 200 OK
[ { "DisplayName": "FV-1/0000" }, { "DisplayName": "FV-2/0000" } ... ]
PŘÍKLAD 9 - dohledání Příklad použití vnořeného EXISTS v klauzuli WHERE.
GET http://localhost:81/demodata/queryTělo požadavku:
{ "class": "storecards", "select": [ { "value": "ID", "name": "idecko" }, "Code", "Name", "EAN", { "name": "StoreUnits", "value": [ "ID", { "name": "StoreEans", "value": [ "EAN" ] } ] } ], "where": "exists(StoreUnits WHERE exists(StoreEANS WHERE EAN = '123698776559'))" }
Výsledek zpracování požadavku:
Status: 200 OK
[ { "idecko": "2100000101", "Code": "01", "Name": "Panasonic 65\" Class 4K Ultra HD TV", "EAN": "5445444444556", "StoreUnits": [ { "ID": "2100000101", "StoreEans": [ { "EAN": "5445444444556" }, { "EAN": "123698776559" } ] } ] }, { "idecko": "1L00000101", "Code": "M-See", "Name": "_Panasonic 65\" Class 4K Ultra HD TV", "EAN": "123698776559", "StoreUnits": [ { "ID": "1O00000101", "StoreEans": [ { "EAN": "123698776559" } ] } ] } ]
PŘÍKLAD 10 - aktualizace hlavičky a řádku objektu v jednom požadavku
Web API umožňuje provést aktualizaci hodnot na hlavičce a v řádcích určitého dokladu v rámci jediného požadavku. Příklad - máme fakturu vydanou s ID 8M00000101, která obsahuje řádek s ID VM00000101. Níže uvedeným požadavkem změníme popis na hlavičce a současně také cenu a množství na řádku.
Požadavek se úspěšně provede díky tomu, že Web API při jeho zpracování přeskakuje ID (pokus o zápis do tohoto pole by skončil chybou). Jedná se o interní mechanismus Web API.
PUT http://localhost:81/demodata/issuedinvoices/8M00000101Tělo požadavku:
{ "description": "dodávka9/2018", "rows": [ { "id": "VM00000101", "unitprice" : 3000.0, "unitquantity": 4 } ] }
PŘÍKLAD 11 - vytvoření dokumentu a jeho přiložení k dokladu
Prostřednictvím Web API je možné také vytvářet Dokumenty a přikládat je k dokladům.
Nejprve vytvoříme dokument (nový záznam v agendě Dokumenty).
Údaje zasílané v požadavku:
- Category_ID - ID kategorie dokumentu
- DocQueue_ID - ID řady dokladů
- Description - popis dokumentu
- Contents/Description - poznámka k obsahu
- FileName - název souboru
-
BlobData - obsah souboru (zakódovaný pomocí Base64 algoritmu)
Při převodu souboru do Base64 si dávejte pozor, aby výsledkem byla binární data (bez konverze do národní znakové sady). V online nástrojích k tomuto účelu obvykle slouží nějaká předvolba, viz obrázek.
Nastavení výstupní znakové sady při konverzi binárního souboru do souboru zakódovaného pomocí Base64 na webu www.base64encode.org.
Pokud převedete soubor v nějakém online nástroji, obsah vygenerovaného souboru můžete ručně vložit do těla požadavku (viz ukázka níže).
Pro automatické zpracování využijte možnosti používaného prostředí - pro převod do Base64 existuje řada standardních knihoven. Příklad konverze v Pythonu:
import binascii with open('Invoice.pdf', 'rb') as f: blob_data = binascii.b2a_base64(f.read(), newline=False)
Vytvořený dokument bude uložen v databázi.
POST http://localhost:81/demodata/Documents?select=id,displayname,description&expand=Contents(id,description,data_id)Tělo požadavku (zkrácené):
{
"Category_ID": "5000000000",
"DocQueue_ID": "1O30000101",
"Description": "Document description",
"Contents": [
{
"Description": "Content description",
"FileName": "AttachmentFileName.pdf",
"Data_ID":
{
"BlobData": "JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqD ... QpzdGFydHhyZWYNCjM2MzkwDQolJUVPRg=="
}
}
]
}Výsledek zpracování požadavku:
Status: 201 Created
{
"id": "1420000101",
"displayname": "DOC-1/2020",
"description": "Document description",
"Contents": [
{
"id": "1310000101",
"description": "Content description",
"data_id": "1310000101"
}
]
}Následně vytvořený dokument s ID = 1420000101 připojíme k existujícímu dokladu (v našem případě k existující faktuře vydané s ID = 1L60000010). Vazba se ukládá do business objektu Relations.
Údaje zasílané v požadavku:
-
rel_def - typ vazby
Kódy všech typů vazeb naleznete v seznamu struktur a definic v kapitole Seznam relací.
- rightside_id - ID připojovaného dokumentu (záznam z agendy Dokumenty, resp. tabulky Documents)
- leftside_id- ID dokladu, ke kterému se dokument připojuje - v našem případě Faktura vydaná
POST http://localhost:81/demodata/Relations?select=id, rel_def, leftside_id, rightside_idTělo požadavku:
{
"rel_def": 600,
"leftside_id": "1L60000101",
"rightside_id": "1420000101"
}Výsledek zpracování požadavku:
Status: 201 Created
{
"id": "BTW0000101",
"rel_def": 600,
"leftside_id": "1L60000101",
"rightside_id": "1420000101"
}Další příklady využití Web API je možné nalézt také v následujících kapitolách: