OAuth és hatókörök
A telepítés szabványos OAuth 2.0 authorization code folyamat: hozzájárulás, token-csere, hibakódok, és a hatókörök, amelyeket az app kérhet.
Szabványos OAuth 2.0 authorization code folyamat. A token-cseréhez mindig kell a client_secret; a PKCE (S256) ajánlott kiegészítő védelem. A kulcs nem jár le, de a bérlő bármikor eltávolíthatja az appot (akkor a kulcs visszavonódik), és hatókör-bővítés csak a bérlő újabb hozzájárulásával lehetséges.
1GET https://prod.dynex.hu/api/apps/oauth/authorize2 ?response_type=code3 &client_id=dxapp_…4 &redirect_uri=https://app.example.com/oauth/callback # pontosan a regisztrált5 &state=<véletlen> # CSRF-védelem6 &scope=contacts.readonly reservations.write # opcionális; kihagyva az app összes hatóköre7 &code_challenge=<base64url(sha256(verifier))>&code_challenge_method=S256 # opcionális PKCE8 9→ a bérlő bejelentkezik (ha kell), látja a hozzájárulási képernyőt (hatókörök emberi néven, havidíj), megerősít10→ 302 https://app.example.com/oauth/callback?code=dxac_…&state=<ugyanaz>11 vagy elutasításnál: ?error=access_denied&state=…1POST https://prod.dynex.hu/api/apps/oauth/token2Content-Type: application/x-www-form-urlencoded3 4grant_type=authorization_code&code=dxac_…&client_id=dxapp_…5&client_secret=dxas_… # KÖTELEZŐ6&code_verifier=… # ha az authorize-ban code_challenge-et küldtél (PKCE)7&redirect_uri=https://app.example.com/oauth/callback # KÖTELEZŐ, pontosan az authorize-beli8 9200 { "access_token": "dxk_…", "token_type": "Bearer", "install_id": "…", "tenant_id": "…",10 "scopes": ["contacts.readonly", "reservations.write"], "embed_secret": "…",11 "webhook_secret": "whsec_…", # null, ha az appnak nincs webhook-feliratkozása12 "sandbox": false } # true, ha a telepítés a teszt-fiókodra történt134xx { "error": "invalid_grant", "error_description": "Authorization code expired." }A code egyszer használatos; párhuzamos beváltásnál csak az egyik nyer. A redirect_uri a token-kérésben is kötelező (nélküle invalid_request). Az embed_secret a telepítés saját titka a beágyazási token helyi ellenőrzéséhez: telepítésenként más, csak ebben a válaszban kapod meg, és a client_secret újragenerálása nem változtatja meg. Tárold a telepítés mellett. A webhook_secret az install webhook-feliratkozásának titka: installonként állandó, újra-engedélyezéskor ugyanaz jön vissza.
| Hibakód | Mikor |
|---|---|
invalid_request | Hiányzó vagy rossz paraméter; a redirect_uri nincs regisztrálva; nem S256 PKCE. |
invalid_client | Ismeretlen client_id, hiányzó vagy rossz client_secret. |
invalid_grant | Ismeretlen, már felhasznált vagy lejárt code (10 perc); eltérő redirect_uri; hibás code_verifier; a telepítés már nem aktív. |
unauthorized_client | Az app fel van függesztve. |
invalid_scope | A kért hatókör ismeretlen, vagy nem része az app jóváhagyott hatóköreinek. |
access_denied | A bérlő elutasította a hozzájárulást (a redirect_uri-n érkezik). |
server_error | Belső hiba; próbáld újra az engedélyezést. |
Az app csak azokat a hatóköröket kérheti, amelyeket a beküldéskor megadott és a tulajdonos jóváhagyott; a bérlő a hozzájárulási képernyőn ezeket az emberi neveket látja. Az .readonly végű hatókörök csak olvasnak.
| Hatókör | Mit enged a bérlőnek megjelenítve | Típus |
|---|---|---|
reservations.readonly | Foglalások megtekintése | olvasás |
reservations.write | Foglalások létrehozása és módosítása | írás |
reservations.manage | Foglalások teljes kezelése (törlés, státusz) | írás |
contacts.readonly | Kapcsolatok megtekintése | olvasás |
contacts.write | Kapcsolatok létrehozása és módosítása | írás |
contacts.delete | Kapcsolatok törlése | írás |
deals.readonly | Üzletek (pipeline) megtekintése | olvasás |
deals.write | Üzletek létrehozása és mozgatása | írás |
orders.readonly | Rendelések megtekintése | olvasás |
menu.readonly | Étlap megtekintése | olvasás |
menu.write | Étlap szerkesztése | írás |
loyalty.readonly | Hűségprogram-egyenlegek megtekintése | olvasás |
reviews.readonly | Értékelések megtekintése | olvasás |
webhooks.manage | Webhook-feliratkozások kezelése | írás |
content.readonly | Tartalmak (blog) megtekintése | olvasás |
content.write | Tartalmak (blog) írása | írás |
cameras.write | Kamerás vendégszámláló adatok beküldése | írás |
conversions.write | Konverziós események küldése | írás |
calendar.readonly | Naptárak és időpontok megtekintése | olvasás |
calendar.write | Időpontok foglalása és lemondása | írás |
webshop.readonly | Webshop-termékek és -rendelések megtekintése | olvasás |
webshop.write | Webshop-termékek szerkesztése, rendelések állapotának léptetése | írás |
ticketing.readonly | Rendezvények, jegyrendelések és jegyek megtekintése | olvasás |
ticketing.write | Jegyek érvényesítése (beléptetés) | írás |
attendance.readonly | Munkaidő-adatok megtekintése (dolgozók, beosztás, jelenlét) | olvasás |
attendance.absences.readonly | Dolgozói távollétek megtekintése (betegszabadság is - egészségügyi adat) | olvasás |
erp.readonly | Vállalatirányítási adatok megtekintése | olvasás |
erp.bank.readonly | Banki tranzakciók megtekintése (bérutalások és magánszemélyek adatai is) | olvasás |
emails.readonly | E-mail sablonok és kampányok megtekintése | olvasás |
emails.send | E-mail küldése a kapcsolataidnak a nevedben | írás |
Webhook-események, amelyekre az app alapértelmezetten feliratkozhat (default_webhook_events); a kézbesítésük leírása: Webhookok és események.
reservation.createdreservation.updatedreservation.cancelledcontact.createdcontact.updatedcontact.deleteddeal.createddeal.stage_changeddeal.wondeal.lostreview.createdreview.replied