Az API használata

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.

  1. Hozzon létre egy tokent, és a frissítő tokent (refresh token) tárolja biztonságosan.

  2. Cserélje be a frissítő tokent egy hozzáférési tokenre (access token):

    bash
    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 új refreshToken értéket tartalmaz (mindkettőben token és lejárat). Az új frissítő tokent tárolja el: az előző érvényét veszti. A POST /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.

  3. Minden hívásnál küldje el a hozzáférési tokent:

    bash
    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.

  4. Ha a hozzáférési token lejár (alapértelmezetten 8 óra után), ismételje meg a 2. lépést.

A frissítő token új tokenpárra cserélhető; a hozzáférési token minden hívással megy.

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.json JWT 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.
Nem találta, amit keresett?

Írjon nekünk, vagy foglaljon időpontot. Válaszolunk a funkciókkal, a telepítéssel és a licenceléssel kapcsolatos kérdésekre.

Kapcsolat