API-hozzáférések és jogosultságok: mihez mi kell?

A DiKAS többféle módon teszi lehetővé a bejelentkezést egy interfészre. Mindegyiknek saját jogosultságai és saját célja van. Ez az oldal segít megválaszolni a kérdést: „Melyik hozzáférésre van szükségem a feladatomhoz?" – és a láncutalványok esetében azt is megmutatja, melyik jogosultság melyik híváshoz tartozik.

A hozzáférési módok áttekintése

Hozzáférés	Ki hozza létre	Bejelentkezés	Mi határozza meg a jogosultságokat	Tipikus felhasználás
Felhasználói bejelentkezés (REST API 1-es verzió)	A példány adminisztrátora (felhasználó)	POST /api/v1/auth/login → Bearer-token	A bejelentkezett felhasználó jogosultságai	Saját kimutatások, termék- és ügyféladatok karbantartása, helyi utalvány lekérdezése
API-kulcs (régi interfész, /rest/…)	Adminisztrátor az Adminisztráció → Beállítások → API-kulcsok menüpontban	X-Api-Key fejléc (a {key} útvonalszakasz helyén ekkor -)	A kulcs hozzáférési típusa	Webáruház, meglévő szoftver ügyfél-/utalványkapcsolata, fizetőautomaták, forgókapu
Egy üzletlánc integrációs hozzáférése	A lánctulajdonos az Ügyfélportálon	Authorization: Bearer <schlüssel> vagy X-Api-Key fejléc	A hozzáférés jogosultságai (voucher:…) és üzletei	Külső pénztárak, amelyek láncutalványokat ellenőriznek, beváltanak, visszatérítenek, kiadnak
Portálbejelentkezés	Az ügyfél a saját fiókjával (konto.dikas.de)	Portálbejelentkezés	Szerepkör a láncban: tulajdonos vagy üzlet	A lánc kezelése, integrációs hozzáférések létrehozása, elszámolás, jelentések

Ökölszabály: egy hozzáférés, amely pénzt mozgat, csak azokat a jogosultságokat kapja meg, amelyekre a feladatához szüksége van, és csak azokat az üzleteket, amelyekben dolgozik. Inkább pénztáranként vagy szolgáltatónként hozzon létre külön hozzáférést – így egyetlen hozzáférés letiltható anélkül, hogy a többit zavarná.

„Szeretnék …" – melyik hozzáférés kell?

Feladat	Hozzáférés	Jogosultság / típus
Egy helyi utalvány lekérdezése	Felhasználói bejelentkezés (GET /api/v1/vouchers/…) vagy API-kulcs	Felhasználói jogosultságok, illetve Voucher hozzáférési típus
Helyi utalvány létrehozása vagy terhelése egy meglévő alkalmazásból	API-kulcs (/rest/extern/voucher/-/…)	Voucher hozzáférési típus
Egy láncutalvány ellenőrzése	Integrációs hozzáférés	voucher:lookup
Láncutalvány beváltása (zárolás, bejelentés, megerősítés, feloldás)	Integrációs hozzáférés	voucher:redeem
Láncutalvány visszatérítése	Integrációs hozzáférés	voucher:refund
Láncutalványok kiadása vagy kártyák aktiválása (lezárással és megszakítással együtt)	Integrációs hozzáférés	voucher:issue
A láncutalványok változásainak lekérése	Integrációs hozzáférés	voucher:export
Egy folyamat lekérdezése (operations/…) vagy a program (programs) olvasása	Integrációs hozzáférés	bármilyen jogosultság
Integrációs hozzáférés létrehozása, megújítása vagy letiltása	Portálbejelentkezés	Lánctulajdonos
Rendelések fogadása saját webáruházból	API-kulcs	OnlineOrder hozzáférési típus
Fizetőautomata (Disco) csatlakoztatása	API-kulcs	Disco hozzáférési típus
Ügyfelek, termékek, foglalások vagy nyomtatási feladatok szerkesztése a régi interfészen	API-kulcs	megfelelő hozzáférési típus (lásd lent)
A lánc elszámolásának, számlázásának és kártyaíveinek megtekintése	Portálbejelentkezés	Lánctulajdonos

API-kulcsok: hozzáférési típusok

Amikor az Adminisztráció → Beállítások → API-kulcsok menüpontban kulcsot hoz létre, kiválasztja a hozzáférési típust. Ez határozza meg, mire jogosult a kulcs. Technikailag a következő típusok léteznek: OnlineOrder (online rendelések), LagerOrder, Bookings, Customer, Article, Print, CustomerBookings, Voucher, Disco és CustomerContacts.

• Egy kulcsnak pontosan egy hozzáférési típusa van. Ha két feladatra van szüksége, hozzon létre két kulcsot.
• Fizetőautomaták esetén a kulcs a munkaállomást is meghatározza (lásd REST API).
• Bizalmas kulcsok nem kerülhetnek URL-be. Az új kliensek az X-Api-Key fejlécben küldik őket, az útvonalban pedig - marad.
• Egy kulcs bármikor törölhető és lecserélhető; a kapcsolatot ekkor át kell állítani.

Integrációs hozzáférés: melyik híváshoz melyik jogosultság kell?

Minden hívás a /api/v1/integrations/vouchers alatt található. A szükséges jogosultság nélküli hívás 403 INSUFFICIENT_SCOPE válasszal ér véget, mielőtt bármi könyvelésre kerülne.

Hívás	Szükséges jogosultság
GET /programs	bármilyen jogosultság
POST /lookup	voucher:lookup
POST /reservations	voucher:redeem
POST /reservations/{id}/prepare	voucher:redeem
POST /reservations/{id}/commit	voucher:redeem
POST /reservations/{id}/release	voucher:redeem
POST /refunds	voucher:refund
POST /issues	voucher:issue
POST /activations	voucher:issue
POST /operations/{id}/complete	voucher:issue
POST /operations/{id}/cancel	voucher:issue
GET /changes, GET /transactions	voucher:export
GET /operations/{id}, GET /operations/by-reference/{referenz}	bármilyen jogosultság

Tipikus jogosultságcsomagok

Felhasználás	Jogosultságok
Külső pénztár, amely csak bevált	voucher:lookup, voucher:redeem
Külső pénztár sztornóval/visszáruval	ezen felül voucher:refund
Pénztár, amely utalványokat is értékesít	ezen felül voucher:issue
Könyvelési vagy BI-eszköz, amely csak olvas	voucher:export

Egy csak olvasó hozzáférésnek nincs szüksége sem redeem, sem refund, sem issue jogosultságra. Fordítva: egy beváltó pénztárnak nincs szüksége export jogosultságra, amíg nem kér le adatfolyamot.

Üzletek

A jogosultságokon felül minden integrációs hozzáférés kap egy üzletlistát. Csak ott lát és könyvel:

• A listán kívüli üzlet „ismeretlenként" válaszol (BRANCH_UNKNOWN, 404) – nem „tiltottként". Így nem derül ki, milyen üzletek léteznek.
• Visszatéríteni csak abban az üzletben lehet, amelyik a beváltást végezte.
• Ha egy üzlet kilép a láncból, ez a következő kérésnél lép érvénybe.

Hozzáférés kezelése

Hozzáféréseket csak a lánctulajdonos hozhat létre, újíthat meg és tilthat le (portálbejelentkezéssel, lásd Külső utalványrendszerek csatlakoztatása). A lánc egy üzlete erre nem képes, „Teljes" részvétellel sem.

Művelet	Következmény
Létrehozás	A kulcs egyszer jelenik meg; a DiKAS csak egy hash-t tárol
Kulcs megújítása	A régi kulcs azonnal érvényét veszti
Letiltás	A hívások CLIENT_BLOCKED választ adnak
Jogosultságok vagy üzletek módosítása	A következő kéréstől érvényes

Szerepkörök a láncban (portál)

Az Ügyfélportálon a DiKAS három nézetet különböztet meg. Hogy mit látnak, azt részletesen az Üzletek és üzletláncok – ki mit lát? oldal írja le:

Szerepkör	Mire képes
Lánctulajdonos	A lánc minden része: tagok, beállítások, terméktörzs, elszámolás, számlázás, kártyaívek, integrációs hozzáférések; az utalványokat és az ügyfeleket teljes egészében látja
Üzlet „Teljes" részvétellel	A saját üzlet utalványainak és ügyfeleinek megtekintése (maszkolt számokkal), saját beváltások és visszatérítések végrehajtása; a lánc kezelése nélkül
Üzlet „Csak jelentések" részvétellel	Jelentések és mutatók; nincs hozzáférése az ügyfélelőzményekhez

A „Teljes" részvétel előfeltétele annak, hogy egy üzlet egyáltalán beváltson vagy kiadjon utalványokat. A „Csak jelentések" részvételű üzlet nem vált be – integrációs hozzáférésen keresztül sem.

Hibaképek: a jogosultságon múlik?

Üzenet	Valószínű ok	Teendő
401 / INVALID_CREDENTIALS	A kulcs hibás, lejárt vagy meg lett újítva	Ellenőrizze az aktuális kulcsot; kérjen újat a tulajdonostól
403 INSUFFICIENT_SCOPE	A hozzáférésből hiányzik a híváshoz szükséges jogosultság	Lásd a fenti táblázatot; kérje meg a tulajdonost a jogosultság kiegészítésére
404 BRANCH_UNKNOWN	Az üzlet nincs engedélyezve a hozzáféréshez, vagy kilépett	Ellenőrizze a hozzáférés üzletlistáját
CLIENT_BLOCKED	A hozzáférés le van tiltva	Egyeztessen a tulajdonossal
429 RATE_LIMITED	Percenként több mint 600 hívás	Várja ki a Retry-After időt, és ismételje meg ugyanazzal a kulccsal
Régi interfész: válasz adatok nélkül 200 ellenére	Az API-kulcs hozzáférési típusa hibás	Ellenőrizze az IsOk és az ErrorId értékét; ellenőrizze a kulcs típusát

A legkisebb jogosultság elve

Kezdje a voucher:lookup jogosultsággal, és csak akkor adjon hozzá további jogosultságokat, amikor a kapcsolatnak szüksége van rájuk. Így egy kapcsolat hibája legfeljebb azt válthatja ki, amire a hozzáférése szolgál.