﻿# Az API használata

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

Source: https://workwise-solutions.net/hu/docs/api-usage/ · Language: hu · English version: https://workwise-solutions.net/docs/api-usage/

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](https://workwise-solutions.net/hu/docs/features/personal-access-tokens/) 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.

![Személyes hozzáférési tokenek](https://workwise-solutions.net/docs/images/diagram-pat-hu.png)
*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](https://workwise-solutions.net/hu/docs/permissions-and-roles/)): 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](https://workwise-solutions.net/hu/docs/features/service-user-catalog/) vagy a saját vaultjában.
