API-hívások

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

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:

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

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

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

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

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.

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.

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.

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.

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.