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

> API-kulcsok létrehozása, hitelesítés és az öt csak olvasható végpont (partnerek, kreatívok, kifizetések, ajánlások, látogatások) paraméterei.

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](https://hub.hellowp.io/hu/plugins/affiliate-wp/fejlesztoknek-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.

![Az API-kulcsok fül az Eszközök oldalon](./kepek/fejlesztoknek-api-kulcsok.webp)

*Az API-kulcsok fül az Eszközök oldalon* (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:

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

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

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