## Amazon Creators API – GetItems (PHP/Composer)

Esempio minimale, basato sulla documentazione ufficiale, per recuperare informazioni di un prodotto a partire dall’ASIN usando la Creators API.

### Prerequisiti

- PHP 8+
- Composer
- Credenziali Creators API (client id / client secret) e partner tag valido per il marketplace target.

### Installazione

```bash
composer install
```

### Configurazione rapida

Imposta le variabili d’ambiente (o crea un file `.env` nella root del progetto: il loader integrato dell’esempio le legge automaticamente):

```bash
export CREATORS_CLIENT_ID="...client id..."
export CREATORS_CLIENT_SECRET="...client secret..."
export CREATORS_REGION="EU"                      # NA, EU o FE
export CREATORS_CREDENTIAL_VERSION="2.2"         # 2.1 (NA), 2.2 (EU), 2.3 (FE)
export CREATORS_MARKETPLACE="www.amazon.it"      # vedi Common Request Headers and Parameters
export CREATORS_PARTNER_TAG="tuo-store-21"
```

Esempio `.env`:
```
CREATORS_CLIENT_ID=YOUR_CLIENT_ID
CREATORS_CLIENT_SECRET=YOUR_CLIENT_SECRET
CREATORS_REGION=EU
CREATORS_CREDENTIAL_VERSION=2.2
CREATORS_MARKETPLACE=www.amazon.it
CREATORS_PARTNER_TAG=tuo-store-21
```

### Test rapido GetItems

```bash
php tests/get_item.php B0FJ8X2CL4
```

Il client:

1) ottiene il token OAuth2 dal token endpoint corrispondente alla credential version (vedi `src/CreatorsApiClient.php`), con `scope=creatorsapi/default` per le 2.x e `scope=creatorsapi::default` per le 3.x, e lo tiene in cache fino a scadenza;
2) chiama `https://creatorsapi.amazon/catalog/v1/getItems` con header:
   - `Authorization: Bearer <access_token>` (3.x) oppure `Bearer <access_token>, Version <credential_version>` (2.x)
   - `Content-Type: application/json`
   - `x-marketplace: <marketplace>`
3) invia nel body JSON almeno `itemIds`, `marketplace`, `partnerTag` e, se serve, `resources` (es. `images.primary.small`, `itemInfo.title`, `parentASIN`).

### Note utili (riassunto doc)

- Token endpoint per credential version (il flusso dipende dalla versione):
  - **2.x — Cognito** (form-urlencoded, scope `creatorsapi/default`):
    - NA (2.1) `https://creatorsapi.auth.us-east-1.amazoncognito.com/oauth2/token`
    - EU (2.2) `https://creatorsapi.auth.eu-south-2.amazoncognito.com/oauth2/token`
    - FE (2.3) `https://creatorsapi.auth.us-west-2.amazoncognito.com/oauth2/token`
  - **3.x — Login with Amazon** (body JSON, scope `creatorsapi::default`):
    - NA (3.1) `https://api.amazon.com/auth/o2/token`
    - EU (3.2) `https://api.amazon.co.uk/auth/o2/token`
    - FE (3.3) `https://api.amazon.co.jp/auth/o2/token`
- Base API: `https://creatorsapi.amazon`
- Path GetItems: `/catalog/v1/getItems`
- Max 10 `itemIds` per chiamata; `itemIdType` default `ASIN`.
- Header `Authorization`: il suffisso `, Version <x.y>` serve **solo** alle credenziali 2.x (2.1/2.2/2.3). Le 3.x (LwA) vogliono il solo `Bearer <access_token>`.
- `partnerTag` deve essere valido per il marketplace scelto.

### Feed e Report

Oltre a GetItems, il client espone i feed e i report (questi ultimi sul path
`/reports/v1`, distinto dal catalogo):

```php
$client->listFeeds();               // { feeds: [ { feedName, size, md5, lastUpdated } ] }
$client->getFeed('it-bestsellers'); // { url }

$client->listReports();             // { reports: [ { filename, md5, size, lastModified } ] }
$client->getReport($filename);      // { url } presigned (.tsv.gz)
```

Metadati report normalizzati (famiglia e data derivate dal nome file) via
`App\CreatorsApi\Model\ReportMetadata`. Dettagli:
[ListReports](docs/en/api-reference/operations/list-reports.md),
[GetReport](docs/en/api-reference/operations/get-report.md),
[famiglie di report](docs/en/api-reference/operations/report-families.md).

### Test

Suite offline (nessuna rete, nessuna credenziale) in Docker con PHP 8.3:

```bash
docker compose run --rm php vendor/bin/pest --group=unit
```

I test unit iniettano un client Guzzle mockato; il gruppo `integration` colpisce
Amazon e si auto-salta senza credenziali.

### Struttura

- `src/CreatorsApiClient.php` – client PHP: token OAuth2 + catalogo, feed e report.
- `src/Model/` – DTO normalizzati (`AmazonItem`, `Price`, `ProductItem`, `ReportMetadata`).
- `tests/Unit/` – test offline con MockHandler; `tests/Integration/` – smoke live.
- `Dockerfile` / `docker-compose.yml` – runner PHP 8.3 per la suite.

