REST API: hitelesítés és olvasási végpontok

Az AffiliateWP a WordPress saját REST API-jára épülő, csak olvasható végpontokat ad az adataidhoz. Létrehozni, módosítani és törölni a REST API Extended kiegészítővel lehet.

Hitelesítés

Minden kérésnek hitelesítettnek kell lennie. A hitelesítés alapszintű (Basic) azonosítás, nyilvános kulccsal és tokennel. A kulcsok felhasználóhoz kötődnek.

1. Nyisd meg az AffiliateWP → Eszközök → API-kulcsok fület.
2. Írd be annak a felhasználónak a nevét, akihez a kulcsok tartozni fognak.
3. Kattints az Új API-kulcsok létrehozása gombra.

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

A táblázat a Felhasználónév, Nyilvános kulcs, Token és Titkos kulcs oszlopokat mutatja; a kulcsok a fenti gombbal készülnek.

A kulcshoz tartozó felhasználónak megfelelő jogosultság kell, ez általában a rendszergazdai szerepkört jelenti.

A kérésekben a hitelesítő fejléc a nyilvános kulcsot használja felhasználónévként, a tokent jelszóként. Curl-lel:

curl -u NYILVANOS_KULCS:TOKEN https://pelda.hu/wp-json/affwp/v1/affiliates

Az Authorization fejlécet minden kéréshez mellékelni kell. Ha hiányzik vagy hibás, a válasz 403-as állapotkódú hiba:

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": { "status": 403 }
}

A fő affwp/v1 végpont (a végpontok jegyzéke) kulcs nélkül is elérhető, minden más végponthoz kulcs kell.

Útvonalak

Öt útvonal van, mindegyikhez két olvasási végpont tartozik: a lista (/affwp/v1/<útvonal>) és az egy elemet adó (/affwp/v1/<útvonal>/<ID>). Az útvonalak: affiliates, creatives, payouts, referrals, visits. A végpontok jegyzékét az /wp-json/affwp/v1/ címen éred el, a megengedett paraméterek pedig egy OPTIONS kéréssel kérdezhetők le.

A válaszok JSON formátumúak. A listák az alábbi paramétereket fogadják.

Partnerek (affiliates)

Paraméter	Jelentés
number	Hány találatot adjon vissza
offset	Hány találatot hagyjon ki az elejéről (alapérték 0)
affiliate_id	Partnerazonosító vagy azonosítók tömbje
user_id	Felhasználóazonosító vagy azonosítók tömbje
exclude	Kizárandó partnerazonosító(k)
search	Keresőkifejezés: partnerazonosító vagy szöveg
status	active, inactive, pending vagy rejected
order	ASC vagy DESC
orderby	Rendezési mező (alapérték: date)
fields	A visszaadott mezők: ids vagy bármelyik oszlop (alapérték: összes)
user	true esetén minden partnerhez a felhasználói adatok is bekerülnek
meta	true esetén a partner metaadatai is bekerülnek

A user és a meta partnerenként külön adatbázis-lekérdezést okoz, ezért nagy listáknál lassíthat.

Példa válaszra:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "id": 2737
}

Az egy partnert adó végpont (affiliates/<ID>) a user és meta paramétert is elfogadja: ilyenkor a válaszban megjelenik a user objektum (azonosító, felhasználónév, megjelenített név, regisztráció ideje stb.), illetve a meta tömb.

Kreatívok (creatives)

Paraméter	Jelentés
number, offset	Mint a partnereknél
creative_id	Kreatívazonosító vagy azonosítók tömbje
status	active vagy inactive
order, orderby	Rendezés iránya és mezője
fields	A visszaadott mezők

Válaszmezők: creative_id, name, description, url, text, image, status, date, id.

Kifizetések (payouts)

Paraméter	Jelentés
number, offset	Mint a partnereknél
payout_id	Kifizetésazonosító(k)
affiliate_id	Partnerazonosító(k)
referrals	Ajánlásazonosító(k), amelyekhez a kifizetés tartozik
amount	Összeg, vagy minimum és maximum tartomány
amount_compare	Az összeg összehasonlító művelete: >, <, >=, <=, = vagy !=
status	paid vagy failed
date	Dátum vagy dátumtartomány
order, orderby, fields	Rendezés és a visszaadott mezők

Válaszmezők: payout_id, affiliate_id, referrals (vesszővel elválasztott azonosítók), amount, payout_method, status, date, owner, id.

Ajánlások (referrals)

Paraméter	Jelentés
number, offset	Mint a partnereknél
referral_id	Ajánlásazonosító(k)
affiliate_id	Partnerazonosító(k)
reference	Hivatkozás, például termékazonosító
ref_context	Az ajánlás keletkezésének környezete (integráció)
campaign	Kampány
status	paid, unpaid, pending vagy rejected (több is megadható)
search	Ajánlásazonosító vagy keresőszöveg
date	Dátum vagy dátumtartomány
order, orderby, fields	Rendezés és a visszaadott mezők

Válaszmezők: referral_id, affiliate_id, visit_id, description, status, amount, currency, custom, context, campaign, reference, products, date, payout_id, id.

Látogatások (visits)

Paraméter	Jelentés
number, offset	Mint a partnereknél
visit_id	Látogatásazonosító(k)
affiliate_id	Partnerazonosító(k)
referral_id	Ajánlásazonosító(k)
referral_status	Az ajánlás állapota(i)
campaign	Kampány
order	Alapértéke ASC
orderby, fields	Rendezési mező (alapérték: date) és a visszaadott mezők

Válaszmezők: visit_id, affiliate_id, referral_id, url, referrer, campaign, ip, date, id.