# REST API-integráció

> REST API-hitelesítés, katalóguslekérdezés, előfizetési fizetési folyamat, felhasználáskövetés és a Komashi API-válaszainak kezelése.

Canonical: https://komashi.com/docs/hu/provider/Developers/api-integration/
Language: hu

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.

[![Az API-kulcsok oldala a dokumentáció hivatkozásával és az API-végponttal](https://komashi.com/docs/assets/images/integrations-api-keys.png)](/assets/images/integrations-api-keys.png)

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

```text
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](https://komashi.com/docs/hu/provider/Settings/10api/index.md) oldalon. Az `Authorization` fejlécben add át, és JSON-választ kérj:

```bash
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:

```json
{
  "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.

```bash
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:

```json
{
  "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:

```json
{ "usage": 125 }
```

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

```json
{ "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](https://komashi.com/docs/hu/provider/Settings/10api/index.md), [webhookok](https://komashi.com/docs/hu/provider/Settings/11webhooks/index.md), [MCP-integráció](https://komashi.com/docs/hu/provider/Developers/mcp-integration/index.md).