# OffersV2

> **Traduzione italiana non ufficiale.** Originale: [OffersV2](https://affiliate-program.amazon.com/creatorsapi/docs/en-us/api-reference/resources/offersV2) · [sorgente EN](../../../en/api-reference/resources/offersV2.md) · [indice](../../../README.md)

La risorsa `OffersV2` contiene varie risorse relative ai listini di offerte di un articolo.

## Risorse
* [Listings](#listings)
  * [Availability](#availability)
    * MaxOrderQuantity
    * Message
    * MinOrderQuantity
    * Type
  * [Condition](#condition)
    * ConditionNote
    * SubCondition
    * Value
  * [DealDetails](#dealdetails)
    * AccessType
    * Badge
    * EarlyAccessDurationInMilliseconds
    * EndTime
    * PercentClaimed
    * StartTime
  * IsBuyBoxWinner
  * [LoyaltyPoints](#loyaltypoints)
    * Points
  * [MerchantInfo](#merchantinfo)
    * Name
    * Id
  * [Price](#price)
    * Money
    * PricePerUnit
    * [SavingBasis](#savingbasis)
    * [Savings](#savings)
  * Type
  * ViolatesMAP

### Listings

Specifica i vari listini di offerte associati al prodotto.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| [Availability](#availability) | Struct | Specifica le informazioni sulla disponibilità di un'offerta |
| [Condition](#condition) | Struct | Specifica la condizione dell'offerta |
| [DealDetails](#dealdetails) | Struct | Specifica le informazioni sull'offerta promozionale (deal) |
| IsBuyBoxWinner | Boolean | Specifica se la data offerta è vincitrice della BuyBox nella Detail Page Experience (DPX) di un articolo. È l'offerta migliore consigliata da Amazon per un prodotto: è l'offerta in evidenza che si vede nella pagina di dettaglio di un ASIN. |
| [LoyaltyPoints](#loyaltypoints) | Struct | Specifica le informazioni sui punti fedeltà per un'offerta (attualmente supportato solo nel marketplace del Giappone) |
| [MerchantInfo](#merchantinfo) | Struct | Specifica le informazioni sul venditore di un'offerta |
| [Price](#price) | Struct | Specifica il prezzo di acquisto di un'offerta |
| Type | String | Specifica il tipo di offerta se c'è una distinzione speciale. La maggior parte dei listini non ha un tipo (come i listini regolari e i deal non lampo). <br/>*Valori validi*:<br/> LIGHTNING_DEAL, SUBSCRIBE_AND_SAVE |
| ViolatesMAP | Boolean | Specifica se un'offerta viola la policy MAP. Vedi [questa sezione](#prezzo-minimo-pubblicizzato-map) per maggiori dettagli |

#### Risposta di esempio

```json
{
  "itemsResult": {
    "items": [
      {
        "asin": "B00MNV8E0C",
        "detailPageURL": "https://www.amazon.com/dp/B00MNV8E0C?tag=example&linkCode=ogi&th=1&psc=1",
        "offersV2": {
          "listings": [
            {
              "availability": {
                "maxOrderQuantity": 1,
                "minOrderQuantity": 1,
                "type": "IN_STOCK"
              },
              "condition": {
                "conditionNote": "",
                "subCondition": "Unknown",
                "value": "New"
              },
              "dealDetails": {
                "accessType": "PRIME_EXCLUSIVE",
                "endTime": "2024-11-06T05:35Z",
                "percentClaimed": 38,
                "startTime": "2024-11-05T18:05Z"
              },
              "isBuyBoxWinner": true,
              "merchantInfo": {
                "name": "Amazon.com"
              },
              "price": {
                "money": {
                  "amount": 59.49,
                  "currency": "USD",
                  "displayAmount": "$59.49"
                },
                "pricePerUnit": {
                  "amount": 29.75,
                  "currency": "USD",
                  "displayAmount": "$29.75 / Count"
                },
                "savingBasis": {
                  "money": {
                    "amount": 69.99,
                    "currency": "USD",
                    "displayAmount": "$69.99"
                  },
                  "savingBasisType": "LIST_PRICE",
                  "savingBasisTypeLabel": "List Price"
                },
                "savings": {
                  "money": {
                    "amount": 10.5,
                    "currency": "USD",
                    "displayAmount": "$10.50"
                  },
                  "percentage": 15
                }
              },
              "type": "LIGHTNING_DEAL",
              "violatesMAP": false
            }
          ]
        }
      }
    ]
  }
}
```

### Availability

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| MaxOrderQuantity | Integer | Specifica la quantità massima acquistabile di un prodotto |
| Message | String | Specifica il messaggio di disponibilità di un prodotto |
| MinOrderQuantity | Integer | Specifica la quantità minima necessaria per acquistare un prodotto |
| Type | String | Descrive il tipo di disponibilità del prodotto.<br/>*Valori validi*:<br/> AVAILABLE_DATE, IN_STOCK, IN_STOCK_SCARCE, LEADTIME, <br/>OUT_OF_STOCK, PREORDER, UNAVAILABLE, UNKNOWN |

Maggiori dettagli sui tipi di disponibilità:

| Stato | Descrizione |
|-----------------|--------------------------------------------------------------------------------------------------|
| AVAILABLE_DATE | L'articolo non è disponibile, ma lo sarà in una data futura. |
| IN_STOCK | L'articolo è disponibile. |
| IN_STOCK_SCARCE | L'articolo è disponibile, ma le scorte sono limitate. |
| LEADTIME | L'articolo è disponibile solo dopo un certo tempo di attesa (tempo tra ordine ricevuto e ordine spedito). |
| OUT_OF_STOCK | L'articolo è attualmente esaurito. |
| PREORDER | L'articolo non è ancora disponibile, ma può essere pre-ordinato. |
| UNAVAILABLE | L'articolo non è disponibile. |
| UNKNOWN | Disponibilità sconosciuta. |

#### Risposta di esempio

```json
{
  "availability": {
    "maxOrderQuantity": 30,
    "message": "In Stock",
    "minOrderQuantity": 1,
    "type": "IN_STOCK"
  }
}
```

### Condition

Per le offerte con valore `New`, non ci sarà una `ConditionNote` specificata e `SubCondition` sarà Unknown.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| ConditionNote | String | Specifica la condizione del prodotto come indicata dal venditore. Può essere vuota. |
| Value | String | Specifica la condizione dell'offerta. <br/>*Valori validi*: New, Used, Refurbished, Unknown |
| SubCondition | String | Specifica la sotto-condizione di un'offerta. <br/>*Valori validi*: LikeNew, Good, VeryGood, Acceptable, Refurbished, OEM, OpenBox, Unknown |

#### Risposta di esempio

```json
{
  "condition": {
    "conditionNote": "",
    "subCondition": "Unknown",
    "value": "New"
  }
}
```

### DealDetails

Questo campo viene popolato solo se c'è un deal associato al listing. L'esistenza di questo campo (quando richiesto) implica l'esistenza di un deal.

Il modo più semplice per trovare deal su Amazon è visitare [https://www.amazon.com/deals](https://www.amazon.com/deals), o l'equivalente appropriato per il tuo marketplace.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| AccessType | String | Specifica quali clienti possono usufruire del deal (tutti o solo i membri Prime). <br/> Il Prime Early Access è disponibile prima per i membri Prime (per il tempo specificato da `EarlyAccessDurationInMilliseconds`) prima di diventare disponibile per tutti. <br/> *Valori validi*: ALL, PRIME_EARLY_ACCESS, PRIME_EXCLUSIVE. |
| Badge | String | Specifica un badge che accompagna il deal. <br/> *Valori di esempio*: Limited Time Deal, With Prime, Black Friday Deal, Ends In |
| EarlyAccessDurationInMilliseconds | Integer | Specifica il numero di millisecondi per cui un deal è disponibile prima solo per i membri Prime, se applicabile |
| EndTime | String | Specifica l'orario UTC di fine del deal. È possibile che il deal termini prima (per esempio: esaurito) |
| PercentClaimed | String | Specifica quanta capacità del deal è già stata consumata. Non disponibile per tutti i tipi di deal. |
| StartTime | String | Specifica l'orario UTC di inizio del deal |

#### Maggiori dettagli sul Deal Badge

Il Deal Badge è una stringa visualizzabile per accompagnare il deal. Può descrivere il tipo di deal (es. Limited Time Deal, Black Friday Deal), un particolare aspetto del deal (es. With Prime sui deal esclusivi Prime) o qualche altra informazione sul deal. Per i deal in scadenza, questo badge mostra spesso "Ends In": può essere usato in combinazione con il parametro `EndTime` se vuoi implementare un timer con conto alla rovescia.

#### Maggiori dettagli su start/end time

Non c'è garanzia che nella risposta sia specificato un orario di inizio/fine (come per qualsiasi campo della PA-API, che può essere presente o meno). I deal senza orario di inizio/fine sono in esecuzione a tempo indeterminato e non hanno una durata predefinita. In questo caso, l'esistenza dell'oggetto `DealDetails` nella risposta significa che il deal è attivo al momento della chiamata.

Nota che un Prime Early Access Deal è disponibile solo per i clienti Prime per la durata di early access specificata, prima di diventare disponibile per tutti i clienti secondo lo `StartTime`, quando presente.

#### Risposta di esempio

##### Limited Time Deal
```json
{
   "dealDetails": {
    "accessType": "ALL",
    "badge": "Limited time deal",
    "endTime": "2025-03-02T07:59:59Z",
    "startTime": "2025-02-16T08:00Z"
   }
}
```

##### Deal in scadenza
```json
{
  "dealDetails": {
    "accessType": "PRIME_EARLY_ACCESS",
    "badge": "Ends in ",
    "earlyAccessDurationInMilliseconds": 1800000,
    "endTime": "2025-02-21T05:35Z",
    "percentClaimed": 35,
    "startTime": "2025-02-20T18:05Z"
  }
}
```

### LoyaltyPoints

I punti fedeltà (Loyalty Points) sono un programma solo di Amazon Giappone. Vedi https://www.amazon.co.jp/-/en/gp/help/customer/display.html?nodeId=GGB6FCM85P9UKC7T

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Points | Integer | Specifica i punti fedeltà associati a un'offerta |

#### Risposta di esempio
```json
{
  "loyaltyPoints": {
    "points": 10
  }
}
```

### MerchantInfo

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Id | String | Identificatore univoco del merchant/venditore |
| Name | String | Il nome del merchant/venditore |

#### Risposta di esempio
```json
{
  "merchantInfo": {
    "id": "ATVPDKIKX0DER",
    "name": "Amazon.com"
  }
}
```

### Price

Nota che il prezzo fornito è un valore predefinito basato su un indirizzo di spedizione nel marketplace. Il prezzo restituito dall'API può differire da quello visto da uno specifico cliente per una varietà di fattori.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Money | [Money](#money) | Specifica l'importo di acquisto di un'offerta |
| PricePerUnit | [Money](#money) | Specifica il prezzo per unità. DisplayAmount include la formattazione dell'unità |
| [SavingBasis](#savingbasis) | Struct | Specifica il valore di riferimento su cui si calcola il risparmio |
| [Savings](#savings) | Struct | Specifica il risparmio su un'offerta. È la differenza tra il Money del Price e il Money del SavingBasis |

#### Risposta di esempio
```json
{
  "price": {
    "money": {
      "amount": 59.49,
      "currency": "USD",
      "displayAmount": "$59.49"
    },
    "pricePerUnit": {
      "amount": 29.75,
      "currency": "USD",
      "displayAmount": "$29.75 / Count"
    },
    "savingBasis": {
      "money": {
        "amount": 69.99,
        "currency": "USD",
        "displayAmount": "$69.99"
      },
      "savingBasisType": "LIST_PRICE",
      "savingBasisTypeLabel": "List Price"
    },
    "savings": {
      "money": {
        "amount": 10.5,
        "currency": "USD",
        "displayAmount": "$10.50"
      },
      "percentage": 15
    }
  }
}
```

### SavingBasis

Valore di riferimento rispetto al quale viene calcolato il risparmio.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Money | [Money](#money) | Specifica le informazioni sull'importo del saving basis |
| SavingBasisType | String | Specifica il tipo di saving basis. <br/>*Valori validi*: LIST_PRICE, LOWEST_PRICE, LOWEST_PRICE_STRIKETHROUGH, WAS_PRICE |
| SavingBasisTypeLabel | String | Stringa etichetta che può essere inclusa accanto all'importo del saving basis. |

#### Risposta di esempio
```json
{
  "savingBasis": {
    "money": {
      "amount": 69.99,
      "currency": "USD",
      "displayAmount": "$69.99"
    },
    "savingBasisType": "LIST_PRICE",
    "savingBasisTypeLabel": "List Price"
  }
}
```

### Savings

Risparmio di un'offerta.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Money | [Money](#money) | Specifica le informazioni sull'importo del risparmio |
| Percentage | Integer | Specifica la percentuale di risparmio su un'offerta |

#### Risposta di esempio
```json
{
  "savings": {
    "money": {
      "amount": 10.5,
      "currency": "USD",
      "displayAmount": "$10.50"
    },
    "percentage": 15
  }
}
```

### Money

Struct comune usato per rappresentare il denaro.

| Nome attributo | Tipo | Descrizione |
|:---|:---|:---|
| Amount | BigDecimal | Specifica l'importo |
| Currency | String | Specifica la valuta associata all'importo di acquisto |
| DisplayAmount | String | Specifica l'importo formattato |

## Operazioni pertinenti

Le operazioni che possono usare queste risorse includono:

* [GetItems](../operations/get-items.md)
* [SearchItems](../operations/search-items.md)
* [GetVariations](../operations/get-variations.md)

## Appendice

### Prezzo minimo pubblicizzato (MAP)

Alcuni produttori hanno un prezzo minimo pubblicizzabile (MAP, Minimum Advertised Price) che può essere mostrato su Amazon.com. Quando il prezzo Amazon è inferiore al MAP, il produttore non consente di mostrare il prezzo finché il cliente non compie un'ulteriore azione, come mettere l'articolo nel carrello o, in alcuni casi, procedere alla fase finale di checkout. I clienti devono andare su Amazon per vedere il prezzo sul sito retail, ma non sono obbligati ad acquistare il prodotto.

### Mappatura dei campi da OffersV1 a OffersV2

La tabella seguente fornisce una mappatura completa di tutti i campi dalla vecchia risorsa Offers alla nuova risorsa OffersV2. I campi contrassegnati come "Non disponibile" sono stati intenzionalmente rimossi in OffersV2. OffersV2 fornisce solo i listini in evidenza (featured) mostrati ai clienti retail nella buybox della pagina di dettaglio Amazon, che rappresentano le migliori offerte complessive per il prodotto. **Se non ci sono offerte in evidenza, OffersV2 mostrerà lo stato come esaurito (out of stock).**

| **Campo OffersV1** | **Campo OffersV2** |
|:---|:---|
| **Struttura di base** | |
| `Offers.Listings` | `OffersV2.Listings` |
| `Offers.Summaries` | Non disponibile |
| `Offers.Summaries.Condition` | Non disponibile |
| `Offers.Summaries.HighestPrice` | Non disponibile |
| `Offers.Summaries.LowestPrice` | Non disponibile |
| `Offers.Summaries.OfferCount` | Non disponibile |
| **Availability** | |
| `Offers.Listings.Availability.MaxOrderQuantity` | `OffersV2.Listings.Availability.MaxOrderQuantity` |
| `Offers.Listings.Availability.Message` | `OffersV2.Listings.Availability.Message` |
| `Offers.Listings.Availability.MinOrderQuantity` | `OffersV2.Listings.Availability.MinOrderQuantity` |
| `Offers.Listings.Availability.Type` | `OffersV2.Listings.Availability.Type` |
| **Condition** | |
| `Offers.Listings.Condition.Value` | `OffersV2.Listings.Condition.Value` |
| `Offers.Listings.Condition.SubCondition.Value` | `OffersV2.Listings.Condition.SubCondition` |
| `Offers.Listings.Condition.ConditionNote.Value` | `OffersV2.Listings.Condition.ConditionNote` |
| **DeliveryInfo** | |
| `Offers.Listings.DeliveryInfo.IsAmazonFulfilled` | Non disponibile |
| `Offers.Listings.DeliveryInfo.IsFreeShippingEligible` | Non disponibile |
| `Offers.Listings.DeliveryInfo.IsPrimeEligible` | Non disponibile |
| `Offers.Listings.DeliveryInfo.ShippingCharges` | Non disponibile |
| **Campi di base del Listing** | |
| `Offers.Listings.Id` | Non disponibile |
| `Offers.Listings.IsBuyBoxWinner` | `OffersV2.Listings.IsBuyBoxWinner` |
| `Offers.Listings.ViolatesMAP` | `OffersV2.Listings.ViolatesMAP` |
| **LoyaltyPoints** | |
| `Offers.Listings.LoyaltyPoints.Points` | `OffersV2.Listings.LoyaltyPoints.Points` |
| **MerchantInfo** | |
| `Offers.Listings.MerchantInfo.DefaultShippingCountry` | Non disponibile |
| `Offers.Listings.MerchantInfo.FeedbackCount` | Non disponibile |
| `Offers.Listings.MerchantInfo.FeedbackRating` | Non disponibile |
| `Offers.Listings.MerchantInfo.Id` | `OffersV2.Listings.MerchantInfo.Id` |
| `Offers.Listings.MerchantInfo.Name` | `OffersV2.Listings.MerchantInfo.Name` |
| **Price** | |
| `Offers.Listings.Price.Amount` | `OffersV2.Listings.Price.Money.Amount` |
| `Offers.Listings.Price.Currency` | `OffersV2.Listings.Price.Money.Currency` |
| `Offers.Listings.Price.DisplayAmount` | `OffersV2.Listings.Price.Money.DisplayAmount` |
| `Offers.Listings.Price.PricePerUnit` | `OffersV2.Listings.Price.PricePerUnit` |
| **ProgramEligibility** | |
| `Offers.Listings.ProgramEligibility.IsPrimeExclusive` | Non disponibile |
| `Offers.Listings.ProgramEligibility.IsPrimePantry` | Non disponibile |
| **Promotions** | |
| `Offers.Listings.Promotions` | Non disponibile |
| **SavingBasis** | |
| `Offers.Listings.SavingBasis.Amount` | `OffersV2.Listings.Price.SavingBasis.Money.Amount` |
| `Offers.Listings.SavingBasis.Currency` | `OffersV2.Listings.Price.SavingBasis.Money.Currency` |
| `Offers.Listings.SavingBasis.DisplayAmount` | `OffersV2.Listings.Price.SavingBasis.Money.DisplayAmount` |
| **Nuovi in OffersV2** | |
| N/D | `OffersV2.Listings.DealDetails` |
| N/D | `OffersV2.Listings.DealDetails.AccessType` |
| N/D | `OffersV2.Listings.DealDetails.Badge` |
| N/D | `OffersV2.Listings.DealDetails.EarlyAccessDurationInMilliseconds` |
| N/D | `OffersV2.Listings.DealDetails.EndTime` |
| N/D | `OffersV2.Listings.DealDetails.PercentClaimed` |
| N/D | `OffersV2.Listings.DealDetails.StartTime` |
| N/D | `OffersV2.Listings.Price.SavingBasis` |
| N/D | `OffersV2.Listings.Price.SavingBasis.SavingBasisType` |
| N/D | `OffersV2.Listings.Price.SavingBasis.SavingBasisTypeLabel` |
| N/D | `OffersV2.Listings.Price.Savings` |
| N/D | `OffersV2.Listings.Price.Savings.Money` |
| N/D | `OffersV2.Listings.Price.Savings.Percentage` |
| N/D | `OffersV2.Listings.Type` |
