REST API Extended: létrehozás, módosítás és törlés

A REST API Extended kiegészítő a csak olvasható REST API mellé létrehozó, módosító és törlő végpontokat ad. Így külső alkalmazásból is kezelheted a partnereket, ajánlásokat, kifizetéseket, kreatívokat, látogatásokat és vásárlókat. A használatához az AffiliateWP-nek és a kiegészítőnek is aktívnak kell lennie.

Bekapcsolás

Nyisd meg az AffiliateWP → Beállítások → REST API fület. Itt végpont-csoportonként külön négyzet tartozik minden művelethez:

https://minta-bolt.hu/wp-admin/admin.php?page=affiliate-wp-settings&tab=rest_api

A fül csoportjai: partnerek, Kreatívok végpontjai, Vásárlók végpontjai, Kifizetések végpontjai, Ajánlások végpontjai és Látogatások végpontjai. Mindegyikben négy sor van:

Beállítás	Mit csinál	Alapérték
Olvasás	A GET módszer. Az AffiliateWP alapból bekapcsolja, nem kapcsolható ki	Bekapcsolva
Létrehozás	Engedélyezi a POST módszert	Kikapcsolva
Szerkesztés/frissítés	Engedélyezi a POST, PUT és PATCH módszert	Kikapcsolva
Törlés	Engedélyezi a DELETE módszert	Kikapcsolva

Jelöld be, amelyik műveletre szükséged van, majd kattints a Módosítások mentése gombra. Minden sor alatt egy példakérés is látszik a saját oldalad címével.

A kérések hitelesítése ugyanaz, mint az olvasási végpontoknál: API-kulcsokkal (AffiliateWP → Eszközök → API-kulcsok).

Közös szabályok

• Minden útvonalnak két alakja van: a lista (/wp-json/affwp/v1/<útvonal>) és az egy elem (/wp-json/affwp/v1/<útvonal>/<ID>).
• Lista GET kérésre listát ad, POST vagy PUT kérésre új elemet hoz létre.
• Az egy elem végpontja GET kérésre lekérdez, PATCH (vagy POST) kérésre módosít, DELETE kérésre töröl.
• Az OPTIONS kérés megmutatja az elérhető módszereket, a paramétereket (kötelező-e, típus, leírás) és az elem szerkezetét. Ez a legkönnyebb módja annak, hogy kiderítsd, mit fogad egy végpont.
• A paramétereket a kérés címében (lekérdezési sztringként) add meg.
• Sikeres létrehozás és módosítás esetén a válasz állapotkódja 201. Sikeres törlésnél 200, és a válaszban "deleted": true szerepel, mellette a törölt elem előző adataival (previous).

Partnerek

Létrehozás: POST vagy PUT a /wp-json/affwp/v1/affiliates címre.

Paraméter	Jelentés
user_id	A partnerhez tartozó WordPress-felhasználó azonosítója (minden partner egy felhasználóhoz kötődik)
username	Nem kötelező. Új felhasználó létrehozásakor a bejelentkezési név. Ha üres, a fizetési e-mail-címből készül
create_user	Logikai érték: új felhasználót is létrehoz a user_id helyett. Egyedi payment_email kell hozzá
rate	A partner jutaléka. Ha nincs megadva, az általános alapérték érvényes
rate_type	percentage (százalékos) vagy flat (fix összeg). Ha nincs megadva, az általános alapérték érvényes
payment_email	A kifizetés e-mail-címe. Ha üres, a felhasználó e-mail-címe számít. create_user esetén kötelező
status	active, inactive, pending vagy rejected (alapérték: pending)
notes	Megjegyzések

Példa felhasználó-azonosítóval (a partner az 5-ös azonosítójú felhasználóhoz tartozik, jutaléka 25 százalék):

POST /wp-json/affwp/v1/affiliates/?user_id=5&rate=25&rate_type=percentage

Példa új felhasználóval együtt:

POST /wp-json/affwp/v1/affiliates/?create_user=1&[email protected]

Módosítás: POST vagy PATCH a /affiliates/<ID> címre. Elfogadott paraméterek: account_email, payment_email, rate, rate_type, status, notes. Példa, a partner állapota aktívra:

PATCH /wp-json/affwp/v1/affiliates/31?status=active

Törlés: DELETE a /affiliates/<ID> címre, további paraméter nélkül.

Kreatívok

Létrehozás: POST vagy PUT a /wp-json/affwp/v1/creatives címre.

Paraméter	Jelentés
name	A kreatív neve
description	Leírás
url	A cím, ahova a kreatív mutat
text	A kreatívval megjelenő szöveg
image	A kreatív képe (a médiatár képének azonosítója)
status	active vagy inactive (alapérték: active)

Példa:

POST /wp-json/affwp/v1/creatives/?name=Új+kreatív&text=REST

Módosítás: POST vagy PATCH a /creatives/<ID> címre, ugyanezekkel a paraméterekkel. Példa: PATCH /wp-json/affwp/v1/creatives/20?status=inactive. Törlés: DELETE a /creatives/<ID> címre.

Kifizetések

Létrehozás: POST vagy PUT a /wp-json/affwp/v1/payouts címre.

Paraméter	Jelentés
affiliate_id	A partner azonosítója (kötelező)
referrals	A kifizetésbe tartozó ajánlások azonosítói, tömbként vagy vesszővel elválasztva
amount	A kifizetés összege (általában az ajánlások összegéből adódik)
payout_method	A kifizetés módja
status	paid vagy failed (alapérték: paid)

Példa: a 30-as partner 10-es, 15-ös és 20-as ajánlásának kifizetése:

POST /wp-json/affwp/v1/payouts/?affiliate_id=30&referrals=10,15,20

Módosítás: POST vagy PATCH a /payouts/<ID> címre, ugyanezekkel a paraméterekkel, például PATCH /wp-json/affwp/v1/payouts/15?status=paid. Törlés: DELETE a /payouts/<ID> címre.

Ajánlások

Létrehozás: POST vagy PUT a /wp-json/affwp/v1/referrals címre.

Paraméter	Jelentés
affiliate_id	A partner azonosítója. Ha hiányzik, a user_id vagy a user_name alapján keresi meg a partnert
user_id	A partnerhez tartozó felhasználó azonosítója
user_name	A partnerhez tartozó felhasználónév
amount	A végleges, kiszámolt ajánlási jutalék összege (nem a rendelés összege)
currency	Az összeg pénzneme
description	Leírás
reference	Hivatkozás, általában termékazonosítók
context	A keletkezés környezete, általában az integráció azonosítója
status	paid, unpaid, pending vagy rejected (alapérték: pending)

Példa: új, függő ajánlás a 30-as partnernek, 15 összeggel:

POST /wp-json/affwp/v1/referrals/?affiliate_id=30&amount=15

Módosítás: POST vagy PATCH a /referrals/<ID> címre. Elfogadott paraméterek: affiliate_id, visit_id, amount, currency, description, reference, context, status. Példa: PATCH /wp-json/affwp/v1/referrals/450?status=paid. Törlés: DELETE a /referrals/<ID> címre.

Látogatások

Létrehozás: POST vagy PUT a /wp-json/affwp/v1/visits címre.

Paraméter	Jelentés
affiliate_id	A partner azonosítója (kötelező)
referral_id	A látogatáshoz tartozó ajánlás azonosítója
url	A meglátogatott cím
referrer	A hivatkozó cím
campaign	A kampány
ip	A látogató IP-címe

Példa:

POST /wp-json/affwp/v1/visits/?affiliate_id=30&url=https%3A%2F%2Fpelda.hu

Módosítás: POST vagy PATCH a /visits/<ID> címre, a fenti paraméterekkel (a visit_id kötelező). Példa: PATCH /wp-json/affwp/v1/visits/541?campaign=tavaszi-akcio. Törlés: DELETE a /visits/<ID> címre.

Vásárlók

A Vásárlók végpontjai csoport ugyanígy működik a /wp-json/affwp/v1/customers útvonalon. A REST API fülön megjelenő példakérések: létrehozás customers/?affiliate_id=123, módosítás customers/1?affiliate_id=123, olvasás és törlés customers/1.

Példa: két WordPress-oldal összekötése

Gyakori felhasználás, hogy az egyik WordPress-oldal (A) partnert vesz fel egy másik, AffiliateWP-t futtató oldalon (B). A kérést a WordPress HTTP API-jával küldheted.

Hitelesítés a kódban

A fejléc értéke a „Basic ” szó és a nyilvános_kulcs:token párosnak a Base64-kódolt alakja:

$hitelesites = 'Basic ' . base64_encode( "{$public_key}:{$token}" );

A wp_remote_* függvényeknek így add át:

wp_remote_post( $keres_url, array(
    'headers' => array(
        'Authorization' => $hitelesites,
    ),
) );

Partner létrehozása

Ha már van érvényes felhasználóazonosítód:

$keres_url = add_query_arg( array( 'user_id' => 5 ), 'https://pelda.hu/wp-json/affwp/v1/affiliates' );

$valasz = wp_remote_post( $keres_url, array(
    'headers' => array( 'Authorization' => $hitelesites ),
) );

A paramétert a címben adtuk át, nem a kérés törzsében, hogy a PUT és PATCH módszerű példákkal egységes maradjon (azok nem fogadnak paramétert a törzsben). Ha nincs felhasználód, a create_user és a payment_email paraméterrel egy lépésben hozhatod létre mindkettőt.

Kifizetés létrehozása

A kifizetéshez kötelező az affiliate_id és a referrals:

$keres_url = add_query_arg( array(
    'affiliate_id'  => 2,
    'referrals'     => '2,3,4',
    'payout_method' => 'REST',
), 'https://pelda.hu/wp-json/affwp/v1/payouts' );

$valasz = wp_remote_post( $keres_url, array(
    'headers' => array( 'Authorization' => $hitelesites ),
) );

A payout_method nem kötelező, de jól mutatja, hogy a kifizetés REST-en át készült.

Ajánlás módosítása

Módosításkor az elem azonosítója a végpont címében van, ezért a paraméterek között nem kell megadnod. A PATCH módszerhez a wp_remote_request() függvény kell:

$keres_url = add_query_arg( array( 'status' => 'paid' ), 'https://pelda.hu/wp-json/affwp/v1/referrals/3' );

$valasz = wp_remote_request( $keres_url, array(
    'method'  => 'PATCH',
    'headers' => array( 'Authorization' => $hitelesites ),
) );

A válasz ellenőrzése

A legegyszerűbb a válasz állapotkódját nézni: létrehozásnál és módosításnál sikeres kérésre 201, törlésnél 200 jön.

if ( 201 === wp_remote_retrieve_response_code( $valasz ) ) {
    $torzs = wp_remote_retrieve_body( $valasz );
    // a válasz feldolgozása
} else {
    // hibaüzenet megjelenítése
}

Gyakori kérdések

• Mire való a REST API Extended? A csak olvasható végpontokat egészíti ki létrehozó, módosító és törlő műveletekkel partnerekhez, ajánlásokhoz, kifizetésekhez, kreatívokhoz és látogatásokhoz.
• Hogyan hitelesítsem a kéréseket? Az AffiliateWP → Eszközök → API-kulcsok fülön létrehozott nyilvános kulccsal és tokennel, alapszintű azonosítással.