Az API használata
Ezen az oldalon
A webes felület minden műveletét a WorkSmartHub REST API végzi, így az integrációk ugyanezt megtehetik: munkajegyet hozhatnak létre egy másik rendszerből, státuszokat olvashatnak ki egy riporthoz, komponenseket szinkronizálhatnak, és így tovább.
Swagger#
Ha az appsettings.json fájlban a Swagger.Enabled értéke true (ez az alapértelmezés), az interaktív API dokumentáció a telepítés /swagger címén érhető el, az OpenAPI leírás pedig a /swagger/api/swagger.json címen. Ha a Swagger ki van kapcsolva, mindkettő 404-et ad. A Státusz oldal mutatja, hogy be van-e kapcsolva.
Minden végpontnál fel vannak sorolva a lehetséges hibakódok (például generic.not_authorized, license.error). Az API klienseket a futó verzió OpenAPI leírásából generálja, és minden frissítés után generálja újra őket: az új verziók új enum értékeket hoznak (például hiba- és eseménytípusokat), amelyeket egy régebbi verzióból generált kliens nem tud beolvasni.
Hitelesítés személyes hozzáférési tokennel#
Az API kliensek a Személyes Hozzáférési Tokenek oldalon létrehozott személyes hozzáférési tokennel hitelesítenek. A token annak a felhasználónak a jogosultságaival működik, aki létrehozta.
-
Hozzon létre egy tokent, és a frissítő tokent (refresh token) tárolja biztonságosan.
-
Cserélje be a frissítő tokent egy hozzáférési tokenre (access token):
curl -s -X POST https://wsh.example.com/api/pats/refresh-token \ -H "Content-Type: application/json" \ -d '{"refreshToken": "<refresh token>"}'A válasz egy új
accessTokenés egy újrefreshTokenértéket tartalmaz (mindkettőbentokenés lejárat). Az új frissítő tokent tárolja el: az előző érvényét veszti. APOST /api/pats/refresh?refreshToken=<refresh token>ugyanezt teszi, de a tokent az URL-be teszi; a JSON törzs jobb, mert így a token nem kerül URL-ekbe és hozzáférési naplókba. -
Minden hívásnál küldje el a hozzáférési tokent:
curl -s -X POST https://wsh.example.com/api/workspaces/query \ -H "Authorization: Bearer <access token>" \ -H "Content-Type: application/json" -d '{}'Az
?access_token=<access token>query paraméter is működik, de a fejléc a jobb megoldás. -
Ha a hozzáférési token lejár (alapértelmezetten 8 óra után), ismételje meg a 2. lépést.
Szabályok:
- A személyes hozzáférési token csak API hívásokat hitelesít: böngészős munkamenetet soha nem indít, és nem hozhat létre újabb tokent.
- Egy érvénytelenített vagy törölt tokent körülbelül 1 percen belül minden szerver elutasít.
- Az
appsettings.jsonJWT aláíró kulcsának módosítása minden tokent érvénytelenít.
A GET /api/account/test a hívó azonosságát és jogosultságait adja vissza; egy token ellenőrzésére használható.
Bejelentkezés nélkül elérhető végpontok#
| Végpont | Cél |
|---|---|
GET /health |
Állapotellenőrzés |
GET /api/licensing/status |
Licenc állapota |
POST /api/licensing/set |
Licenc feltöltése: a kérés törzse maga a licencfájl, nyersen (Content-Type: application/octet-stream, például curl --data-binary @license.key), nem multipart űrlap. Csak amíg nincs érvényes licenc; érvényes licenc cseréjéhez Super Admin token kell. |
GET /api/app/mobile-activation |
Mobil alkalmazás aktiválása (a licencelt funkció kell hozzá) |
Példák#
A legtöbb listázó végpont POST .../query hívás JSON szűrő törzzsel (egy üres {} az első oldalt adja vissza).
| Feladat | Hívás |
|---|---|
| Munkaterületek listázása | POST /api/workspaces/query |
| Egy munkaterület munkajegyeinek listázása | POST /api/workspaces/{workspaceId}/tickets/admin/query |
| Munkajegy létrehozása | POST /api/workspaces/{workspaceId}/tickets/admin/create |
| Munkajegy módosítása | POST /api/tickets/admin/{workTicketId}/update |
| Ügyfelek listázása | POST /api/clients/query |
| Komponensek listázása | POST /api/components/query |
| Események lekérdezése | POST /api/audit/query |
Ugyanazok a jogosultsági szabályok érvényesek, mint a webes felületen (Jogosultságok és szerepkörök): például egy technikus tokenje csak az adott felhasználóhoz rendelt munkajegyeket látja. A melléklet- és képfeltöltés kezdő / hozzáfűző / lezáró (begin / append / finish) hívások sorozatából áll; ezek leírása a Swaggerben található.
Jó gyakorlat#
- Minden integrációhoz hozzon létre egy külön felhasználót, csak a szükséges jogosultságokkal, és a tokent ennek a felhasználónak hozza létre (a Super Admin ezt a felhasználó sorából is megteheti).
- Rövid projektekhez abszolút, hosszan futó integrációkhoz gördülő lejáratú tokent használjon, és állítson be lejárati figyelmeztetést egy értesítési csatornára.
- A tokeneket titoktárban tartsa, például a szolgáltatás felhasználói katalógusban vagy a saját vaultjában.