# REST API

> Többnyelvű WooCommerce-tartalom létrehozása, lekérdezése és módosítása a WordPress REST API-n át.

A bővítmény kompatibilis a WordPress REST API-val. Vele létrehozhatod, lekérdezheted, módosíthatod és törölheted a lefordított WooCommerce-tartalmakat. A fejezet fejlesztőknek szól, akik saját bővítményükben, oldalukon vagy alkalmazásukban kínálnak több nyelvű WooCommerce-élményt.

## Követelmények

- WordPress 4.7 vagy újabb.
- WooCommerce 3.9.0 vagy újabb.
- A bővítmény 4.11.0 vagy újabb változata.
- A WooCommerce REST PHP kliensfüggvénytár (`automattic/woocommerce`).
- Szép (pretty) állandó hivatkozások a **Beállítások → Állandó hivatkozások** oldalon.

## A kliensfüggvénytár beállítása

A kliensfüggvénytár egy PHP-burkoló, amellyel egyszerűbben éred el a WooCommerce REST API-t. Más kliens is használható.

1. Telepítsd a függvénytárat Composerrel:

   ```bash
   composer require automattic/woocommerce
   ```

2. A PHP-kód elején töltsd be az automatikus betöltőt, és hozd létre a klienst:

   ```php
   require __DIR__ . '/vendor/autoload.php';

   use Automattic\WooCommerce\Client;

   $woocommerce = new Client(
       'http://example.com',
       'ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
       'cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
       [
           'wp_api'  => true,
           'version' => 'wc/v3',
       ]
   );
   ```

3. Generáld le a Consumer Key és a Consumer Secret értékét: **WooCommerce → Beállítások → Haladó → REST API kulcsok**, itt kattints a kulcs hozzáadására. Add meg a **Leírás**t, a **Felhasználó**t és a **Jogosultságok**at, majd kattints az **API-kulcs generálása** gombra.

   ![A REST API kulcs létrehozó űrlapja a WooCommerce haladó beállításai között](./kepek/fejlesztoknek-api-kulcsok.webp)

   *A REST API kulcs létrehozó űrlapja a WooCommerce haladó beállításai között* (https://minta-bolt.hu/wp-admin/admin.php?page=wc-settings&tab=advanced&section=keys&create-key=1)

   Az űrlapon a leírást, a felhasználót és a jogosultságot (olvasás, írás vagy mindkettő) kell megadnod.

4. Írd be a kapott kulcsot és titkot a PHP-kódba (`ck_…` és `cs_…` kezdetű értékek).
5. Állítsd be a kliens további beállításait a függvénytár dokumentációja szerint.

## Műveletek

### Rendelések lekérdezése

A `lang` paraméterrel megadott nyelven kapod vissza a rendelések tartalmát. Feltétel, hogy a termékek le legyenek fordítva az adott nyelvre. Így például a rendeléseket az oldal alapnyelvén is láthatod.

Példa: csak a francia nyelven leadott rendelések.

```php
$orders = $woocommerce->get('orders', array( 'per_page' => 25, 'lang' => 'fr' ) );
```

### Egy rendelés lekérdezése

Ha a `lang` paramétert megadod, és a rendelés más nyelven készült, a tételek (ha léteznek) a megadott nyelvű fordításukban jelennek meg.

Példa: a 110-es rendelés angolul.

```php
$order = $woocommerce->get('orders/110', array( 'lang' => 'en' ) );
```

### Termékek lekérdezése

A `lang` paraméterrel adott nyelvű termékeket kapsz. Az összes nyelv termékéhez a `lang` értéke `all`.

Példa: csak a spanyol termékek.

```php
$products = $woocommerce->get('products', array( 'per_page' => 25, 'lang' => 'es' ) );
```

### Egy termék lekérdezése

A válasz tartalmazza a nyelvi és a fordítási adatokat. Ha a több pénznemes mód be van kapcsolva és be van állítva, és vannak kézi árak a másodlagos pénznemekben, azok is szerepelnek.

```php
$product = $woocommerce->get('products/99');
```

A válasz többek között ilyen mezőket tartalmaz:

```text
[title] => An English product
[id] => 28
[type] => simple
[status] => publish
[price] => 100.00
[regular_price] => 100.00
[translations] => stdClass Object
    (
        [bg] => 31
        [es] => 30
    )
[lang] => en
```

A `translations` a fordítások nyelvkódját és termékazonosítóját adja, a `lang` a termék saját nyelve.

### Termék-taxonómiák lekérdezése

Ide tartozik a termékkategória, a címke, a jellemző és a szállítási osztály. A `lang` paraméterrel adott nyelvű elemeket kapsz, az összes nyelvhez használd az `all` értéket.

Példa: a kategóriák minden nyelven.

```php
$categories = $woocommerce->get('products/categories', array( 'per_page' => 10, 'lang' => 'all' ) );
```

### Jelentések

Az eladási jelentést a `currency` paraméterrel kérheted adott pénznemben:

```php
$query = [ 'period' => 'year', 'currency' => 'EUR' ];
$woocommerce->get( 'reports/sales', $query );
```

A legnépszerűbb termékek és a termékösszesítők jelentése a `lang` paraméterrel adott nyelven kérhető:

```php
$query = [ 'lang' => 'fr' ];
$woocommerce->get( 'reports/top_sellers', $query );
$woocommerce->get( 'reports/products/totals', $query );
```

### Termék létrehozása

Három paramétert használhatsz:

| Paraméter | Mit csinál |
|---|---|
| `lang` | A termék nyelve. Ha kihagyod, az oldal alapnyelve lesz. |
| `translation_of` | Nem kötelező. A megadott azonosítójú termék fordításaként jön létre. Ha kihagyod, új fordítási csoport (trid) kezdődik. |
| `custom_prices` | Kézi árak megadása a másodlagos pénznemekben. |

Példa:

```php
$data = [
    'name'              => 'English Test Post',
    'type'              => 'simple',
    'regular_price'     => '10.00',
    'description'       => 'This is a Simple English Test Post',
    'short_description' => 'This is a Simple English Test Post',
    'categories'        => [ [ 'id' => 10 ], [ 'id' => 12 ] ],
    'images'            => [
        [ 'src' => 'https://example.com/image-1.png', 'position' => 0 ],
        [ 'src' => 'https://example.com/image-2.png', 'position' => 1 ]
    ],
    'lang'              => 'en',
    'custom_prices'     => [
        'EUR' => [ 'regular_price' => 1999, 'sale_price' => 1500 ],
        'USD' => [ 'regular_price' => 2100, 'sale_price' => 2099 ]
    ]
];
$product = $woocommerce->post( 'products', $data );
```

Ha az előző hívással létrejött termék azonosítója 23, a francia fordítást így veheted fel:

```php
$data = [
    'name'              => 'French Test Post',
    'type'              => 'simple',
    'regular_price'     => '10.00',
    'description'       => 'This is a Simple French Test Post',
    'short_description' => 'This is a Simple French Test Post',
    'lang'              => 'fr',
    'translation_of'    => '23'
];
$product = $woocommerce->post('products', $data);
```

Ha a kategóriák már le vannak fordítva, és a WPML-ben be van kapcsolva a taxonómia másolása a fordításokra, a fordításnál nem kell megadnod őket: automatikusan hozzáadódnak.

### Változó termékek

#### Változat helyi jellemzővel

A változat létrehozásakor ugyanaz a három paraméter használható (`lang`, `translation_of`, `custom_prices`), mint a termékeknél.

```php
$data = [
    'lang'          => 'en',
    'regular_price' => '10',
    'attributes'    => [ [ 'name' => $local_attribute_name, 'option' => 'red' ] ]
];
$woocommerce->post( 'products/{$variable_product_id}/variations', $data );
```

A fordítás a `translation_of` megadásával készül. Ha az előző hívással létrejött elem azonosítója 25:

```php
$data = [
    'name'           => 'Translation of Variable Product',
    'type'           => 'variable',
    'description'    => 'Translate of Product Description',
    'lang'           => 'fr',
    'translation_of' => 25,
    'attributes'     => [
        [
            'name'      => $local_attribute_name,
            'visible'   => true,
            'variation' => true,
            'options'   => [ '$translation_of_red' ]
        ]
    ]
];
$woocommerce->post('products', $data);
```

#### Változat globális jellemzővel

Előbb hozd létre és fordítsd le a globális jellemző értékeit, utána a változó terméket:

```php
$data = [
    'name'           => 'Test Variable Product',
    'type'           => 'variable',
    'description'    => 'Test Variable Product for REST',
    'lang'           => 'en',
    'translation_of' => null,
    'attributes'     => [
        [
            'id'        => $global_attribute_id,
            'visible'   => true,
            'variation' => true,
            'options'   => [ 'Red' ]
        ]
    ]
];
$woocommerce->post('products', $data);
```

Ezután jönnek a változatok. Ha az eredeti termék azonosítója 25, a `batch` végpontot használd, és a jellemzőérték slugját add meg:

```php
$data = [
    'create' => [
        [
            'lang'           => 'en',
            'translation_of' => null,
            'regular_price'  => '10',
            'attributes'     => [
                [
                    'id'     => $global_attribute_id,
                    'option' => 'blue-en' // a jellemzőérték slugja
                ]
            ]
        ]
    ]
];
$woocommerce->post( 'products/25/variations/batch', $data );
```

A változó termék fordítása:

```php
$data = [
    'name'           => 'FR Test Variable Product',
    'type'           => 'variable',
    'description'    => 'FR Test Variable Product for REST',
    'lang'           => 'fr',
    'translation_of' => 25,
    'attributes'     => [
        [
            'id'        => $global_attribute_id,
            'visible'   => true,
            'variation' => true,
            'options'   => [ 'red-fr' ] // a lefordított jellemzőérték slugja
        ]
    ]
];
$woocommerce->post('products', $data);
```

### Rendelés létrehozása

A `lang` paraméter a rendelés nyelvét állítja be. Ha a rendelésbe a megadottól eltérő nyelvű termék kerül, az nem alakul át automatikusan: a saját nyelvén kerül a rendelésbe.

```php
$data = [
    'payment_details' => [
        'method_id'    => 'bacs',
        'method_title' => 'Direct Bank Transfer',
        'paid'         => true
    ],
    'billing_address' => [
        'first_name' => 'Minta',
        'last_name'  => 'Vásárló',
        'address_1'  => 'Minta utca 1.',
        'city'       => 'Budapest',
        'postcode'   => '1011',
        'country'    => 'HU',
        'email'      => 'vasarlo@example.com'
    ],
    'customer_id' => 2,
    'line_items'  => [
        [ 'product_id' => 58, 'quantity' => 2 ],
    ],
    'shipping_lines' => [
        [ 'method_id' => 'flat_rate', 'method_title' => 'Flat Rate', 'total' => 10 ]
    ],
    'lang'     => 'el',
    'currency' => 'usd'
];
$order = $woocommerce->post('orders', $data );
```

### Taxonómiaelemek létrehozása

A REST API-val a jellemzők értékeit (például „Kék”) fordíthatod, a jellemzők nevét (például „Szín”) nem. A jellemzőnevek fordításához nyisd meg a **WPML → Taxonómia fordítása** oldalt, válaszd ki a jellemzőt a legördülő listából, és a **Taxonómia-címkék és bázisok fordításai** szakaszban add meg a fordításokat.

Két paraméter használható:

| Paraméter | Mit csinál |
|---|---|
| `lang` | Az elem nyelve. Ha kihagyod, az oldal alapnyelve lesz. |
| `translation_of` | Nem kötelező. A megadott azonosítójú elem fordításaként jön létre. Ha kihagyod, új fordítási csoport (trid) kezdődik. |

Példa: kategória létrehozása a második nyelven.

```php
$category = [ 'name' => 'Product Category ES', 'translation_of' => $original_category_id, 'lang' => 'es' ];
$woocommerce->post( 'products/categories', $category );
```

Példa: globális jellemzőérték fordítása a második nyelvre.

```php
$attribute_term = [ 'name' => 'Black ES', 'translation_of' => $original_attribute_term_id, 'lang' => 'es' ];
$woocommerce->post( 'products/attributes/{$attribute_id}/terms', $attribute_term );
```