Další příklady použití Web API v ABRA Gen

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.

V tomto oddíle naleznete příklady práce s agendou Adresář firem.

Adresář firem

Zobrazí všechny záznamy z agendy Adresář firem se všemi údaji.

Požadavek: 

GET http://localhost:81/demodata/firms

Zkrá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í.

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"
	},
	...
]

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 ABRA Gen, v sekci Rozvíjení vybraných BO (klazule EXPAND).

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/3000000101

Vý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.

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/9000000101

Tě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,name

Vý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,name

Ná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/firms

Tě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=id

Vý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/6400000101

Tě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/3200000101

Tělo požadavku:

{
	"residenceaddress_id": { "City" : "Wien" }
}
POST http://localhost:81/demodata/firms/3200000101/majorcorrection

Tělo požadavku:

{
	"residenceaddress_id": { "City" : "Praha" }
}

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.

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 ABRA Gen 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=id

Tě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í.

Viz související FAQ Jak pomocí skriptování správně zadávat celkovou a jednotkovou cenu na řádcích dokladů? (FAQ se týká skriptování, ale princip je identický.) 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 doklad Dodací list. 

POST http://localhost:81/demodata/outgoingtransfers?select=id

Tě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",
				"unituquantity": 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 GenDoc.chm v kapitole Seznam importních managerů.

POST http://localhost:81/demodata/incomingtransfers/import/outgoingtransfers/9J20000101?select=id

Tě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í dokladu Dodací list s jedním skladovým řádkem.

POST http://localhost:81/demodata/billsofdelivery?select=id

Tě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 (byl vytvořen doklad Dodací list s ID FJ200000101):

Status: 201 Created 

{
	"id": "FJ20000101"
}

Přidání dodavatele (existující firmy z agendy Adresář firem) k existující skladové kartě (tj. doplnění záznamu na záložku Dodavatelé):

POST http://localhost:81/demodata/suppliers?select=id

Tě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 skladové karty, Firm_ID = ID firmy (dodavatele), UnitPurchasePrice = nákupní cena, PurchaseCurrency_ID = ID měny nákupní ceny, PurchaseCurrRate = kurz nákupní měny, PurchaseDate$DATE = datum poslední aktualizace nákupní ceny, QUnit = jednotka, k níž se vztahuje nákupní cena, UnitRate = vztah jednotky k 1

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 ke skladové kartě přidali dodavatele. Nyní ho nastavíme jako hlavního dodavatele této skladové karty.

PUT http://localhost:81/demodata/storecards/I600000101?select=id,mainsupplier_id

Tělo požadavku:

{
	"mainsupplier_id": "ID00000101"
}

Výsledek zpracování požadavku (na skladové kartě s ID I600000101 byl dodavatel s ID ID00000101 nastaven jako hlavní):

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=code

Zkrá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=5

Vý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 CZ Mitsumi"
	}
]

Funkce umožní zrušit příjem hotového výrobku na sklad v API. Supluje tedy funkci ve vizuálním prostředí v agendě Dokončené výrobky, tlačítko Příjem -> Zrušení příjmu na sklad.

Funkce nemá žádné tělo ani parametry.

PUT http://localhost:81/demodata/plmfinishedproducts/id/rows/id1/cancelreceipt

Příklady v této sekci se věnují práci s objednávkami přijatými - podíváme se na jejich načítání, vytváření, úpravy nebo export do PDF.

Vytvoření objednávky přijaté s jedním skladovým řádkem.

POST http://localhost:81/demodata/receivedorders?select=id

Tě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=id

Tě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 ABRA Gen.

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.name

Zkrá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"
	},
	...
]

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čitou skladovou kartu. Jedná se o ukázku omezení podle vnořené kolekce (v tomto případě řádek dokladu) s využitím klauzule exists.

GET http://localhost:81/demodata/receivedorders/?select=displayname,firm_id&expand=rows(storecard_id,store_id,unitquantity,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.

Příklady související s modulem Banka.

V tomto příkladu vygenerujeme Žádost o platební příkaz, a to pomocí endpointu /paymentorderrequests/generate.

POST http://localhost:81/demodata/paymentorderrequests/generate

Endpoint /generate podporuje jen metodu POST s tělem, ve kterém jsou povinné položky class a id zdrojového dokumentu. Např.:

{
    "class": "receivedinvoices",
    "id": "1940000101
}

Položka id může být také formy pole. V takové situaci se pro každý dokument vytváří samostatná žádost. Při této příležitosti je možné přidat i položku merge. Pokud je položka merge nastavena na hodnotu true, vygeneruje se jediná platební žádost pro všechny zdrojové dokumenty. Celý tento mechanismus reflektuje funkce, které lze vyvolat prostřednictvím dialogového okna v systému ABRA Gen.

Další nepovinnou položkou je objekt params, pomocí kterého je možné zadat parametry, které ovlivní zpracování platební žádosti. Provolá se i skriptingový háček GenPOReq_BeforeSaveBO_Hook (stejný jako z vizuálna), kde lze tyto parametry ovlivnit.

Další volitelnou položkou je objekt params, který umožňuje definovat parametry ovlivňující proces zpracování platební žádosti. Při tomto procesu dojde také k vyvolání skriptovacího háčku GenPOReq_BeforeSaveBO_Hook (identického s tím v uživatelském rozhraní), kde je možné tyto parametry upravit.

Příklad zadání kompletních parametrů:

"params": {
    "foreignissue": 1,
    "urgent": 1,
    "paymenttype": 1,
    "bankaccount": "1000000101",
    "constsymbol_id": "0000558000",
    "overwriteallconstsymbols": False,
    "specsymbol": "25097563",
    "description": "důležitá informace - testovací příkaz",
    "amount": 110.45,
    "targetbanksettings": True,
    "targetbankaccount": "8765674938/0300",
    "targetbankname": "airbank",
    "targetbankstreet": "Pražská",
    "targetbankcity": "Praha",
    "targetbankpostcode": "10010",
    "targetbankcountry": "SK",
    "targetbankcountry_id": "00000SK000",
    "swiftcode": "TATRSKBXXXX",
}

Další informace k vybraným položkám:

foreignissue - Způsob úhrady dodatečných poplatků. Může nabývat těchto hodnot:

  • 0 - OUR = všechny poplatky platí plátce - neboli všechny poplatky k tíži účtu příkazce
  • 1 - BEN = poplatky rozděleny mezi plátce a příjemce neboli každý hradí poplatky vzniklé na své straně
  • 2 - SHA = všechny poplatky platí příjemce - neboli všechny poplatky k tíži účtu příjemce

urgent - způsob provedení platby (urgence). Může nabývat těchto hodnot:

  • 0 - STD - standardní
  • 1 - URG - urgentní

paymenttype - typ platby. Může nabývat těchto hodnot:

  • 0 - Určí ovladač
  • 1 - Tuzemská
  • 2 - Zahraniční

Položkay amount a target lze použít jen v kombinaci s jedním zdrojovým dokladem. Položka Amount navíc musí být větší než nula.

Pro položky s prefixem target platí, že pokud se mají tyto položky uplatnit na řádku platební žádosti, musí se nastavit položky targetbanksettings na true.

Níže uvádíme několik příkladů v jazyku Python:

import base64

import requests
from http_constants.headers import HttpHeaders


def _response_info(rsp):
    print("\nresponse information")
    print(f"status code: {rsp.status_code}")
    print("response body:")
    print(rsp.text)


def _paymentorder_info(oid):
    res = session.get(
        url=f"http://localhost:81/demodata/paymentorderrequests/{oid}?select=Amount,Description,TargetBankAccount",
        headers=headers,
    )
    if res.status_code == 200:
        print(f"\nInfo about generated payment\n{res.text}")
    else:
        _response_info(res)


def _delete_paymentorder_info(oid):
    res = session.delete(
        url=f"http://localhost:81/demodata/paymentorderrequests/{oid}", headers=headers
    )
    if res.status_code == 204:
        print("\ngenerated payment deleted\n")
    else:
        _response_info(res)


session = requests.Session()
headers = {}
headers[HttpHeaders.CONTENT_TYPE] = HttpHeaders.CONTENT_TYPE_VALUES.json
headers[HttpHeaders.AUTHORIZATION] = "Basic " + (
    base64.urlsafe_b64encode(("tester" + ":" + "testerp").encode("utf-8"))
).decode("utf-8")

url = "http://localhost:81/demodata/paymentorderrequests/generate"

# Vystavení žádosti o platební příkaz na fakturu přijatou (volá se stejný kód jako v systému ABRA Gen), tedy
# se třeba automaticky doplní nezaplacená částka. Vrací se seznam OID založených platebních příkazů
# jako pole (v tomto případě jen s jedním prvkem, viz další příklady).
body = {"class": "receivedinvoices", "id": "2940000101"}
response = session.post(url=url, headers=headers, json=body)
_response_info(response)
_paymentorder_info(response.json()[0])
_delete_paymentorder_info(response.json()[0])


# Vystavení žádosti o platební příkaz na fakturu přijatou s parametry (volá se i skriptingový háček
# GenPOReq_BeforeSaveBO_Hook stejně jako v případě generování v systému ABRA Gen)
#
# První 3 parametry jsou výčty odpovídající hodnotám z dialogu pro generování žádostí v systému ABRA Gen:
#
# foreingissue - Způsob úhrady dod. popl.:
# 0 - OUR
# 1 - BEN
# 2 - SHA
# urgent - Způsob provedení platby:
# 0 - STD
# 1 - URG
# paymenttype - Typ platby:
# 0 - Určí ovladač
# 1 - Tuzemská
# 2 - Zahraniční
body = {
    "class": "receivedinvoices",
    "id": "2940000101",
    "params": {
        "foreignissue": 1,
        "urgent": 1,
        "paymenttype": 1,
        "bankaccount": "2200000101",
        "constsymbol_id": "0000558000",
        "overwriteallconstsymbols": False,
        "specsymbol": "25097563",
        "description": "důležitá informace - testovací příkaz",
        "amount": 110.45,
        "targetbanksettings": True,
        "targetbankaccount": "8765674938/0300",
        "targetbankname": "airbank",
        "targetbankstreet": "Pražská",
        "targetbankcity": "Praha",
        "targetbankpostcode": "10010",
        "targetbankcountry": "SK",
        "targetbankcountry_id": "00000SK000",
        "swiftcode": "TATRSKBXXXX",
    },
}
response = session.post(url=url, headers=headers, json=body)
_response_info(response)
_paymentorder_info(response.json()[0])
_delete_paymentorder_info(response.json()[0])


# Vystavení jedné žádosti o platební příkaz ze 2 faktur přijatých. Pokud parametr merge zůstane
# na false(výchozí hodnota), vystaví se žádost na každou fakturu přijatou zvlášť.
# V případě zadání více zdrojových dokladů je třeba nastavit bankovní účet v parametrech.
body = {
    "class": "receivedinvoices",
    "merge": True,
    "id": ["2940000101", "1950000101"],
    "params": {
        "bankaccount": "2200000101",
    },
}
response = session.post(url=url, headers=headers, json=body)
_response_info(response)
_paymentorder_info(response.json()[0])
_delete_paymentorder_info(response.json()[0])

Příklady související s ceníky - zejména dotazování na existující záznamy.

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/query

Tě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 - ke skladové kartě byly dohledány dva záznamy v ceníku:

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
			}
		]
	}
]

Další příklad rozšířeného dotazování (dotaz předávaný v těle POST požadavku).

POST http://localhost:81/demodata/storeprices/query

Tě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 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 zadanou skladovou kartu, sklad, jednotku, definici ceny a firmu. Seznam a popis dostupných funkcí naleznete v GenDoc.chm, v kapitole Seznam QuickReports funkcí.

POST http://localhost:81/demodata/qrexpr

Tě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/rows

Tě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"
}

Zde je nutné uvědomit si strukturu cen a ceníku v ABRA Gen a znát patřičná ID.

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 ABRA Gen 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 ke skladové kartě provedeme vytvořením objektu StorePrices vyplněnými řádky cen.

POST http://localhost:81/demodata/storeprices

Tě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 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/query

Tě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
			}
		]
	}
]

Do této sekce jsou zařazeny různé příklady pro práci s modulem Pokladna.

Požadavek:

GET http://localhost:81/demodata/cashdesks/<id pokladny>/cashdesksdocqueues

Výsledek zpracování požadavku:

Status: 200 OK 

[
    {
        "id": "7600000101"
    },
    {
        "id": "8600000101"
    },
    {
        "id": "9600000101"
    },
    {
        "id": "A600000101"
    }
]

Požadavek:

PUT http://localhost:81/demodata/cashdesks/<id pokladny>/addcashdesksdocqueue

Tělo požadavku:

{"id": ["8600000101", "7600000101"]}

Výsledek zpracování požadavku:

Status: 204 No content

Požadavek:

PUT http://localhost:81/demodata/cashdesks/<id pokladny>/removecashdesksdocqueue

Tělo požadavku:

{"id": ["8600000101", "7600000101"]}

Výsledek zpracování požadavku:

Status: 204 No content

Příklady na vyhledávání položek (pozic a skladových karet) a jejich doplňování do hlavních inventárních protokolů a dílčích inventárních protokolů.

Na hlavní inventární protokol s ID 1400000101 přidáme skladovou kartu s ID 2100000101 a jednotkou se zkratkou kg.

POST http://localhost:81/demodata/maininvprotocols/1400000101/storecards

Tě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žadaovaná 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.

Zjišťujeme, zda hlavní inventární protokol s ID 1400000101 obsahuje skladovou kartu s ID 2100000101.

GET http://localhost:81/demodata/maininvprotocols/1400000101/storecards?storecard_id=2100000101

Výsledek zpracování požadavku - protokol skladovou kartu obsahuje, na řádku 1O00000101:

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/positions

Tě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 skladovou kartu s ID 2000000101.

GET http://localhost:81/demodata/maininvprotocols/2300000101/positions?storeposition_id=2000000101

Vý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 se skladovou kartou s ID 1J00000101, jednotkou kg a rovnou nastavíme zjištěný počet 1.

Na dílčích inventárních protokolech lze dohledávat/přidávat skladové karty na dané pozici dílčího inventárního protokolu. Na rozdíl od hlavního protokolu lze při přidávání rovnou i nastavit zjištěný počet pomocí vyplnění položky unitrealquantity. Na řádku dílčího inventárního protokolu lze také dohledávat nebo přidávat šarže/sériová čísla.

POST http://localhost:81/demodata/partialinvprotocolpositions/2000000101/storecards

Tě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 skladové karty a množství 0.

Zjišťujeme, zda v pozici s ID 2000000101 existuje řádek obsahující skladovou kartu s ID 1J00000101.

GET http://localhost:81/demodata/partialinvprotocolpositions/2000000101/storecards?storecard_id=1J00000101

Výsledek zpracování požadavku - pozice skladovou kartu obsahuje, na řádku 1X00000101:

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/storebatches

Tě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=AB00000101

Vý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"
}

Příklady v této sekci se věnují práci s agendou Inventury majetku.

Následující dotaz zobrazí všechny inventury majetku.

GET http://localhost:81/demodata/assetinvs

Výsledek zpracování požadavku:

Status: 200 OK 

{
    "committee_id": "1000000101",
    "correctedat$date": null,
    "correctedby_id": null,
    "createdat$date": "2024-04-02T03:05:42.811Z",
    "createdby_id": "SUPER00000",
    "description": "",
    "docdate$date": "2024-04-01T16:00:00.000Z",
    "docqueue_id": "1O50000101",
    "enddate$date": null,
    "id": "1000000101",
    "inventorystate": 0,
    "inventorytype": 0,
    "objversion": 1,
    "ordnumber": 1,
    "period_id": "1Q90000101",
    "restrictionkind": 0,
    "startdate$date": null
}

K zahájení inventury slouží endpoint /assetinvs/{id}/startinventory.

Nyní provedeme zahájení inventury pro ID 1000000101.

POST http://localhost:81/demodata/assetinvs/1000000101/startinventory

Výsledek zpracování požadavku:

Status: 200 OK 

{
    "classid": "XDU4SZ5ETE04J5VLNPIAUUZZWC",
    "committee_id": "1000000101",
    "correctedat$date": "2024-04-02T03:28:41.377Z",
    "correctedby_id": "SUPER00000",
    "createdat$date": "2024-04-02T03:05:42.811Z",
    "createdby_id": "SUPER00000",
    "description": "",
    "displayname": "IM-1/2024",
    "docdate$date": "2024-04-01T16:00:00.000Z",
    "docqueue_id": "1O50000101",
    "enddate$date": null,
    "id": "1000000101",
    "inventorystate": 1,
    "inventorystateastext": "Zahájena",
    "inventorytype": 0,
    "inventorytypeastext": "Úplná",
    "newrelateddocument_id": "",
    "newrelatedtype": 0,
    "objversion": 4,
    "ordnumber": 1,
    "period_id": "1Q90000101",
    "restrictionkind": 0,
    "restrictionkindastext": "Podle umístění",
    "rows": [
        {
            "classid": "2VM0K45P5L5411NVTYKQKDXXQC",
            "committee_id": "3000000101",
            "displayname": "IM-1/2024-02",
            "id": "1000000101",
            "includedassettypeastext": "Dlouhodobý i drobný majetek",
            "includedassettypes": 0,
            "objversion": 2,
            "parent_id": "1000000101",
            "restrictionrows": [
                {
                    "assetlocation_id": "2000000101",
                    "classid": "CAK55LK2NQS4B5CH5X2DAFO0M4",
                    "displayname": "",
                    "evidencedivision_id": null,
                    "expensesdivision_id": null,
                    "id": "1000000101",
                    "includedassettypes": 0,
                    "objversion": 2,
                    "parent_id": "1000000101",
                    "responsible_id": null
                },
                {
                    "assetlocation_id": "4000000101",
                    "classid": "CAK55LK2NQS4B5CH5X2DAFO0M4",
                    "displayname": "",
                    "evidencedivision_id": null,
                    "expensesdivision_id": null,
                    "id": "2000000101",
                    "includedassettypes": 0,
                    "objversion": 1,
                    "parent_id": "1000000101",
                    "responsible_id": null
                },
                {
                    "assetlocation_id": "3000000101",
                    "classid": "CAK55LK2NQS4B5CH5X2DAFO0M4",
                    "displayname": "",
                    "evidencedivision_id": null,
                    "expensesdivision_id": null,
                    "id": "3000000101",
                    "includedassettypes": 0,
                    "objversion": 1,
                    "parent_id": "1000000101",
                    "responsible_id": null
                }
            ]
        }
    ],
    "startdate$date": "2024-04-02T03:28:41.320Z"
}

Obdobně provedeme zrušení inventury přes endpoint /assetinvs/{id}/cancelinventory a ukončení inventury přes endpoint endpoint /assetinvs/{id}/endinventory.

Endpointy /startinventory, /endinventory a /cancelinventory podporují HATEOAS.

Úvod k používání QuickReports funkcí včetně několika dalších příkladů naleznete v kapitole Struktura URI.

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/qrexpr

Tělo požadavku:

{
	"expr": "NxGetAvailableQuantity('Z100000101','',0)"
}

Výsledek požadavku: 

{
	"result": 9
}

Následující požadavek vrátí dostupné množství skladové karty s ID Z100000101 (snížené o případné rezervace) na skladu s kódem 01.

POST http://localhost:81/demodata/qrexpr

Tělo požadavku:

{
	"expr": "NxGetAvailableQuantity('Z100000101',NxStoreID('01'),0)"
}

Výsledek zpracování požadavku: 

{
	"result": 8
}

V rozhraní API, systému ABRA Gen lze vytvářet i editovat všechny externí dokumenty i dokumenty uložené v ABRA Gen přímo přes endpoint:document.

Popis položek:

  • DataAsBytes: Nepersistentní položka. V JSON je její hodnotou base64 zakódovaný řetězec s dekomprimovaným obsahem souboru. Pokud uživatel volající API dotaz není v seznamu uživatelů s právem pro čtení, potom si nemůže obsah položky dataasbytes zobrazit. Editovat položky dokumentu může jen uživatel s právem pro zápis.
GET http://localhost:80/DemoData/documents/1300000101/contents?select=id,filename,dataasbytes

Návratová hodnota

[
	{
	"id": "1300000101",
	"filename": "GenLogo.jpg"
	"dataasbytes":"80/9j/4QptRXhpZgAATU0AKgAAAAgADAEAAAMAAAABAJsAAAEBAAMAAAABAJYAAAECAAMAAA
	  ADAAAAngEGAAMAAAABAAIAAAESAAMAAAABAAEAAAEVAAMAAAABAAMAAAEaAAUAAAABAAAApAEbAAUAAAA
	  4IDE2OjAwOjE1AAAAAASQAAAHAAAABDAyMjGgAQADAAAAAQABAACgAgAEAAAAAQAAAJugAwAEAAAAAQAA
	  YAAAAAAAAABgEDAAMAAAABAAYAAAEaAAU"														
    }
]
PUT http://localhost:80/DemoData/documents/24A0000101/contents/23A0000101

Tělo požadavku

{
	"dataasbytes": "T2JzYWggZXh0ZXJuw61obyBzb3Vib3J1IG5vdsO9"
}

Příklady v této sekci se týkají vytvoření nového obrázku z různých zdrojů.

Pro práci s obrázky se používají dva parametry:

  • Picturetype: není uživatelsky editovatelný a obsahuje řetězec s typem reprezentovaného obrázku.
  • Picturedata: obsahuje base64 zakódována binární data obrázku, tak, jak jsou v obrázku přirozeně uložena, bez přídavné hlavičky. Přes tuto položku je tak možné data přímo přečíst nebo uložit. Položka funguje i pro externí obrázky.

Ukázka uložení obrázku do databáze. Obrázek je obsažen v položce Picturedata.

POST http://localhost:80/DemoData/pictures

Tělo požadavku:

{
	"externalfile": false,
	"picturetitle": "obrazekvdb",
	"picturedata": "R0lGODlhWAImAvcAAAAAAIAAAACAAICAAAAAgIAAgACAgICAgM"
}

Ukázka uložení obrázku do databáze. Obrázek je obsažen v cestě uloženou v položce Pathandfilename.

POST http://localhost:80/DemoData/pictures

Tělo požadavku:

{
	"pathandfilename": "C:\\Users\\toje\\Desktop\\obrazek.gif",
	"externalfile": false,
	"picturetitle": "obrazekvdbzesouboru"
}

Ukázka uložení obrázku do externího souboru, jehož umístění a název se zadá do položky Pathandfilename. Obrázek je obsažen v položce Picturedata.

POST http://localhost:80/DemoData/pictures

Tělo požadavku:

{
	"pathandfilename": "C:\\Users\\toje\\Desktop\\obrazekexterni.gif",
	"externalfile": true,
	"picturetitle": "obrazekexterni",
	"picturedata": "R0lGODlhWAImAvcAAAAAAIAAAACAAICAAAAAgIAAgACAg"
}

Ukázka uložení obrázku do externího souboru uveden v položce Ppathandfilename. Obrázek je obsažen v položce Pathandfilename.

POST http://localhost:80/DemoData/pictures

Tělo požadavku:

{
	"pathandfilename":"C:\\Users\\toje\\Desktop\\obrazekexternizesouboru.gif",
	"externalfile": true,
	"picturetitle": "obrazekexternizesouboru"
}

Příklady práce (GET, POST PUT) s položkami s historií v rámci API.

Ukázka vytvoření karty drobného majetku obsahující položku s historií.

POST http://localhost:80/DemoData/smallassetcards?select=ID

Tělo požadavku:

{
	"name": "karta majetu",
	"responsible_id": "3000000101",
	"dateofchange": "2022-10-20T",
	"assetlocation_id": "3000000101",
	"evidencedivision_id":"2100000101"
	"expensesdivision_ID": "2100000101"
}

Ukázka přidání hodnoty do položky s historií k již existujícímu záznamu

PUT http://localhost:80/DemoData/smallassetcards/8210000101?Select=ID

Tělo požadavku:

{
	"responsible_id": "4000000101",
	"dateofchange": "2022-10-21T"
}

Ukázka získání hodnoty položky s historií, která je platná k nějakému konkrétnímu datu. V případě našeho příkladu 21.10.2022.

GET http://localhost:80/DemoData/smallassetcards/query?vieweddate=2022-10-21T

Tělo požadavku:

{
	"select": [
	   "responsible_id.person_id.firstname"
	],
	"where": "ID = '8210000101' and responsible_id.person_id.firstname <> 'Otakar'"
}

Do této sekce jsou zařazeny různé příklady pro práci s modulem Projektové řízení.

Požadavek:

PUT http://localhost:81/demodata/crmactivitytypes/<id typu aktivity>/addactivityprocess

Tělo požadavku:

{"id": ["8600000101", "7600000101"]}

Výsledek zpracování požadavku:

Status: 204 No content

Obdobně lze procesy aktivit odpojit pomocí endpointu /removeactivityprocess.

Požadavek:

PUT http://localhost:81/demodata/crmactivitytypes/<id typu aktivity>/addactivityarea

Tělo požadavku:

{"id": ["8600000101", "7600000101"]}

Výsledek zpracování požadavku:

Status: 204 No content

Obdobně lze oblasti aktivit odpojit pomocí endpointu /removeactivityarea.

Požadavek:

PUT http://localhost:81/demodata/crmactivitytypes/<id typu aktivity>/addactivityqueue

Tělo požadavku:

{"id": ["8600000101", "7600000101"]}

Výsledek zpracování požadavku:

Status: 204 No content

Obdobně lze řady aktivit odpojit pomocí endpointu /removeactivityqueue.

Endpoint /servicedocuments podporuje HATEOAS.

Mějme neuzavřený servisní list s ukončenými montážními listy (a vydaným materiálem).

Požadavek:

PUT localhost:81/demodata/servicedocuments/1000000101/close

Tělo požadavku:

{
    "guarantyrepair": 2,
    "servicedocpaymenttype": 1,
    "insurancefirm_id": null,
    "servicedocstate_id": "D102000000",
    "garanteeenddate": "2023-02-15T",
    "addtinymaterialcalc": {
        "tinymaterialpercent": 10,
        "tinymaterialbaserange": {
            "tinymaterialbaselessthan": 99999999,
            "tinymaterialbasegreaterthan": 0
        },
        "workbaserange": {
            "workbaselessthan": 99999999,
            "workbasegreaterthan": 0
        },
        "onlyforstore_id": null,
        "exceptstore_id": null
    }
}

Výsledek dotazu:

Status: 200 OK 

{
    "acceptedbyuser_id": "4300000101",
    "address_id": "1100000101",
    "busorder_id": null,
    "busproject_id": null,
    "bustransaction_id": null,
    "changedstorebatch_id": null,
    "changedstorecard_id": null,
    "classid": "BCHF52UGXCO4H5MIAQVY5P3ZOC",
    "correctedby_id": "SUPER00000",
    "createdby_id": "SUPER00000",
    "currency_id": "0000CZK000",
    "damagedescription": "",
    "dateofchange": "2024-02-23T16:00:00.000Z",
    "defects": [
        {
            "charged": true,
            "classid": "WSM5RRXCO55OT3QTVRB4XCA15C",
            "defecttext": "Ulomená anténa",
            "displayname": "Řádek č. 1",
            "estimatedprice": 0,
            "estimatedpricewithoutvat": 500,
            "id": "1000000101",
            "objversion": 2,
            "parent_id": "1000000101",
            "posindex": 1,
            "servicedefect_id": null
        }
    ],
    "defectsastext": "Ulomená anténa",
    "displayname": "SL-1/2011",
    "division_id": "1200000101",
    "docdate$date": "2011-06-08T02:27:27.057Z",
    "docqueue_id": "1E00000101",
    "docs": [],
    "equipment": "",
    "estimatedprice": 500,
    "firm_id": "3000000101",
    "firmoffice_id": "3000000101",
    "firstserviceassemblyform_id": "1000000101",
    "guaranteeenddate": null,
    "guarantyrepair": 2,
    "guarantyrepairastext": "ano",
    "id": "1000000101",
    "informclientkind": 1,
    "insuarancefirm_id": null,
    "internaltext": "",
    "invoicedamount": 0,
    "lastclosingdocstate_id": "D102000000",
    "mainsourcestore_id": null,
    "newrelateddocument_id": "",
    "newrelatedtype": 0,
    "objectkind": 2,
    "objversion": 5,
    "operations": [],
    "ordnumber": 1,
    "outdoorplacedescription": "",
    "payerfirm_id": null,
    "payerfirmoffice_id": null,
    "payerperson_id": null,
    "paymenttype": 1,
    "period_id": "1900000101",
    "person_id": "5000000101",
    "pictures": [],
    "priority": 0,
    "promiseddeadline$date": "2011-06-10T14:27:27.057Z",
    "quantity": 1,
    "returnedatdate$date": null,
    "returnedbyuser_id": null,
    "salebillofdelivery_id": null,
    "servicedobject_id": null,
    "servicedobjectidcode": "02",
    "servicedobjectonstore": false,
    "servicedobjectserialnr": "P25651-123",
    "servicedobjecttext": "",
    "servicedobjecttype_id": "N000000101",
    "servicedocstate_id": "D102000000",
    "servicesolutionkind_id": null,
    "servicetype_id": "1000000101",
    "store_id": null,
    "storebatch_id": null,
    "storecard_id": "3100000101",
    "storereceiptdoctype": 0,
    "subjectcode": "02",
    "subjectname": "TV Panasonic TX-14B4TP",
    "subjectserial": "P25651-123",
    "tinymaterial": 0,
    "totalamount": 0,
    "totalmaterial": 0,
    "totalother": 0,
    "totalwork": 0,
    "totalworkoperationtime": 0
}

Mějme uzavřený servisní list bez připojených faktur.

Požadavek:

PUT localhost:81/demodata/servicedocuments/1000000101/unclose

Výsledek dotazu:

Status: 200 OK 

{
    "acceptedbyuser_id": "4300000101",
    "address_id": "1100000101",
    "busorder_id": null,
    "busproject_id": null,
    "bustransaction_id": null,
    "changedstorebatch_id": null,
    "changedstorecard_id": null,
    "classid": "BCHF52UGXCO4H5MIAQVY5P3ZOC",
    "correctedby_id": "SUPER00000",
    "createdby_id": "SUPER00000",
    "currency_id": "0000CZK000",
    "damagedescription": "",
    "dateofchange": "2024-02-23T16:00:00.000Z",
    "defects": [
        {
            "charged": true,
            "classid": "WSM5RRXCO55OT3QTVRB4XCA15C",
            "defecttext": "Ulomená anténa",
            "displayname": "Řádek č. 1",
            "estimatedprice": 0,
            "estimatedpricewithoutvat": 500,
            "id": "1000000101",
            "objversion": 2,
            "parent_id": "1000000101",
            "posindex": 1,
            "servicedefect_id": null
        }
    ],
    "defectsastext": "Ulomená anténa",
    "displayname": "SL-1/2011",
    "division_id": "1200000101",
    "docdate$date": "2011-06-08T02:27:27.057Z",
    "docqueue_id": "1E00000101",
    "docs": [],
    "equipment": "",
    "estimatedprice": 500,
    "firm_id": "3000000101",
    "firmoffice_id": "3000000101",
    "firstserviceassemblyform_id": "1000000101",
    "guaranteeenddate": null,
    "guarantyrepair": 2,
    "guarantyrepairastext": "ano",
    "id": "1000000101",
    "informclientkind": 1,
    "insuarancefirm_id": null,
    "internaltext": "",
    "invoicedamount": 0,
    "lastclosingdocstate_id": "D102000000",
    "mainsourcestore_id": null,
    "newrelateddocument_id": "",
    "newrelatedtype": 0,
    "objectkind": 2,
    "objversion": 6,
    "operations": [],
    "ordnumber": 1,
    "outdoorplacedescription": "",
    "payerfirm_id": null,
    "payerfirmoffice_id": null,
    "payerperson_id": null,
    "paymenttype": 1,
    "period_id": "1900000101",
    "person_id": "5000000101",
    "pictures": [],
    "priority": 0,
    "promiseddeadline$date": "2011-06-10T14:27:27.057Z",
    "quantity": 1,
    "returnedatdate$date": null,
    "returnedbyuser_id": null,
    "salebillofdelivery_id": null,
    "servicedobject_id": null,
    "servicedobjectidcode": "02",
    "servicedobjectonstore": false,
    "servicedobjectserialnr": "P25651-123",
    "servicedobjecttext": "",
    "servicedobjecttype_id": "N000000101",
    "servicedocstate_id": "C102000000",
    "servicesolutionkind_id": null,
    "servicetype_id": "1000000101",
    "store_id": null,
    "storebatch_id": null,
    "storecard_id": "3100000101",
    "storereceiptdoctype": 0,
    "subjectcode": "02",
    "subjectname": "TV Panasonic TX-14B4TP",
    "subjectserial": "P25651-123",
    "tinymaterial": 0,
    "totalamount": 0,
    "totalmaterial": 0,
    "totalother": 0,
    "totalwork": 0,
    "totalworkoperationtime": 0
}

Příklady v této sekci se týkají funkcionality obecné ochrany dat.

Příznak Zaměstnanec/Pracovník v agendě Adresář 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,isemployee

Tě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. Více viz popis příznaku v kapitole Adresář osob - záložka Detail.

Příznak Právnická osoba v agendě Adresář 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,legalperson

Tě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.

Příklady související s modulem E-maily a interní vzkazy.

E-mail lze odeslat pouze tehdy, když je ve stavu koncept. Do dotazu je možné zadat stejné select parametry jako pro obecný dotaz na business objekt.

PUT http://localhost:81/demodata/emailsents/${emailsent_id}/send?select=sentstate

Akci /setasread je nutné volat nad konkrétní instancí BO:

Endpoint /msgssent podporuje HATEOAS.

PUT http://localhost:81/demodata/msgssent/1000000101/setasread

Výsledek požadavku:

Status: 200 OK 

{
    "attachments": [],
    "classid": "33XZARXR1BM4L55MOX54NTRBWG",
    "confirmreading": true,
    "deleteafterdeletingbyall": true,
    "displayname": "Test (Super)",
    "id": "1000000101",
    "links": [],
    "msgbody": "Lorem ipsum dolor sit amet.",
    "msgsubject": "Test",
    "objversion": 1,
    "recipients": [
        {
            "classid": "HM5J53LDNXYOZAJLUODFDFINHC",
            "displayname": "DARA",
            "email": "",
            "emailaccount_id": null,
            "id": "1000000101",
            "objversion": 1,
            "parent_id": "1000000101",
            "posindex": 1,
            "recipienttype": 0,
            "securitygroup_id": null,
            "securityrole_id": null,
            "securityuser_id": "4300000101"
        }
    ],
    "recipientsinoneline": "Daniel Rasak",
    "senderuser_id": "SUPER00000",
    "sentdate$date": "2024-02-24T09:23:18.064Z",
    "validtodate$date": null
}

Uživatelské parametry je možné definovat v agendě Skupiny parametrů. Přístup do skupin parametrů je realizován přes následující endpointy:

http://localhost:81/demodata/userparamgroups
http://localhost:81/demodata/userparamgroups/[ID]/rows
http://localhost:81/demodata/userparamgroups/[ID]/assignments

Čtení parametrů je realizováno přes endpoint /userparameters obecného předka všech BO. Načtení všech parametrů např. pro sklad s ID 3200000101 provedeme takto:

GET http://localhost:81/demodata/stores/3200000101/userparameters

Odpověď obsahuje všechny parametry definované pro daný BO rozdělené do skupin. Skupiny jsou seřazené ve správném pořadí. Pokud má nějaký parametr vyplněnou hodnotu, je tato hodnota součástí vrácených dat. Na volání tohoto endpointu je třeba právo Spustit na objekt, ke kterému se parametr váže.

Ukládání hodnot parametrů je realizováno přes standardní rozhraní API objektu UserParamValues.

Založení nové hodnoty parametru s ID 1020000101 pro sklad s ID 3200000101:

POST http://localhost:81/demodata/userparamvalues
{
  "CLSID": "SFMSB5W15BDL3CL100C4RHECN0",
  "Object_ID": "3200000101",
  "UserParam_ID": "1020000101",
  "ParamValue": "bbb"
}

Aktualizace hodnoty s ID 10B0000101 (ID hodnoty získáme po přečtení parametrů endpointem /userparameters):

PUT http://localhost:81/demodata/userparamvalues/10B0000101
{
  "ParamValue": "ddd"
}

Kromě pole ParamValue existují pro zápis tyto speciální pole:

  • ParamValueAsString

  • ParamValueAsInteger

  • ParamValueAsFloat

  • ParamValueAsBoolean

  • ParamValueAsDateTime

Hodnotu pole je třeba vyplnit polem správného typu. Tato pole existují proto, aby na pozadí provedly správnou konverzi do stringové hodnoty v perzistentním poli ParamValue. Aby uživatel mohl uložit hodnotu parametrů, musí mít nejprve k uživatelským parametrům licenci a dále buď právo Opravit na objekt, ke kterému se parametr váže, nebo privilegium Obcházet práva k API.

Vytvoření skupiny uživatelských parametrů s jedním parametrem a přířazením k jedné třídě business objektu (v příkladu Skladová karta).

POST http://localhost:81/demodata/userparamgroups?select=id

Tělo požadavku:

{
    "code": "SK1",
    "name": "Vlastnosti zboží",
    "description": "Vlastnosti zboží na skladové kartě",
    "rows": [
        {
            "code": "SK1B",
            "name": "Barva",
            "defaultvalue": "Černá",
            "isreadonly": false,
            "paramtype": 0
        }
    ],
    "assignments": [
        {
            "boclsid": "C3V5QDVZ5BDL342M01C0CX3FCC",
            "usealways": false,
            "condition": "Category=1"
        }
    ]
}

Hodnoty paramtype pro jednotlivé typy parametrů jsou:

  • 0 - Text

  • 1 - Celé číslo

  • 2 - Ano/Ne

  • 3 - Desetinné Číslo

  • 4 - Peníze

  • 5 - Datum

Výsledek zpracování požadavku (byla vytvořena skupina uživatelských parametrů s ID 5000000101):

Status: 201 Created 

{
    "id": "5000000101"
}

Čtení uživatelských parametrů na vybraném business objektu (v příkladu Skladová karta).

Požadavek:

GET http://localhost:81/demodata/storecards/1J00000101/userparameters

Výsledek zpracování požadavku Odpověď obsahuje všechny parametry definované pro daný business objekt rozdělené do skupin, skupiny jsou seřazené ve správném pořadí. Pokud má nějaký parametr vyplněnou hodnotu, je tato hodnota součástí vrácených dat.

Status: 200 OK 

{
    "userparametergroups": [
        {
            "id": "2000000101",
            "order": 0,
            "code": "SK1",
            "name": "Vlastnosti zboží",
            "description": "Vlastnosti zboží na skladové kartě",
            "userparameters": [
                {
                    "id": "2000000101",
                    "code": "SK1B",
                    "name": "Barva",
                    "description": "",
                    "isreadonly": false,
                    "type": 0,
                    "precision": 0,
                    "rollclsid": null,
                    "defaultvalue": "Černá",
                    "minimalvalue": "",
                    "maximalvalue": "",
                    "value_id": null,
                    "valuecorrectedat$date": null,
                    "valuecorrectedby_id": null,
                    "valuecorrectedby_id_name": "",
                    "valueisset": false,
                    "value": "Černá"
                },
                {
                    "id": "6000000101",
                    "code": "SK1V",
                    "name": "Váha [kg]",
                    "description": "",
                    "isreadonly": false,
                    "type": 3,
                    "precision": 1,
                    "rollclsid": null,
                    "defaultvalue": "2",
                    "minimalvalue": "0.1",
                    "maximalvalue": "20",
                    "value_id": "1000000101",
                    "valuecorrectedat$date": "2023-09-21T13:44:55.080Z",
                    "valuecorrectedby_id": "SUPER00000",
                    "valuecorrectedby_id_name": "Supervisor",
                    "valueisset": true,
                    "value": 4.5
                }
            ]
        }
    ]
}

Založení nové hodnoty uživatelského parametru s ID 2000000101 pro skladovou kartu s ID 1J00000101:

Požadavek

POST http://localhost:81/demodata/userparamvalues?select=id

Tělo požadavku:

{
	"CLSID": "C3V5QDVZ5BDL342M01C0CX3FCC",
	"Object_ID": "1J00000101",
	"UserParam_ID": "2000000101",
	"ParamValue": "Zelená"				
}

Kromě ParamValue jsou pro zápis vytvořená speciální pole ParamValueAsString, ParamValueAsInteger, ParamValueAsFloat, ParamValueAsBoolean a ParamValueAsDateTime. Hodnota by se měla plnit polem správného typu v závislosti na typu parametru.

Výsledek zpracování požadavku (byla vytvořena nová hodnota pro zadaný parametr na zadaném business objektu s ID 2000000101):

Status: 201 Created 

{
   "id": "2000000101"
}

Schvalování dokladů lze realizovat dvěma způsoby.

Jde o obdobu schválení dokladů v rámci jednotlivých dokladových agend.

Přehled schvalovaní pro aktuální doklad:

GET http://localhost:81/demodata/{BO kolekce dokladu}/{id}/docconfirmation

Zahájení schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/{BO kolekce dokladu}/{id}/docconfirmation/start

Zamítnutí schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/{BO kolekce dokladu}/{id}/docconfirmation/reject

Vrácení k doplnění schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/{BO kolekce dokladu}/{id}/docconfirmation/return

Schválení aktuálního dokladu.

PUT http://localhost:81/demodata/{BO kolekce dokladu}/{id}/docconfirmation/confirm

U /reject, /return a /confirm lze pomocí nastavit poznámku v těle požadavku PUT:

{
    "note": "<string>"
}

V tomto příkladu schválíme nabídku vydanou a přidáme na ni schvalovací poznámku.

PUT http://localhost:81/demodata/issuedoffers/5620000101/docconfirmation/confirm

Tělo požadavku:

{
    "note": "OK"
}

Status: 200 OK

Výsledkem zpracování dotazu je schválená nabídka vydaná.

Schvalování přes všechny doklady se realizuje na endpointu /docconfirmations. Jde o obdobu schválení dokladů v rámci agendy Schvalování dokladů.

Přehled schvalovaní pro aktuální doklad:

GET http://localhost:81/demodata/docconfirmations

Zahájení schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/docconfirmations/{BO}/start

Zamítnutí schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/docconfirmations/{BO}/reject

Vrácení k doplnění schvalování aktuálního dokladu:

PUT http://localhost:81/demodata/docconfirmations/{BO}/return

Schválení aktuálního dokladu.

PUT /docconfirmations/{BO}/confirm

U /reject, /return a /confirm lze pomocí nastavit poznámku v těle požadavku PUT:

{
  "note": "<string>"
}

V tomto příkladu schválíme nabídku vydanou a přidáme na ni schvalovací poznámku.

PUT http://localhost:81/demodata/docconfirmations/5620000101/confirm

Tělo požadavku:

{
    "note": "OK"
}

Status: 200 OK

Výsledkem zpracování dotazu je schválená nabídka vydaná.

Další příklady z praxe, které se nevešly do žádné z předchozích kategorií.

Příklad na použití funkce NxSQLSelect.

POST http://localhost:81/demodata/qrexpr

Tě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/query

Tě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 na použití importního manažeru. Seznam implementovaných parametrů je k dispozici v GenDoc.chm v kapitole Seznam importních managerů.

POST http://localhost:81/demodata/billsofdelivery/import/receivedorders/1700000101?select=id,displayname

Tě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_documents s polem ID importovaných objektů:

{
  "input_documents": ["1700000101", "1800000101"],
  "params": { ...... }
}

Další příklad použití importního manažeru. Seznam implementovaných parametrů je k dispozici v GenDoc.chm, v kapitole Seznam importních managerů.

POST http://localhost:81/demodata/otherincomes?select=id,displayname

Tě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"
}

Zápis tržby do systému, získání FIK a BKP.

PUT http://localhost:81/demodata/eetturnovers/3300000101/process

Zkrá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/colors

Vý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
	}
]

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=displayname

Zkrácený výsledek zpracování požadavku:

Status: 200 OK 

[
	{
		"displayname": "FV-1/0000"
	},
	{
		"displayname": "FV-2/0000"
	}
	...
]

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+DisplayName

Zkrácený výsledek zpracování požadavku:

Status: 200 OK 

[
	{
		"DisplayName": "FV-1/0000"
	},
	{
		"DisplayName": "FV-2/0000"
	}
	...
]

Příklad použití vnořeného EXISTS v klauzuli WHERE.

POST http://localhost:81/demodata/query

Tě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"
					}
				]
			}
		]
	}
]

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/8M00000101

Tělo požadavku:

{
	"description": "dodávka 9/2018",
	"rows": [
		{
			"id": "VM00000101",
			"unitprice" : 3000.0,
			"unitquantity": 4
		}
	]
}

Mazání řádků lze provést pomocí klíčového slova "kolekce@delete", které se skládá z názvu kolekce a @delete. Hodnotou je objekt obsahující 4 nepovinné klíče:

  • All - "All": true
    Tento klíč s hodnotou true říká, že mají být smazány všechny řádky, vyjma řádků obsažených v seznamu ExcludeIDs.
  • Where - "Where": "podmínka"
    Umožňuje zadat query podmínku, která vrací řádky určené ke smazání.
  • IncludeIDs - "IncludeIDs": []
    Jednoduché zadání seznamu ID řádků ke smazání, vyhodnotí se jako sjednocení s podmínkou Where.
  • ExcludeIDs - "ExcludeIDs": []
    Seznam řádků, které se nemají mazat, jsou odebrány od sjednocení Where a IncludeIds, případně z All, pokud je použito.

Tělo požadavku:

{
 "kolekce@delete": {
  "All": true,
  "Where": "Firm_ID ne 1100000101",
  "IncludeIDs": ["2000000101"],
  "ExcludeIDs": ["3000000101"]
 },
 "kolekce": [
  {
   "id": "3000000101",  //tomuto řádku bude nastavena položka na hodnotu 5
   "položka": 5
  },
  {
   "id": "2000000101",  //chyba, nelze updatovat řádek, který je určen ke smazání 
   "položka": 5
  },
  {
   "položka": 5  //založí se nový řádek s hodnotou 5
  }
 ]
}

Požadavek:

POST na http://localhost:81/demodata/firms

Tělo požadavku:

{
    "Code": "TestX",
    "Name": "Firma bez předvyplnění provozovny",
    "firmoffices": [
        {
            "address_id": {
                "city": "London",
                "country": "GB",
                "email": "kvak@kvak.cz"
            },
            "masscorrespondence": true,
            "name": "some name",
            "synchronizeaddress": false
        }
    ],
    "firmoffices@delete": {
        "All": true
    },
    "TAXIdentNumber": "",
    "VATIdentNumber": ""
}

Výsledek dotazu:

Status: 201 Created

Obdobně lze například řešit i založení skladové karty bez první jednotky.

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)

Tělo požadavku (zkrácené):

{
	"Category_ID": "5000000000",
	"DocQueue_ID": "E200000101",
	"Contents": [
		{
			"Description": "PopisAPITest",
			"FileName": "TestSouboru.pdf",
			"DataAsBytes": "JVBERi0xLjcNCiW1tbW1DQoxIDA..... dHhyZWYNCjMzOTI3DQolJUVPRg=="
		}
		 ]
}

Výsledek zpracování požadavku:

Status: 201 Created 

{
	"id": "5400000101",
	"displayname": "OLE-2/2022",
	"description": "",
	"Contents": [
	 {
		"id": "4300000101",
		"description": "PopisAPITest"
		 }
	]
}

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_id

Tě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říklad ukazuje situaci, kdy máme daňovou zálohu na 5000 Kč. Pomocí importu založíme FV s jedním řádkem na 2000 Kč a zúčtujeme DZV ve výši 2000 Kč.

POST http://localhost:81/demodata/import?select=id,displayname

Tělo požadavku

{
   "input_document_clsid": "S3YFE5QQNYQORJXLJWXDL3QV0K",
   "output_document_clsid": "O3BDOKTWEFD13ACM03KIU0CLP4",
   "input_documents": "C0B0000101",
   "params": {
       "DepositAmounts": 2000,
       "DocQueue_ID": "4000000101"
   },
   "output_document_update": {
   "Description": "DZV do Fv přes API",
   "rows": [
	 {
		"rowtype": "2",
		"text": "Technická podpora",
		"vatrate_id": "02100X0000",
		"division_id": "1000000101",
		"quantity": 1,
		"qunit": null,
		"unitprice": "5000.00"
    	}
   ]
 } 
}

Výsledek zpracování požadavku je vytvoření Faktury vydane se zaúčtováním DVZ ve výši 2000 Kč.

Další příklad použití importního manažeru. Tentokrát se bude importovat víceřádkový DZV do FV.

Mějme Daňový zálohový list vydaný, který má dva řádky:

řádek 1: částka 500, 21% DPH

řádek 2: částka 1000, 21% DPH

Při importu daňové zálohy do faktury je třeba u parametru DepositAmount provést oddělení částek jednotlivých řádků daňové zálohy pomocí znaků \n viz tento příklad.

POST http://localhost:81/demodata/import?select=id,displayname

Tělo požadavku:

{
    "input_document_clsid": "S3YFE5QQNYQORJXLJWXDL3QV0K",
    "output_document_clsid": "O3BDOKTWEFD13ACM03KIU0CLP4",
    "input_documents": "E0C0000101",
    "params": {
        "DepositAmounts":"500\n1000",
        "DocQueue_ID": "4000000101"
    },
    "output_document_update": {
        "Description": "DZV do Fv přes API",
        "PricesWithVAT": true,
        "rows": [
            {
                "rowtype": "2",
                "text": "Technická podpora",
                "vatrate_id": "02100X0000",
                "division_id": "1000000101",
                "quantity": 1,
                "qunit": null,
                "unitprice": "1500.00"
            }
        ]
    }
}

Požadavek:

GET http://localhost:81/demodata/api-docs/documenttypes

Výsledek zpracování požadavku:

Status: 200 OK 

[
    {
        "documenttype": "33",
        "x-abra-bo-name": "Přesun mezi pozicemi",
        "x-abra-bo-clsid": "IFQWSXYA5XBOH3ZUHIYD4C4WY0"
    },
    {
        "documenttype": "P0",
        "x-abra-bo-name": "Odeslaná pošta",
        "x-abra-bo-clsid": "EFMK3ZXZQGE4B1SSCYEBDGMCCK"
    },
    ...
]

Kurzovní lístky je možné aktualizovat přes endpoint /updateexchangerates.

POST http://localhost:81/demodata/exchangerates/updateexchangerates

Tělo požadavku:

{
    "exchange_rates_source": 1,
    "exchange_rates_date_offset": 0,
    "exchange_rates_use_previous": false,
    "exchange_rates_individual_WWW": ""
}

Podrobnosti k parametrům:

  • exchange_rates_source - zdroj dat kurzovního lístku. Platné hodnoty:

    • 1 - Korunový z webu ČNB

    • 9 - Korunový z webu ČNB (ostatní měny)

    • 4 - Eurový z webu ECB

    • 2 - Korunový z webu Abra

    • 3 - Individuální zdroj

  • exchange_rates_date_offset - datum platnosti kurzovního lístku. Platné hodnoty:

    • 0 - Aktuální kurz

    • 1 - Dnes

    • 2 - Včera

    • 3 - Předevčírem

  • exchange_rates_use_previous - použít nejbližší předchozí kurz. lístek

  • exchange_rates_individual_WWW - Individuální WWW adresa (nepovinný parametr)

První tři parametry jsou povinné. Pokud nejsou vyplněné nebo mají špatnou hodnotu, API vrátí chybu i s informacemi, jaké jsou platné hodnoty.

Níže uvádíme skript v Pythonu, který umožní hromadnou aktualizaci kurzovního lístku na všech spojeních, které jsou ve stavu OK. Je třeba mít nainstalovaný Python a modul requests. Ten se nainstaluje takto:

pip install requests

Skript v Pythonu pojmenujme update_exchangerates_all_connections.py. Bude obsahovat:

import requests
ABRA_API_URL = "http://localhost"
USERNAME = "Supervisor"
PASSWORD = ""
def update_exchangerates(connection_name):
    """Aktualizuje kurzy v předaném spojení"""
    try:
        url = f"{ABRA_API_URL}/{connection_name}/exchangerates/updateexchangerates"
        # parametry pro aktualizaci kurzů
        params = '{"exchange_rates_source": 1, "exchange_rates_date_offset": 0, "exchange_rates_use_previous": false}'
        response = requests.post(url, timeout=60, data=params, auth=(USERNAME, PASSWORD))
        if response.status_code == 200:
            print(f"{connection_name}: SUCCESS")
            if response.text:
                print(response.text)
        else:
            print(f"{connection_name}: FAIL: {response.status_code} - {response.reason} - {response.text}")
    except Exception as e:
        print(f"{connection_name}: FAIL: {e}")
def update_exchangerates_all_connections(url):
    """Získá seznam spojení a pro každé zavolá aktualizaci kurzů"""
    try:
        # vypíšeme si seznam spojení
        response = requests.get(url, timeout=15)
        if response.status_code == 200:
            json_data = response.json()
            # pro každé spojení zavoláme aktualizaci kurzovního lístku
            for connection in json_data["connections"]:
                if connection["state"] == "OK":
                    update_exchangerates(connection["name"])
        else:
            print(f"FAIL: {response.status_code} - {response.reason} - {response.text}")
    except Exception as e:
        print(f"FAIL: {e}")
# Example usage
if __name__ == "__main__":
    update_exchangerates_all_connections(ABRA_API_URL)

Skript spustíme takto:

python.exe .\update_exchangerates_all_connections.py

Další příklady využití Web API je možné nalézt také v následujících kapitolách: