REST API-integráció

A REST API-val a saját szerveroldali alkalmazásodat kapcsolhatod a Komashihoz. Lekérdezheted a katalógust, kezelheted az ügyfeleket és kapcsolattartóikat, elindíthatod az előfizetések fizetési folyamatát, rögzítheted a felhasználást és lekérdezheted a számlákat.

A végpont és a referencia megkeresése

Nyisd meg a Vezérlőközpont → Integráció → API oldalt. Itt találod a Dokumentáció hivatkozását és az API-végpontot. Az ott megjelenített végpontot másold ki; az már tartalmazza a verzió előtagját.

A nyilvános szolgáltatás verziózott végpontja:

https://api.komashi.com/v1

A helyi fejlesztői környezet címe ettől eltérhet, például https://komashi-app.test/api/v1. Mindig a saját környezetedben megjelenített értéket használd; ne találgatással egészítsd ki /api vagy /v1 útvonallal.

A Dokumentáció az interaktív OpenAPI-referenciát nyitja meg. Az egyes műveletek pontos mezőit, válaszsémáit és ellenőrzési szabályait ott találod.

Az első hitelesített kérés

Hozz létre egy szolgáltatói kulcsot az Integráció → API oldalon. Az Authorization fejlécben add át, és JSON-választ kérj:

export KOMASHI_API_BASE='https://api.komashi.com/v1'
export KOMASHI_API_KEY='YOUR_PROVIDER_API_KEY'

curl "$KOMASHI_API_BASE/services" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'

A valódi kulcsot szerveroldali környezeti változóban vagy titokkezelőben tárold. A kulcs azonosítja a szolgáltatót, ezért a szokásos szolgáltatói kulcsos kéréshez nem kell külön szolgáltatóazonosító-fejléc.

A kulcsnak rendelkeznie kell az adott művelet jogosultságával. Az első lekérdezéshez az Olvasás elegendő. Előfizetési fizetési folyamat létrehozásához Létrehozás, felhasználás frissítéséhez és előfizetés lemondásához Frissítés szükséges. A jogosultságot nem lehet kizárólag a HTTP-metódusból megállapítani.

JSON-válaszok kezelése

A válaszok közös mezői:

{
  "succeeded": true,
  "status_code": 200,
  "data": []
}

A data tartalmazza az eredményt: ez a művelettől függően lehet egy erőforrás, lista, fizetési eredményobjektum vagy null. További mezők, például message, validációs errors, links és meta is megjelenhetnek. Egyes végpontok error vagy code mezőt is visszaadnak; ne feltételezz egyetlen, minden hibára azonos sémát.

A belsőleg 204 No Content eredményt adó sikeres műveletek HTTP 200 válaszként érkeznek, data: null értékkel. Törlés után ezért ne kizárólag a 204-es státuszt tekintsd sikeresnek.

Lapozás

A lapozható listák page és per_page paramétert fogadnak. Az alapértelmezett oldalméret 25, a legnagyobb 100. Ha van links és meta, ezeket is dolgozd fel a folytatáshoz.

curl "$KOMASHI_API_BASE/customers?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'

A katalógus feltérképezése

Az alábbi útvonalak a verziózott API-végponthoz relatívak.

Kérés	Feladat
GET /services	Szolgáltatások listázása.
GET /services/{service}	Egy szolgáltatás lekérdezése.
GET /services/{service}/plans	A szolgáltatás csomagjai.
GET /services/{service}/plans/{plan_id}/periods	Egy csomag időszakai.
GET /services/{service}/addons	A szolgáltatás kiegészítői.
GET /services/{service}/addons/{addon_id}/options	Egy kiegészítő opciói.
GET /services/{service}/service-prices/discounts	Elérhető kedvezmények lekérdezése.

Először a szolgáltatást, majd a csomagokat, időszakokat, kiegészítőket és opciókat kérdezd le. A válaszokban kapott azonosítókkal dolgozz. A katalógust és a kuponkedvezményeket a Vezérlőközpontban állítsd be; nem minden katalóguselemhez tartozik nyilvános REST írási végpont.

Ügyfelek és előfizetések összekapcsolása

Az ügyfelek listázása, megtekintése, létrehozása, módosítása és törlése a /customers útvonalakon érhető el. A kapcsolattartók műveletei a /customers/{customer_id}/contacts alatt találhatók.

Új ügyfélhez szükséges többek között a billing_name, billing_address, billing_zip, billing_city és billing_country. Egyes országoknál a régió/állam megadása is kötelező. A szolgáltató által kötelezővé tett saját ügyfélmezők szintén érvényesek. A kérés összeállítása előtt nézd meg az OpenAPI-referenciát.

Előfizetési fizetési folyamat létrehozásához küldj POST /services/{service}/subscriptions kérést. Az alábbi szemléltető törzsben az azonosítókat valódi, a szolgáltatódhoz tartozó értékekre kell cserélni:

{
  "customer_id": "CUSTOMER_UUID",
  "plan_id": "PLAN_UUID",
  "period_id": "PERIOD_UUID",
  "quantity": 1,
  "external_reference": "your-internal-order-reference",
  "return_url": "https://your-app.example/subscription/return",
  "cancel_url": "https://your-app.example/subscription/cancel"
}

A JSON-t Content-Type: application/json fejléccel küldd. A válasz data mezőjében találod a checkout_url, subscription_id, group_id és a létrehozott előfizetési tételek értékeit. A vásárlót a checkout_url címre irányítsd. A visszatérési URL önmagában nem igazol sikeres fizetést; fizetett hozzáférés megadásához ellenőrizd az előfizetés aktuális állapotát.

Kérés	Feladat
GET /services/{service}/subscriptions	Egy szolgáltatás előfizetései.
GET /subscriptions/{subscription_id}	Egy előfizetés adatai.
GET /subscriptions/groups/{group_id}	Egy előfizetési csoport adatai.
POST /subscriptions/{subscription_id}/payment-link	Fizetési link készítése, ha az adott előfizetésnél elérhető.
POST /subscriptions/{subscription_id}/change-plan	Csomagváltás kezdeményezése a célkonfigurációval.
PATCH /subscriptions/{subscription_id}/dates	A támogatott életciklusdátumok módosítása.
PATCH /subscriptions/{subscription_id}/status	Állapot és opcionális megújítási beállítás módosítása.
DELETE /subscriptions/{subscription_id}/cancel	Előfizetés vagy függő csomagváltás lemondása.
GET /invoices és GET /invoices/{invoice_id}	Számlaadatok lekérdezése.

A lemondás a szolgáltató lemondási szabályait követi. A csoportazonosító nem helyettesíti a művelethez szükséges egyedi előfizetés-azonosítót. A csomagváltás és a fizetési link saját üzleti feltételekhez kötött; a referenciát és a visszaadott hibát is ellenőrizd.

Felhasználás rögzítése

A GET /subscriptions/{subscription_id}/usage lekérdezéssel ellenőrizheted a felhasználási keretet. A csoporthoz tartozó összesítés a GET /subscriptions/groups/{group_id}/usage címen érhető el.

A POST /subscriptions/{subscription_id}/sync-usage kérésben az új abszolút összesített értéket add meg:

{ "usage": 125 }

A POST /subscriptions/{subscription_id}/adjust-usage művelettel növelést vagy csökkentést kérhetsz:

{ "action": "increase", "value": 1 }

Az action értéke increase vagy decrease lehet; a value elhagyásakor az érték 1. Az ismételten elküldött növelés ismét módosítja a fogyasztást. Hálózati időtúllépés után ne küldd el automatikusan ugyanazt az írási kérést: ha az eredmény bizonytalan, először kérdezd le az aktuális állapotot.

Hibák és kéréskorlát

Státusz	Mit ellenőrizz?
401	Hiányzó, érvénytelen vagy törölt kulcs.
403	Nem megfelelő tokentípus vagy hiányzó jogosultság.
404	Ismeretlen erőforrás vagy másik szolgáltatóhoz tartozó rekord.
409	Üzleti állapotütközés, például piszkozat vagy összeférhetetlen függő művelet.
422	Hibás mező, nem támogatott érték vagy üzleti validációs hiba.
429	Kéréskorlát; várj, majd növekvő késleltetéssel próbáld újra.
5xx	Szerveroldali hiba; az írás megismétlése előtt őrizd meg a kivizsgáláshoz szükséges adatokat.

A beállított REST-korlát percenként 100 kérés. Akkor is kezeld a 429 választ, ha a saját integrációd forgalma szerint még nem érte el a korlátot.

Kapcsolódó útmutatók: API-kulcsok, webhookok, MCP-integráció.