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

Így kösd a saját ügyfélportálodat egy előfizetéskezelő API-hoz: azonosítótérkép, API-kulcs-jogosultságok, vásárlás, állapot, webhookok és elfogadási checklist.

- Szerző: Komashi Team
- URL: https://komashi.com/blog/2026/11/11/elofizeteskezelo-api-ugyfelportal-integracio/
- Megjelent: 2026-11-11
- Frissítve: 2026-11-11
- Language: hu

## 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](https://komashi.com/blog/2026/11/09/elofizeteses-rendszer-fejlesztes-vagy-kesz-megoldas/) 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](https://komashi.com/blog/2026/11/05/sajat-markas-ugyfelportal-tervezes/) 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](https://komashi.com/product/customer-portal) termékoldala azt mutatja, mit kap az ügyfél akkor, ha nem építesz saját felületet.

Az adatfolyam egyszerűsítve:

```text
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ó](https://komashi.com/docs/hu/provider/Developers/api-integration/) és a [widgetek](https://komashi.com/docs/hu/provider/Developers/widget-integration/) 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ó](https://komashi.com/docs/hu/provider/Settings/10api/)).

| 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):

```bash
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](https://komashi.com/docs/hu/provider/subscriptions/) 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](https://komashi.com/docs/hu/provider/Settings/11webhooks/) 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](https://komashi.com/product/usage-addons) 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:

  ```bash
  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ó](https://komashi.com/docs/hu/provider/Developers/api-integration/), az API-t és a webhookokat áttekintően a [Komashi fejlesztői oldala](https://komashi.com/developers) 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](https://komashi.com/docs/hu/provider/Developers/widget-integration/) 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

- [Komashi Docs — REST API-integráció](https://komashi.com/docs/hu/provider/Developers/api-integration/)
- [Komashi Docs — API-kulcsok](https://komashi.com/docs/hu/provider/Settings/10api/)
- [Komashi Docs — Webhookok](https://komashi.com/docs/hu/provider/Settings/11webhooks/)
- [Komashi Docs — Widgetek beágyazása](https://komashi.com/docs/hu/provider/Developers/widget-integration/)
- [Komashi Docs — Előfizetések](https://komashi.com/docs/hu/provider/subscriptions/)
- [Komashi Docs — Fejlesztői áttekintés](https://komashi.com/docs/hu/provider/Developers/who-is-a-developer/)