Protokol REST (KS webAPI)

Základní informace

Komplexní API pro správu dat souhrnů údajů, zaměstnanců a autentizaci uživatelů. Umožňuje vkládání, aktualizaci, výběr a mazání dat v různých souhrnech údajů na základě specifikovaných kritérií a operací prováděných prostřednictvím HTTP metod.

Autentizace

1. Zabezpečení protokolu

   Všechny dotazy na API musí být zasílány prostřednictvím zabezpečeného protokolu HTTPS.

2. Přístupová oprávnění

   Uživatel musí mít povolení k užívání API, které mu uděluje administrátor. K tomu je nezbytné mít vygenerováno jméno a heslo k API.

3. Autentizace

   Pro autentizaci je třeba odeslat na adresu .../KSAsServer/WebService/WebAPI/rest/users/authenticate JSON body s údaji "Username" a "Password". Pokud jsou tyto údaje správné, obdržíte token, který je nutný pro používání API po určitou dobu. Token i jeho platnost jsou vráceny v těle odpovědi.

4. Použití tokenu

   Při každém volání API ,mimo autentizaci, je třeba zaslat platný token jedním ze dvou způsobů:

   • V HEADER

     Plain:

     Authorization -   eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

     Bearer:

     Authorization -   Bearer eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

   • V URI

     GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/Jmeno/Karel?token=eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

   Způsob HEADER je preferován před URI.

Příklad

Požadavek

POST /KSAsServer/WebService/WebAPI/rest/user/authenticate

body:
{
    "Username": "jmeno",
    "Password": "heslo"
}
        

Odpověď

{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Created",
    "ResponseDatetime": "/Date(1720705997339+0200)/",
    "StatusCode": 201,
    "Token": "jkdsjflsdfjsdfklsjdflskdfjs.6tQew",
    "ValidTo": "/Date(1720715997000+0200)/"
}

Metody

Veškerá dokumentakce k metodám: Metody.

Parametry

• Request header

  Content-Type - application/raw

  Accept - application/json

• Items

  Vyplňuje se v případě volání metody GET/POST. Předává se seznam Položky, které budou v návratové datové struktuře, na které má uživatel oprávnění. Jednotlivé položky se oddělují čárkou. Pokud bude v parametru předáno více položek, vrací se návratová datová struktura, která obsahuje všechny položky uvedené v parametru oddělené čárkami. Pokud bude zadáno více 'Item' v parametru, bude vrácena množina údajů odpovídající průniku záznamů jednotlivých 'Item'. V případě nezadání paramteru, vrátí všechny položky, na které má uživatel oprávnění.

• JsonSearchCriteria
• JsonOptions
• Token

Proměnné cesty

• ItemGroup

  (Required) Název souhrnu údajů. Parametr {ItemGroup} je nutno zaměnit za reálný souhrn údajů. Předává se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').

GET /KSAsServer/WebService/WebAPI/rest/{ItemGroup]/{Item}?token=12asd16a5sda1s32d&Items=Jmeno,Prijmeni,OsCislo,RodneCislo&JsonSearchCriteria=[{ 'Item': 'OsCislo', 'Operator': '<=', 'Value': 100 }]

GET - Vrací data souhrnu údajů podle zadaného názvu souhrnu.

Povinné parametry: Token, ItemGroup.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde OsCislo <= 100.

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/?token=12asd16a5sda1s32d&Items=Jmeno,Prijmeni,OsCislo,RodneCislo&JsonSearchCriteria=[{ 'Item': 'OsCislo', 'Operator': '<=', 'Value': 100 }]

Odpověď

{
    "Data": "[{\"OsCislo\":36,\"Titul\":null,\"Jmeno\":\"Miroslav\",\"Prijmeni\":\"Nový\",\"RodneCislo\":\"123456789\"...}],
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720696754982+0200)/",
    "StatusCode": "200"
}

GET - Vyhledá zaměstnance ze skupiny údajů 'KmenoveUdaje' podle zadaného osobního čísla.

Povinné parametry: Token, ItemGroup, aOsCislo.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde OsCislo = 1. Vrátí sloupce OsCislo, Titul, Jmeno, Primeni, RodneCislo

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/1?token=eyJ0eXAiOIiwi7_GcdkwUuTTLDL4&Items=OsCislo, Titul, Jmeno, Prijmeni, RodneCislo

Odpověď

{
    "Data": "[{\"OsCislo\":1,\"Titul\":\"Ing.\",\"Jmeno\":\"Pavel\",\"Prijmeni\":\"Hovorka\",\"RodneCislo\":\"581227411\"}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720766282434+0200)/",
    "StatusCode": "200"
}

GET - Vrací data, kde údaj 'Item' má hodnotu 'Value' v rámci zadaného souhrnu údajů 'ItemGroup'.

Povinné parametry: Token, ItemGroup, Item, Value.

Volitelné parametry: JsonSearchCriteria, Items, JsonOptions.

Příklad

Vrátí data ze souhrnu údajů "KmenoveUdaje", kde Jmeno = Pavel.

Požadavek

GET /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje/Jmeno/Pavel?token=eyJ0eXAwibmFtZSI6InBhdmVIuMDGtBE1GxcdkwUuTTLDL4&

Odpověď

{
    "Data": "[{\"OsCislo\":1,\"Titul\":\"Ing.\",\"Jmeno\":\"Pavel\",\"Prijmeni\":\"Hovorka\",\"RodneCislo\":\"581227411\"},
            {\"OsCislo\":18,\"Titul\":null,\"Jmeno\":\"Pavel\"...}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Data nalezena.",
    "ResponseDatetime": "/Date(1720766630099+0200)/",
    "StatusCode": "200"
}

POST - Vkládá data do zadaného souhrnu údajů.

Metoda InsertData zapisuje data do databáze KS mzdy.

Povinné parametry: Token, ItemGroup, JsonChangeData (data v těle požadavku).

Příklad

Vloží data z body požadavku do souhrnu údajů "KmenoveUdaje".

Požadavek

POST /KSAsServer/WebService/WebAPI/rest/KmenoveUdaje?token=eyJ0eXAiOiJKV1QtL2BDA7_GcdkwUuTTLDL4&

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

Odpověď

{
    "Data": "[{\"OsCislo\": 95967,\"IdPodniku\": 1,\"Jmeno\": \"Karel\",\"Prijmeni\": \"Nový\""...}]",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla vložena.",
    "ResponseDatetime": "/Date(1720767043837+0200)/",
    "StatusCode": "201"
}

PUT / UPDATE - Aktualizuje data do zadaného souhrnu údajů.

Povinné parametry: Token, ItemGroup, JsonChangeData (data v těle požadavku), JsonSearchCriteria.

Příklad

Aktualizuje data v souhrnu údajů "Kontakty", kde Hodnota = 222 222 222, na Hodnota = 111 111 111.

Požadavek

PUT /KSAsServer/WebService/WebAPI/rest/Kontakty?token=eyJ0eXAiOiJKV1QiLaW_GcdkwUuTTLDL4&JsonSearchCriteria=[{ "Item": "Hodnota", "Operator": "=", "Value": "222 222 222"}]

Body:
[
    {
        "Hodnota": "111 111 111"
    }
]

Odpověď

{
    "Data": "",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla aktualizována.",
    "ResponseDatetime": "/Date(1721030337638+0200)/",
    "StatusCode": "204"
}

DELETE - Smaže data v zadaném souhrnu údajů.

Metoda DELETE smaže data v databázi KS mzdy.

Povinné parametry: Token, ItemGroup, JsonSearchCriteria.

Příklad

Smaže data v souhrnu údajů "Kontakty", kde Hodnota = 111 111 111

Požadavek

DELETE KSAsServer/WebService/WebAPI/rest/Kontakty?token=eyJ0eXAiOiJKV1QiLCk&JsonSearchCriteria=[{ "Item": "Hodnota", "Operator": "=", "Value": "111 111 111"}]

Odpověď

{
    "Data": "",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "ErrorText": null,
    "IsError": false,
    "Message": "Vybraná data byla smazána.",
    "ResponseDatetime": "/Date(1721030823993+0200)/",
    "StatusCode": "204"
}

Odkazy

• Protokoly