Čo je potrebné odlíšiť

Pri práci s používateľmi cez API rozlišujte dve samostatné operácie:

Založenie globálneho používateľa – používateľ vznikne na úrovni služby.
Pridanie používateľa do konkrétnej firmy – používateľ získa prístup do vybranej firmy a konkrétnu rolu.

Bez pridania do firmy nebude mať samotné založenie používateľa praktický dopad na prístup do firmy.

💡 Info: Postupy nižšie sú overené v aplikácii Postman voči cloudovej inštancii Flexi.

Vytvorenie globálneho používateľa

Globálneho používateľa založíte požiadavkou PUT na endpoint /u Údaje sa neposielajú v JSON tele, ale ako parametre v URL.

Do budúcna sa vytváranie používateľov zmení. Plánovaná je podpora zasielania parametrov v JSON tele požiadavky, namiesto súčasného odosielania cez hlavičku.

Používané parametre a ich význam

jmeno > unikátne používateľské meno
heslo > heslo pre prihlásenie
email > unikátny email používateľa
default_role > predvolená rola používateľa
userType > Typ používateľa: NORMAL, REST_API, READ_ONLY, vysvetlenie jednotlivých typov
blocked > pre blokovanie/zablokovanie používateľa
manage_all > hodnotou true pridáte používateľa do všetkých firiem, odpadá tak nutnosť ho pridávať v následnom kroku zvlášť

Parametre udeľujúce práva serveru (vhodné pre rolu ADMIN) s hodnotami true/false zodpovedajúcimi tomuto nastaveniu:

create_company > povolí zakladať firmy
delete_company > povolí mazanie firiem
create_user > povolí zakladať používateľov
change_password > povolí meniť používateľom heslo
grant_permisson > povolí udeľovať oprávnenia používateľom
license_mgmt > povolí spravovať licencie

Postup

Pošlite PUT na endpoint /u
Do URL doplňte prihlasovacie meno, heslo, e-mail a predvolenú rolu.
Po úspešnom vykonaní vznikne globálny používateľ.

Overený príklad

PUT

https://alpe.flexibee.eu:5434/u?jmeno=api_new&heslo=Heslo123&email=api_new@api.cz&default_role=SKLADNIK

Týmto volaním založíte používateľa api_new.

⚠️ Warning: Endpoint podľa overenia neberie JSON telo požiadavky. Ak dáta pošlete v body, vytvorenie používateľa nemusí prebehnúť. Podpora bude doplnená v nasledujúcich verziách.

Editácia používateľa

Editácia používateľa prebieha volaním PUT na endpoint /u/{uzivatel}.json

a podporuje už JSON zápis v tele požiadavky.

Postup

Pošlite PUT na endpoint /u/{uzivatel}.json
Nastavte hlavičku Content-Type: application/json.
V JSON tele uveďte údaje, ktoré chcete upraviť

Overený príklad

PUT

https://alpe.flexibee.eu:5434/u/api_new.json
Content-Type: application/json
{
    "email": "new_email@email.cz"
}

Pridanie používateľa do firmy

Po založení globálneho používateľa je potrebné pridať ho do konkrétnej firmy. To vykonáte cez firemný endpoint evidencie používateľov.

Postup

Pošlite PUT na endpoint /c/{firma}/uzivatel
Nastavte hlavičku Content-Type: application/json
V JSON tele uveďte používateľa a rolu, ktorú má mať v danej firme

Overený príklad

PUT

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel
Content-Type: application/json
{ "winstrom": { "uzivatel": [ { "id": "code:api_new", "role": "code:ADMIN" } ] } }

V uvedenom príklade sa používateľ api_new pridá do firmy sk_firma_cloud s rolou ADMIN.

💡 Info: Predvolená rola pri založení globálneho používateľa a rola pridelená vo firme sú dve odlišné veci.

Editácia role používateľa na firme

Rovnako ako pridanie, editácia používateľa prebieha volaním PUT na endpoint /c/{firma}/uzivatel

s hodnotami v tele požiadavky v JSON.

Postup

Pošlite PUT na endpoint /c/{firma}/uzivatel
Nastavte hlavičku Content-Type: application/json.
V JSON tele uveďte údaje, ktoré chcete upraviť, napríklad zmeníme rolu na SKLADNIK

Overený príklad

PUT

https://alpe.flexibee.eu:5434/c/flexi_gui_s_r_o_/uzivatel
Content-Type: application/json
{
  "winstrom": {
    "uzivatel": [
      {
        "id": "code:api_new",
        "role": "code:SKLADNIK"
      }
    ]
  }
}

Odobratie používateľa z firmy

Ak potrebujete používateľovi zrušiť prístup do konkrétnej firmy, zmažte jeho väzbu na firmu v evidencii uzivatel.

Postup

Pošlite PUT na endpoint /c/{firma}/uzivatel.
Nastavte hlavičku Content-Type: application/json.
V tele použite akciu delete a identifikáciu používateľa.

Overený príklad

PUT

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel
Content-Type: application/json
{ "winstrom": { "uzivatel": [ { "@action": "delete", "id": "code:api_new" } ] } }

Týmto volaním odoberiete používateľa api_new z firmy sk_firma_cloud.

⚠️ Warning: Týmto krokom používateľa odoberiete z konkrétnej firmy, ale ak je to jeho jediná pridelená firma, vymaže sa globálne.

Ak sú na používateľa už historicky naviazané záznamy v databáze, odobratie používateľa neprejde, v takom prípade sa vykonáva Blokácia používateľa.

Blokácia používateľa

Blokácia používateľa normal_v1 v cURL:

curl -u "user:password" -X POST -d "blocked=true" "https://moje.flexibee.eu/u/normal_v1.json"

V Postman:

POST

https://alpe.flexibee.eu:5434/u/normal_v1.json

Body JSON

{
  "blocked": true,
  "blocked@message": "Blocked from API"
}

⚠️ Warning: Blokáciou používateľa uvoľníte jeho licenciu a znemožníte jeho prihlásenie. Odblokovanie vykonáte rovnako s hodnotou "false".

Výpis všetkých používateľov

Pre kontrolu všetkých globálnych používateľov použite výpis nad endpointom /u.json.

Postup

GET

https://alpe.flexibee.eu:5434/u.json

Vracia zoznam všetkých používateľov.

Výpis používateľov z konkrétnej firmy

Ak potrebujete zistiť, ktorí používatelia sú pripojení do konkrétnej firmy, použite firemnú evidenciu používateľov.

Postup

GET

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel.json?limit=0&detail=full

Vracia používateľov naviazaných na konkrétnu firmu.

⚠️ Warning
Parameter limit=0 ruší predvolený limit 20 záznamov na neobmedzený, pre získanie všetkých používateľov danej firmy.

Parameter detail=full zobrazuje všetky polia a ich hodnoty pre úplný detail.

Výpis rolí vo firme

Dostupné roly vo firme zistíte cez dotaz nad evidenciou role.

Postup

Pošlite GET na c/{firma}/role.json
V JSON tele nastavte požadovaný detail výstupu.
Pre prehľadný zoznam vráťte len ID, kód a názov.

Overený príklad

GET

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/role.json?limit=0

Takto získate prehľad rolí dostupných vo vybranej firme.

⚠️ Warning
Parameter detail=full tu vracia zoznam všetkých nastavených práv, tj. cez 10 000 riadkov za každú 1 rolu. Ak je nutné čítať nastavenie práv na rolu, odporúčaním je obmedziť dotaz iba za jednu, napríklad za rolu ADMIN:

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/role/code:ADMIN.json?detail=full

Prehľad endpointov

Operácia	Metóda a endpoint	Poznámka
Vytvorenie globálneho používateľa	PUT `/u`	Parametre iba v URL
Editácia globálneho používateľa	PUT `/u`	JSON telo
Editácia používateľa na firme	PUT `/c/{firma}/uzivatel`	JSON telo
Pridanie používateľa do firmy	PUT `/c/{firma}/uzivatel`	JSON telo
Odobratie používateľa z firmy	PUT `/c/{firma}/uzivatel`	`@action: delete`
Blokácia používateľa	POST`/u/{uzivatel}.json`	hodnota blocked=true sa v Postman posiela cez body typu x-www-form-urlencoded
Výpis všetkých používateľov	GET `/u.json`	Globálni používatelia
Výpis používateľov z firmy	GET`/c/{firma}/uzivatel.json?limit=0&detail=full`	Používatelia konkrétnej firmy
Výpis rolí	GET`/c/{firma}/role.json?limit=0`	Odporúčaný custom detail opatrne s ?detail=full!

Na čo dať pozor

⚠️ Warning: Založenie používateľa a pridanie do firmy sú dve oddelené operácie. Je potrebné vykonať obe.

⚠️ Warning: Výpisy s detail=full môžu byť výrazne rozsiahle a menej prehľadné.

⚠️ Warning: Prácu s používateľmi cez API je vhodné vyladiť na testovacom prostredí či voči testovacej databáze.

⚠️ Warning: Roly sú zatiaľ iba na čítanie, nedajú sa do nich v API zapisovať.

Súvisiace články

Dávkové operácie, Batch API
- https://podpora.flexibee.eu/cs/articles/4786921-davkove-operace
Používateľské roly v API
- https://podpora.flexibee.eu/cs/articles/13396639-uzivatelske-role-rest-api

Sorodni članki

Správa používateľov cez API

Vytvorenie globálneho používateľa

Používané parametre a ich význam

Parametre udeľujúce práva serveru (vhodné pre rolu ADMIN) s hodnotami true/false zodpovedajúcimi tomuto nastaveniu:

Postup

Editácia používateľa

Postup

Pridanie používateľa do firmy

Postup

Editácia role používateľa na firme

Postup

Odobratie používateľa z firmy

Postup

Blokácia používateľa

Výpis všetkých používateľov

Postup

Výpis používateľov z konkrétnej firmy

Postup

Výpis rolí vo firme

Postup

Prehľad endpointov

Na čo dať pozor

Súvisiace články