Hogyan integráld a Komashit a weboldaladba?

A Komashi kétféleképpen illeszthető a saját felületedbe: egy beágyazható widgettel vagy a REST API-n keresztül. A widget néhány sor kóddal fut, az API teljes kontrollt ad. Ez az útmutató végigveszi, melyik mikor jobb, és hogyan indulj el.

---

Ha már van egy futó weboldalad vagy webalkalmazásod, a Komashi kétféle módon illeszthető bele: egy beágyazható widgettel vagy a REST API-n keresztül. A két megközelítés más fejlesztői tudást és eltérő mértékű munkát igényel, de mindkettő ugyanazt a célt szolgálja: az előfizetési és vásárlási folyamat megjelenítését a saját felületeden belül.

Ez az útmutató bemutatja, mikor melyik opciót érdemes választani, mit kell tudni mindkettőről, és hogyan indulhatsz el néhány lépésben.

Miért érdemes beágyazni, ahelyett hogy átirányítanád?

A Komashi alapból tartalmaz egy white-label storefrontot, amelyre a végfelhasználókat egyszerűen átirányíthatod. Ez sok esetben teljesen elegendő — külön fejlesztés nélkül is működőképes vásárlási élményt ad.

Mégis van két helyzet, amikor a közvetlen integráció valódi értéket hoz:

Egységes ügyfélélmény. Egy átirányítás megszakítja a vásárlási folyamatot és kilép a saját brandedből. Ha azt szeretnéd, hogy a felhasználó végig a te felületeden maradjon — különösen, ha prémium ügyfélélménnyel dolgozol —, a widget vagy az API az út.

Saját rendszer összekötése. Ha meglévő ügyfélportálhoz, belső dashboardhoz vagy egyedi üzleti logikához kell csatlakoztatni a Komashit, az API-integráció ad valódi kontrollt. Webhookokkal kombinálva valós idejű szinkronizációt is megvalósíthatsz.

Két megközelítés: widget és API

Widget: gyors beágyazás, minimális fejlesztéssel

A Komashi widget egy előre megépített UI-komponens. Beillesztése egyetlen script tag elhelyezéséből áll — nincs szükség saját frontend megépítésére, és backend módosítást sem igényel.

A widget automatikusan kezeli:

• a szolgáltatáslista megjelenítését,
• az előfizetési folyamatot,
• a reszponzív elrendezést mobil és asztali nézetben egyaránt,
• a Komashi API-val való kommunikációt.

Konfiguráció: a widget viselkedése néhány data- attribútummal testre szabható.

Attribútum	Kötelező	Leírás
data-key	Igen	Az API-kulcsod
data-mode	Igen	marketplace, provider vagy service
data-provider-id	Nem	Adott providerre szűkít
data-theme	Nem	light vagy dark (alapértelmezett: light)
data-lang	Nem	Nyelvkód, pl. hu vagy en

Mikor válaszd? Ha gyorsan, minimális fejlesztési erőforrással szeretnéd megjeleníteni az előfizetési lehetőségeket. A widget arra van kialakítva, hogy néhány percen belül üzemelő állapotba lehessen hozni — különösen hasznos, ha nincs dedikált fejlesztői csapatod, de mégis integrált élményt szeretnél adni az ügyfeleidnek.

Amire szükséged lesz:

• érvényes Komashi API-kulcs
• script taget betölteni képes weboldal
• backend oldali változtatás nem szükséges

API: teljes kontroll, saját frontend

A Komashi REST API-n keresztül programozottan kérdezheted le és módosíthatod a platform adatait. Minden kérést egy Bearer token azonosít, amelyet az Authorization fejlécben kell megadni.

Az API legfontosabb endpointjai:

Metódus	Endpoint	Leírás
GET	/providers	Providerek listája
GET	/providers/{id}/services	Egy provider szolgáltatásai
GET	/customers	Ügyfelek lekérdezése
POST	/customers	Új ügyfél létrehozása
GET	/subscriptions	Aktív előfizetések
GET	/invoices	Számlázási előzmények

A válaszok JSON formátumban érkeznek. Sikeres kérésnél data mező, hiba esetén error mező és HTTP státuszkód érkezik. Rate limit túllépésnél 429-es választ kapsz — ilyenkor exponenciális visszalépéssel érdemes újrapróbálkozni.

Mikor válaszd? Ha saját UI-t építesz, meglévő ügyfélrendszerbe integrálsz, vagy olyan egyedi logikát valósítasz meg, amit a widget önmagában nem fed le. Az API-t érdemes választani akkor is, ha CRM-hez vagy belső riportinghoz kell a Komashi adatokat szinkronizálni.

Amire szükséged lesz:

• Komashi API-kulcs a megfelelő jogosultságokkal
• backend vagy frontend kliens az API hívások kezeléséhez
• hibakezelési és rate limit logika

Hogyan működik ez a Komashi szemszögéből?

Mindkét integráció API-kulcson alapul. A kulcsot a Komashi admin dashboardon lehet generálni a Beállítások → API szekciójában.

Kulcs létrehozásakor meg kell adni a nevet és a hozzárendelt jogosultságokat: olvasás, létrehozás, szerkesztés, törlés. A legkisebb szükséges jogosultság elvét érdemes követni: ha az integráció csak adatot olvas, törlési jogot ne kapjon. Ez csökkenti a kockázatot abban az esetben, ha a kulcs illetéktelen kézbe kerül.

Fontos: az API-kulcs értéke csak egyszer jelenik meg a generálás után. Azonnal mentsd el biztonságos helyre — a rendszer többet nem mutatja meg.

Tipikus hibák, amikre figyelj

Widget esetén:

• Hiányzó data-mode attribútum: a widget nem jelenik meg megfelelően, ha a megjelenítési mód nincs megadva.
• Érvénytelen API-kulcs: a widget csendben nem tölt be, hibára nem feltétlenül figyelmeztet.
• HTTP környezet: a widget HTTPS kapcsolatot vár. HTTP-n kiszolgált oldalon nem fog megfelelően működni.

API esetén:

• Túl széles jogosultságok: Create + Delete jog egy olvasó integrációhoz szükségtelen kockázat.
• Nem kezelt 429-es válasz: burst forgalomnál rate limit hibák jelenhetnek meg. Tervezz be újrapróbálkozási logikát.
• Feltételezett válaszstruktúra: ne feltételezd, hogy minden válasz data mezővel érkezik — mindig vizsgáld meg az error mezőt is.

Lépésről lépésre

1. Generálj API-kulcsot a Komashi dashboardban (Beállítások → API → Új API-kulcs).
2. Add meg a szükséges jogosultságokat — csak annyit, amennyit az integráció tényleg igényel.
3. Döntsd el, hogy widget vagy direkt API-integráció illik a projektedhez.
4. Widget esetén: illeszd be a script taget, add meg a data-key és data-mode attribútumokat, és teszteld a böngészőben.
5. API esetén: kezdd a /providers endpointtal, nézd meg a visszakapott JSON struktúrát, és épülj rá a saját UI-d.
6. Tesztelj sandbox környezetben mielőtt élesbe állsz.
7. Monitorozd az API hívásokat és a widget betöltési hibákat az első éles deploymentet követően.

Összefoglaló

	Widget	API
Fejlesztési idő	Alacsony	Magasabb
Saját UI szükséges	Nem	Igen
Backend szükséges	Nem	Általában igen
Rugalmasság	Korlátozott	Teljes
Legjobb, ha...	Gyors beágyazás kell	Egyedi logika vagy rendszerintegráció kell

A Komashi mindkét esetben kezeli a fizetési folyamatot, az előfizetési logikát és a számlázást — neked csak az adatok megjelenítéséről vagy a saját rendszered összekötéséről kell gondoskodnod.

A részletes technikai leírást, az elérhető konfigurációs opciókat és a teljes endpoint dokumentációt ebben a cikkben találod.