Fejlesztői dokumentáció

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.

Kb. 6 perc olvasás

OAuth-folyamat

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.

1. Hozzájárulás
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=…
2. Token-csere
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ódok

HibakódMikor
invalid_requestHiányzó vagy rossz paraméter; a redirect_uri nincs regisztrálva; nem S256 PKCE.
invalid_clientIsmeretlen client_id, hiányzó vagy rossz client_secret.
invalid_grantIsmeretlen, 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_clientAz app fel van függesztve.
invalid_scopeA kért hatókör ismeretlen, vagy nem része az app jóváhagyott hatóköreinek.
access_deniedA bérlő elutasította a hozzájárulást (a redirect_uri-n érkezik).
server_errorBelső hiba; próbáld újra az engedélyezést.

Hatókörök

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örMit enged a bérlőnek megjelenítveTípus
reservations.readonlyFoglalások megtekintéseolvasás
reservations.writeFoglalások létrehozása és módosításaírás
reservations.manageFoglalások teljes kezelése (törlés, státusz)írás
contacts.readonlyKapcsolatok megtekintéseolvasás
contacts.writeKapcsolatok létrehozása és módosításaírás
contacts.deleteKapcsolatok törléseírás
deals.readonlyÜzletek (pipeline) megtekintéseolvasás
deals.writeÜzletek létrehozása és mozgatásaírás
orders.readonlyRendelések megtekintéseolvasás
menu.readonlyÉtlap megtekintéseolvasás
menu.writeÉtlap szerkesztéseírás
loyalty.readonlyHűségprogram-egyenlegek megtekintéseolvasás
reviews.readonlyÉrtékelések megtekintéseolvasás
webhooks.manageWebhook-feliratkozások kezeléseírás
content.readonlyTartalmak (blog) megtekintéseolvasás
content.writeTartalmak (blog) írásaírás
cameras.writeKamerás vendégszámláló adatok beküldéseírás
conversions.writeKonverziós események küldéseírás
calendar.readonlyNaptárak és időpontok megtekintéseolvasás
calendar.writeIdőpontok foglalása és lemondásaírás
webshop.readonlyWebshop-termékek és -rendelések megtekintéseolvasás
webshop.writeWebshop-termékek szerkesztése, rendelések állapotának léptetéseírás
ticketing.readonlyRendezvények, jegyrendelések és jegyek megtekintéseolvasás
ticketing.writeJegyek érvényesítése (beléptetés)írás
attendance.readonlyMunkaidő-adatok megtekintése (dolgozók, beosztás, jelenlét)olvasás
attendance.absences.readonlyDolgozói távollétek megtekintése (betegszabadság is - egészségügyi adat)olvasás
erp.readonlyVállalatirányítási adatok megtekintéseolvasás
erp.bank.readonlyBanki tranzakciók megtekintése (bérutalások és magánszemélyek adatai is)olvasás
emails.readonlyE-mail sablonok és kampányok megtekintéseolvasás
emails.sendE-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.created
  • reservation.updated
  • reservation.cancelled
  • contact.created
  • contact.updated
  • contact.deleted
  • deal.created
  • deal.stage_changed
  • deal.won
  • deal.lost
  • review.created
  • review.replied