Előfizetéskezelő API és ügyfélportál: integrációs checklist

Röviden

Ha a saját alkalmazásod fiókoldalán akarod megmutatni és kezelni az előfizetéseket, három dolgot kell összekötnöd: a szerveroldali REST API-t, a felületet (saját nézet vagy beágyazott widget) és a webhookos szinkront. A legtöbb hiba nem a hívásokban, hanem az azonosítókban és a jogosultságokban van, ezért a cikk egy szintetikus azonosítótérképpel, kulcsjogosultsági táblával és elfogadási checklisttel segít.

Röviden: mit kell összekötni?

Az ügyfeled már belépett az alkalmazásodba. Miért kellene egy másik felületre küldened, hogy megnézze a csomagját, letöltse a számláját vagy lemondja az előfizetését? Ha ezt a saját fiókoldaladon akarod megoldani, az ügyfélportál-integrációhoz egy előfizetéskezelő API-t három ponton kell bekötnöd:

1. Szerveroldali REST API: ügyfél létrehozása, vásárlás indítása, az előfizetés és a számlák kiolvasása, csomagváltás, lemondás, felhasználás rögzítése.
2. Felület: a portálod vagy saját nézetet rajzol az API adataiból, vagy beágyaz egy kész widgetet, amely egy konkrét előfizetést mutat és kezel.
3. Szinkron: webhookok jelzik a változást, a pontos állapotot pedig az API-ból olvasod vissza.

A legtöbb integrációs hiba nem a hívásokban van, hanem abban, hogy melyik saját felhasználóhoz melyik Komashi-ügyfél és melyik előfizetés tartozik, és hogy melyik kulcs mit tehet. Ezért ez a checklist az azonosítótérképpel és a jogosultságokkal kezd.

Ha még azt döntöd el, mit érdemes egyáltalán magadnak fejleszteni, előbb nézd át a saját fejlesztés vagy kész megoldás döntési mátrixát. Ha neked elég a Komashi saját, márkázott ügyfélportálja, az ügyfélportál tervezéséről szóló cikk a jobb kiindulópont.

Melyik megoldás illik a portálodhoz?

Megoldás	Mikor illik	Mit kell megépítened
Link a Komashi szolgáltatói oldalára	A portálod csak továbbküld; az ügyfél ott vásárol és ott kezeli az előfizetését	Gomb, magyarázó szöveg; fejlesztés alig
Beágyazott widget a portálban	Az előfizetés a te oldaladon látszódjon, de a kezelőfelületet nem akarod megírni	Backend, amely kiválasztja a belépett felhasználó előfizetés-azonosítóját; a widget beágyazása
Saját nézet az API-ból	Saját dizájn, saját logika, például a csomag mellett a felhasználási keret vagy a számlák listája	Szerveroldali API-hívások, saját felület, hibakezelés, szinkron

A második és a harmadik megoldás keverhető: a csomag és a lemondás a widgetben, a felhasználási keret és a számlák listája saját nézetben. A Komashi ügyfélportál termékoldala azt mutatja, mit kap az ügyfél akkor, ha nem építesz saját felületet.

Az adatfolyam egyszerűsítve:

Böngésző (belépett felhasználó)
   │  csak a saját munkameneteddel
   ▼
Saját backend ──── Bearer API-kulcs ────▶ Komashi REST API (/v1)
   ▲                                          │
   └──────── aláírt webhook ◀─────────────────┘
Böngésző ◀── widget (csak a backend által kiválasztott subscription_id)

Az API-kulcs soha nem hagyja el a backendet; a böngésző csak a te munkamenetedet és a backend által kiválasztott azonosítót látja.

Azonosítótérkép: mit tárolj a saját adatbázisodban?

Az alábbi táblázat szintetikus példa: kitalált azonosítókkal mutatja, melyik saját mezőhöz melyik Komashi-azonosító tartozik. Nem éles fiókból származó adat.

Saját rendszered (példa)	Komashi-azonosító	Honnan kapod	Mire kell
users.id = u_1842	–	saját	a belépett felhasználó
users.komashi_customer_id	customer_id	az ügyfél létrehozásának válaszából vagy az ügyféllistából	vásárlás indítása, ügyféladatok olvasása
orders.ref = ord_2026_0042	external_reference	te adod meg a vásárlás indításakor	a saját rendelésed visszakeresése
subscriptions.komashi_id	subscription_id	a vásárlás indításának válaszából	állapot, widget, csomagváltás, lemondás, felhasználás
subscriptions.komashi_group_id	group_id	ugyanabból a válaszból	csoportszintű felhasználás olvasása
catalog.plan_id, catalog.period_id	plan_id, period_id	a katalógus lekérdezéséből	melyik csomagot és időszakot vásárolják

Három szabály, amelyet a REST API-integráció és a widgetek dokumentációja rögzít:

• A group_id nem helyettesíti a subscription_id-t. A csomagváltás, a lemondás és az Előfizetés részletei widget az egyedi előfizetés-azonosítót kéri.
• Az ügyfélazonosító sem helyettesíti az előfizetés-azonosítót a widgetben.
• Azonosítót ne találj ki. A szolgáltatás-, csomag- és időszakazonosítót a katalógusból olvasd ki, ne a felületről másold kézzel a kódba.

API-kulcs: melyik feladathoz milyen jog kell?

Az API-kulcsot a Vezérlőközpont → Integráció → API oldalon hozod létre. A kulcs a szolgáltatót azonosítja, ezért nem kell külön szolgáltatóazonosító-fejléc. A teljes kulcs csak létrehozáskor látszik; ha elveszted, újat kell készítened (API-kulcsok útmutató).

Portálfeladat	Hívás (a /v1 végponthoz képest)	Szükséges jog
Csomagok és időszakok megjelenítése	GET /services, .../plans, .../periods	Olvasás
Ügyfél létrehozása a saját felhasználóhoz	POST /customers	Létrehozás
Vásárlás indítása	POST /services/{service}/subscriptions	Létrehozás
Előfizetés állapotának olvasása	GET /subscriptions/{subscription_id}	Olvasás
Számlák listázása	GET /invoices	Olvasás
Felhasználás olvasása	GET /subscriptions/{subscription_id}/usage	Olvasás
Csomagváltás	POST /subscriptions/{subscription_id}/change-plan	Frissítés
Lemondás	DELETE /subscriptions/{subscription_id}/cancel	Frissítés
Felhasználás rögzítése	sync-usage vagy adjust-usage	Frissítés

Gyakorlati döntések:

• Ne ments üres jogosultsággal kulcsot. A dokumentáció szerint a jelenlegi űrlap ilyenkor teljes hozzáférést ad, nem hozzáférés nélküli kulcsot. Mentés után a listában is nézd meg a jogosultságokat.
• Külön integrációhoz külön kulcs. Ha az egyiket cserélni kell, a többi rendszer tovább működik.
• A kulcs csak a szerveren lehet, környezeti változóban vagy titokkezelőben. A böngészőbe, a mobilalkalmazásba és a widget kódjába nem kerülhet.

Négy folyamat, amelyet a portálnak kezelnie kell

1. Új előfizetés a portálból

Egy kitalált példán: a felhasználó (u_1842) a fiókoldalon a havi csomagot választja.

1. Ha még nincs komashi_customer_id, a backend létrehozza az ügyfelet. A dokumentáció szerint ehhez számlázási adatok kellenek (billing_name, billing_address, billing_zip, billing_city, billing_country, országtól függően billing_state), és a szolgáltató által kötelezővé tett egyedi mezők is. Ezeket a portálodnak be kell kérnie, mielőtt elindítja a vásárlást.
2. A backend elküldi a POST /services/{service}/subscriptions kérést a customer_id, plan_id, period_id, quantity, external_reference, return_url és cancel_url mezőkkel.
3. A válaszból elmenti a subscription_id és group_id értékét, majd a felhasználót a checkout_url címre irányítja.

A 2. lépés szerveroldalon, a REST API-integráció dokumentációjában szereplő formában (a nagybetűs értékek helyőrzők, a mezőket és a válaszsémát az interaktív API-referenciában ellenőrizd):

curl -X POST "https://api.komashi.com/v1/services/SERVICE_UUID/subscriptions" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUSTOMER_UUID",
    "plan_id": "PLAN_UUID",
    "period_id": "PERIOD_UUID",
    "quantity": 1,
    "external_reference": "ord_2026_0042",
    "return_url": "https://app.example/subscription/return",
    "cancel_url": "https://app.example/subscription/cancel"
  }'

A válasz data része tartalmazza a checkout_url, subscription_id és group_id mezőt. 4. A return_url oldalon nem ad azonnal hozzáférést. Kiolvassa az előfizetést, és csak akkor nyit, ha az állapot ezt indokolja. Addig „feldolgozás alatt” üzenetet mutat.

2. Meglévő előfizetés megjelenítése

• Widgettel: a jogosultság-ellenőrzés nem annyi, hogy a helyes azonosító kerül a HTML-be. Három feltétel kell együtt:

  1. a widgetet tartalmazó oldal csak a te bejelentkezésed mögött érhető el;
  2. az azonosítót a backend a munkamenet felhasználójából keresi ki a saját adatbázisodban (users.id → subscriptions.komashi_id), soha nem URL-ből, űrlapmezőből vagy sütiből veszi át;
  3. ha a felhasználónak nincs előfizetése, az oldal nem renderel widgetet.

  A böngésző látja a HTML-be írt azonosítót, ezért ne feltételezd, hogy a widget a te felhasználód jogosultságát ellenőrzi helyetted. Az elfogadási checklist 4. pontja ezt teszteli.

• Saját nézettel: a backend kiolvassa az előfizetést, a felhasználást és a számlákat, és csak a saját ügyfélhez tartozó rekordokat adja ki. A szűrési paramétereket az interaktív API-referenciában nézd meg; ezt a Vezérlőközpont → Integráció → API oldalon a Dokumentáció hivatkozás nyitja meg.

3. Csomagváltás és lemondás

A widget a meglévő előfizetés kezelésére is szolgál. Ha saját gombot építesz, a csomagváltás és a lemondás Frissítés jogú kulccsal hívható. A lemondás a szolgáltatói szabályaidat követi (időszak végéig vagy azonnal), a csomagváltás szabályai szerint pedig a felminősítés különbözetét arányosítva még aznap kell kifizetni, a leminősítés a ciklus végén lép életbe, visszatérítés nélkül. A portálod szövege ugyanezt mondja, mint a szabályaid.

4. Szinkron webhookkal

A webhookok közül ügyfélportálhoz jellemzően a customers.* és a subscription.create, subscription.update, subscription.delete események kellenek. Ha a portál csomaglistát mutat, a katalógusváltozásokat a service.* eseményekkel követheted. Általános fizetési vagy számlaeseményre ne építs, mert a választható eseménylistában ilyen nincs; a számlákat az API-ból olvasd.

• Az aláírást (HMAC-SHA256, hexadecimális) az eredeti kérés bájtjain ellenőrizd, feldolgozás előtt.
• Gyorsan válaszolj 2xx kóddal, a lassú munkát háttérben végezd.
• Egy kézbesítésre legfeljebb négy kísérlet jut (újrapróbálás 10, 60 és 300 másodperc után), sorrendgarancia és univerzális kézbesítési azonosító nincs. A feldolgozás legyen ismétlésbiztos, kétes esetben pedig olvasd ki az aktuális állapotot az API-ból.
• A dokumentáció szerint a Webhookok oldal jelenleg nem ad másolási lehetőséget az aláírási titokhoz. Integráció előtt tisztázd, hogyan jut el a titok biztonságosan a fogadó szerveredhez.

Gyakori buktatók

• A return_url-t fizetésnek tekinteni. Csak a böngésző visszatérését jelzi.
• Vakon újrapróbálni egy írást. Az adjust-usage minden ismétléskor újra alkalmazza a változást; időtúllépés után előbb olvasd ki az aktuális értéket. A felhasználási keretek beállítását a használati limitek és kiegészítők oldala mutatja be.
• A 429-es választ figyelmen kívül hagyni. A REST-korlát percenként 100 kérés; várj és próbáld újra visszalépéssel. Listáknál a lapméret legfeljebb 100.
• Egyoldalú alkalmazásba (SPA) később beszúrt widget. A betöltő az első futáskor talált beágyazásokat inicializálja; a dokumentáció szerint utólag beszúrt elemeket nem keres újra automatikusan.
• Szigorú Content Security Policy. A widget hostját engedélyezni kell a külső szkriptek és keretek között.
• Katalógus írása API-n. A katalógust és a kuponokat a Vezérlőközpontban állítod be; a dokumentáció szerint nem minden katalóguselemhez van nyilvános REST írási végpont.

Elfogadási checklist élesítés előtt

Ezt a listát tesztügyféllel és a saját környezetedben járd végig. A teszt valódi fizetéssel járhat, ezért a lehető legkisebb árú tesztcsomaggal dolgozz.

1. Minden saját felhasználóhoz legfeljebb egy customer_id tartozik, és ezt tárolod.
2. A vásárlás external_reference értéke alapján visszakereshető a saját rendelésed.
3. A return_url oldal nem ad hozzáférést, amíg az állapot nincs kiolvasva.
4. Egy másik felhasználó előfizetés-azonosítójával a portál semmit nem mutat.
5. A portál a widgetben vagy a saját nézetben csak a saját előfizetést és számlákat mutatja.
6. A csomagváltás szövege a portálon egyezik a Komashi visszaigazoló képernyőjével (ma fizetendő / következő megújítás).
7. A lemondás a szolgáltatói szabályod szerint működik, és a portál ezt írja ki.
8. Egy szándékosan hibás aláírású webhookot a fogadó elutasít.
9. Ugyanaz a webhook kétszer elküldve nem okoz kétszeres változást.
10. A 401, 403, 409, 422 és 429 válaszoknak van érthető üzenete a portálon és naplóbejegyzése a backendben.
11. Az API-kulcs nem szerepel a frontend kódban, a naplókban és a hibaüzenetekben.
12. Kulcscserét kipróbáltál: új kulcs, konfigurációcsere, működés ellenőrzése, régi kulcs törlése.

Következő lépés

• Fejlesztőként kezdenéd? Az első lépés negyedóra: hozz létre egy csak Olvasás jogú kulcsot, és kérd le a szolgáltatásaidat:

  curl "https://api.komashi.com/v1/services" \
    -H "Authorization: Bearer $KOMASHI_API_KEY" \
    -H "Accept: application/json"

  A válaszból kapod a szolgáltatás-, csomag- és időszakazonosítókat, amelyekkel az azonosítótérkép kitölthető. A teljes folyamatot a REST API-integráció útmutató, az API-t és a webhookokat áttekintően a Komashi fejlesztői oldala mutatja.

• Elég a kész felület? A Komashi szolgáltatói oldala és ügyfélportálja fejlesztés nélkül is működik; a beágyazási lehetőségeket a widgetek útmutatója mutatja.

Gyakori kérdések

Kell saját ügyfélportált építenem, ha Komashit használok?

Nem. Az ügyfél a szolgáltatói oldaladon, belépés után a Komashi ügyfélportálján is kezelheti az előfizetéseit. Saját portálra akkor van szükség, ha az ügyfeled már a te alkalmazásodba lép be, és ott szeretnéd megmutatni a csomagját, a számláit vagy a felhasználását.

Melyik jogosultság kell az API-kulcshoz?

Olvasáshoz az Olvasás elég (katalógus, ügyfelek, előfizetések, számlák, felhasználás). Ügyfél és vásárlás létrehozásához Létrehozás, csomagváltáshoz, lemondáshoz és felhasználás-frissítéshez Frissítés kell. A lemondás is Frissítés jogot igényel, pedig DELETE metódusú hívás. Üres kijelöléssel ne mentsd a kulcsot: a jelenlegi űrlap ilyenkor teljes hozzáférést ad.

Elég a return_url ahhoz, hogy hozzáférést adjak?

Nem. A visszatérési cím csak azt jelzi, hogy a böngésző visszajött. Fizetős hozzáférés előtt olvasd ki az előfizetés aktuális állapotát az API-n.

Mire figyeljek a webhookoknál?

Ellenőrizd a HMAC-SHA256 aláírást az eredeti kérés bájtjain, válaszolj gyorsan 2xx kóddal, és dolgozd fel ismétlésbiztosan: egy kézbesítés legfeljebb négyszer érkezhet, sorrendgarancia nincs. Kétes esetben az aktuális állapotot olvasd ki az API-n.

Kerülhet az API-kulcs a böngészőbe vagy a widgetbe?

Nem. A REST-kulcs csak a szervereden lehet. A widget beágyazókódjában nincs API-kulcs, a megjelenített előfizetés-azonosítóról viszont a te backendednek kell eldöntenie, hogy a belépett látogató láthatja-e.

Források és további olvasnivaló

• Komashi Docs — REST API-integráció
• Komashi Docs — API-kulcsok
• Komashi Docs — Webhookok
• Komashi Docs — Widgetek beágyazása
• Komashi Docs — Előfizetések
• Komashi Docs — Fejlesztői áttekintés

Frissítve: 2026. november 11.