# API-hívások

> A licencszerver végpontjai: aktiválás, deaktiválás, állapot, frissítés és a kérések paraméterei.

Saját kliens (mobilalkalmazás, SaaS, asztali program) készítéséhez vagy a PHP-könyvtár nélküli integrációhoz ez a fejezet írja le a kérések felépítését. A WordPress-bővítmények és -sablonok a [PHP-könyvtárral](https://hub.hellowp.io/hu/plugins/woocommerce-api-manager/php-konyvtar/) egyszerűbben bekötik magukat.

Az API eredetileg WordPress-bővítmények és -sablonok licencelésére készült, ezért a `plugin_name` és `slug` paraméterek erre utalnak. Más szoftvernél tetszőleges, de azonos formátumú értékeket küldhetsz, a szerver így is visszaadja a letöltési URL-t és a verzióadatokat.

## Kérés felépítése

A kliens HTTP(S) kérést küld a bolt gyökér URL-jére, POST vagy GET módszerrel, kulcs és érték párokat tartalmazó lekérdezési karakterlánccal. A végpont mindig `wc-api=wc-am-api`, az akciót a `wc_am_action` paraméter adja meg:

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=activate
```

A további paramétereket `&` jellel fűzd hozzá. Ügyelj rá, hogy a gyökér URL és a `?` között ne legyen dupla perjel.

### Paraméterek

| Paraméter | Jelentése |
|---|---|
| `instance` | Egyedi, alfanumerikus karakterlánc, amely nem ismétlődik. Az aktiváló eszköz hozza létre. |
| `product_id` | A licencelt termék azonosítója (pozitív egész). Variálható terméknél a szülő vagy egy variáció azonosítója is jó. |
| `api_key` | A licenckulcs: felhasználói vagy termékkulcs. |
| `plugin_name` | WordPress-bővítménynél a bővítménymappa neve, perjel, a főfájl neve (például `minta-bovitmeny/minta-bovitmeny`, a `.php` végződés elhagyható). Sablonnál a sablon mappájának neve, perjel, ugyanaz a név. Más szoftvernél hasonló formátumú érték. |
| `version` | A szoftver verziója. Frissítéskérésnél használatos. |
| `object` | Az aktiválás helye: szerver, telefon vagy bármi, ami HTTP(S)-kérést tud küldeni. |
| `slug` | A bővítmény vagy sablon mappájának neve kisbetűkkel (például `minta-bovitmeny`). |

WordPress-bővítménynél és -sablonnál a kérés fajtájától függően kell a `plugin_name` és a `slug`. Nem WordPress-szoftver kitalált értékeket is küldhet, úgy formázva, mintha WordPress-szoftver lenne.

Ajánlott gyakorlat: a `product_id`-t mindig fixen, a kódban add át a kérésekben. Ez elkerüli az aktiválási hibákat. Variálható terméknél a szülő azonosítójával a vevő szintet válthat anélkül, hogy új fájlt kellene letöltenie vagy kulcsot cserélnie.

### Az instance azonosító

Az instance egy egyedi kód, amelyet a szoftver vagy az eszköz hoz létre, amikor először aktivál egy kulcsot. Jelszóként viselkedik: egyedi, titkos, és az adott aktiváláshoz tartozik. Az aktiválás összes további kérésében ugyanezt kell küldeni, a deaktiválásig.

- Minden aktiváláshoz új, egyedi instance kell.
- Deaktiváláskor törölheted, vagy elmentheted egy későbbi újraaktiváláshoz.
- Ha új azonosítóval aktiválsz újra, az új aktiválásnak számít.
- A létrehozás módja rád van bízva. A PHP-könyvtár a WordPress jelszógenerátorát használja.

### Aktiválás korlátozása IP-címre

Az API-hozzáférést megbízható IP-címekre korlátozhatod a `WC_AM_TRUSTED_SOURCES` állandóval. Ez akkor hasznos, ha egy távoli szolgáltatás (például tagsági rendszer) hív be a boltba licencellenőrzésre vagy frissítésre.

1. Add hozzá a `wp-config.php` fájlhoz:

   ```php
   define( 'WC_AM_TRUSTED_SOURCES', array( '192.168.1.1', '2001:0db8:85a3::8a2e:0370:7334' ) );
   ```

2. Minden kérésben küldj egy `ip_address` paramétert a szerver IP-címével.
3. A rendszer két dolgot ellenőriz: a lekérdezésben küldött `ip_address` és a kérést ténylegesen küldő IP-cím is szerepel-e a megbízható listában. Mindkettőnek egyeznie kell.

Terheléselosztó vagy proxy mögött gondoskodj arról, hogy a megbízható listában szereplő IP-cím jusson át.

## Akciók

A `wc_am_action` lehetséges értékei:

| Érték | Mire való |
|---|---|
| `activate` | Licenckulcs aktiválása. |
| `deactivate` | Aktiválás törlése. |
| `status` | Egy aktiválás állapotának lekérdezése. |
| `product_list` | A kulcshoz tartozó termékek listája. |
| `verify_api_key_is_active` | Annak ellenőrzése, hogy a kulcs aktív erőforráshoz tartozik. |
| `information` | Termékinformáció (a bővítményinformációs ablakhoz). |
| `update` | Frissítésellenőrzés, és letöltési URL. |
| `plugininformation`, `pluginupdatecheck` | Elavult, csak régi kliensekhez, sorosított válasszal. |

A válasz formátuma JSON, kivéve az elavult két akciót.

### activate

Aktiválja a licenckulcsot, így hozzáférhetővé válik az API-erőforrás.

- Kötelező: `api_key`, `product_id`, `instance`.
- Opcionális: `object`, `version` (az aktiválás mellé mentődnek).

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=activate&instance=p1uOusaNM5ub3&object=minta-oldal.example.com&product_id=16&version=1.0.0&api_key=A_TE_KULCSOD
```

Ha az `object` URL, hagyd el a `http://` vagy `https://` előtagot, mert egyes szerver-biztonsági beállítások elrontják az egész lekérdezést.

Sikeres válasz (üzenet a bolt nyelvén):

```json
{
  "activated": true,
  "message": "Hátralévő aktiválások: 2 / 3",
  "success": true,
  "data": {
    "unlimited_activations": false,
    "total_activations_purchased": 3,
    "total_activations": 1,
    "activations_remaining": 2
  },
  "api_call_execution_time": "0.036061 seconds"
}
```

Hibás válasz esetén `success: false`, egy `code` és egy `error` üzenet érkezik, például ha ugyanazzal az instance-szal már aktiválták a kulcsot.

### deactivate

Törli az aktiválást, így a hely felszabadul.

- Kötelező: `api_key`, `product_id`, `instance`.

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=deactivate&instance=p1uOusaNM5ub3&product_id=16&api_key=A_TE_KULCSOD
```

Sikeres válaszban `deactivated: true` és a hátralévő aktiválások száma szerepel.

### status

Az aktiválás állapotát adja vissza: az összes vásárolt aktiválást, a felhasználtakat, a hátralévőket, és hogy az adott kulcs aktivált-e.

- Kötelező: `api_key`, `product_id`, `instance`.
- Opcionális: `version` (a kérés beérkezésekor frissül).

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=status&instance=p1uOusaNM5ub3&product_id=16&api_key=A_TE_KULCSOD
```

Ha a `status_check` értéke `active`, vagy az `activated` értéke `true`, a licenc nem járt le és aktív (előfizetésnél az előfizetés is aktív). A szerver a válasz előtt ellenőrzi, hogy az aktiválásnak még léteznie kell-e, és törli, ha lejárt az időkorlát vagy inaktív az előfizetés. A válasz a `api_key_expirations` mezőben a lejáró aktiválások adatait is tartalmazza.

Ha nincs hozzá erőforrás, a hibaüzenet: **No API resources exist.**

### product_list

Egyedi, rendezett listát ad a kulcshoz tartozó termékekről (azonosító, cím, rendelés azonosítója, előfizetésnél az előfizetés azonosítója).

- Kötelező: `api_key`, `instance`. Az instance itt csak a válasz egyórás gyorsítótárazásához kell, nem jelent aktiválást.

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=product_list&api_key=A_TE_KULCSOD&instance=p1uOusaNM5ub3
```

### verify_api_key_is_active

Sikert ad vissza, ha a kulcs létezik és aktív erőforráshoz van rendelve.

- Kötelező: `api_key`.

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=verify_api_key_is_active&api_key=A_TE_KULCSOD
```

### information

Termékinformáció (név, verzió, szerző, honlap, követelmények, változásnapló). A visszaadott adatok attól függnek, hogy a kérés hitelesített-e.

- Hitelesített kérés kötelező paraméterei: `api_key`, `product_id`, `plugin_name`, `instance`, `version`.
- Hitelesítés nélkül: `product_id`, `plugin_name`.

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=information&instance=p1uOusaNM5ub3&product_id=16&version=1.0.0&api_key=A_TE_KULCSOD&plugin_name=minta-bovitmeny/minta-bovitmeny.php
```

### update

Megmondja, érhető-e el frissítés. Hitelesített kérésnél (instance-szal) a letöltési fájl URL-jét is visszaadja a `package` mezőben.

- Hitelesített kérés kötelező paraméterei: `api_key`, `product_id`, `plugin_name`, `instance`, `version`.
- Opcionális, de ajánlott: `slug`.
- Hitelesítés nélkül: `product_id`, `plugin_name`. Ilyenkor a `package` üres.

```text
https://pelda.hu/?wc-api=wc-am-api&wc_am_action=update&instance=p1uOusaNM5ub3&product_id=16&version=1.0.0&api_key=A_TE_KULCSOD&plugin_name=minta-bovitmeny/minta-bovitmeny.php&slug=minta-bovitmeny
```

### plugininformation és pluginupdatecheck

Az `information` és az `update` megfelelői, de sorosított (serialized) választ adnak. Csak a 2.0 előtti PHP-könyvtárat használó régi kliensekhez kellenek, újonnan ne használd őket.

## Hibaválaszok

Hiba esetén a válasz `success: false`, és tartalmaz egy `code` (például `100`) és egy `error` mezőt, valamint a `data` alatt ugyanezt. Például ha a termékazonosító nem létezik, az üzenet jelzi, hogy a termék nem található a boltban.

## Terhelhetőség

A `status` akciót egy mérés során 500 kéréssel terhelték, HTTPS-kapcsolaton, gyorsítótár nélkül, nagy ügyféladatbázisú éles szerveren (2 magos processzor, 2 GB memória, Nginx és PHP-FPM). Három változatot próbáltak:

| Egyidejű kérések | Teljes idő | Átlag kérésenként | Kérés másodpercenként | Sikertelen kérés |
|---|---|---|---|---|
| 1 | kb. 38 mp | kb. 77 ms | kb. 13 | 0 |
| 10 | kb. 20 mp | kb. 39 ms | kb. 25 | 0 |
| 100 | kb. 19 mp | kb. 38 ms | kb. 26 | 0 |

A mérés alapján a szerver nagyobb terhelésnél gyorsabb kérésenkénti átlagot ad, és a kisebb boltoktól a nagyokig elbírja a terhelést. A mért idő nagy részét a HTTPS-titkosítás adja, gyorsítótárral a válaszok még gyorsabbak lehetnek.

## Tesztelés

A kérések tesztelésére a Postman ajánlott. Az API Manager mellé tartozik egy előre elkészített Postman-gyűjtemény (.json), amelyben a szerver URL-jét, a kulcsokat és az értékeket a saját termékedhez és szerveredhez kell igazítani.

A teszteléshez rendelésből kapsz licenckulcsot: hozz létre egy rendelést a licencelt termékre (**Teljesítve** állapottal), és a licencet a rendelésen vagy az **API Manager → Licencek** listában találod.