Kuba1

KS WebAPI je webová služba postavená na technologii Windows Communication Foundation. Umožňuje předávat údaje z databáze KS mzdy klientské aplikaci nebo ukládat údaje do databáze KS mzdy zaslané klientskou aplikací.

Komunikační protokol

Pro hostování webové služby se využívá KS aplikační server. Komunikačním protokolem je http, případně ve spojení se SSL (HTTPS). Pro výměnu zpráv se používá protokol SOAP. Ve výchozím nastavení je připraven typ endpointu wsHttpBinding.

Metody webové služby

KS WebAPI nabízí metody: GetData, InsertData, UpdateData.

Všechny metody přebírají v parametru strukturu KSWebAPI_Parameters a vrací návratovou strukturu KSWebAPI_Response.

GetData

Metoda GetData vrací data z databáze KS mzdy dle zadaných kritérií.

Nastavení parametrů struktury KSWebAPI_Parameters

• ItemGroup

Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').

• Items

Předá se seznam položek, které budou v návratové datové struktuře. Jednotlivé položky se oddělí čárkou (Příklad: OsCislo, Jmeno, Prijmeni).

• JsonSearchCriteria

Předá se vyhledávací podmínka v JSON formátu.

Popis údajů v návratové struktuře KSWebAPI_Response

• Data

Očekávané data vyhovující podmínce v JsonSearchCriteria ve formátu JSON.

InsertData

Metoda InsertData zapisuje data do databáze KS mzdy.

Nastavení parametrů struktury KSWebAPI_Parameters

• ItemGroup

Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').

• JsonChangeData

Povinný údaj. V JSON struktuře se předají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o pole, kde v jednotlivých objektech pole jsou data pro insert.

Příklad dat pro vložení jednoho záznamu

[
    [{ "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-01-01"}]
]

Příklad dat pro vložení více záznamů

[
[{ "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-01-01"},
{ "IdPodniku": "1", "Jmeno": "Petr", "Prijmeni": "Test", "RodneCislo": "81101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "101", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-02-01"},
{ "IdPodniku": "1", "Jmeno": "Marie", "Prijmeni": "Nová", "RodneCislo": "820101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "102", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-03-01"}]

]

Popis údajů v návratové struktuře KSWebAPI_Response

• Data

V JSON formátu jsou předána data, která byla vložena do databáze.

KSWebAPI_Parameters

Struktura obsahuje parametry:

• ItemGroup

Povinný údaj. Předává se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').

• Items

Vyplňuje se v případe volání metody GetData. Předává se seznam položek, které budou v návratové datové struktuře, na které má uživatel oprávnění. Jednotlivé položky se oddělují čárkou (Příklad: OsCislo, Jmeno, Prijmeni).

• JsonChangeData

Vyplňuje se v případe volání metody InsertData nebo UpdateData. V JSON struktuře se předávají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o JSON pole.

• JsonSearchCriteria

Slouží k předání vyhledávacích kritérií pro omezení množiny zpracovávaných údajů. Podmínka se zapisuje v JSON formátu. Vyhledávací kritérium se skládá z výrazů (výraz obsahuje atributy 'Item', 'Operator', 'Value'), přičemž může být zadán buď jediný výraz nebo složený, oddělený logickými operátory.

Přípustné logické operátory: OR, AND

Přípustné operátory porovnání: =, <=, >=, >, <, LIKE, NOT LIKE, IN, NOT IN

Příklady

1 (jednoduchý výraz)

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 }
]

1 AND 2

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 },
    "AND",
    { "Item": "DatumNastupu", "Operator": ">=", "Value": "2000-01-01" }
]

1 OR 2

[
    { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
    "OR",
    { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
]

(1 OR 2) AND (3 OR 4)

[
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
        "OR",
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" }
    ],
    "AND",
    [
        { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
        "OR",
        { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
    ]
]

1 OR (2 AND (3 OR 4))

[
    { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
    "OR",
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" },
        "AND",
        [
            { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
            "OR",
            { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
        ]
    ]
]

KSWebAPI_Response

Struktura obsahuje parametry:

• ResponseDatetime

Datum a čas odpovědi.

• StatusCode

Stav odpovědi. 200 – OK, 500 – chyba.

• Message

Zpráva odpovědi.

• IsError

Indikace zda nastala chyba.

• ErrorMessage

Chybová zpráva o chybovém stavu při zpracování metody.

• Data

Data ve formátu JSON.