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

> A REST API Extended kiegészítő bekapcsolása, a teljes CRUD-végpontok paraméterei és példák távoli kérésekre.

A REST API Extended kiegészítő a csak olvasható [REST API](https://hub.hellowp.io/hu/plugins/affiliate-wp/fejlesztoknek-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:

![A REST API fül beállításai](./kepek/fejlesztoknek-rest-api-beallitasok.webp)

*A REST API fül beállításai* (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&payment_email=partner@example.com
```

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:

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

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

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

```php
$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`:

```php
$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:

```php
$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.

```php
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.