Hitelesítés és kulcsok

Az OkosMunkalap REST API minden hívása API kulccsal hitelesített. A kulcs azonosítja a fiókot és meghatározza, hogy mely műveleteket és mely adatokat éri el az integráció.

Bearer hitelesítés

A kulcsot az Authorization HTTP fejlécben kell elküldeni, Bearer sémával:

Authorization: Bearer omk_live_a1b2c3d...

A kulcs kizárólag a fejlécben fogadható el. Query paraméterben vagy a kéréstörzsben küldött kulcs nem érvényes (ezek könnyen szivároghatnak naplókba).

Az API szerver-szerver használatra készült, és nem küld CORS fejléceket. Böngészőből, kliensoldali JavaScriptből ne hívd közvetlenül: a kulcs ott bárki számára láthatóvá válna. A hívásokat mindig a saját szervered (backend) végezze.

Kulcs formátum

A nyers kulcs felépítése:

omk_<mód>_<token>

• A <mód> jelenleg mindig live (éles), tehát a kulcs omk_live_ előtaggal kezdődik. Külön teszt mód később érkezik.
• A <token> egy véletlen, URL-biztos karaktersorozat.

A rendszer a kulcsnak csak az SHA-256 lenyomatát tárolja, a nyers kulcsot soha. Ezért a kulcs teljes értéke csak egyszer, a létrehozáskor jelenik meg. Ha elveszett, nem állítható vissza, csak új kulcs hozható létre.

Kulcs igénylése

1. Jelentkezz be az alkalmazásba.
2. Nyisd meg a Beállítások → Integrációk → Kulcsok oldalt (csak a fiók tulajdonosa és az adminok érik el).
3. Hozz létre egy új kulcsot: adj nevet, válaszd ki a jogosultságokat, az adat hatókört, és igény szerint a webhook beállításokat.
4. Másold ki és tárold biztonságosan a megjelenő nyers kulcsot.

A kulcsot bármikor visszavonhatod ugyanitt. A visszavonás után a kulcs rövid ideig (legfeljebb egy percig) még működhet a belső gyorsítótár miatt, utána minden hívása 401 hibát ad.

Jogosultságok

Minden kulcshoz jogosultságok (permission) tartoznak, amelyek meghatározzák, mely műveleteket végezheti. A jogosultság a terület:művelet formátumot követi:

Jogosultság	Engedélyezett művelet	Érintett végpontok
customers:read	ügyfelek olvasása	GET /v1/customers, GET /v1/customers/{id}
customers:create	ügyfelek létrehozása	POST /v1/customers
customers:write	ügyfelek módosítása	PATCH /v1/customers/{id}
worksheets:read	munkalapok olvasása	GET /v1/worksheets, GET /v1/worksheets/{id}, GET /v1/worksheet-statuses, GET /v1/service-locations
worksheets:create	munkalapok létrehozása	POST /v1/worksheets
worksheets:write	munkalapok módosítása	PATCH /v1/worksheets/{id}/status, POST /v1/worksheets/{id}/assign
quotes:read	árajánlatok olvasása	GET /v1/quotes, GET /v1/quotes/{id}
quotes:create	árajánlatok létrehozása	POST /v1/quotes
materials:create	készlet-tételek létrehozása	POST /v1/materials
team:read	csapattagok olvasása	GET /v1/team-members

A GET /v1/custom-fields végponthoz a customers:read vagy a worksheets:read jogosultság egyike is elegendő.

Adj a kulcsnak mindig csak annyi jogosultságot, amennyire az integrációnak ténylegesen szüksége van. Ha egy hívás olyan műveletet kísérel meg, amelyhez a kulcsnak nincs jogosultsága, az API 403 hibát ad MISSING_PERMISSION kóddal.

Megjegyzés: a munkalap létrehozása ügyféllétrehozással (a customer.createIfMissing ággal, lásd az integrációs példát) a worksheets:create mellett a customers:create jogosultságot is megköveteli.

A felületen (Beállítások → Integrációk → Kulcsok) a team:read a Csapat soron kapcsolható be. Azért külön jogosultság, mert személyes adatot (nevet, email címet) ad vissza: ne örökölje minden olvasó kulcs. Ugyanezért igényli a munkalap létrehozása is, ha a kéréshez assignments listát adsz: a válaszban a hozzárendelt kolléga neve is megjelenik.

Adat hatókör (dataScope)

Míg a jogosultság azt szabályozza, hogy milyen műveletet végezhet a kulcs, az adat hatókör azt, hogy mely adatokon. Két érték lehetséges:

Hatókör	Jelentés
external_system	A kulcs csak a saját külső rendszer névteréhez (vagy névtereihez) kötött ügyfeleket és munkalapokat látja és módosíthatja.
all_account	A kulcs a teljes fiók adatait eléri (a jogosultságai keretein belül).

A hatókör alapértelmezése: ha a kulcshoz tartozik legalább egy külső rendszer névtér (lásd lent), akkor external_system, egyébként all_account.

A hatókörön kívüli erőforrásokra az API szándékosan 404 (nem található) hibát ad, nem 403-at. Így az sem derül ki, hogy az adott azonosítójú erőforrás egyáltalán létezik-e a fiókban.

Külső rendszer azonosító és névtér

Egy integráció saját külső rendszer névteret kaphat a kulcsán. Ez egy rövid, gépi azonosító (pl. monitoring, crm, callcenter), amely egy névteret nyit a fiókon belül. Megengedett karakterek: kisbetűk, számok, kötőjel és aláhúzás, legfeljebb 64 karakter (a rendszer kisbetűsíti); minta: ^[a-z0-9_-]{1,64}$.

A külső azonosítók (externalId) ebbe a névtérbe kerülnek. Például ha az integrációd minden ügyfélhez tárol egy saját azonosítót, azt az OkosMunkalap az adott kulcs névtere alá rendeli. Ennek két fontos következménye van:

• Match-or-create. Egy ügyfelet a saját külső azonosítóddal kereshetsz meg (GET /v1/customers?externalId=...), és munkalap indításakor egy lépésben létrehozhatod, ha még nem létezik. Lásd az integrációs példát.
• Elszigetelés. Két különböző integráció két különböző névteret kap. Egyikük sem látja a másik külső azonosítóit, akkor sem, ha ugyanarról a valós ügyfélről van szó. external_system hatókörnél az ügyfél válaszában csak az adott kulcshoz tartozó névtér(ek) azonosítója szerepel.

external_system hatókörű kulcsnál a külső azonosító kötelező új ügyfél létrehozásakor (POST /v1/customers), különben a kulcs később a saját maga által létrehozott ügyfelet sem érné el.

Több névtér egy kulcson

Egy kulcshoz több külső rendszer névtér is rendelhető (legfeljebb 10), egy elsődleges névtérrel. Erre akkor van szükség, ha ugyanaz az integráció többféle azonosító-típust használ (például egy távfelügyeleti és egy pénzügyi ügyfélszámot). Ilyenkor:

• Adat hatókör. external_system hatókörnél a kulcs a teljes névtér-listájához kötött ügyfeleket és munkalapokat látja: egy entitás akkor esik a hatókörbe, ha bármely névteréhez tartozik külső azonosító.
• Elsődleges névtér. Az egyik névtér az elsődleges, és ez a célja a külső azonosítót létrehozó hívásoknak (POST /v1/customers, illetve a munkalap createIfMissing ága), ha a kérés nem ad meg explicit cél-névteret. A célzott névtér megadásáról és a feloldás szabályairól lásd az API referencia externalSystem paraméterét.
• Olvasás. A külső azonosító alapú kereséskor (GET /v1/customers?externalId=, ?phone=, GET /v1/worksheets?customerExternalId=) a kulcs alapból minden névterében keres. Ha a keresés két különböző ügyfélre is illeszkedne (több névtérben vagy azonos telefonszámmal), a hívás 409 (EXTERNAL_ID_AMBIGUOUS) hibát ad; ezt a célzott externalSystem paraméterrel kerülheted el.

A beállításról. A névterek a kulcskezelő felületen állíthatók (Beállítások / Integrációk / Kulcsok): a kulcs létrehozásakor és szerkesztésekor is felvehetsz legfeljebb 10 névteret, és kijelölheted az elsődlegest (két vagy több névtérnél kötelező). Meglévő kulcshoz új névtér hozzáadása kiszélesíti a kulcs hozzáférését, ezért a felület külön megerősítést kér. Az egyedi mező és a névtér összekötése (a mező értéke külső azonosítóként működjön) szintén a felületen állítható: Beállítások / Extra testreszabás / Egyedi mezők, a mező szerkesztőjében a „Külső rendszer névtér“ megadásával — a névtérnek egyeznie kell a kulcson beállítottal.

Ha a kulcsnak egyetlen névtere van, ezek a szabályok egyszerűsödnek: minden írás és olvasás magától ehhez az egy névtérhez kötődik, és nincs többértelműség.

Lejárat és állapot

A kulcsnak lehet lejárati ideje. Lejárt kulccsal a hívás 403 hibát ad KEY_EXPIRED kóddal. A visszavont kulcs a REST híváson 401 (INVALID_API_KEY) hibát ad, mert az API csak aktív kulcsot fogad el.

Hitelesítési hibák

Helyzet	HTTP	Kód
Hiányzó vagy formátum szerint érvénytelen kulcs	401	INVALID_API_KEY
Ismeretlen vagy visszavont kulcs	401	INVALID_API_KEY
Lejárt kulcs	403	KEY_EXPIRED
A kulcsnak nincs joga a művelethez	403	MISSING_PERMISSION
A művelethez külső rendszer kell, de a kulcson nincs beállítva	400	EXTERNAL_SYSTEM_NOT_CONFIGURED

A teljes hibakód listát a Hibakódok oldal tartalmazza.