Web API - Zpracování požadavků v mezipaměti (/serverstate)

Nejprve v mezipaměti vytvoříme novou fakturu vydanou.

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
        	 "cacheid": "xb1",
        	 "type": "create",
        	 "data": {
        		"class": "issuedinvoices",
        		"object_data": {
				    "firm_id": "F011000000",
        			"docqueue_id": "5600000101",
        			"storedocqueue_id": "P600000101",
        			"rows": [
        				 {
        					 "@temporaryid": "ID1",
        					 "rowtype": 0,
        					 "text": "testovaci radek",
        					 "division_id": "2100000101"
        				 },
        				 {
        					 "@temporaryid": "ID2",
        					 "rowtype": 3,
        					 "store_id": "2100000101",
        					 "storecard_id": "2100000101",
        					 "unitquantity": 10,
        					 "unitprice": 20.5,
        					 "division_id": "2100000101"
        				 }
        			]
        		}
        	 }
        }

V dalším kroku aktualizujeme popis na faktuře, upravíme existující řádek, další řádek smažeme a doplníme nový řádek.

Hodnoty objid, které začínají na NEW_, je, jak bylo řečeno výše, třeba získat z dat po předchozím kroku a doplnit tyto konkrétní hodnoty.

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
            "cacheid": "xb1",
            "type": "update",
            "data": {
                "class": "issuedinvoices",
		        "object_id": "NEW_FV_OID",
                "object_data": {
                    "description": "testovaci faktura",
                    "rows": [
                        {
                            "id": "NEW_ROW_OID_1",
                            "text": "zmena textu"
                        },
                        {
                            "@temporaryid": "ID4",
                            "rowtype": 0,
                            "text": "textovy radek c 2",
                            "division_id": "2100000101"
                        }
                    ]
                    "rows@delete": {
                        "IncludeIDs": [NEW_ROW_OID_3]
                    }
                }
            }
        }

V posledním kroku aktualizujeme položku unitquantity na řádku identifikovaném NEW_ROW_OID_2 a fakturu uložíme do databáze.

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
            "cacheid": "xb1",
            "type": "save",
            "data": {
                "class": "issuedinvoices",
		  "object_id": "NEW_FV_OID",
                "object_data": {
                    "rows": [
                        {
                            "id": "NEW_ROW_OID_2",
                            "unitquantity": 12
                        }
                    ]
                }
                    "query": {
                    "select": [
                        "id"
                    ]
                }
            }
        }

V tomto příkladu provedeme import objednávky přijaté do dokladu Výdejka.

Mějme čerpatelnou objednávku přijatou s ID 15C0000101.

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "xb1",
    "type": "import",
    "data": {
            "class": "billsofdelivery",
	        "import_data": {
            "input_document_clsid": "01CPMINJW3DL342X01C0CX3FCC",
            "output_document_clsid": "050I5SAOS3DL3ACU03KIU0CLP4",
            "input_documents": "15C0000101",
            "params": {
                "docqueue_id": "P600000101"
            }
        },
        "object_data": {},
        "query": {
            "select": [
                "ID"
            ]
        }
    }
}

Status: 200 OK

Výsledek zpracování dotazu:

{
    "data": {
        "ID": "49F0000101",
        "@meta": {
            "version": 1
        }
    }
}

V tomto příkladu vytvoříme v mezipaměti fakturu vydanou a následně vyfiltrujeme ID a kódy středisek z číselníku z druhého řádku této faktury pomocí typu fieldlookup.

Skript v jazyce Python:

import base64
import json
import sys

import requests
from http_constants.headers import HttpHeaders

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

# uvolníme objekty z mezipaměti, aby bylo možné pouštět opakovaně
print("\ndiscard objects from cache:")
body = {"cacheid": "testFieldLookUp", "type": "discard"}
response = session.post(
	url="http://localhost:81/demodata/serverstate",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
if response.status_code != 204:
	sys.exit(0)


# založíme novou fakturu vydanou se 2 řádky
print("\ncreate fv:")
body = {
	 "cacheid": "testFieldLookUp",
	 "type": "create",
	 "data": {
		"object_data": {
			"firm_id": "F011000000",
			"docqueue_id": "5600000101",
			"storedocqueue_id": "P600000101",
			"rows": [
				 {
					 "@temporaryid": "ID1",
					 "rowtype": 0,
					 "text": "testovaci radek",
					 "division_id": "2100000101"
				 },
				 {
					 "@temporaryid": "ID2",
					 "rowtype": 3,
					 "store_id": "2100000101",
					 "storecard_id": "2100000101",
					 "unitquantity": 10,
					 "unitprice": 20.5,
					 "division_id": "2100000101"
				 }
			]
		}
	 }
}

response = session.post(
	url="http://localhost:81/demodata/issuedinvoices/serverstate",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))

if response.status_code != 200:
	sys.exit(0)

resp = json.loads(response.content.decode("utf-8"))

# Získáme id vytvořené faktury vydané
oid = resp["data"]["id"]

rows = resp["data"].get("rows", [])

# Získáme id druhého řádku
row2_id = next((row["id"] for row in rows if row["@temporaryid"] == "ID2"), None)

# Nyní použijeme fieldlookup pro vyfiltrování id a kódů středisek z druhého řádku faktury
print("\nlook up division's IDs on the 2nd row:")
body = {
		  "cacheid": "testfieldLookUp",
		  "type": "fieldlookup",
		  "data": {
					"class": "issuedinvoices",
					"object_id": f"{oid}",
					"field": f"rows/id:{row2_id}/store_id",
					"query": {
							  "select": [
								"ID",
								"Code",
								"Name"
							  ]
					}
		  }
}
response = session.post(
	url="http://localhost:81/demodata/serverstate",
	headers=headers,
	json=body,
)
print(f"status code: {response.status_code}")
print("response body:")
print(json.dumps(response.json(), indent=2))

if response.status_code != 200:
	sys.exit(0)

Výsledek zpracování dotazu:

Status: 200 OK

[
	{
		"ID": "2100000101",
		"Code": "000",
		"Name": "Centrála"
	},
	{
		"ID": "1200000101",
		"Code": "100",
		"Name": "Prodej, služby"
	},
	{
		"ID": "2200000101",
		"Code": "200",
		"Name": "Restaurace Na vršku"
	},
	{
		"ID": "1300000101",
		"Code": "300",
		"Name": "Vývoj, výzkum"
	},
	{
		"ID": "1400000101",
		"Code": "400",
		"Name": "Výroba"
	},
	{
		"ID": "2400000101",
		"Code": "401",
		"Name": "Logistika a zásobování"
	},
	{
		"ID": "3400000101",
		"Code": "402",
		"Name": "Výroba  - dílna"
	}
]

V dalším příkladu si ukážeme volání funkce fieldlookup, která vrátí objednávky přijaté z dodacích listů, které je možné nastavit do parametru selectedheader.

Nejprve vytvoříme importního manažeru DL->FV

				{
    "cacheid": "cache",
    "type": "create",
    "data": {
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "object_data": {
            "inputdocuments": [
                "59W1000101", "29Y1000101"
            ]
        },
        "query": {
            "select": [
                "id",
                "selectedheader"
            ]
        },
        "meta": {
            "validation": {
                "errors": true,
                "warnings": true
            },
            "objectdiff": {
                "includesource": true,
                "addjsonpath": true
            },
            "objectinfo": {
                "types": [
                    "canupdate",
                    "usableenums"
                ],
                "includebefore": true,
                "includeafter": true,
                "includepatch": true
            }
        }
    }
}

Volání funkce fieldlookup vrátí objednávky přijaté z dodacích listů které je možné nastavit do parametru selectedheader.

				{
    "cacheid": "cache",
    "type": "fieldlookup",
    "data": {
        "object_id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "field": "selectedheader",
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "query": {
            "select": [
                "id",
                "displayname"
            ]
        }
    }
}

Příklad ukazuje vytvoření nové řady pro fakturu vydanou pomocí přidané sekce forreference, proto předáme jako vazební pole issuedinvoice, docqueue_id konkrétní faktury.

Do mezipaměti nahrajeme fakturu vydanou a poté si necháme vytvořit novou řadu, tak, aby přesně vyhovovala požadavkům na použití ve faktuře vydané. V sekci select jsme si zvolil, že z nové řady chceme jen tyto položky id, documenttype, code

Nejprve nahrajeme do keše serverstate fakturu vydanou

{
    "cacheid": "",
    "type": "load",
    "data": {
        "class": "issuedinvoices",
        "object_id": "3L50000101",
        "query": {
            "select": [
                "id"
            ]
        }
    }
}

Výsledek zpracování dotazu:

{
    "data": {
        "id": "3L50000101",
        "@meta": {
            "version": 1
        }
    }
}

Poté necháme vytvořit novou řadu, tak, aby přesně vyhovovala požadavkům na použití ve faktuře vydané. V sekci select jsme zvolili, že z nové řady chceme jen položky id, documenttype, code

{
    "cacheid": "",
    "type": "create",
    "data": {
        "class": "docqueues",
        "object_data": {},
        "forreference": {
            "class": "issuedinvoices",
            "object_id": "3L50000101",
            "field": "docqueue_id"
        },
        "query": {
            "select": [
                "id",
                "documenttype",
                "code"
            ]
        }
    }
}

Výsledek zpracování dotazu:

{
    "data": {
        "id": "2O70000101",
        "documenttype": "03",
        "code": "FV",
        "@meta": {
            "version": 1
        }
    }
}

Endpoint /serverstate umožňuje s importními manažery (IM) pracovat stavově. To znamená, že místo jediného volání (jako přes /import) můžete instanci IM nejprve vytvořit v mezipaměti, následně měnit její parametry (a průběžně je validovat) a až nakonec ji spustit. Celý proces využívá specifické hodnoty parametru type.

Ve vlastnosti class se v tomto případě neposílá CLSID business objektu, ale GUID importního manažera. Seznam všech IM a jejich GUIDů získáte z endpointu /api-docs/importmanager.

Krok 1: Vytvoření instance IM (type: create)

Nejprve vytvoříme instanci IM v mezipaměti. Jako class použijeme GUID importního manažera (zde import OP do DL). V parametru inputdocuments předáme ID zdrojového dokladu (objednávky přijaté).

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "im_cache_01",
    "type": "create",
    "data": {
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "object_data": {
            "inputdocuments": "15C0000101"
        },
        "query": {
            "select": [
                "docqueue_id",
                "deliverydate$date"
            ]
        },
        "meta": {
            "validation": {
                "errors": true,
                "warnings": true
            },
            "objectinfo": {
                "types": [
                    "canupdate"
                ],
                "includeafter": true
            }
        }
    }
}

Odpověď obsahuje dočasné ID instance IM (zde "CWZHRX..."), předvyplněné parametry (docqueue_id) a validační chyby (chybí řada dokladů).

{
    "data": {
        "id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "docqueue_id": null,
        "deliverydate$date": "2025-11-06T00:00:00.000Z",
        "@meta": {
            "version": 1,
            "validation": {
                "errors": {
                    "count": 1,
                    "values": [
                    {
                            "docqueue_id": {
                                "@description": "Položka \"Řada dokladů\" musí být vyplněna.",
                                "@code": 0,
                                "@displaylabel": "Řada dokladů"
                    }
                        }
                    ]
            },
                "warnings": {
                    "count": 0,
                    "values": []
                }
            },
            "objectinfo": {
                "after": {
                    "docqueue_id": {
                        "canupdate": true
                    },
                    "deliverydate": {
                        "canupdate": true
                    }
                }
            }
        }
    }
}

Krok 2: Nastavení parametrů (type: update)

Nyní na vytvořenou instanci IM (pomocí jejího dočasného ID z kroku 1) pošleme chybějící parametr (řadu dokladů P600000101).

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "im_cache_01",
    "type": "update",
    "data": {
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "object_id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "object_data": {
            "docqueue_id": "P600000101"
        },
        "query": {
            "select": [
                "docqueue_id"
            ]
        },
        "meta": {
            "validation": {
                "errors": true,
                "warnings": true
            }
        }
    }
}

Odpověď již neobsahuje žádné validační chyby, IM je připraven ke spuštění.

{
    "data": {
        "id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "docqueue_id": "P600000101",
        "@meta": {
            "version": 2,
            "validation": {
                "errors": [],
                "warnings": []
            }
        }
    }
}

Krok 3: Spuštění IM (type: execute)

Nyní, když je IM nakonfigurován a bez chyb, provedeme jeho spuštění. Tím se vytvoří cílový doklad (dodací list). Volitelně lze použít příznaky saveproperties (pro uložení hodnot jako výchozích) nebo breakiflocked (pro převzetí zámku nad cílovým dokladem).

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "im_cache_01",
    "type": "execute",
    "saveproperties": false,
    "breakiflocked": false,
    "data": {
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "object_id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "query": {
            "select": [
                "outputdocument_id",
                "outputdocument_id.displayname"
            ]
        }
    }
}

Odpověď obsahuje outputdocument_id – tedy ID nově vytvořeného dodacího listu. Tento doklad je nyní v mezipaměti v neuloženém stavu. Instance IM je automaticky uvolněna z paměti.

{
    "data": {
        "outputdocument_id": "49F0000101",
        "outputdocument_id.displayname": "DL-1/2025"
    }
}

Krok 4: Uložení vytvořeného dokladu (type: save)

Cílový doklad (49F0000101) vytvořený v kroku 3 je stále v mezipaměti. Aby byl trvale uložen do databáze, musíme na něj zavolat standardní příkaz save pro business objekt (zde `billsofdelivery`).

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "im_cache_01",
    "type": "save",
    "data": {
        "class": "billsofdelivery",
        "object_id": "49F0000101",
        "query": {
            "select": [
                "id",
                "displayname"
            ]
        }
    }
}

Po tomto volání je doklad uložen v databázi a je uvolněn z mezipaměti.

{
    "data": {
        "id": "49F0000101",
        "displayname": "DL-1/2025"
    }
}

Volitelný krok: Dotaz na hodnoty číselníku (type: rolllookup)

Pokud bychom v kroku 2 neznali ID řady dokladů, můžeme použít rolllookup na parametr docqueue_id, abychom získali seznam platných hodnot (podobně jako Příklad 4 - Filtrování položek číselníku (Fieldlookup)).

Požadavek:

POST http://localhost:81/demodata/serverstate

Tělo požadavku:

{
    "cacheid": "im_cache_01",
    "type": "rolllookup",
    "data": {
        "object_id": "CWZHRXCCDOY4VGKSAZCCMNCQ20",
        "field": "docqueue_id",
        "class": "ZUMBGNJTXF44H4YIMBETLJJRQ0",
        "query": {
            "take": 5,
            "select": [
                "id",
                "name",
                "code"
            ]
        }
    }
}

Odpověď vrátí seznam dostupných řad dokladů:

[
    {
        "id": "P600000101",
        "name": "Dodací listy",
        "code": "DL"
    },
    {
        "id": "1H20000101",
        "name": "Dodací listy ENG",
        "code": "DL-ENG"
    }
]

Pomocí @cloneid lze vytvořit klon řádku v kolekci uvnitř BO. Pro identifikaci nově nakopírovaného řádku lze využít @temporaryid

Tělo požadavku:

{
	"cacheid": "a",
	"type": "load",
	"data": {
		"class": "O3BDOKTWEFD13ACM03KIU0CLP4",
		"object_id": "1LV0000101",
		"object_data": {
			"rows": [
				{
					"@cloneid": "4LC0000101",
					"@temporaryid": "CLONE1",
					"text": "CLONE 1 test"
				}
			]
		}
	}