Hub per sviluppatoriStato dell'APISupporto

Guida ai casi d'uso dell'API Definizioni dei tipi di prodotto v2020-09-01

Accedi in modo programmatico agli attributi del tipo di prodotto e ai requisiti di dati nel catalogo Amazon.

Versione API: 2020-09-01

Cosa sono le definizioni del tipo di prodotto API?

Utilizzando API per i partner di vendita per le definizioni dei tipi di prodotto (definizioni del tipo di prodotto API), puoi cercare e recuperare le definizioni dei tipi di prodotto Amazon. Le definizioni dei tipi di prodotto Amazon descrivono gli attributi e i dati richiesti per gli articoli nel catalogo Amazon utilizzando lo schema JSON.

Per ulteriori dettagli sul formato dello Schema JSON fornito dalle definizioni del tipo di prodotto API, vedi la documentazione sul Metaschema di definizione del tipo di prodotto Amazon (v1).

Fare riferimento alla Riferimento alle definizioni dei tipi di prodotto API v2020-09-01 per informazioni dettagliate sulle operazioni API e sui tipi di dati e schemi associati.

Caratteristiche principali

  • Schemi JSON: le definizioni del tipo di prodotto API forniscono schemi JSON che descrivono i requisiti indipendenti dal venditore per un determinato tipo di prodotto Amazon. Ciò include il formato dei dati, i vincoli degli attributi (per esempio quelli obbligatori, di lunghezza, di valore massimo e così via) e i vincoli degli attributi applicati in modo condizionale (per esempio il tipo di batteria nel caso in cui le batterie siano incluse).

  • Compatibile con le librerie open source: Gli schemi JSON forniti possono essere utilizzati con librerie open source e commerciali, applicazioni e servizi disponibili su larga scala per comprendere i requisiti dei dati, crearne delle mappature, generare interfacce utente e convalidare i dati delle offerte prima dell'invio ad Amazon.

  • Dettagli della presentazione localizzati: gli schemi JSON forniti includono le etichette di visualizzazione e le descrizioni degli attributi in qualsiasi impostazione locale supportata da qualsiasi marketplace.

  • Consigli sui tipi di prodotto: L'API Product Type Definitions fornisce consigli per aiutarti a scegliere il tipo di prodotto più applicabile. Questi consigli si basano sui titoli dei prodotti in qualsiasi lingua supportata per qualsiasi marketplace, se disponibili.

Terminologia

  • Schema JSON: lo Schema JSON è un vocabolario che ti consente di annotare e convalidare i documenti JSON. Per ulteriori dettagli, vedi json-schema.org.

  • Metaschema: i metaschemi descrivono il vocabolario usato dai documenti a Schema JSON. Per esempio, gli schemi dei tipi di prodotto Amazon includono il vocabolario per selectors e editable. Questo vocabolario è descritto in un metaschema che consente alle librerie e alle applicazioni di comprendere e convalidare i dati JSON basandosi su queste estensioni al vocabolario standard dello Schema JSON.

  • Tipo di prodotto: un tipo di prodotto Amazon è una categorizzazione gerarchica degli articoli nel catalogo Amazon. I requisiti relativi ai dati degli articoli sono legati al tipo di prodotto associato all'articolo.

Tutorial: cerca le definizioni dei tipi di prodotto disponibili

Usa questo tutorial per cercare e identificare i tipi di prodotto Amazon disponibili nelle definizioni di prodotto API di un determinato Marketplace Amazon e del tipo di account del partner di vendita.

Prerequisiti

Per completare questo tutorial, avrai bisogno di:

  • Autorizzazione dal partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, vedi Autorizzazione delle applicazioni API per i partner di vendita.

  • Approvazione per il ruolo Offerte di prodotti nel tuo profilo sviluppatore.

  • Il ruolo Offerte di prodotti selezionato nella pagina di registrazione dell'app per la tua applicazione.

Cerca le definizioni dei tipi di prodotto

Chiama l'operazione searchDefinitionsProductTypes per cercare i tipi di prodotto disponibili nelle definizioni del tipo di prodotto API.

Parametri della richiesta

Parametro Esempio Descrizione Obbligatorio
marketplaceIds ATVPDKIKX0DER Un elenco di identificativi dei marketplace Amazon delimitato da virgole per la richiesta.

Consulta ID marketplace per un elenco di identificativi dei marketplace.
keywords LUGGAGE Un elenco di parole chiave delimitato da virgole in base a cui cercare i tipi di prodotto.

Impostazione predefinita: quando non ci sono parole chiave o itemName vengono forniti, viene fornito l'elenco completo dei tipi di prodotto disponibili.
No
locale en_US La lingua per i nomi visualizzati nella risposta.

Impostazione predefinita: lingua principale del marketplace.
No
searchLocale en_US La lingua utilizzata per le parole chiave o itemName parametri.

Impostazione predefinita: lingua principale del marketplace.
No

Esempio di richiesta

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes ?marketplaceIds=ATVPDKIKX0DER &keywords=LUGGAGE &locale=en_US &searchLocale=en_US

Risposta

Una risposta con esito positivo include quanto segue:

Nome Esempio Descrizione
productTypes Fai riferimento all'esempio di risposta Elenco dei tipi di prodotto che corrispondono alla ricerca richiesta.
name LUGGAGE Nome del tipo di prodotto Amazon.
displayName Luggage La descrizione leggibile e localizzata del tipo di prodotto Amazon.
marketplaceIds ATVPDKIKX0DER Elenco degli identificativi di Marketplace Amazon per i quali è disponibile il tipo di prodotto (all'interno degli identificativi marketplace richiesti).
productTypeVersion UHqSqmb4FNUk= I dettagli della versione per il tipo di prodotto Amazon..

Esempio di risposta

{ "productTypes": [ { "name": "LUGGAGE", "displayName": "Luggage", "marketplaceIds": [ "ATVPDKIKX0DER" ] } ], "productTypeVersion": "UHqSqmb4FNUk=" }

Tutorial: Ottieni consigli sulla definizione del tipo di prodotto

Usa questo tutorial per ottenere consigli sui tipi di prodotto Amazon dall'API Product Type Definitions per un determinato marketplace Amazon, tipo di account partner di vendita e nome dell'articolo.

Prerequisiti

Per completare questo tutorial, avrai bisogno di:

  • Autorizzazione dal partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, vedi Autorizzazione delle applicazioni API per i partner di vendita.

  • Approvazione per il ruolo Offerte di prodotti nel tuo profilo sviluppatore.

  • Il ruolo Offerte di prodotti selezionato nella pagina di registrazione dell'app per la tua applicazione.

Cerca le definizioni dei tipi di prodotto

Chiama il searchDefinitionsProductTypes operazione per ottenere consigli sui tipi di prodotto in base al itemName dall'API Product Type Definitions.

Parametri della richiesta

Parametro Esempio Descrizione Obbligatorio
marketplaceIds ATVPDKIKX0DER Un elenco di identificativi dei marketplace Amazon delimitato da virgole per la richiesta.

Consulta ID marketplace per un elenco di identificativi dei marketplace.
itemName Softside Luggage with Spinner Wheels, Black Il titolo dell'ASIN per ottenere il tipo di prodotto consigliato.

Impostazione predefinita: quando non ci sono parole chiave o itemName vengono forniti, viene fornito l'elenco completo dei tipi di prodotto disponibili.
No
locale en_US La lingua per i nomi visualizzati nella risposta.

Impostazione predefinita: lingua principale del marketplace.
No
searchLocale en_US La lingua utilizzata per le parole chiave o itemName parametri.

Impostazione predefinita: lingua principale del marketplace.
No

Esempio di richiesta

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes ?marketplaceIds=ATVPDKIKX0DER &itemName=Softside%20Luggage%20with%20Spinner%20Wheels%2C%20Black, &locale=en_US &searchLocale=en_US

Risposta

Una risposta con esito positivo include quanto segue:

Nome Esempio Descrizione
productTypes Fare riferimento alla risposta di esempio Elenco dei tipi di prodotto che corrispondono alla ricerca richiesta.
name LUGGAGE Nome del tipo di prodotto Amazon.
displayName Luggage La descrizione leggibile e localizzata del tipo di prodotto Amazon.
marketplaceIds ATVPDKIKX0DER Elenco degli identificativi di Marketplace Amazon per i quali è disponibile il tipo di prodotto (all'interno degli identificativi marketplace richiesti).
productTypeVersion UHqSqmb4FNUk= I dettagli della versione per il tipo di prodotto Amazon.

Esempio di risposta

{ "productTypes": [ { "name": "LUGGAGE", "displayName": "Luggage", "marketplaceIds": [ "ATVPDKIKX0DER" ] } ], "productTypeVersion": "UHqSqmb4FNUk=" }

Tutorial: recupera una definizione del tipo di prodotto

Usa questo tutorial per restituire le definizioni del tipo di prodotto Amazon e gli schemi correlati delle definizioni del tipo di prodotto API per un determinato partner di vendita, tipo di prodotto Amazon e Marketplace Amazon.

Prerequisiti

Per completare questo tutorial, avrai bisogno di:

  • Autorizzazione dei partner di vendita per i quali stai effettuando chiamate. Fai riferimento a Autorizzazione delle applicazioni API per i partner di vendita per ulteriori informazioni.

  • Approvazione per il ruolo Offerte di prodotti nel tuo profilo sviluppatore.

  • Il ruolo Offerte di prodotti selezionato nella pagina di registrazione dell'app per la tua applicazione.

Recupera la definizione del tipo di prodotto

Chiama l'operazione getDefinitionsProductType per recuperare una definizione del tipo di prodotto Amazon dalle definizioni del tipo di prodotto API.

Parametri della richiesta

Parametri del percorso

Parametro Esempio Descrizione Obbligatorio
productType LUGGAGE Nome del tipo di prodotto Amazon.

Tipo: stringa

Parametri di query

Parametro Esempio Descrizione Obbligatorio
sellerId AXXXXXXXXXXXXX L'identificativo del partner di vendita. Se forniti, i requisiti e i valori specifici del venditore vengono inseriti all'interno dello schema di definizione del tipo di prodotto, come per esempio i nomi dei marchi associati al partner di vendita.

Tipo: stringa

No
marketplaceIds ATVPDKIKX0DER Elenco delimitato da virgole degli identificativi del marketplace Amazon.
Nota: questo parametro è limitato a un MarketplaceID alla volta.

Fare riferimento a ID del marketplace per l'elenco degli identificativi del marketplace Amazon.

Tipo: < stringa > array (csv)

productTypeVersion U1d1eorqMs3U= Versione della definizione del tipo di prodotto Amazon da recuperare. Le versioni precedenti al rilascio delle definizioni dei tipi di prodotto possono essere recuperate con RELEASE_CANDIDATE. Se al momento non è disponibile alcuna versione precedente al rilascio, verrà fornita una versione liveLATEST.

Impostazione predefinita: LATEST

Tipo: stringa

No
requirements LISTING Nome dei requisiti impostati per i quali recuperare i requisiti.

  • LISTING - Requisiti che includono le informazioni sul prodotto e le condizioni di vendita.
  • LISTING_OFFER_ONLY - Requisiti che includono solo le condizioni di vendita.
  • LISTING_PRODUCT_ONLY - Requisiti che includono solo le informazioni sul prodotto.

Impostazione predefinita: LISTING

Tipo: enum (Requirements)

No
requirementsEnforced ENFORCED Identifica se gli attributi richiesti per un set di requisiti sono applicati dallo schema di definizione del tipo di prodotto. I requisiti non applicati consentono la convalida strutturale dei singoli attributi senza la presenza di tutti gli attributi richiesti (per esempio per gli aggiornamenti parziali).

  • ENFORCED - Gli attributi obbligatori vengono applicati dallo schema.
  • NOT_ENFORCED - Gli attributi obbligatori non vengono applicati dallo schema.

Impostazione predefinita: ENFORCED

Tipo: enum (RequirementsEnforced)

No
locale en_US Impostazioni locali per recuperare i dettagli della presentazione (etichette e descrizioni) per. Il valore predefinito è la lingua principale di Marketplace Amazon.

Impostazione predefinita: DEFAULT

Tipo: enum (Locale)

No

Esempio di richiesta

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE ?marketplaceIds=ATVPDKIKX0DER &requirements=LISTING &locale=en_US

Risposta

Una risposta con esito positivo include quanto segue:

Nome Esempio Descrizione
metaSchema
"metaSchema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
}
Link per recuperare il documento Metaschema di definizione del tipo di prodotto Amazon (valido per 7 giorni).

Viene fornito il checksum per il confronto coi documenti recuperati in precedenza.

Tipo: SchemaLink

schema
"schema": {
  "link": {
    "resource": "https://...",
    "verb": "GET"
  },
  "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
}
Link per recuperare il documento dello Schema JSON per la definizione del tipo di prodotto Amazon (valido per 7 giorni).

Viene fornito il checksum per il confronto coi documenti recuperati in precedenza.

Tipo: SchemaLink

requirements LISTING Nome del set di requisiti a cui si applica la definizione del tipo di prodotto Amazon.

  • LISTING - Requisiti che includono le informazioni sul prodotto e le condizioni di vendita.
  • LISTING_OFFER_ONLY - Requisiti che includono solo le condizioni di vendita.
  • LISTING_PRODUCT_ONLY - Requisiti che includono solo le informazioni sul prodotto.

Impostazione predefinita: LISTING

Tipo: enum (Requirements)

requirementsEnforced ENFORCED Identifica se gli attributi richiesti per un set di requisiti sono applicati dallo schema di definizione del tipo di prodotto. I requisiti non applicati consentono la convalida strutturale dei singoli attributi senza la presenza di tutti gli attributi richiesti (per esempio per gli aggiornamenti parziali).

  • ENFORCED - Gli attributi obbligatori vengono applicati dallo schema.
  • NOT_ENFORCED - Gli attributi obbligatori non vengono applicati dallo schema.

Impostazione predefinita: ENFORCED

Tipo: enum (RequirementsEnforced)

propertyGroups
"propertyGroups": {
  "offer": {
    "title": "Offer",
    "description": "Product Offer",
    "propertyNames": [
      "purchasable_offer"
    ]
  }
}
I gruppi di proprietà definiscono le segmentazioni logiche delle proprietà descritte nel documento sullo schema JSON di definizione del tipo di prodotto Amazon. Queste segmentazioni possono essere utilizzate per raggruppare le proprietà nelle interfacce utente, identificare lo scopo e così via.

I gruppi di proprietà sono solo informativi e non influiscono sulla struttura o sulla formattazione dei dati.

Tipo: < stringa, PropertyGroup > mappa

locale en_US Le impostazioni locali dei dettagli della presentazione (etichette e descrizioni) fornite nel documento schema JSON di definizione del tipo di prodotto Amazon.

Tipo: enum (Locale)

marketplaceIds ATVPDKIKX0DER Identificatori di Marketplace Amazon a cui è applicabile la definizione del tipo di prodotto Amazon.

Type: < stringa > array

productType LUGGAGE Il nome del tipo di prodotto Amazon a cui si applica questa definizione del tipo di prodotto.

Tipo: stringa

productTypeVersion U8L4z4Ud95N16tZlR7rsmbQ== Versione della definizione del tipo di prodotto Amazon.

Tipo: (ProductTypeVersion)

displayName Luggage La descrizione leggibile e localizzata del tipo di prodotto Amazon.

Esempio di risposta

{ "metaSchema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "QFQDmPwMARO7vwMEyLhOtw==" }, "schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" }, "requirements": "LISTING", "requirementsEnforced": "ENFORCED", "propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "fulfillment_channel_availability", "purchasable_offer", "condition_type", "condition_note", "list_price", "product_tax_code", "merchant_release_date", "merchant_shipping_group", "max_order_quantity", "gift_options", "main_offer_image_locator", "other_offer_image_locator_1", "other_offer_image_locator_2", "other_offer_image_locator_3", "other_offer_image_locator_4", "other_offer_image_locator_5" ] }, "images": { "title": "Images", "description": "Physical images or URL's", "propertyNames": [ "main_product_image_locator", "other_product_image_locator_1", "other_product_image_locator_2", "other_product_image_locator_3", "other_product_image_locator_4", "other_product_image_locator_5", "other_product_image_locator_6", "other_product_image_locator_7", "other_product_image_locator_8", "swatch_product_image_locator" ] }, "shipping": { "title": "Shipping", "description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)", "propertyNames": [ "item_dimensions", "item_package_dimensions", "item_package_weight" ] }, "variations": { "title": "Variations", "description": "Variations that product will use", "propertyNames": [ "parentage_level", "child_parent_sku_relationship", "variation_theme" ] }, "safety_and_compliance": { "title": "Safety & Compliance", "description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))", "propertyNames": [ "country_of_origin", "warranty_description", "batteries_required", "batteries_included", "battery", "num_batteries", "number_of_lithium_metal_cells", "number_of_lithium_ion_cells", "lithium_battery", "supplier_declared_dg_hz_regulation", "hazmat", "safety_data_sheet_url", "item_weight", "ghs", "supplier_declared_material_regulation", "california_proposition_65", "pesticide_marking" ] }, "product_identity": { "title": "Product Identity", "description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)", "propertyNames": [ "item_name", "brand", "supplier_declared_has_product_identifier_exemption", "externally_assigned_product_identifier", "merchant_suggested_asin", "item_type_keyword", "item_type_name", "model_number", "manufacturer" ] }, "product_details": { "title": "Product Details", "description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)", "propertyNames": [ "product_description", "bullet_point", "generic_keyword", "special_feature", "style", "department", "target_gender", "age_range_description", "material", "outer", "fabric_type", "lining_description", "number_of_items", "number_of_wheels", "wheel", "model_name", "color", "size", "size_map", "part_number", "compliance_media" ] } }, "locale": "en_US", "marketplaceIds": [ "ATVPDKIKX0DER" ], "productType": "LUGGAGE", "displayName": "Luggage", "productTypeVersion": { "version": "U8L4z4Ud95N16tZlR7rsmbQ==", "latest": true, "releaseCandidate": false } }

Recupera i documenti dello schema

Nel passaggio precedente, la definizione del tipo di prodotto Amazon recuperata include i dettagli sul tipo di prodotto Amazon e i link per recuperare i documenti del metaschema e dello schema del tipo di prodotto. I link forniti sono validi per 7 giorni.

I documenti dello schema possono essere recuperati programmaticamente con un client HTTP standard o manualmente con un browser.

❗️

I nomi dei meta-schemi non possono essere risolti via web

Importante: il documento Definizione del tipo di prodotto Amazon secondo gli schemi JSON fa riferimento al metaschema per nome. Alcune librerie di schemi JSON tentano di risolvere i nomi dei metaschemi online tramite il Web, cosa che il Metaschema di definizione del tipo di prodotto Amazon (v1) non supporta. Queste librerie devono essere invece configurate per utilizzare una copia scaricata del metaschema. Per ulteriori dettagli, vedi il documento allegato Metaschema di definizione del tipo di prodotto Amazon (v1).

Domande frequenti

Questa documentazione contiene le domande frequenti e i dettagli comuni per le definizioni del tipo di prodotto API. Per domande o dubbi non presenti in questa documentazione, contatta l'assistenza API per i partner di vendita o crea un ticket nel repository GitHub.

Quanto sono aggiornate le definizioni dei tipi di prodotto Amazon?

A meno che productTypeVersion non venga precedentemente specificato, le definizioni dei tipi di prodotto Amazon descrivono sempre i requisiti più recenti e aggiornati del catalogo Amazon.

Le definizioni del tipo di prodotto API sono disponibili per tutti i tipi di prodotti Amazon?

Amazon amplia continuamente il supporto per tipi di prodotti Amazon nuovi ed esistenti nelle definizioni del tipo di prodotto API. Per un elenco aggiornato dei tipi di prodotto Amazon disponibili, utilizza le definizioni del tipo di prodotto API.

Quale versione dello Schema JSON viene utilizzata?

La definizione del tipo di prodotto Amazon secondo gli schemi JSON si estende allo Schema JSON 2019-09. Per ulteriori dettagli, vedi il documento allegatoMetaschema di definizione del tipo di prodotto Amazon (v1).

Come verranno sfruttate le versioni future dello Schema JSON?

Man mano che le versioni future dello Schema JSON verranno adottate dalle definizioni del tipo di prodotto API, saranno accompagnate da una nuova versione delle definizioni del tipo di prodotto API e dal Metaschema di definizione del tipo di prodotto Amazon.

Le versioni future dello Schema JSON non verranno adottate dalle versioni esistenti delle Definizioni del tipo di prodotto API o dal Metaschema di definizione del tipo di prodotto Amazon.

Gli schemi JSON di definizione del tipo di prodotto includono un vocabolario personalizzato?

La maggior parte dei requisiti del catalogo Amazon sono descritti utilizzando il vocabolario standard dello Schema JSON 2019-09. Tuttavia, ci sono alcuni requisiti che richiedono l'estensione dello Schema JSON con un vocabolario personalizzato. Per ulteriori dettagli, vedi lil documento allegato Metaschema di definizione del tipo di prodotto Amazon (v1).

Sono obbligato a implementare la convalida per il vocabolario personalizzato?

Il Metaschema di definizione del tipo di prodotto Amazon (v1) utilizza un vocabolario personalizzato per descrivere i requisiti del catalogo Amazon. La convalida dei dati con dati personalizzati consente di prevenire il verificarsi della maggior parte dei problemi relativi alle inserzioni prima di inviarli ad Amazon. Tuttavia, spetta a te implementare tale convalida. Senza l'implemento della convalida, l'invio dei dati ad Amazon potrebbe causare problemi relativi alle offerte dopo l'invio.

Mi serve un codice personalizzato per utilizzare gli schemi JSON?

La quantità di codice personalizzato dipende dall'applicazione. Scenari di esempio:

  • Utilizzo di una libreria open source con convalida del vocabolario personalizzato: sfruttare una libreria open source per gestire la maggior parte della convalida degli schemi JSON significa che è necessario un codice personalizzato per recuperare gli schemi dalle definizioni del tipo di prodotto API, implementare la convalida del vocabolario personalizzato e integrarli con la libreria open source.

  • Utilizzo della libreria open source senza la convalida del vocabolario personalizzato: Sfruttare una libreria open source per gestire la maggior parte della convalida degli schemi JSON significa che è necessario un codice personalizzato per recuperare gli schemi dalle definizioni del tipo di prodotto API e integrarli con la libreria open source.

Quali librerie open source sono disponibili?

Sono disponibili dozzine di librerie e implementazioni open source per convalidare i dati, renderizzare le interfacce utente e generare il codice. Per un elenco completo, vedi Implementazioni dello Schema JSON.

Amazon non supporta o approva in maniera diretta le librerie e le implementazioni specifiche open source e commerciali. Gli esempi forniti in questa documentazione sono solo di riferimento.

Quali esempi sono disponibili per la convalida dei dati con schemi di tipi di prodotto?

Il documento allegato Metaschema di definizione del tipo di prodotto Amazon (v1) include esempi di integrazioni con librerie open source per convalidare i dati con un vocabolario personalizzato in .NET (C#), Java e JavaScript (Node.js).

Come posso segnalare eventuali problemi con le definizioni del tipo di prodotto Amazon?

Per problemi specifici relativi alle definizioni del tipo di prodotto API o al contenuto degli schemi JSON di definizione del tipo di prodotto Amazon, contatta il Supporto API per i partner di vendita.


Questa pagina ti è stata utile?